futuristic
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.
Status
Experimental
Install
npm install futuristic
Futures
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 err
and res
,
that denote the result of the computation.
When we often find this kind of code in javascript:
var { // ...}; ;
Defining a future, that would become:
var { // ... compute a future ... return res;}; ;
Even if javascript has no type system, it can be helpfull to use types to help
reason about what object we expect to receive or pass to functions.
For instance, we could say that the function first
var { if strlength === 0 return '' else return str0 }
has the type String -> String
.
A future that computes a value of type a
has the type Future a
.
API through examples
First, load futuristic:
var futuristic = ;var Future = futuristicFuture;// log will be used to display futuresvar log = Futurelog;
new Future(value)
Creates a future that returns value
.
var a = 'Hello World';a;
Future.fail(error)
Creates a future that fails with error
as its error value.
var b = Future;b;
Future.log(name)
Creates a callback that can be used to check futures.
Future.futurize(f)
If f
is an asynchronous function that fires a callback with res
and err
as arguments,
it creates a function that creates a future with the same functionality.
var fs = ;var readFile = Future;
Future.create(f)
If f
is an asynchronous function that takes only a callback as an argument,
it creates a future from it.
var two = Future;two;
Future#bind(f)
var { return x+1;};var one = 1;var two = one;var err = Future;var incrErr = err;two;incrErr;
If f
is of type a -> Future b
and this
is of type Future a
,
it returns a future of type Future b
that computes the result
of f
applied to the future value of this
.
If this
results in an error, f
is ignored and the error is passed along.
Future#bind2(f)
This is like bind
, but the function now takes two arguments and is invoked in all cases, not only when this
succeeds.
var { if err if err instanceof TypeError return 0; else return Future; else return res*res; };var a = 3;var b = Future;var c = Future;a;b;c;
Future#then([onSuccess[, onError]])
Using 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:
var { return x*x;};var { if err instanceof TypeError return 0; else return Future; };var a = 3;var b = Future;var c = Future;a;b;c; a;b;c; a;b;c; a;b;c;
Future#delay(millis)
Creates a future that will wait millis
milliseconds before passing the value it received.
If this
fails, it will not wait though.
var a = 1;var b = Future;a;b;
Future.timeout(millis[, error])
Creates a future that will give only millis
milliseconds for this
to complete.
If error
is specified, then it will be used as the error value.
var a = 1;var b = 2;var c = 3;a;b;c;
Future.all([futureA[, futureB[, ...]]])
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 = 1;var b = 2;var c = 3;Futurealla b;Futurealla b c;Futureall;
Future.waitForAll([futureA[, futureB[, ...]]])
Creates a future that waits for all futures to succeed or fail and pass all the results. If will never fail.
var a = 1;var b = 2;var c = 3;Future;Future;Future;
Future#spread(f)
This is like bind
, but to use after all
to pass the values as arguments to f
.
var { return x + y;}var a = 1;var b = 2;var c = 3;Futurealla b;Futurealla c;
It can be used with multi-valued functions also.
Future.any([futureA[, futureB[, ...]]])
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 = 1;var b = 2;var c = 3;Future;Future;Future;Future;
Future.first([futureA[, futureB[, ...]]])
Creates a future that will pass the value of the first future that completes, wether it succeeds or fails.
var a = 1;var b = 2;var c = 3;Future;Future;Future;
License
MIT (See LICENCE file)