Chain Commander
Chain commander is a library based on bluebird library, to encapsulate business rules logic in form of javascript objects or JSON.
Since it uses promises, it can keep going until no more "then"s are found, while mutating the value it started with. You can store your commands in JSON or in a POJO (plain old javascript object), and execute them whenever you need, asynchronously, associating them with a context.
You can change the business logic in your database/json definition files, and don't ever have to touch your frontend code, it all depends on the context and your defined functions.
Usage
Install from NPM:
npm install chain-commander
Require it in your node:
var Q = cc = Q;
or browser, after Bluebird:
Business rules
Let's pretend you have a lot of users and each user have their own triggers and conditional, so they can execute their own "code" in your app, like give instructions to your app to execute code in order they are meant to.
Basically, your definitions should not be aware of your object data, but your context functions should.
That means that if your object has an id, a name and some definitions, and if you want your function to
know the id, you should pass your objects to the execute
function or a literal argument.
You can store anything in the the rules, from coordinates, sequence of commands, conditional statements, pairs of data.
The rules are meant to be "non verbose", to be easy to write and adapt, when testing with new rules on the database or json file
for example. It's also meant to feel natural and familiar to javascript (if
and else
, brackets and strings).
They offload the dynamic nature of your applcation to where it belongs: your data. The application code should only be prepared to deal with whatever you throw at it.
var cmds = // It uses arrays because it's the only way it can ensure order. if: // if (obj.check("first") and obj.check("second")) then check: 'check' 'first' // must match all 'check' 'second' // will be executed if obj.check("first") and obj.check("second") returns true // ALL checks can return promises as well exec : 'multiply' 10 // neither checks were present, make another check // "else" works as "if not" else : if : // else if (obj.check("third")) then check: 'check' 'third' // obj.check("third") // will be executed only the obj.check("third") returns true exec : 'alert' msg: 'aww yeah' // alert({msg: "aww yeah"}) // this will be executed regardless of the above if exec: 'add' 1 // execute add(1) 'alert' msg: 'else' // execute alert({msg: "else"}) // exec the alert function exec: 'alert' msg: 'Doodidoo' // exec the startTimer exec: 'startTimer' // go on! new values, it will start executing after 1s from startTimer exec: 'goOn' ;
Given the above object/JSON, you will create a new context that will deal with all the data in order:
var instance = myvalue : 3 { // if in your definition, you call your function with paramters, the last param // (in this case, called "value") will always be the current value in chain if type === 'first' return value > 0; else if type === 'second' return value < 30; return true; } { return thismyvalue === 3; } { return value * number; } { return value + number; } { console; // does nothing, just logs to console return value; } { if !thissecondPass // pay attention that the context is at the moment of the execution thissecondPass = true; // important so it won't create an endless loop return cc; // yes, you can execute the same CC and continue from there, start all over } { var self = this; return { if selfsecondPass === false ; else ; }; } ; cc = ; cc;
The above is a "silly" example (although a long one).
For a full-fledged practical example, check the example
folder, there's a "build your plan with combos and many activities"
type of app created with Chain Commander and AngularJS (do a bower install
inside that folder first)
API
new ChainCommander(definitions: Array|string, options: Object = null)
Creates a new predefined chain that will execute your code when you call execute
var cc = "exec": "oops" ;
When creating a ChainCommander
with the member
function, all executed functions will be passed as the last
parameter the current bound object, like so:
var context = { // value = 0 (from execute) // thisobj = obj } obj = some:'data' defs: "exec": "oops" cc = obj debug: true throws: true member: 'defs'; cc;
ChainCommander.prototype.execute(initialValue: any, context: Object|Function)
Executes your definitions on the given context. Returns a promise.
var cc = "exec": "oops" debug: true throws: true context = { objinitial = 'b'; objvalue++; return obj; } ; cc;
ChainCommander.all(initialValue: any, arr: ChainCommander[], context: Object|Function, tap: Function = void 0)
Taking that you have an array with many Chain Commanders, that you want to execute in order, with the same context returning a promise in the end:
var arrayOfCommanders = defs defs2 defs3; ChainCommanderall'initial value' arrayOfCommanders context;
the arrayOfCommanders also allow an array of array of Commanders, that means, you can use it like this:
{ return arr ;} var arrayOfItemsThatGotCommanders1 = /*...*/; ChainCommanderall'initial value' commanderInstance context;
The optional tap
parameter is a functions that after each item, will be called. It's a side effect
callback and you can use it to "spy" on the current commands being executed
ChainCommanderall'initial value' arrayofcmds context consolelog; // spits out the current value (and the item in the last parameter if you used member)
Debug
The definition and the executing code is "forgiving", it means, if you try to use a function that doesnt exists, it will fail silently and continue in the chain.
You can watch the flow in a verbose mode setting the debug
option to true
var cc = ;
then watch your console. If you want to spot undefined functions or mismatched arguments, set throws
to true
.
Never use any of those in production, since they might generate a lot of unresolved promises.