ambi

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

Backend

1. Install Node.js
2. npm install --save ambi

Frontend

1. See Browserify

Usage

Example

// Import
var ambi = require('ambi');
var result;

// Sample methods
var syncMethod = function(x,y){
	return x*y;
};
var asyncMethod = function(x,y,next){
	return setTimeout(function(){
		next(null,x*y);
	},0);
};

// Call the synchronous function asynchronously
result = ambi(syncMethod, 5, 2, function(err,result){ // ambi adds support for this asynchronous callback automatically
	console.log(err, result); // null, 10
});
console.log(result); // 10 - just like normal

// Call the asynchronous function asynchronously
result = ambi(asyncMethod, 5, 2, function(err,result){ // ambi doesn't do anything special here
	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 the same amount of arguments as those ambi received, then we assume it is an asynchronous method and let it handle calling of the completion callback itself
• If the method does not have the same amount of arguments as those 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

History

You can discover the history inside the History.md file

License

Licensed under the incredibly permissive MIT License
Copyright © 2013+ Bevry Pty Ltd
Copyright © 2011-2012 Benjamin Arthur Lupton

Changelog

v2.1.0 2013 August 19

• will now always return null for consistency
• as return values are only possible with synchronous methods
• will now ignore returned errors on asynchronous functions
• asynchronous errors must now give the error via the completion callback
• this is to avoid the possibility of the completion callback being called twice (once for the returned error via ambi, once via your application)
• will now ignore thown errors
• this was determined to be outside the scope of ambi, if you want this functionality use the more full featured taskgroup package