tiny-deferred.js

Implementation originally inspired by Mariusz Nowak's deferred

NPM tiny-deferred.js link

Features

• Very fast
• Easy to understand
• Dependency free
• Using native JavaScript code
• Works on server and browser side smoothly
• Works with require.js library
• Written with TDD
• Compiled + gzipped weighs less than 1kB

Why to use tiny-deferred?

• You dont have to remember about .catch'ing errors - this library is automatically showing catched JS errors! No more hidden JS errors

Installation

• download from Github
• npm: npm install tiny-deferred.js
• bower: bower install tiny-deferred

Methods

tiny-deferred.js's promise is chainable. Each promise method is returning new promise instance.

defer.resolve(value/promise)

Value can be a callback, promise or data

Resolving awaiting deferreds and executing win callbacks

defer.resolve(value/promise)

Value can be a callback, promise or data

Resolving awaiting deferreds and executing fail callbacks

promise.then(win, fail)

After defer.resolve() - executing win callback

After defer.reject() - executing fail callback

promise.always(callback)

After defer.resolve() and defer.reject() - executing callback

Examples

Basic example

var defer = deferred();
 
defer.resolve(1);
// async execution - imagine ajax call
setTimeout(function() {
    // only first resolve is taken - so the value will be 1
    defer.resolve(2);
 
    console.log(defer.promise.resolved); // true
    console.log(defer.promise.value); // 1
    console.log(defer.promise.valueOf()); // 1
}, 100);

Nesting

var defer1 = deferred(),
    defer2 = deferred(),
    x = {},
    promise;
 
// defer1 will still be waiting for defer2 resolve
defer1.resolve(defer2.promise);
// this callback will be postponed until defer2 resolves
promise = defer1.promise.then(function(arg) {
    return [arg, 'foo'];
});
// defer2 resolves so defer1 will immadietely execute awaiting callbacks
defer2.resolve(x);
 
console.log(promise.resolved); // true (promise is resolved)
console.log(promise.value); // [{}, 'foo']

Nesting - another example

var defer1 = deferred(),
    promise1 = defer1.promise,
    x = {},
  	defer2 = deferred(),
  	promise2 = defer2.promise;
 
promise1(function (result) {
    // "result" will be the same as a value of promise2
    console.log(result); // {}
});
 
// promise1 will be waiting to execute awaiting callbacks until defer2 resolves
defer1.resolve(promise2);
// imagine ajax call
setTimeout(function() {
    defer2.resolve(x);
}, 100);

Chaining

var defer = deferred(),
    promise = defer.promise,
    arg1 = 'arg1',
    arg2 = 'arg2',
    arg3 = 'arg3';
 
// this chain will be postponed until defer resolves
promise.then(function(value) {
    var def = deferred();
 
    // argument will be the same as resolved value
    console.log(value); // 'arg1'
 
    setTimeout(function() {
        def.resolve(arg2);
    }, 100);
 
    // then callback can be either a promise
    return def.promise;
}).then(function(value) {
    var def = deferred();
 
    // argument will be the same as resolved value
    console.log(value); // 'arg2'
 
    // this log is important
    // - promises chain execution each time creates new promise
    // - will not change already resolved promise value
    // - "promise" var points to initially created deferred's promise
    console.log(promise.value); // 'arg1'
 
    def.resolve(arg3);
 
    return def.promise;
}).then(function(value) {
    // argument will be the same as resolved value
    console.log(value); // 'arg3'
 
    return value;
}).then(function(value) {
    var def = deferred();
 
    setTimeout(function() {
        // previously we have just returned argument - nothing changed
        console.log(value); // 'arg3'
 
        def.resolve(arg1+value);
    }, 100);
 
    return def.promise;
}).then(function(test) {
    // result of concatenating arg1+value
    console.log(value); // 'arg1arg3'
});
 
// imagine here ajax call
setTimeout(function() {
    // defer resolves - execute chain
    defer.resolve(arg1);
}, 100);

Executing more callbacks on resolve

var defer = deferred(),
    promise = defer.promise,
    count = 0;
 
// we can bind to promise as many callbacks as we want
// these callbacks will be executed 'fifo' order
promise(function () {
    // executes first
    ++count;
});
 
promise(function () {
    // executes second
    console.log(count); // 1
});
 
defer.resolve(x);

Processing collections - map

var text = 'Lorem Ipsum is simply dummy text of the printing';
 
deferred.map(text.split(' '), function(word) {
    var defer = deferred();
 
    setTimeout(function() {
        defer.resolve(word.toLowerCase());
    }, 10);
 
    return defer.promise;
}).then(function(result) {
    var textLowerCase = result.join(' ');
 
    console.log(Array.isArray(result)); // true
    // same order - no missing words
    console.log(textLowerCase === text.toLowerCase()); // true
});

Processing collections - reduce

var defer1 = deferred();
var defer2 = deferred();
var defer3 = deferred();
var values = [2,3,8];
 
deferred.reduce([defer1.promise, 1, defer2.promise, defer3.promise], function(previous, current, index) {
    var defer = deferred();
    
    // index always starts from 1, not 0 - as in Array.prototype.reduce specification
    if(index === 1) {
        console.log(previous, current, index); // 2, 1, 1
    } else if(index === 2) {
        console.log(previous, current, index); // 3, 3, 2
    } else if(index === 3) {
        console.log(previous, current, index); // 6, 8, 3
    }
 
    setTimeout(function() {
        defer.resolve(previous+current);
    }, 10);
 
    return defer.promise;
}).then(function(result) {
    console.log(result); // 14
});
 
defer1.resolve(values[0]);
defer2.resolve(values[1]);
defer3.resolve(values[2]);

For more working examples:

Check out tests file

License

MIT