[![Build Status](https://travis-ci.org/kaerus-component/uP.png)](https://travis-ci.org/kaerus-component/uP)

microPromise(uP) - A+ v1.1 compliant promises

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 !''