PromisePipe - reusable promise chains
PromisePipe allows to build a reusable Promise chains. It returns a function which you can call multiple times and each time all chains will be called. The Function returns a promise each time you call it.
var pipe = ; var result = ; // calls doSmth, doSmthElse and returns a promise// result is a Promise
PromisePipe is built with small core API. It can be extended with custom methods. You can build your domain specific API that describes your business logic.
var saveEventItem =
PromisePipe is a singleton. You build chains of business logic and run the code both on server and client. Chains marked to be executed on the server will be executed on the server only and chains marked to be executed in the client will be executed in the client. You need to set methods in PromisePipe to pass messages from the client to the server. And it is up to you what transport to use.
check simple todo app
and todo with mongodb and session, live on heroku https://promisepipe-todo.herokuapp.com/
install
npm install promise-pipe
Getting Started
The core API mimics api of Promise. So it should be pretty obvious how to use it. Additionally with data
that is returned from previous chain as first argument each function have access to context
object.
var PromisePipe = ; //create a PromisePipe singleton var { // do data transformations // change context return data; //pass data to next chain} var { return { //use Promise for async transformations // do data transformations // change context || };} var { //handle error //change context return err;} var newPipe = ; var context = {};var data = 1; ;
Core API
PromisePipe() : pipe
pipe : Promise
Is a constructed pipe that returns a promise. First argument is a data, second is a context. While data
behaves the same way as in Promises context
is passing thorough whole chain of promises.
var pipe = ;//2 {}//3 {foo:"bar"}//4 {foo:"bar", xyz:"baz"}
pipe.then
.then
adds a simple chain to the pipe
var pipe =
pipe.all
As in Promises you can compose promise pipes
var pipe = all
pipe.catch
The catch is catching error or reject of previous chains. Behaves as Promise catch.
pipe.join
You can join PromisePipes if you like.
var pipe = ; var pipe2 = ; //4
PromisePipe.use(name, handler)
Allows to build your own customized DSL. handler
is a function with at least 2 arguments data and context as in simple chain.
{ //you can return Promise return data;}PromisePipe;
Other arguments arg1, ..., argN
are used to additionally modify the chain behavior. For example we can build smarter log()
method:
var PromisePipe = ; PromisePipe var action = ; // {foo:"baz", bar:"xyz"} <- log()// baz <- log('foo')
Transitions
When the PromisePipe is running on several environments and the execution comes to a chain marked to be executed on other environment PromisePipe tries to pass a message to that environment. To make it work you should describe how to pass the message between environments. Following methods are built for that.
PromisePipe.setEnv
With .setEnv
method you are setting environment for the PromisePipe. All methods marked same as the pipe will be executed only in this environment.
if(typeof(window) !== 'object'){
PromisePipe.setEnv('server');
} else {
PromisePipe.setEnv('client');
}
PromisePipe.in
Creates wrapper that marks chains as executable in specific environment.
var doOnServer = PromisePipevar addItemAction = // will be executed on server // will be executed on server ; // will pass complete chain
PromisePipe.envTransition(from, to, handler)
Setting transition of a message between environments. from
and to
are environments names. For example 'client' and 'server'. handler
is a function that passes the message to other env and returns a PromisePipe.promiseMessage(message)
. PromiseMessage is used to watch the call to be back from server.
PromisePipe
PromisePipe.execTransitionMessage(message)
The message created in PromisePipe.envTransition
comes to another env and must be executed here. When the message is prepared you need to execute it on a PromisePipe. It will resolve what chains it need to execute and will return a Promise that you need to handle and return updated message back to client.
{ PromisePipe;}
On client you would also need to execute the message that comes back:
{ PromisePipe;}
PromisePipe.localContext(context) : PromisePipeWithContext
With serverside you would probably need to have some isolated context like session that should not be accessible on client. You can extend the context for environment. (Usage Eaxmple)
PromisePipeWithContext.execTransitionMessage(message)
The message will be executed with access to additional context.
PromisePipeWithContext.wrap(fn)
The function will be executed with access to additional context.
Connectors
To make connecting different environments easier there is connectors API.
PromisePipe.stream(from, to, Handler).connector(Connector)
This is setting up transitions to use Connector.
Connector is an object that should implement two methods: send
and listen
{ //send message } { //if message comes call handler function with the message object }
There are implemented connectors for SocketIO, HTTP, SocketIO + sessions, Webworkers
Debugging
PromisePipe.setMode
To set up PromisePipe in debug mode you need to call PromisePipe.setMode('DEBUG'). Then in chrome you will be able to see in console values of arguments passed inside each chain within pipe: