♎ Libra, a module to handle bindings between commands and Redis replies. Moreover, it implements an automatic rollback mechanism for subscriptions.
npm install libra
!NODE VERSION
!NPM YEARLY
!NPM TOTAL
> _♎ Libra_, a module to handle bindings between commands and __Redis__ replies. Morover, it implements an __automatic rollback mechanism__ for subscriptions. It is heavily based on __Train__ module, a __well-tested__ and fast __FIFO__ queue.
> __NOTE__: It accepts only commands generated/encoded by __Syllabus__.
``bash`
$ npm install libra [-g]
// clone repo
$ git clone git@github.com:rootslab/libra.git
> __install and update devDependencies__:
`bash`
$ cd libra/
$ npm install
# update
$ npm update
> __require__
`javascript`
var Libra = require( 'libra' );
> See examples.
`bash`
$ cd libra/
$ npm test
`bash`
$ cd libra/
$ npm run bench
> __NOTE__: You should install _devDependencies_ (_Syllabus_) for running benchmarks.
> Create an instance, argument within [ ] is optional.
`javascript`
var l = Libra( [ opt ] )
// or
var l = new Libra( [ opt ] )
#### Options
> Default options are listed.
`javascript`
opt = {
// rollback queue max size ( for Train )
rollback : 64 * 1024
// log the last access time to the queue's head
, timestamps : false
}
> __WARNING__: Don't mess with these properties.
`javascript
// command queue
Libra.cqueue : Train
// status properties
Libra.status : {
subscription : {
on : 0
, active : 0
, channels : 0
, patterns : 0
}
, transaction : {
on : 0
, active : 0
}
, monitoring : {
on : 0
, active : 0
}
// it holds special AUTH command
, auth : []
// it holds special SELECT command
, select : []
// timestamp for the last message received
, last_update : 0
}
`
> __NOTE__: to avoid messy conditions Libra doesnt't allow:
> - to send subscription commands inside transactions ( a MULTI cmd was previuosly queued ).
> - to push commands in monitoring mode ( a MONITOR cmd was previuosly queued ), only QUIT command is allowed.
> Arguments within [ ] are optional.
`javascript
/*
* Update the current auth status property. In this way the AUTH command
* has priority over the other commands in the queue; when #pop() will be
* called, it will return this command regardless if the command queue is
* empty or not.
*
* It returns the current auth status property ( encoded AUTH command ).
*
* NOTE: only Syllabus AUTH command will be accepted and stored.
*/
Libra#auth( Object syllabus_auth_command ) : Object
/*
* Update the current select status property. In this way the SELECT command
* has priority over the other commands in the queue (after AUTH); when #pop()
* will be called, it will return this command regardless if the command queue
* is empty or not.
*
* It returns the current select status property ( encoded SELECT command ).
*
* NOTE: only Syllabus SELECT command will be accepted and stored.
*/
Libra#select( Object syllabus_select_command ) : Object
/*
* Update internal subscription status ( using a un/subscription reply ), passing the command and
* the number of current subscribed channels, received as message reply. It returns the total number
* of subscribed channels and patterns.
*
* Examples: Libra#update( 'subscribe', 5 ) or Libra#update( 'unsubscribe', 3 )
*
* NOTE: Except for subscription commands, QUIT is the only command accepted in pubsub mode.
*/
Libra#update( subscription_command_reply [, channels_number ] ) : Number
/*
* Get the total number of channels/patterns in status.subscriptions
*/
Libra#subs() : Libra
/*
* Push a Syllabus command to the internal queue.
* It returns the number of command objects currently in the queue, or -1
* if the command wasn't allowed/pushed.
*
* NOTE: only Syllabus commands are accepted.
*/
Libra#push( Object syllabus_command ) : Number
/*
* Pop a Syllabus command from the internal queue.
* It pops the current head of the command queue.
*/
Libra#pop() : Object
/*
* Get a element in the command queue without popping it.
* The default position is 0.
*/
Libra#head( [ Number pos ] ) : Object
/*
* Start rolling up.
* From now, all items evicted from the queue could be restored, executing #rollBack().
* Disable rollUp passing false.
* It returns the current Libra instance.
*/
Libra#rollUp( [ Boolean on ] ) : Libra
/*
* Do rollback; previously evicted items are restored to the head of queue.
* Optionally, it is possible to re-enable rollUp mechanism after the rollBack,
* passing true.
* It returns the current Libra instance.
*
* NOTE: no rollBack will be done if rollUp was not already activated.
*/
Libra#rollBack( [ Boolean on ] ) : Libra
/*
* Apply a fn to every element of the internal command queue;
* fn will get 3 arguments: Object element, Number index, Function done.
* After that every fn will have called done(), the callback will be launched
* with an err argument ( if any has occurred ) and a number, representing
* the total processed / iterated elements in the queue.
*
* If boolean "evict" was set to true, after the last fn call to done(),
* the queue will be flushed.
*
* NOTE: when queue size is 0, the callback will be immediately executed
* with arguments: ( null, 0 ).
*
* NOTE: on iteration, the size is fixed to the current queue size,
* then it is possible to push other elements to the tail, these
* added elements are not affected by iteration.
*/
Libra#iterate( Function fn [, Object scope [, Function cback [, Boolean evict ] ] ] ) : Libra
/*
* Flush the internal queue, reset all internal status properties,
* then disable rollback mechanism.
* It returns the current Libra instance.
*/
Libra#flush() : Libra
/*
* Reset all internal status properties, then disable rollback mechanism.
* It returns the current Libra instance.
*/
Libra#reset() : Libra
``
------------------------------------------------------------------------
> Copyright (c) 2013-present < Guglielmo Ferri : 44gatti@gmail.com >
> Permission is hereby granted, free of charge, to any person obtaining
> a copy of this software and associated documentation files (the
> 'Software'), to deal in the Software without restriction, including
> without limitation the rights to use, copy, modify, merge, publish,
> distribute, sublicense, and/or sell copies of the Software, and to
> permit persons to whom the Software is furnished to do so, subject to
> the following conditions:
> __The above copyright notice and this permission notice shall be
> included in all copies or substantial portions of the Software.__
> THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.