assure

Promises/A+ micro library to help with asynchronous work flow. The deferred methods match jQuery's when possible for convenience and familiarity, but under the hood it is a Promises/A+ spec!

Example

var deferred = assure();

deferred.done(function (arg) {
	console.log("Outcome: " + arg);
});

deferred.always(function (arg) {
	...
});

What is Supported?

• AMD loaders (require.js, cujo.js, etc.)
• node.js (npm install assure)
• script tag

How do I use this?

Promises (deferreds/futures/etc.) are a way to create a tangible connection between now and an eventual outcome. Promises are a good pattern for asynchronous I/O, such as API interaction, AJAX operations, etc., by providing optional success & failure handling.

A then() will return a new Promise which is in a hierarchal relationship. When a "parent" is reconciled, it's "children" inherit the outcome.

API

always

Method

Registers a function to execute after Promise is reconciled

param  {Function} arg Function to execute
return {Object}       Deferred

Example

var deferred = assure();

deferred.always(function() {
	console.log("This is always going to run");
});

done

Method

Registers a function to execute after Promise is resolved

param  {Function} arg Function to execute
return {Object}       Deferred

Example

var deferred = assure();

deferred.done(function() {
	console.log("This is going to run if Promise is resolved");
});

fail

Method

Registers a function to execute after Promise is rejected

param  {Function} arg Function to execute
return {Object}       Deferred

Example

var deferred = assure();

deferred.fail(function() {
	console.log("This is going to run if Promise is rejected");
});

isRejected

Method

Determines if Deferred is rejected

return {Boolean} `true` if rejected

Example

var deferred = assure();

deferred.isRejected(); // false, it's brand new!

isResolved

Method

Determines if Deferred is resolved

return {Boolean} `true` if resolved

Example

var deferred = assure();

deferred.isResolved(); // false, it's brand new!

reject

Method

Breaks a Promise

param  {Mixed} arg Promise outcome
return {Object}    Promise

Example

var deferred = assure();

deferred.then(null, function (e) {
	console.error(e);
});

deferred.reject("rejected");

resolve

Method

Promise is resolved

param  {Mixed} arg Promise outcome
return {Object}    Promise

Example

var deferred = assure();

deferred.then(function (arg) {
	console.log(arg);
});

deferred.resolve("resolved");

state

Method

Gets the state of the Promise

return {String} Describes the state

Example

var deferred = assure();

deferred.state(); // `pending`

then

Method

Registers handler(s) for a Promise

param  {Function} success Executed when/if promise is resolved
param  {Function} failure [Optional] Executed when/if promise is broken
return {Object}           New Promise instance

Example

var deferred = assure();

deferred.then(function (arg) {
	console.log("Promise succeeded!");
}, function (e) {
	console.error("Promise failed!");
});

deferred.resolve("resolved");

when

Method

Accepts Deferreds or Promises as arguments or an Array

return {Object} Deferred

Example

var d1 = assure(),
    d2 = assure(),
    d3 = assure();

...

when(d1,d2,d3).then(function (values) {
	...
});

License

Copyright (c) 2013 Jason Mulligan
Licensed under the BSD-3 license.