roseredis

Easy to use abstraction layer for node_redis

Installation

npm install roseredis --save

Usage Example

var rose = require('roseredis');
var roseClient = rose.createClient();

var redisKey = {
  foo: 'fooKey',
  bar: 'barKey'
};

var commands = {
  setFoo:
  function(value) {
    return ['set',redisKey.foo,value];
  },
  getFoo:
  function() {
    return {
      command: ['get',redisKey.foo],
      handler: function(reply, result) {
        return result.foo = reply;
      }
    };
  },
  setBar:
  function(value) {
    return ['set',redisKey.bar,value];
  },
  getBar:
  function() {
    return {
      command: ['get',redisKey.bar],
      handler: function(reply, result) {
        result.bar = parseInt(reply) || 0;
      }
    };
  },
};

roseClient.registerCommands(commands);

roseClient.multi()
  .setFoo('Foo is set to this')
  .setBar(123456)
  .getFoo()
  .getBar()
  .exec()
  .then(function(result) {
    console.log(result.foo);
    // Foo is set to this
    console.log(result.bar, typeof result.bar);
    // 123456 'number'
  });

Creating the client

A rose client can be created by calling rose.createClient()

var rose = require('roseredis');
var roseClient = rose.createClient();

If you already have a redis client configured, you may pass this in.

var rose = require('roseredis');

var redis = require('redis');
var redisClient = redis.createClient();

// Configure your redisClient here

var roseClient = rose.createClient(redisClient);

Once the rose client has been created, you may access it's redisClient at anytime from roseClient.redisClient

roseClient.redisClient.quit();
// This will disconnect from the redis server

Full documentation of node_redis can be found here:
https://github.com/NodeRedis/node_redis#readme

Client clones

You may clone the client using client.createClient().
Commands registered in the clone will not affect the scope of the parent client.
Commands registered to the parent after the clone has been created will not affect the clone's scope.

roseClient.registerCommand('commandA', function(){});

var cloneClient = roseClient.createClient();

cloneClient.registerCommand('commandB', function(){});

roseClient.registerCommand('commandC', function(){});

console.log( typeof roseClient.commandA ); // function
console.log( typeof roseClient.commandB ); // undefined
console.log( typeof roseClient.commandC ); // function

console.log( typeof cloneClient.commandA ); // function
console.log( typeof cloneClient.commandB ); // function
console.log( typeof cloneClient.commandC ); // undefined

Creating commands

Rose commands are methods that return a redis command array and optional reply handler.

function getFoo() {
  return {
    command: ['get', 'fooKey'],
    handler: function(reply, result) {
      result.foo = reply;
    }
  };
}

Command is the redis command array.
(This gets the value stored at redis key 'fooKey')

command: ['get', 'fooKey'],

Handler wraps the reply from redis.
reply is the redis response from your command
result is the object that gets returned in the callback

This allows you to give your result values meaningful names, instead of having to keep track of reply indices

handler: function(reply, result) {
  result.foo = reply;
}

You can optionally return just the redis command if you're not doing anything with the redis reply.
(This is common for setters)

function setFoo(value) {
  return ['set', 'fooKey', value];
}

You can use the handler to provide additional formatting of the data, such as parsing values from the reply.

handler: function(reply, result) {
  result.bar = parseInt(reply) || 0;
}

Use result.setKey to set a deeply nested field in the result object.

function getFooBar() {
  return {
    command: ['hget','foo', 'bar'],
    handler: function(reply, result) {
      result.setKey('foo.bar', reply);
    }
  };
}

roseClient.registerCommand('getFooBar', getFooBar);
roseClient.getFooBar(function(err, result) {
  // result.foo.bar will be set to the reply value
});

(See the deepref github page for full documentation of setKey)
https://github.com/isaymatato/deepref

Registering commands

Once created, you'll need to register commands with the rose client.

This can be done one at a time, using client.registerCommand(label, method);

function setFoo(value) {
  return ['set', 'fooKey', value];
}

roseClient.registerCommand('setFoo', setFoo);

Or, more typically, you can use registerCommands to register all the commands defined in an object

var commands = {
  setFoo:
  function(value) {
    return ['set',redisKey.foo,value];
  },
  getFoo:
  function() {
    return {
      command: ['get',redisKey.foo],
      handler: function(reply, result) {
        result.foo = reply;
      }
    };
  }
};
roseClient.registerCommands(commands);

Executing commands

Once registered, you may execute a single command by calling roseClient[commandName]
The command will return a promise.

function setFoo(value) {
  return ['set','foo',value];
}

roseClient.registerCommand('setFoo', setFoo);
roseClient.setFoo(42)
.then(function() {
  // redis key 'foo' will now be set to '42'
});

You may also execute multiple commands using roseClient.multi()

roseClient.multi()
  .setFoo('Foo is set to this')
  .setBar(123456)
  .getFoo()
  .getBar()
  .exec()
  .then(function(result) {
    console.log(result.foo);
    // Foo is set to this
    console.log(result.bar, typeof result.bar);
    // 123456 'number'
  });
  

Tests

npm test

Release Notes

As of version 1.4.0, all async methods return a promise. Callbacks are still supported, though it's recommended you use promises instead. The last argument passed in to any of the async methods will be treated as a callback if it is a function.

roseClient.multi()
  .exec(function(err, result) {
    // This still works but please don't use it
  });

Contributing

Please use the included style guide. If you change anything, please test and add unit tests for any new functionality. If you're fixing a bug, please add a unit test that would have failed before the bug was fixed. Thanks!