Futures for node.js
Futures for node.js
This is inspired by the read of : Currying the callback, or the essence of futures… and Callbacks are imperative, promises are functional: Node’s biggest missed opportunity.
npm install futuristic
Here, a future represents a computation that is yet to be performed.
As such a future simply encapsulates a function that takes one argument, a callback,
which is fired when the computation ended.
The callback must be called with two arguments, usually noted
that denote the result of the computation.
var// ...;doSomethingAsyncv1 v2if errhandleerr;else// ...;
Defining a future, that would become:
var// ... compute a future ...return res;;doSomethingif errhandleerr;else// ...;
reason about what object we expect to receive or pass to functions.
For instance, we could say that the function
varif strlength === 0return ''elsereturn str0
has the type
String -> String.
A future that computes a value of type
a has the type
First, load futuristic:
var futuristic = require'futuristic';var Future = futuristicFuture;// log will be used to display futuresvar log = Future.log;
Creates a future that returns
var a = 'Hello World';acalllog'My first future';
Creates a future that fails with
error as its error value.
var b = Futurefail'Oh no!';bcalllog'My first failure';
Creates a callback that can be used to check futures.
f is an asynchronous function that fires a callback with
err as arguments,
it creates a function that creates a future with the same functionality.
var fs = require'fs';var readFile = FuturefuturizefsreadFile;readFile'/path/to/a/file'calllog
f is an asynchronous function that takes only a callback as an argument,
it creates a future from it.
var two = FuturecreateprocessnextTickcallbacknull 2;;;twocalllog;
varreturn x+1;;var one = 1;var two = onebindincr;var err = Futurefail'error';var incrErr = errbindincr;twocalllog'two!';incrErrcalllog'err';
f is of type
a -> Future b and
this is of type
it returns a future of type
Future b that computes the result
f applied to the future value of
this results in an error,
f is ignored and the error is passed along.
This is like
bind, but the function now takes two arguments and is invoked in all cases, not only when
varif errif err instanceof TypeErrorreturn 0;elsereturn Futurefailerr;elsereturn res*res;;var a = 3;var b = Futurefail'b';var c = Futurefail'c';abind2fcalllog'a';bbind2fcalllog'b';cbind2fcalllog'c';
then is like using
bind2, but now you can give two separate functions.
If one of the arguments is not a function, it is replace by one that will just pass the value.
The example for
bind2 can be rewritten as:
varreturn x*x;;varif err instanceof TypeErrorreturn 0;elsereturn Futurefailerr;;var a = 3;var b = Futurefail'b';var c = Futurefail'c';athenf1 f2calllog'1. a';bthenf1 f2calllog'1. b';cthenf1 f2calllog'1. c';athenf1calllog'2. a';bthenf1calllog'2. b';cthenf1calllog'2. c';athennull f2calllog'3. a';bthennull f2calllog'3. b';cthennull f2calllog'3. c';athencalllog'4. a';bthencalllog'4. b';cthencalllog'4. c';
Creates a future that will wait
millis milliseconds before passing the value it received.
this fails, it will not wait though.
var a = 1delay200;var b = Futurefail'error'delay300;acalllog'a';bcalllog'b';
Creates a future that will give only
millis milliseconds for
this to complete.
error is specified, then it will be used as the error value.
var a = 1delay300timeout200 'too long';var b = 2delay300timeout500;var c = 3delay300timeout500delay300;acalllog'a';bcalllog'b';ccalllog'c';
Creates a future that waits for all futures to succeed and pass all the values. If one of the futures fails, this will fail too.
var a = 1delay300;var b = 2delay200;var c = 3delay700timeout100;Futurealla bcalllog'a & b';Futurealla b ccalllog'a & b & c';Futureallcalllog'nothing?';
Creates a future that waits for all futures to succeed or fail and pass all the results. If will never fail.
var a = 1delay300;var b = 2delay200;var c = 3delay700timeout100;FuturewaitForAlla bcalllog'a & b';FuturewaitForAlla b ccalllog'a & b & c';FuturewaitForAllcalllog'nothing?';
This is like
bind, but to use after
all to pass the values as arguments to
varreturn x + y;var a = 1delay300;var b = 2delay200;var c = 3delay700timeout100;Futurealla bspreadaddcalllog'a + b';Futurealla cspreadaddcalllog'a + c';
It can be used with multi-valued functions also.
Creates a future that will pass the value of the first future that succeeds. Fails if empty argument list or all futures fail.
var a = 1delay300;var b = 2delay200;var c = 3delay700timeout100;Futureanya b ccalllog'a | b | c';Futureanya ccalllog'a | c';Futureanyccalllog'c';Futureanycalllog'nothing?';
Creates a future that will pass the value of the first future that completes, wether it succeeds or fails.
var a = 1delay300;var b = 2delay200;var c = 3delay700timeout100;Futurefirsta b ccalllog'a | b | c';Futurefirsta bcalllog'a | b';Futurefirstcalllog'nothing?';
MIT (See LICENCE file)