Monadic function chaining around asynchronously-fulfilled values. Built to be simple and small.
This document assumes a basic familiarity with promises.
A promise can be created with or without a value:
var p1 = promise(); // unfulfilled
var p2 = promise('foobar'); // fulfilled
var p3 = promise(p2); // passes through (p3 === p2)Functions may be chained using then (for non-erroneous values) or except (for erroneous values). Each function will receive the current value as the first parameter, and must return a value in order to continue the chain.
var myPromise = promise();
myPromise.then(function(v) {
return v + 1;
}).then(log);
promise.fulfill(5);
// => logs "6"The current promise is bound to this within the then and except functions. If a function does not return a value, it may later continue the chain by calling this.fulfill or this.reject.
var myPromise = promise();
myPromise.then(function(v) {
var self = this;
setTimeout(function() { self.fulfill(v + 1); }, 1000);
}).then(log);
promise.fulfill(5);
// => logs "6" after a 1-second delayIf an Error type or subtype is returned, the promise will use that to reject.
var myPromise = promise();
myPromise.then(function(v) {
return new Error("Oh noooo");
}).except(log);
promise.fulfill(5);
// => logs "Error: Oh noooo"Extra parameters may be passed to a then or except call:
function add(a, b) { return a + b; }
function subtract(a, b) { return a - b; }
function wait(v, t) { var self = this; setTimeout(function() { self.fulfill(v); }, t); }
function log(v) { console.log(v); }
promise(10)
.then(add, 5)
.then(wait, 1000)
.then(subtract, 10)
.then(log);
// => waits 1 second, then logs "5"Promises may be chained, to allow the fulfillment or rejection of one to be passed on to the other:
var p1 = promise(), p2 = promise();
p2.then(log).except(log);
p1.chain(p2);
p1.fulfill('foobar');
// => logs "foobar"If a promise is not going to continue the chain, and wants to release the references held by downstream promises, it may call cancel:
mypromise
.then(function(canStop) {
if (canStop) {
// program logic says we're done
console.log('stopping');
this.cancel();
} else {
return 'foobar';
}
})
.then(function(v) {
console.log(v);
});
mypromise.fulfill(true);
// => logs "stopping"
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent