Next Planet of Monkeys

    callback-promise

    0.5.0 • Public • Published

    callback-promise Build Status codecov

    Convert callback style APIs to Promise based APIs.

    Suitable for Browsers and Node.js.

    Pure JS for best performance, no evals, withs or other "dangerous" constructs used.

    Breaking Changes

    v0.5.0

    • The this of the arguments transformation function became the promise:
    const papi = c2p(obj, meth, function (...args) {
        const context = this; 
        // in v0.4 context === obj, 
        // in v0.5 context.this === obj, 
        //     and context is the promise object returned by papi()
        ...
    });
    
    let promise = papi(x, y, z);
    // promise.this === obj

    Install

    • Just add a script tag to your page (Browser):
    <script src="https://unpkg.com/callback-promise"></script>
    • Alternatively copy c2p.js to your project or install it using npm:
    npm install callback-promise
    • Then import c2p to your app (ESM):
    import c2p from 'callback-promise';
    • or require c2p (AMD or CommonJs):
    const c2p = require('callback-promise');
    • Make sure there is a Promise implementation or get a polyfill like es6-promise.
    c2p.Promise = require('es6-promise').Promise; // polyfill

    Usage

    • Convert any API based on callbacks to promises
    // convert speciffic methods
    var pAPI = {
        meth: c2p([API, ]API.meth, resultArgNo, errorArgNo, cbAtStart, noCb),
    };
    
    // or convert the entire API object
    var pAPI = c2p.all(API[, dest_pAPI], resultArgNo, errorArgNo, cbAtStart, noCb);
    
    
    // @param any      API        - a context object for API.meth.
    // @param Function meth       - a function (name on API) that accepts a callback argument and optinally other arguments.
    // @param int     resultArgNo - argument number of result in callback. If false, all arguments are considered the result.
    // @param int     errorArgNo  - argument number of error in callback.
    // @param Boolean cbAtStart   - if _fn expects callback as first argument, set this to true.
    // @param Boolean noCb        - if true, the new version of _fn doesn't accept the callback argument.
    
    // Note: All argumetns except .meth are optional
    
    // @return Function that accepts same arguments as _fn, except callback, and returns a Promise
    • Now you can use your new pAPI
    pAPI.meth(arg1, arg2, ...)
        .then(function(result){...})
        .catch(function(error){...})
    ;
    
    // equivalent with old API
    
    API.meth(arg1, arg2, ..., function (some, args, with, result, and, error){
        if ( error ) ...;
        ...
    })

    Examples

    Node API

    // Common Node.js code
    fs.readFile(filename, function (error, data) {
        if ( error ) {
            ...
        }
        else {
            ...
        }
    });
    
    // convert to Promise based API:
    pfs.readFile = c2p(fs.readFile, 1, 0);
    // same with explicit arguments mapping
    pfs.readFile = c2p(fs.readFile, function (error, data) {
        if ( error ) throw error;
        return data;
    });
    // or with this
    pfs.readFile = c2p(fs, 'readFile', 1, 0);
    
    // then
    pfs.readFile(filename)
        .then(function (data) { })
        .catch(function (error) { })
    ;

    Callback with sync return

    // Node.js method that accepts a callback and returns an EventEmitter
    var child = child_process.exec(command, options, function (error, stdout, stderr){ ... });
    var pid = child.pid;
    child.stdin.end();
    
    // convert to Promise base API:
    pchild_process.exec = c2p(child_process.exec, 1, 0);
    
    
    // then
    var pchild = pchild_process.exec(command, options);
    
    var child = pchild.result; // like an event in jQuery
    var pid = child.pid;
    child.stdin.end();
    
    pchild
        .then(function (stdout){ ... })
        .catch(function (error){ ... })
    ;
    
    
    // and if you need to catch stderr, use the callback:
    var pchild = pchild_process.exec(command, options, function (error, stdout, stderr){ ... })
        .then(function(stdout){ ... })
        .catch(function (error){ ... })
    ;

    Chrome Extension API

    // Common Chrome Extension code
    chrome.tabs.update(tabId, props, function (tab) {});
    
    // becomes:
    pchrome.tabs.update = c2p(chrome.tabs.update);
    // or with this
    pchrome.tabs.update = c2p(chrome.tabs, 'update');
    // either
    pchrome.tabs.update = c2p(chrome.tabs, chrome.tabs.update);
    // either with explicit arguments mapping and API error handling
    pchrome.tabs.update = c2p(chrome.tabs.update, function (tab) {
        var error = chrome.runtime.lastError;
        if ( error ) throw error;
        return tab;
    });
    
    // then
    pchrome.tabs.update(tabId, props)
        .then(function (tab) {})
        .catch(function (error) {})
    ;

    Other use cases

    var wait = c2p(setTimeout, true);
    wait(100).then(function () { doSomethingLater() })

    Testing

    npm test     # test in node
    npm test-dev # test in browsers using karma with livereload

    to be continued ...

    Install

    npm i callback-promise

    DownloadsWeekly Downloads

    8

    Version

    0.5.0

    License

    MIT

    Unpacked Size

    24.6 kB

    Total Files

    6

    Last publish

    Collaborators

    • duzun