README
Σ Syllabus
Σ Syllabus, a collection of helpers mix-ins to encode Redis commands and to decode Redis replies, builded upon Sermone. Moreover, Syllabus mantains a cache for LUA scripts, using the Camphora module. See Syllabus.lua property.
It also uses the Hoar module to handle semantic versioning, then Bolgia and Abaco modules to get some utilities.
NOTE: If you need to handle bindings between Syllabus commands and Redis replies, take a look at ♎ Libra, it uses Train queue under the hood, to get a simple rollback mechanism for commands, and to gain some performances in some particular situations.
NOTE: If you need a full-featured Redis client, built with the help of ♎ Libra and Σ Syllabus modules, try ♠ Spade.
Now 190 Redis commands mix-ins are implemented.
Table of Contents
- Install
- Run Tests
- Run Benchmarks
- Constructor
- Sample Usage
- Properties, Methods
- Syllabus Commands
- MIT License
Install
$ npm install syllabus [-g]
// clone repo
$ git clone git@github.com:rootslab/syllabus.git
require:
var Syllabus = require( 'syllabus' );
Run Tests
$ cd syllabus/
$ npm test
Run Benchmarks
$ cd syllabus/
$ npm run bench
Constructor
Create an instance. Optionally it is possible to:
- enable development / informational mode, with a boolean.
- enable development mode and restrict commands available for a particular Redis version, passing a Semver string like "1.0.0".
var s = Syllabus( [ Boolean develop | String semver ] )
Sample Usage
Create a normal syllabus, then some syllabus in development mode.
var log = console.log
// production use
, syll = Syllabus()
// enable development mode
, full = Syllabus( true )
, recent = Syllabus( '2.6.0' )
, old = Syllabus( '2.4.0' )
, ancient = Syllabus( '1.0.0' )
;
log( full.size() );
log( recent.size() );
log( old.size() );
log( ancient.size() );
See examples.
Properties, Methods
Arguments within [ ] are optional.
Syllabus : {
/*
* A collection of Redis commands mix-ins.
*/
commands : { .. }
/*
* Redis commands categories/keywords.
*/
, types : { .. }
/*
* Use raw encoding for commands.
* It accepts 4 different signatures.
* See Sermone#encode.
*/
, encode : Function
/*
* Wrap all Syllabus commands with a function that gets
* as argument the result object from the command encoding.
*
* NOTE: It is useful to automatically enqueue or write
* an encoded command to a socket.
* See usage example in Spade code: https://github.com/rootslab/spade
*/
, wrap : function ( Function wrapper ) : Boolean
lua : {
/*
* The current initialized cache object/hash for LUA scripts,
* a Camphora instance.
*
* NOTE: This property will remain hidden/empty until you call
* the #init method to explicitly show the LUA cache for scripts.
*/
cache : null | Camphora
/*
* Initiliazing LUA script cache. Load all the files
* found in the './lib/lua/scripts' directory, into the
* cache; then encode all SCRIPT LOAD commands with
* resulting data from files.
* Optionally you could pass a config hash, as the last
* argument, to create a new cache instance.
*
* - All script files are loaded in the local cache, a list
* of SCRIPT LOAD encoded commands will be passed to this
* callback.
*
* 'onCacheLoaded' : function ( Array commands )
*
* - This callback will be executed after that the script file
* will be loaded into the local cache and successfully
* processed by Redis.
*
* 'onFileProcessed' : function ( Boolean is_err_reply, String scr_name, String scr_digest, String scr_txt, Boolean isLast )
*
* Syllabus default options are:
*
* 'cache_init_opt' : (default cache is pre-initialized with this options)
* {
* capacity : 128
* , encrypt_keys : false
* , algorithm : 'sha1'
* , input_encoding : 'binary'
* , output_encoding : 'hex'
* }
*
* See Camphora constructor options at https://github.com/rootslab/camphora#options.
*
* 'file_load_opt' :
* {
* // set encoding to utf8
* encoding : 'utf8'
* , flag : 'r'
* , payload : true
* , filepath : __dirname + '/scripts'
* }
*
* See Camphora#load options at https://github.com/rootslab/camphora#methods.
*/
, init : function ( Function onCacheLoaded, Function onFileProcessed [, Object file_load_opt [, Object cache_init_opt] ] ) : undefined
/*
* SCRIPT commands shortcuts that updating the cache.
*/
, script : {
/*
* Flush Syllabus.lua.cache. 'fback' function will be called with the number
* of elements flushed from the cache.
* It returns encoded "SCRIPT FLUSH" command for Redis.
*/
flush : function ( [ Function cback [, Function fback ] ] ) : Object
/*
* Load a key/script into the cache.
* 'lback' function will be called with an argument that represents the entry
* loaded in the cache, or undefined if an error occurs.
* It returns encoded "SCRIPT LOAD data" command for Redis.
*/
, load : function ( String key, String data [, Function cback [, Function lback ] ] ) : Object
/*
* Run a LUA script from the cache using its key/name.
* It returns encoded "EVALSHA digest" command.
*/
, run : function ( String sname, Array keys, Array args [, Function cback ] ) : Object
}
/*
* Wrap Syllabus.lua.scripts commands with a function that gets
* as argument the result object from the command encoding.
*
* NOTE: It is useful to automatically enqueue or write
* an encoded command to a socket.
* See usage example in Spade code: https//github.com/rootslab/spade
*/
, wrap: function ( fn ) : Boolean
/*
* an hash of utilities to format special replies.
*/
, formatters: {
/*
* format/convert a string like:
*
* - 'monitor 1404871788.612598 [0 127.0.0.1:35604] "ping"'
*
* to an object/hash:
*
* {
* ip: '127.0.0.1',
* port: 47573,
* db: 0,
* cmd: '"ping"',
* utime: 1405478664248,
* time: [ 1405478664, 248185 ]
* }
*
*/
monitor : function ( String message ) : Object
/*
* Format/convert a pubsub message to an object.
*
* NOTE: the 'formatter' function converts an Array like:
*
* - [ unsubscribe, 'channel', 0 ]
*
* to an object/hash:
*
* {
* type : 'unsubscribe'
* , chan : 'channel'
* . subs : 0
* }
*
* - [ 'message', 'channel', 'Hello folks!' ]
*
* to an object/hash:
*
* {
* type : 'message'
* , chan : 'channel'
* . msg : 'Hello folks!!'
* }
*/
, message : function ( Array message ) : Object
}
}
/* NOTE: methods below exist only in develop mode. */
/*
* Get some infos about a command.
*
* Example: Syllabus.info( 'PiNg' );
*
* Output is:
*
* {
* req: 'PiNg',
* name: 'ping',
* args: 0,
* type: 'connection',
* cmd: 'PING',
* sub: [],
* url: 'http://redis.io/commands/ping'
* rtype: '+|$|*',
* since: '1.0.0',
* hint: 'PING',
* descr: 'Ping the server.'
* }
*
* NOTE:
*
* - 'name' is the mix-in method name.
*
* - 'args' refers to the number of arguments expected by the command
* mix-in method, not by the original Redis command.
*
* - 'sub' collects command direct child(ren) for commands like:
* OBJECT REFCOUNT, PUBSUB CHANNELS, etc..
*
* - 'hint' is the Redis command infos, not the signature of mix-in method.
*
* - 'since' indicates the Redis version from which the command is available.
*
* - 'rtype' is the reply type expected from Redis, when the command will
* be write to socket.
* Redis reply types are:
* - ':' or integer reply.
* - '+' or simple string reply.
* - '