promise-redis

Tiny library that adds promise awareness to node_redis

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
promise-redis
0.0.58 years ago8 years agoMinified + gzip package size for promise-redis in KB

Popular Searches

Readme

-------------

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 `noderedis 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.
.. noderedis: https://github.com/mranney/noderedis .. node_redis documentation: https://github.com/mranney/noderedis#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/GlobalObjects/Promise