promiz

A proper compact promise (promises/A+ spec compliant) library.

npm install promiz
15 downloads in the last week
20 downloads in the last month

Promiz.js

Promises/A+ logo A proper compact promise (promises/A+ spec compliant) library. (How it was built)

Install

# Node.js
npm install promiz --save
<!-- Browser -->
<script src='promiz.js'></script>

Promiz: 590 bytes (min + gzip) - as reported by uglify.js
Promiz Micro: 238 bytes (min + gzip) - as reported by uglify.js

What are promises?

function testPromise(val) {
    // An example asynchronous promise function
    var deferred = Promiz.defer()
    setTimeout(function(){
        deferred.resolve(val)
    }, 0)
    return deferred
}
testPromise(22).then(function(twentyTwo){
    // This gets called when the async call finishes

    return 33
}).then(function(thiryThree){
    // Values get passed down the chain. Simple right?
    // Now lets return a promise instead of a value

    return testPromise(99)
}).then(function(ninetyNine){
    // The inner promise was resolved asynchronously, and its value passed in
    // If you've ever used the async library, it's akin to a waterfall
    // Finally, one last mind bending trick

    return [testPromise(11), testPromise(33), testPromise(55)]
}).all().then(function(list){
    // list === [11, 33, 55]
    // Yeah, try doing that with async (obviously you could, but it would look hideous)
    // and just because we can
    return list
}).spread(function(eleven, thirtyThree, fiftyFive){
    // There you go, now you have a general idea of how promises work
    // To answer the original question, a promise is just a special deferred object

// .done() makes sure that if any errors occurred during execution, they get thrown
}).done()
// alternatively, catch errors with the `fail` function
// .fail(function(err){ })

Building your own promises with Promiz

Promiz has many helper functions to help you convert regular functions into promises

Promiz.defer()

function testPromise(val) {
    // create a new instance of a deferred object (a `promise`)
    var deferred = Promiz.defer()
    setTimeout(function(){
        if (val === 42) {
            deferred.resolve('correct')
        } else {
            // This throws an error, which can be caught by .catch() or .done()
            deferred.reject(new Error('incorrect input'))
        }
    }, 0)
    return deferred
}
testPromise(42).then()

Promiz.fcall() (function call)

function testFn(val){
    if (val === 42){
        return 'correct'
    }
    throw new Error('incorrect input')
}
Promiz.fcall(testFn, 42).then()

promiz.nfcall() (node function call)

function nodeFn(val, callback) {
    if (val === 42) {
        return callback(null, 'correct')
    }
    return callback(new Error('incorrect input'))
}

Promiz.nfcall(nodeFn, 42).then()

Promise methods

.then(:success, :error (optional))

// .then() takes an optional second error handler, which will catch all errors from previous calls
// including the current success call
promise.then(function success(){}, function error(){})

.spread(:success)

// .spread() calls .all() and then `applies` over the target function
promise.then(function(){ return [promise(), promise()] }).spread(function(one, two){ })

.all()

// resolves all promises in the result array
promise
.then(function(){ return [promise(), promise()] })
.all() // all()
.then(function(list){ /* all promises have been resolved */})

.fail(:error)

// catches any errors that have been thrown thus far
promise.then(function(){ throw new Error('hello') }).fail(function(err){ })

.done()

// If any errors have not been caught by this point, throw them.
// This ends the promise chain
promise.done()

.nodeify(:callback)

// Sometimes you may need to support both promises and callbacks
// (eg. a developer on your team doesn't know promises)
// This function allows you to create dual functions, that can act like both
function dualFunction(/* optional callback */ callback){
    return promise.nodeify(callback)
}
// you can use it as a promise function
dualFunction().then()
// or a node-style callback function
dualFunction(function(err, val){ })

Promiz Micro

(Promises/A+ spec compliant)

Promiz.defer()

function testPromise(val) {
    // create a new instance of a deferred object (a `promise`)
    var deferred = Promiz.defer()
    setTimeout(function(){
        if (val === 42) {
            deferred.resolve('correct')
        } else {
            // This throws an error, which can be caught by .catch() or .done()
            deferred.reject(new Error('incorrect input'))
        }
    }, 0)
    return deferred
}
testPromise(42).then()

.then(:success, :error (optional))

// .then() takes an optional second error handler, which will catch all errors from previous calls
// including the current success call
promise.then(function success(){}, function error(){})

Licence: MIT

githalytics.com alpha

npm loves you