[Home] FuturesJS - Promises, Subscriptions, Joins, etc for JavaScript Part 1

What is FuturesJS?


FuturesJS is a JavaScript library which (when used as directed) simplifies handling Callbacks, Errbacks, Promises, Subscriptions, Joins, Synchronization of asynchronous data, and Eventually Consistent data. It is akin to this well documented this MSDN library, but with a liberal MIT license.


What is a Promise?


A promise (as per Douglas Crockford) is (essentially) a chainable callback object with the following methods:
Chainable means that the object returns itself so these methods can be called in sequence. A normal callback function might look like this:

result = getAsyncData(arg1, arg2, callback, {onError : errback, setTimeout : 5000});

To use a promise with such a function you would do something like this:

var p = Futures.promise();

result = getAsyncData(arg1, arg2, p.fulfill, {onError : p.fail, setTimeout : 5000});
p.when(callback1)
.when(callback2)
.when(callback3)
.fail(callback4);
But you can also "promisify" a function in a number of ways: A) return an object with the when() and fail() methods

function getAsyncData(param1, param2) {

var p = Futures.promise(),
result = oldGetAsyncData(arg1, arg2, p.fulfill, {onError : p.smash, setTimeout : 5000});
// Implements a synchronous callback to hand back the original data
p.withResult = function(func) {
func(result); // XMLHTTPRequest object is the result in this case
}
return p;
}
var xhr;
getAsyncData(param1, param2)
.withResult(function (r) {
xhr = r;
})
.when(doStuff)
.when(doMoreStuff)
.fail(undoStuff);
if (i_change_my_mind) {
xhr.abort();
}
B) allow a promise to be passed instead of a callback or returned with a synchronous callback.

function getAsyncData(param1, param2, p) {

return oldGetAsyncData(arg1, arg2, p.fulfill, {onError : p.smash, setTimeout : 5000});
}
var promise = Futures.promise(),
xhr;
xhr = getAsyncData(param1, param2, promise);
promise
.when(doStuff)
.when(doMoreStuff)
.fail(undoStuff);
if (i_change_my_mind) {
xhr.abort();
}
C) pass back a promise as a synchronous callback

function getAsyncData(param1, param2, promiseback) {

var p = Futures.promise();
return oldGetAsyncData(arg1, arg2, p.fulfill, {onError : p.smash, setTimeout : 5000});
}
var promise,
xhr;
xhr = getAsyncData(param1, param2, function (p) {
promise = p;
});
promise
.when(doStuff)
.when(doMoreStuff)
.fail(undoStuff);
if (i_change_my_mind) {
xhr.abort();
}
Where many functions allow only one callback, a promise allows you to enlist multiple callbacks before and after the target function has been called. FuturesJS provides convenience functions for you to wrap existing functions via promisify() (method A) and noConflict() (method C).

What are Joins?

A join is a special type of promise which allows you to get the results of multiple promises once all of them have completed or failed.

// Futures.join(p1, p2, p3, ..., pN)

Futures.join(p1, p2, p3) // There is no limit to how many promises you pass in
.when(function (p_arr) {
// p_arr[0] is the result of p1
// p_arr[N-1] is the result of pN
})
.fail(function (p_arr) {
// at least one of the promises was smashed
// you'll have to discover which on your own
});

Recap: Why is this useful?

I have two main use cases:
If you're lucky I'll write some psuedo-code for these examples in Part 2.

Hang around and I'll explain more about subscriptions and other fun stuff.
blog comments powered by Disqus Updated at