@hal313/promiseifyish NPM

promiseifyish

Wraps functions and objects into promises.

Introduction

Wraps functions of the form fn([...args], successCallback, failureCallback) into Promises. This can be useful in cases where functions with callbacks are being chained together. Using promises avoids some flow issues and often simplifies the logic.

For example:

someFunction1(() => {
    someFunction2(() => {
        someFunction3(() => {
            someFunction4(() => {}, errorHandler);
        }, errorHandler);
    }, errorHandler;
}, errorHandler);

Becomes

someFunction1()
    .then(someFunction2)
    .then(someFunction3)
    .then(someFunction4)
    .catch(errorHandler)

WARNING: If a success callback is specified as a non-function (such as null or undefined) AND a failure callback is specifed as a function, then the failure function may not correctly be invoked. See issue 4 in GitHub.

See an example.

Usage

Use Promiseifyish to promiseify a function or an object. Project environment dictates how the code is imported. ES6, ES5 and AMD/CommonJS are all supported. Comprehensive documentation and examples may be found at the GitHub pages.

As a function

/**
 * A function to demonstrate callback behavior.
 *
 * @param {boolean} success if true, the success callback will be invoked
 * @param {*} value the value to pass to the callback
 * @param {Function} [successCallback] the success callback
 * @param {Function} [failureCallback] the failure callback
 */
function someFunction(success, value, successCallback, failureCallback) {
    if (success && 'function' === typeof successCallback) {
        successCallback(value);
    } else if (!success && 'function' === typeof failureCallback) {
        failureCallback(value);
    }
}

// Standard usage:
someFunction(true, 'some value',
    value => console.log('standard', 'succes', value),
    error => console.log('standard', 'failure', error)
);


// After promisification:
var promisifiedFunction = Promiseifyish.Promiseify(someFunction);
// Invoke as a promise
promisifiedFunction(true, 'some value')
    .then(value => console.log('promiseified', 'success', value))
    .catch(error => console.log('promiseified', 'failure', error));

As an Object

// Standard usage
var someObject = {
    booleanMember: true,
    stringMember: 'some value',
    functionMember: someFunction(success, value, successCallback, failureCallback) {
        if (success && 'function' === typeof successCallback) {
            successCallback(value);
        } else if (!success && 'function' === typeof failureCallback) {
            failureCallback(value);
        }
    }
};
// Invoke the function
someObject.functionMember(true, 'some value',
    value => console.log('succes', value),
    error => console.log('failure', error)
);


// After promisification:
// Promiseify the object
var promiseifiedObject = Promiseifyish.Promiseify(someObject);
// All functions are now promises
promiseifiedObject.functionMember(true, 'some value')
    .then(value => console.log('success', value))
    .catch(error => console.log('failure', error));

Advanced Usage

Passing options to the Promiseify function can alter the behavior of promiseification.

If neither only nor include are specified, all functions are included except for functions on Object.

only

Using {only: ['function1'[, ..., 'functionN']]} as the options object parameter will promiseify only the specified functions, regardless of any other options (specifically exclude).

include

Using {include: ['function1'[, ..., 'functionN']] as the options object parameter will include only the specified functions, subject to any function in exclude.

exclude

Using {exclude: ['function1'[, ..., 'functionN']] as the options object parameter will exclude the specified functions from promiseification. This value is not used when only is used.