Wondering what’s next for npm?Check out our public roadmap! »

    promisify-any

    2.0.1 • Public • Published

    promisify-any.js

    Promisify any of: callback function, sync function, generator function, promise-returning function

    Current status

    NPM version Build Status Dependency Status Dev dependency Status Coverage Status

    API is stable and all features are tested.

    What is it for?

    There are plenty of modules for promisifying callback functions. But what if you are writing a module where the user provides a function as an input to your API and you want to give them flexibility to either use promises or callbacks in that function? And what about generator functions?

    This module takes an input which can be any of:

    • Async callback function
    • Sync function
    • Promise-returning function
    • Generator function which yields promises

    ...and turns any of the above into a promise-returning function.

    Usage

    Installation

    npm install promisify-any
    

    Loading

    var promisify = require('promisify-any');

    Promisifying

    Pass the function to be converted to promisify.

     
    fn = promisify(fn);
     

    The result of calling fn now will be a promise.

    fn().then(function(result) {
        // ...
    });

    If the function expects arguments, the number of arguments (not including the callback) MUST be provided as a 2nd argument to promisify.

    var fn = function(a, b, cb) {
        return cb(null, a + b);
    };
     
    fn = promisify(fn, 2);

    This is so that you end up with the same function, with any of the following inputs:

    var fns = [
        function(a, b, cb) { return cb(null, a + b); },
        function(a, b) { return a + b; },
        function(a, b) { return Promise.resolve(+ b); },
        function *(a, b) { return yield Promise.resolve(+ b); }
    ];
     
    fns = fns.map(function(fn) {return promisify(fn, 2)});
    // fns[0] == fns[1] == fns[2] == fns[3]
     

    promisify-any works out if an input function uses a callback or not, based on the number of arguments the function has. So it needs to know in advance how many arguments it should have!

    Async callback functions

    Async callback functions are "promisified".

    e.g. Returning a value through callback:

    var fn = promisify(function(cb) {
        setImmediate(function() {
            cb(null, 123);
        });
    });
     
    fn().then(function(result) {
        // result = 123
    });

    e.g. Taking arguments (note that number of expected arguments is passed to promisify):

    var fn = promisify(function(x, y, cb) {
        setImmediate(function() {
            cb(null, x + y);
        });
    }, 2);
     
    fn(3, 4).then(function(result) {
        // result = 7
    });

    e.g. Returning an error through callback:

    var fn = promisify(function(cb) {
        setImmediate(function() {
            cb(new Error('oops!'));
        });
    });
     
    fn().catch(function(err) {
        // err.message = 'oops!'
    });

    Sync functions

    Sync functions are turned into asynchronous promise-returning functions:

    var fn = promisify(function(x, y) {
        return x + y;
    }, 2);
     
    fn(3, 4).then(function(result) {
        // result = 7
    });
    var fn = promisify(function() {
        throw new Error('oops!');
    });
     
    fn().catch(function(err) {
        // err.message = 'oops!'
    });

    Promise-returning functions

    Promise-returning functions are left unchanged.

    var fn = promisify(function(x, y) {
        return Promise.resolve(+ y);
    }, 2);
     
    fn(3, 4).then(function(result) {
        // result = 7
    });

    Generator functions

    Generator functions are wrapped using co (co.wrap()) so that they can yield promises. The resulting function also returns a promise.

    var fn = promisify(function *(x, y) {
        var values = yield [
            Promise.resolve(* 10),
            Promise.resolve(* 10)
        ];
     
        return values[0] + values[1];
    }, 2);
     
    fn(3, 4).then(function(result) {
        // result = 70
    });

    NB Generators are only supported in node v0.11 upwards and require node to be run with the --harmony flag.

    Mixing sync and promise returns

    In this example, a user is loaded from the database, but records are cached in a local variable, and the cached version is used first if it exists. The function may do any of:

    • return a promise that is asynchronously resolved
    • return a promise that is asynchronously rejected
    • return a result synchronously (from the cache)
    • throw synchronously
    var cache = [];
    function getUserFromDb(id) {
        if (!id) throw new Error('Must provide id');
     
        if (cache[id]) return cache[id];
     
        // userModel.find() returns a promise
        return userModel.find( { where: { id: id } } ).then(function(result) {
            if (!result) return Promise.reject(new Error('User not found'));
     
            cache[id] = result;
            return result;
        };
    }

    This will not work if the function returns synchronously:

    getUserFromDb(123).then(function(result) {
        // do something with the result
    });

    But this will always work:

    getUserFromDb = promisify(getUserFromDb, 1);
     
    getUserFromDb(123).then(function(result) {
        // do something with the result
    });

    It's less cumbersome to write functions in this way - returning/throwing either synchronously or asynchronously.

    promisify.generators(object)

    Promisifies all methods of the object which are generators.

    var obj = {
        addOne: function *(x) {
            return yield Promise.resolve(+ 1);
        },
        double: function *(x) {
            return yield Promise.resolve(* 2);
        }
    };
     
    promisify.generators(obj);
     
    obj.addOne(10).then(obj.double).then(function(result) {
        // result = 22
    });

    promisify.use(Promise)

    Creates a new instance of promisify-any, which uses the Promise implementation provided.

    var Bluebird = require('bluebird');
    var promisify = require('promisify-any').use(Bluebird);
     
    // now use `promisify-any` in the usual way
    var fn = promisify(function() {});
     
    var p = fn();
     
    console.log(instanceof Bluebird); // true

    Tests

    Use npm test to run the tests or npm run test-harmony to include generator tests. Use npm run cover to check coverage.

    Changelog

    See changelog.md

    Issues

    If you discover a bug, please raise an issue on Github. https://github.com/overlookmotel/promisify-any/issues

    Contribution

    Pull requests are very welcome. Please:

    • ensure all tests pass before submitting PR
    • add an entry to changelog
    • add tests for new features
    • document new functionality/API additions in README

    Install

    npm i promisify-any

    DownloadsWeekly Downloads

    22,427

    Version

    2.0.1

    License

    none

    Last publish

    Collaborators

    • avatar