chainit3
Turn an asynchronous JavaScript api into an asynchronous chainable JavaScript api.
This is a fork of chainit, with more work into getting a well-defined behavior of the transformation.
usage
{}MyApiprototype {}MyApiprototype {} var chainit = ;var MyChainApi = ;var obj = ;obj // 1st call // 2nd call ; // 5th call
Adding or overriding methods
Adding and overriding methods works at both prototype level and instance level.
You must use chainit.add(chain, methodName, method)
, since direct assignations
won't wrap your method properly.
{}MyApiprototype {}MyApiprototype {} var chainit = ;var MyChainApi = ; var obj = ; // override instance methodchainit; obj // calls the newly added method1 ; // revert original methodchainit; // override prototype methodchainit; var obj2 = ; obj2; // calls the newly chained prototype `method1`
Like a state machine
It is also possible to have a custom function called immediately, in addition to the function that is queued:
chainit;chainit; // this worksobj // okobj;
The first function is pushed to the queue, the second function is called immediately.
The second function can set this.chainState = someObject
and the queued
function will be able to access that object.
this.chainState
reference is copied to the next queued (and immediate if any)
functions: this behavior allows queued functions to get information about
which functions were queued before or after them.
error handling
Upon error, execution is stopped and the nearest callback is called, or the error is thrown:
obj ;
Uncaught errors are also caught and handled the same way - which adds some safety to the original API.
variable length arguments
Methods that have a variable number of arguments require special handling. It is advised to define those methods with the smallest number of required arguments:
{ var opts = {}; if typeof cb != "function" opts = cb; cb = arguments2; // ...}
This automatically excludes the case where the function can accept (uri, myfun, cb) with myfun as an optional argument. This is actually a good thing because it prevents undefined behavior.
features
Features:
- supports async apis
- supports (crazy) nested calls
- supports static and prototype methods
- preserves nested calls order
- preserves context in cb()
- preserves cb(args)
- stops execution on error
- propagates error to the nearest callback
- throws error if no callback can handle it
- supports method(fun, cb) signatures
- supports process.nextTick(cb)
- supports setTimeout(cb)
- supports methods redifinition
- supports adding new methods
- fully tested! local:
npm install -g mocha && mocha
, saucelabs:npm test
mixing async/sync apis
There is no easy way to mix sync/async chainable apis because there is no way to differenciate sync/async calls.
obj
We cannot know that syncMethod is synchronous and that we do not need to wait for a callback to be called to continue.
Either your api is fully asynchronous and every method takes a callback.
Either your api is fully synchronous.
If you want synchronous support, make a pull request
adding chainit.sync(Constructor)
.
credits
This module is using jessetane/queue.
A chainable api is queueing methods and reordering calls, so we use a queue.
This module was built to replace the chainable api from webdriverjs.
It is now used by more modules and is maintained with general use in mind now.