simple-promise

1.3.4 • Public • Published

simple-promise Bower version NPM version

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!


Package Sidebar

Install

npm i simple-promise

Weekly Downloads

11

Version

1.3.4

License

MIT

Last publish

Collaborators

  • cobbdb