ambi

Execute a function ambidextrously (normalizes the differences between synchronous and asynchronous functions). Useful for treating synchronous functions as asynchronous functions (like supporting both synchronous and asynchronous event definitions automatically).

Install

NPM

Install: npm install --save ambi
Module: require('ambi')

Browserify

Install: npm install --save ambi
Module: require('ambi')
CDN URL: //wzrd.in/bundle/ambi@2.5.0

Ender

Install: ender add ambi
Module: require('ambi')

Editions

This package is published with the following editions:

ambi aliases ambi/index.js which uses Editions to automatically select the correct edition for the consumers environment
ambi/source/index.js is Source + ESNext + Require
ambi/es2015/index.js is Babel Compiled + ES2015 + Require

Older environments may need Babel's Polyfill or something similar.

## Usage ### Example ``` javascript // Import const ambi = require('ambi') let result = null // Sample methods function syncMethod (x, y) { return x * y } function asyncMethod (x, y, next) { return setTimeout(function () { next(null, x * y) }, 0) } // Call the synchronous function asynchronously // ambi adds support for this asynchronous callback automatically result = ambi(syncMethod, 5, 2, function(err, result) { console.log(err, result) // null, 10 }) console.log(result) // 10 - just like normal // Call the asynchronous function asynchronously // ambi doesn't do anything special here result = ambi(asyncMethod, 5, 2, function (err, result) { console.log(err, result) // null, 10 }) console.log(result) // setTimeout - just like normal ``` ### Notes - Ambi accepts the arguments `(method, ...args)` - `method` is the function to execute - `...args` is the arguments to send to the method - the last argument is expected to be the completion callback - the completion callback is optional, but if defined, is expected to have the signature of `(err, ...results)` - If the method has equal or more arguments than ambi received, then we assume it is an asynchronous method and let it handle calling of the completion callback itself - If the method has less arguments than ambi received, then we assume it is a synchronous method and we'll call the completion callback ourselves - If the synchronous method throws an error or returns an error, we'll try to call the completion callback with a single `err` argument - If the synchronous method executes without error, we'll try to call the completion callback with a `err` argument equal to null, and a `result` argument equal to the returned result of the synchronous method - Ambi can also introspect a different method than the one it fires, by passing `[methodToFire, methodToIntrospect]` as the `method` argument