redispade

Spade, a Redis Client

npm install redispade
12 downloads in the last week
13 downloads in the last month

Spade

build status NPM version

Spade is a Redis 2.x Client for nodeJS.

Install

$ npm install redispade [-g]
// clone repo
$ git clone git@github.com:rootslab/redispade.git

Install / Update dependencies and devDendencies

 $ cd redispade/
 $ npm install --dev
 # update
 $ npm update --dev

require:

var Spade  = require( 'redispade' );

Run Tests

 $ cd redispade/
 $ npm test

Tests require that:

  • Vows was installed.
  • the Redis Server was installed on the local machine,
  • a '/tmp' ( not Windows friendly ) dir exists, for running Redis Server processes.
  • port range 50xxx was available.

Constructor

Create an instance.

Spade( [ Object opt ] ) : Spade;
// or
new Spade( [ Object opt ] ) : Spade;

Options

Create an instance optionally with a configuration object.

See Usage section below for all configuration options.

Connection:

// connect to Redis Server
Spade#connect( [ Object socketOptions ] ) : undefined

// end the client connection, closing the underlying socket
Spade#end() : undefined

Sending commands:

/*
 * send a Redis Command through a client method shortcut,
 * like ping, eval, etc..
 * see lib/mixins/commands to check the exact command signature.
 * see "Simple Usage" section below for callback signatures.
 */
Spade#{RCMD}( String key, Object blob [, Function cback ] ) : undefined

// send a raw command
Spade#cmd( String command, String key, Object blob [, Function cback ] ) : undefined
Logs, Events, Errors:
// log and emit an event
Spade#lemit( .. ) : undefined

// change debug logging ar runtime, see options.debug below
Spade#serviceLog( Object debugOptions ) : undefined

// throw an Error
Spade#throwError( Object cmd, String msg ) : undefined;
Load Commands Mixins at Runtime:
/*
 * load commands mixins from a dir path relative to lib/ directory.
 * it expects to find an index.js file that exports an array 
 * of commands mixins objects ( like './mixins/commands' ).
 * See lib/mixins/commands/index.js for an example.
 * If an error occurs, the error object was passed to callback
 * as the first argument.
 */
Spade#loadCommands( path, cback ) : null
Cloning:
// clone a client to a new instance with the same configuration
Spade#clone() : Spade

Properties

TODO

Events

TODO


Usage

var log = console.log,
    Spade = require( 'redispade' ),
    client = new Spade( {
        debug : {
            // see spade.js for all config options and methods
            level : 2,
            // used for file logging
            path : null,
            size : 1024 * 1024
        },
        socket : {
            /* default values for Cocker/socket configuration */
            port : 6379,
            host : 'localhost',
            // 'ascii', 'utf8', 'utf16le' ('ucs2'), 'ascii', or 'hex'.
            encoding : null,
            // true, or initialDelay in ms
            keepAlive : true,
            // millis to emit timeout event
            timeout : 2000,
            /*
             * True for disabling the Nagle algorithm, then
             * no TCP data buffering for socket.write, like 
             * Redis needs.
             */
            noDelay : true,
            // unix socket domain file descriptor - path
            fd : undefined,
            // 'tcp4', 'tcp6', or 'unix'
            type : null,
            /*
             * By setting allowHalfOpen = true, the socket will not
             * automatically end()s its side, allowing the user to write
             * arbitrary amounts of data, with the caveat that the user is
             * required to end() his side now.
             */
            allowHalfOpen : false,
            // logging to console
            debug : false
            // try 3 times before quitting
            attempts : 3,
            // millis, default to 1 sec
            retryInterval : 1000,
            // interval between retries is calculated also with this value
            retryFactor : ( Math.sqrt( 5 ) + 1 ) / 2
            }
        } );

log( '\nSpade client was instantiated with this configuration object:\n', client.options, '\n' );

// some events

// client is connected to Redis server instance
// address is the result of a Socket.address() call
client.on( 'online', function ( address ) {} );

// client is ready to send commands
// address is the result of a Socket.address() call
client.on( 'ready', function ( address ) {} );
    client.ping( function ( r, e, d ) {
        /*
         * 'r' stands for request object.
         * 'e' stands for error boolean, it signals 
         *     an -ERR reply, not a execution error.
         * 'd' stands for data buffer.
         */
    } );
} );

// client is offline
client.on( 'offline', function () {} );

// socket connection timeout, it is used to notify that the socket has been idle.
client.on( 'timeout', function () {} );

// connection is definitely lost ( after X retries )
client.on( 'lost', function () {} );

// info events
client.on( 'info', function ( msg ) {} );
client.on( 'warning', function ( msg ) {} );

// it signals to slow down the data stream, socket is buffering data stream in memory
// it's the socket 'drain' event bubbled up
client.on( 'orangelight', function ( readyState, currentBufferSize ) {} );

// it's safe to write to socket stream ( it's the socket/cocker 'drain' event bubbled up )
client.on( 'greenlight', function () {} );

// it signals a socket/cocker error
client.on( 'redlight', function ( err ) {} );

// it signals an unrecoverable runtime error
client.on( 'crash', function ( cmd, msg ) {} );

// on pub/sub mode client receives 'message' event on every message published to a subscribed channel
client.on( 'message', function ( payload ) {
    /* payload is an object like :
     * {
     *  type : 'pmessage' or 'message'
     *  pattern : '*' or null,
     *  channel : 'aChannel',
     *  data : 'someData'
     * }
     */
} );

// on monitor mode client receives 'monitor' event on every command that Redis Server receives
client.on( 'monitor', function ( r, e, d ) {
    // 'r' is undefined, 'd' is already a string, not a data Buffer
} );

// connect to Redis Server 
client.connect();

// clone a client to a new instance with the same configuration
client.clone();
npm loves you