Spade

♠ Spade

♠ Spade, a robust, full-featured, multi-module, Redis client:

• It offers the ability to restrict commands to a particular Redis version via the semver constructor option. Specifying this option turns Spade in develop mode, it enables a series of mix-ins to get brief descriptions of every implemented command.
• It implements a simple delayed mechanism for re-connecting to socket when the client connection was not voluntarily interrupted.
• It collects commands in the queue also when the client is offline.
• It implements an automatic command rollback mechanism for subscriptions when connection is lost and becames ready again.
• It implements AUTH logic and automatic db SELECT on socket (re)connection, configurable via the security constructor option.
• It offers automatic LUA scripts caching, using a simple NFU with linear aging eviction algorithm ( NFU stands for Not Frequently Used ).
• It correctly handles multiple (p)(un)subscription commands as we will expect (1 command : multiple replies : multiple callback execution); it was well tested against some weird edge cases. See tests for pubsub.
• It supports the new PING command signature also in PubSub mode.
• It implements a polling mechanism, useful to force automatic re-connection when client hangs while in PubSub mode.
• It facilitates scanning of Redis keyspace, implementing some simple iterators for SCAN/HSCAN/SSCAN/ZSCAN commands. See #loadIterators.

♠ Spade makes use of some well tested modules:

• Σ Syllabus module for command encoding and command helpers mix-ins, it also offers a series of helpers functions to convert a raw data reply in a usable format.

Internally it uses Hoar module to handle Semantic Versioning 2.0, Sermone to encode commands, Abaco and Bolgia modules to get some utilities. Moreover, Syllabus mantains a cache for LUA scripts, using the Camphora module.

• ♎ Libra module to handle bindings between commands which have been sent and relative Redis replies; it handles also commands queue rollbacks with the help of Train module.
• Cocker module to properly handle socket reconnection when the connection is lost.
• Hiboris, a utility module to load hiredis native parser, or to fall back to Boris, a pure js parser module for Redis string protocol; internally Boris uses Peela as command stack.
• Cucu, a tiny module to handle the scheduled execution of repetitive methods/tasks.
• Gerry, a tiny module to handle event logging to console, for debugging and testing purpose.
• Dado, for running tests.
• Vapid, a vacuous Redis implementation, with fully functional PubSub system.

NOTE : If you need a minimal Redis client based on ♠ Spade code, specific for PubSub and Monitor mode try 🂢 Deuces.

Table of Contents

• Install
• Run Tests
• Run Benchmarks
• Constructor
  • Options
• Properties
• Methods
  • #cli
  • #connect
  • #disconnect
  • #initCache
  • #initTasks
    • polling task
  • #loadIterators
  • Redis Commands
  • Command Callback
  • Interactive Mode
  • LUA Cache and SCRIPT Methods
• Events
  • Events Sequence Diagram
  • Error Events
  • Auth Events
  • Select Events
  • Script Cache Events
  • Socket Connection Events
  • PubSub Events
  • Monitor Events
  • Tasks Events
    • polling events
  • Other Debug Events
    • iterators events
• MIT License

---

Install

NOTE: only node engines ">=v0.10.x" are supported.

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

install and update devDependencies:

 $ cd spade/
 $ npm install
 # update
 $ npm update

require

var Spade = require( 'spade' );

See examples.

Run Tests

to run all test files, install devDependecies:

 $ cd spade/
 # install or update devDependecies 
 $ npm install 
 # run tests
 $ npm test

to execute a single test file simply do:

 $ node test/file-name.js

NOTE:

• tests need a running Redis server instance, with default/stock configuration ( port 6379 ).
• for some connection tests you need the Vapid devDependency, a vacuous Redis server module ( port 6380 ).

Run Benchmarks

run benchmarks for spade (fast/tight checks/turtle developer).

 $ cd spade/
 $ npm run bench

run benchmarks for node_redis (faster/loose checks/an army of contributors).

 $ cd spade/
 $ npm install redis
 $ npm run node_redis_bench

run benchmarks for ioredis (slowest/loose checks/unsafe pubsub).

 $ cd spade/
 $ npm install ioredis
 $ npm run ioredis_bench

NOTE:

• benchmarks need a running Redis server instance, with default/stock configuration.
• to switch to the faster hiredis native parser, install devDependencies .

---

Constructor

Create an instance, the argument within [ ] is optional.

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

Options

Default options are listed.

opt = {
    /*
     * Syllabus option to enable develop mode and restrict
     * commands to a particular Redis semantic version.
     * Use:
     * - boolean 'true' or string '*' for all commands available.
     * - semver string to restrict commands ( like '1.0.0' ).
     *
     * NOTE, develop mode enables some utility methods to get command
     * descriptions, like:
     * - Spade.mixins#info( String command ) get cmd infos
     * - Spade.mixins#size() get the current number of commands
     * - Spade.mixins#stick( [ Boolean attach ] ) attach #info to every mix-in.
     *
     * See https://github.com/rootslab/syllabus#properties-methods.
     */
    semver : null

    /*
     * Hiboris option. For default, the loading
     * of 'hiredis' native parser is disabled
     * in favour of ( the slower ) Boris JS parser.
     */
    , hiredis : false

    /*
     * Cocker socket options
     */
    , socket : {
        path : null
        , address : {
            // 'localhost'
            host : '127.0.0.1'
            , port : 6379
            , family : null
        }
        , reconnection : {
            trials : 3
            , interval : 1000
            /*
             * A value to use for calculating the pause between two
             * connection attempts. Default value is the golden ratio.
             * Final value is calculated as:
             * interval * Math.pow( factor, curr.attempts + 1 )
             */
            , factor : ( Math.sqrt( 5 ) + 1 ) / 2
        }
        , connection : {
            /*
             * encoding could be: 'ascii', 'utf8', 'utf16le' or 
             * 'ucs2','buffer'. It defaults to null or 'buffer'.