micropromise
v0.4.10
Published
A+ promises
Downloads
942
Readme
microPromise(uP) - A+ v1.1 compliant promises
- Promise()
- Promise.resolver()
- Promise.thenable()
- Promise.wrap()
- Promise.defer()
- Promise.async()
- Promise.isPending()
- Promise.isFulfilled()
- Promise.isRejected()
- Promise.hasResolved()
- Promise.valueOf()
- Promise.reason()
- Promise.then()
- Promise.spread()
- Promise.done()
- Promise.end()
- Promise.catch()
- Promise.fulfill()
- Promise.reject()
- Promise.resolve()
- Promise.progress()
- Promise.timeout()
- Promise.callback()
- Promise.join()
Promise([mixin]:Object, [resolver]:Function)
Promise constructor
param Object [mixin] - Mixin promise into object
param Function [resolver] - Resolver function(resolve,reject,progress,timeout)
return Object Promise
Promise.resolver(resolver:Function)
Promise resolver
param Function resolver - resolver function(fulfill,reject,progress,timeout)
return Object Promise
Promise.thenable(p:Object)
Helper for identifying a promise-like objects or functions
param Object p - Object or Function to test
return Boolean - Returns true if thenable or else false
Promise.wrap(class:Function, [instance]:Object)
Wrap a promise around function or constructor
- param Function class - class to wrap
- param Object [instance] - optional instance
- return Function function to wrap
- throw
Example: wrap an Array
p = Promise.wrap(Array);
var r = c(1,2,3); // => calls Array constructor and returns fulfilled promise
r.valueOf(); // => [1,2,3];
Promise.defer(-:Function, [args]:...)
Deferres a task and returns a pending promise fulfilled with the return value from task. The task may also return a promise itself which to wait on.
- param Function - task to defer
- param ... [args] - optional list of arguments
- return Object - returns a pending promise
Example: Make readFileSync async
fs = require('fs');
var asyncReadFile = Promise().defer(fs.readFileSync,'./index.js','utf-8');
asyncReadFile.then(function(data){
console.log(data)
},function(error){
console.log("Read error:", error);
});
Promise.async(function:Function, [callback]:Function)
Make function asyncronous and fulfill/reject promise on execution.
- param Function function - function to make async
- param Function [callback] - optional callback to call
- return Object promise
Example: make readFile async
fs = require('fs');
var asyncReadFile = Promise.async(fs.readFile);
asyncReadFile('package.json','utf8').then(function(data){
console.log(data);
},function(error){
console.log("Read error:", error);
});
Promise.isPending()
Check if promise is pending
return Boolean - Returns true if pending or else false
Promise.isFulfilled()
Check if promise is fulfilled
return Boolean - Returns true if pending or else false
Promise.isRejected()
Check if promise is rejeced
return Boolean - Returns true if pending or else false
Promise.hasResolved()
Check if promise has resolved
return Boolean - Returns true if pending or else false
Promise.valueOf()
Get value if promise has been fulfilled
return Boolean - Returns true if pending or else false
Promise.reason()
Get reason if promise has rejected
return Boolean - Returns true if pending or else false
Promise.then(onFulfill:Function, onReject:Function, onNotify:Function)
Attaches callback,errback,notify handlers and returns a promise
- param Function onFulfill callback
- param Function onReject errback
- param Function onNotify callback
- return Object a decendant promise
Example: catch fulfillment or rejection
var p = Promise();
p.then(function(value){
console.log("received:", value);
},function(error){
console.log("failed with:", error);
});
p.fulfill('hello world!'); // => 'received: hello world!'
Example: chainable then clauses
p.then(function(v){
console.log('v is:', v);
if(v > 10) throw new RangeError('to large!');
return v*2;
}).then(function(v){
// gets v*2 from above
console.log('v is:', v)
},function(e){
console.log('error2:', e);
});
p.fulfill(142); // => v is: 142, error2: [RangeError:'to large']
Example: undefined callbacks are ignored
p.then(function(v){
if(v < 0) throw v;
return v;
}).then(undefined,function(e){
e = -e;
return e;
}).then(function(value){
console.log('we got:', value);
});
p.fulfill(-5); // => we got: 5
Promise.spread(onFulfill:Function, onReject:Function, onNotify:Function)
Like then
but spreads array into multiple arguments
- param Function onFulfill callback
- param Function onReject errback
- param Function onNotify callback
- return Object a decendant promise
Example: Multiple fulfillment values
p = Promise();
p.fulfill([1,2,3])
p.spread(function(a,b,c){
console.log(a,b,c); // => '1 2 3'
});
Promise.done(onFulfill:Function, onReject:Function, onNotify:Function)
Terminates chain of promises, calls onerror or throws on unhandled Errors
- param Function onFulfill callback
- param Function onReject errback
- param Function onNotify callback
Example: capture error with done
p.then(function(v){
console.log('v is:', v);
if(v > 10) throw new RangeError('to large!');
return v*2;
}).done(function(v){
// gets v*2 from above
console.log('v is:', v)
});
p.fulfill(142); // => v is: 142, throws [RangeError:'to large']
Example: define onerror handler defined on promise
p.onerror = function(error){ console.log("Sorry:",error) };
p.then(function(v){
console.log('v is:', v);
if(v > 10) throw new RangeError('to large!');
return v*2;
}).done(function(v){
// gets v*2 from above
console.log('v is:', v)
});
p.fulfill(142); // => v is: 142, "Sorry: [RangeError:'to large']"
Promise.end(callback:Function)
Terminates chain, invokes a callback or throws Error on error
param Function callback - Callback with value or Error object on error.
Promise.catch(onError:Function)
Catches errors, terminates promise chain and calls errBack handler.
- param Function onError callback
- return undefined
Example: Catch error
p = Promise();
p.then(function(v){
console.log("someone said:", v); //-> "Hello there"
return "boom!";
})
.then(function(v){ if(v === 'boom!') throw "something bad happened!";})
.catch(function(e){
console.log("error:",e);
});
p.resolve("Hello there");
Promise.fulfill(value:Object)
Fulfills a promise with a value
- param Object value
- return Object promise
Example: fulfillment
p = Promise();
p.fulfill(123);
Example: multiple fulfillment values in array
p = Promise();
p.fulfill([1,2,3]);
p.resolved; // => [1,2,3]
Example: Pass through opaque arguments (experimental)
p = Promise();
p.fulfill("hello","world");
p.then(function(x,o){
console.log(x,o[0]); // => "hello world"
o.push("!");
return "bye bye";
}).then(function(x,o){
console.log(x,o.join('')); // => "bye bye world!"
})
Promise.reject(reason:Object)
Rejects promise with a reason
- param Object reason
- return Object promise
Example:
p = Promise();
p.then(function(ok){
console.log("ok:",ok);
}, function(error){
console.log("error:",error);
});
p.reject('some error'); // outputs => 'error: some error'
Promise.resolve(value:Object)
Resolves a promise and performs unwrapping if necessary
- param Object value - Promise or literal
- return Object promise
Example: resolve a literal
p = Promise();
p.resolve(123); // fulfills promise to 123
Example: resolve value from pending promise
p1 = Promise();
p2 = Promise();
p1.resolve(p2);
p2.fulfill(123) // => p1 fulfills to 123
Promise.progress(arguments:Object)
Notifies attached handlers
- param Object arguments
Example:
p = Promise();
p.then(function(ok){
console.log("ok:",ok);
}, function(error){
console.log("error:",error);
}, function(notify){
console.log(notify);
});
p.progress("almost done"); // optputs => 'almost done'
p.reject('some error'); // outputs => 'error: some error'
Promise.timeout(time:Number, callback:Function)
Timeout a pending promise and invoke callback function on timeout. Without a callback it throws a RangeError('exceeded timeout').
- param Number time - timeout value in ms or null to clear timeout
- param Function callback - optional timeout function callback
- throw
- return Object promise
Example: timeout & abort()
var p = Promise();
p.timeout(5000);
// ... after 5 secs ... => Aborted: |RangeError: 'exceeded timeout']
Example: cancel timeout
p.timeout(5000);
p.timeout(null); // timeout cancelled
Promise.callback(callback:Function)
Resolves promise to a nodejs styled callback function(err,ret) and passes the callbacks return value down the chain.
- param Function callback - Callback function
- return Object promise
Example:
function cb(err,ret){
if(err) console.log("error(%s):",err,ret);
else console.log("success:", ret);
return "nice";
}
p = Promise();
p.callback(cb)
.then(function(cbret){
console.log("callback says:", cbret); //-> callback says: nice
});
p.fulfill("ok"); //-> success: ok
Promise.join(promises:Array)
Joins promises and collects results into an array. If any of the promises are rejected the chain is also rejected.
- param Array promises
- return Object promise
Example: join with two promises
a = Promise();
b = Promise();
c = Promise();
a.join([b,c]).spread(function(a,b,c){
console.log(a,b,c);
},function(err){
console.log('error=',err);
});
b.fulfill('world');
a.fulfill('hello');
c.fulfill('!'); // => 'hello world !''