simple-promise

Simple and fast promise factory for Node and web apps.

$ bower install simple-promise
$ npm install simple-promise

API

promise(task)

• Param task Function Entry point of the promise.

• Returns Function

• var say = promise(function (msg, name) {

  task([{args}], done)

  • Param [args] Any Task arguments.

  • Param done Function Call to signal end of task.

  • Returns Any Return value of task.

  • var say = promise(function (msg, name, done) {

    done([{args}])

    • Param [args] Any Done arguments.
    • Returns Any Return value of then contract.*
    • var thenResult = done('abc123');

promise.then(contract)

• Param contract Function Called on task's done.

• Returns Any Return value of then contract.

• say.then(function (async, sync, msg, name) {

  contract([{async}], [sync], {[args]})

  • Param async Any Call argument(s) of task's done.
  • Param sync Any Return value of task.
  • Returns Any Return value of then contract.
  • say.then(function (async1, async2, sync, msg, name) {

promise.error(contract)

• Param contract Function Called on task error.

• Returns Any Return value of error contract.

• say.error(function (err, msg, name) {

  contract(err, {[args]})

  • Param err Error Error object thrown in task.
  • Param [args] Any All task arguments.
  • Returns Any Return value of error contract.
  • say.error(function (err, msg, name) {

Code Samples

Here are some quick code samples to help you get started.

Load the library

Simple-Promise is a CommonJS library, so the require statement can be used for both Node and web applications!

var promise = require('simple-promise');

Creating a new promise

At their core, promises look and behave like a normal function.

var greet = promise(function (name, done) {
    console.log('Hello %s!', name);
    done();
});

Attach a success behavior

Callbacks can be a hassle and quickly create a mess. Tackle the common usage of callbacks with a promise instead. The then function is optional and is called immediately after successful completion of the promise.

greet.then(function (name) {
    console.log('Farewell %s!', name);
});

Attach an error behavior

Sometimes things don't go as expected. Attach an optional error behavior to handle any problems.

greet.error(function (err, name) {
    console.log('%s caused an error!', name);
    console.error('%s : %s', err.name, err.message);
});

Chain your method calls

Each method supports chaining for quick and clean instantiation.

promise(function (done) {
    console.log('First, this happened.');
    done();
}).then(function () {
    console.log('Then, this happened.');
}).error(function () {
    console.error("Hopefully this won't happen to you.");
});

Immediately invoke your promise

You can invoke immediately with the run method or parens.

var go = promise(function (greeting, name) {
    console.log('%s %s!', greeting, name);
});
go.run('Hello', 'World');
// ~ or ~ like this:
go('Hello', 'World');

Collect all return values

Return values are passed along the chain so you can use them however you need.

var result;
promise(function (name, done) {
    // Some async action.
    setTimeout(function () {
        result = done();
    }, 100);
    return 'Hello!';
}).then(function (sync, name) {
    return name + ' says ' + sync;
}).run('Tom');

var result = promise(function (name) {
    throw Error('Hello!');
}).error(function (err, name) {
    return name + ' says ' + err.message;
}).run('Tom');

Both of these blocks will eventually output the same string; result will equal Tom says Hello!

• See: http://github.com/cobbdb/simple-promise
• License: MIT