promise-redis v0.0.5
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 originalnode_redis
object. So for API docs visitnode_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