promise-redis-legacy

-------------
promise-redis
-------------

promise-redis is a tiny library that adds promise awareness to node_redis_,
the main node.js redis client. You may provide any promise-library. But if you
don't provide any, then native JavaScript Promise_ will be used instead.

Features:

* It is agnostic about what promise library you use. You will want to provide
promise library of your choice (no lock-in) or just use native JavaScript
promises.

* Nothing new to learn. promise-redis just lifts redis commands to return
promises, and then exposes to you the original node_redis_ object. So for
API docs visit node_redis documentation_.

* It is very small.

.. contents::

Installation
------------

The only dependency of promise-redis is node_redis_. To install
promise-redis run:

.. code-block:: bash

npm install promise-redis

Usage
-----

Using redis with native promises is easy:

.. code-block:: javascript

var redis = require('promise-redis')();

Now you can use `redis object as usual, but each command will return
a promise:

.. code-block:: javascript

var client = redis.createClient();
client.set('mykey', 'myvalue')
.then(console.log)
.catch(console.log)

If you want to use some promise library, you need to provide factory function:

.. code-block:: javascript

var redis = require('promise-redis')(function(resolver) {
// do something here that provides a way to create new promise.
});

See below for examples of integration with some well-known promise libraries.

Q
===

Integration with Q_ is easy. Just use Q.Promise as a factory function.

.. code-block:: javascript

var promiseFactory = require("q").Promise,
redis = require('promise-redis')(promiseFactory);

// redis is the usual node_redis object. Do what you usually do with it:
var client = redis.createClient();
client.on("error", function (err) {
console.log("uh oh", err);
});

// All your redis commands return promises now.
client.set('mykey', 'myvalue')
.then(console.log)
.catch(console.log)

// Callback style code is still supported. This can be useful if some of
// old code still relies on callbacks.
client.hmset('myotherkey', {'one': 1, 'two': 2}, function (err, value) {
if (err) {
return console.log("Error: ", err.message);
}
console.log(value);
});

when
====

Integration with when_ is easy as well. Just use when.promise as a factory
function:

.. code-block:: javascript

var promiseFactory = require("when").promise,
redis = require('promise-redis')(promiseFactory);

// redis is the usual node_redis object. Do what you usually do with it:
var client = redis.createClient();
client.on("error", function (err) {
console.log("uh oh", err);
});

// All your redis commands return promises now.
client.set('mykey', 'myvalue')
.then(console.log)
.catch(console.log)

// Callback style code is still supported. This can be useful if some of
// old code still relies on callbacks.
client.hmset('myotherkey', {'one': 1, 'two': 2}, function (err, value) {
if (err) {
return console.log("Error: ", err.message);
}
console.log(value);
});

Bluebird
========

Bluebird_ is a bit different, but still nothing special:

.. code-block:: javascript

var Promise = require("bluebird"),
redis = require('promise-redis')(function(resolver) {
return new Promise(resolver);
});

// redis is the usual node_redis object. Do what you usually do with it:
var client = redis.createClient();
client.on("error", function (err) {
console.log("uh oh", err);
});

// All your redis commands return promises now.
client.set('mykey', 'myvalue')
.then(console.log)
.catch(console.log)

// Callback style code is still supported. This can be useful if some of
// old code still relies on callbacks.
client.hmset('myotherkey', {'one': 1, 'two': 2}, function (err, value) {
if (err) {
return console.log("Error: ", err.message);
}
console.log(value);
});

Other libraries
===============

Pull requests that demonstrate how other libraries can be integrated are
welcome.


Examples
--------

Here is a copy-and-paste example from "Usage" section of node_redis
documentation_. The example is silly and doesn't demonstrate any advantages of
promises. I use when_ library here, but as you already know it really doesn't
matter:

.. code-block:: javascript

var promiseFactory = require("when").promise,
redis = require("promise-redis")(promiseFactory),
client = redis.createClient();

// if you'd like to select database 3, instead of 0 (default), call
client.select(3).then(function() {
console.log("Selected database 3");
});

client.on("error", function (err) {
console.log("Error " + err);
});

client.set("string key", "string val").then(console.log);
client.hset("hash key", "hashtest 1", "some value").then(console.log);
client.hset(["hash key", "hashtest 2", "some other value"]).then(console.log);
client.hkeys("hash key").then(function (replies) {
console.log(replies.length + " replies:");
replies.forEach(function (reply, i) {
console.log(" " + i + ": " + reply);
});
client.quit();
});

And finally here is an example of using client.multi (it is also from
node_redis_ docs):

.. code-block:: javascript

var promiseFactory = require("when").promise,
redis = require("promise-redis")(promiseFactory),
client = redis.createClient();

client.sadd("bigset", "a member");
client.sadd("bigset", "another member");

while (set_size > 0) {
client.sadd("bigset", "member " + set_size);
set_size -= 1;
}

// multi chain
client.multi()
.scard("bigset")
.smembers("bigset")
.keys("*")
.dbsize()
.exec()
.then(function (replies) {
console.log("MULTI got " + replies.length + " replies");
replies.forEach(function (reply, index) {
console.log("Reply " + index + ": " + reply.toString());
});
});

client.multi is a constructor that returns an object, which you can use to
chain (queue) multiple redis commands together. All commands, but exec,
that you issue on Multi don't start any I/O. But when exec command is
issued, all queued operations are executed atomically. exec returns a
promise.

.. _node_redis: https://github.com/mranney/node_redis
.. _node_redis documentation: https://github.com/mranney/node_redis#redis---a-nodejs-redis-client
.. _Q: https://github.com/kriskowal/q/
.. _when: https://github.com/cujojs/when
.. _Bluebird: https://github.com/petkaantonov/bluebird
.. _native JavaScript Promise`: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise