cfy

cfy - CallbackiFY

Simplifies interop between co (promise / generator-based) async functions, and async callback-based functions (both node-style nodebacks where the first parameter is an error, and regular callbacks).

Features

• Write callback-based async functions using generators (using cfy). Can also write node-style ("nodeback") async functions (using cfy_node). If the resulting function is not passed a callback, an ES6 Promise is returned.
• Can yield callback-based functions in generators (using yfy), as well as node-style nodeback-based functions (using yfy_node).
• All features of generators wrapped with co (such as yielding Promises) can be used in generators wrapped with cfy and cfy_node.

Install

npm install cfy

Usage

For the purpose of these examples, we assume you have required the library as follows:

var {cfy, cfy_node, yfy, yfy_node} = require('cfy');

Note that if you only need to use the cfy function, you can simply require it as:

var cfy = require('cfy');

Examples

Turning a generator into a callback/promise-based async function

var cfy = require('cfy');

var cfy_example = cfy(function*() {
  var result = yield Promise.resolve(5); // 5
  return result;
});

cfy_example(function(x) { console.log(x) }); // 5
cfy_example().then(function(x) { console.log(x) }); // 5

Using callback-based async functions in generators

var {cfy, yfy} = require('cfy');

function add_async(x, y, callback) {
  setTimeout(function() {
    callback(x + y);
  }, 1000);
}

var yfy_example_with_arguments = cfy(function*(a, b) {
  var result = yield yfy(add_async)(5, 1); // 6
  return result + a + b;
});

yfy_example_with_arguments(2, 7, function(x) { console.log(x) }); // 15
yfy_example_with_arguments(2, 7).then(function(x) { console.log(x) }); // 15

Writing a wrapper for setTimeout (sleep)

var sleep = cfy(function*(time) {
  function sleep_base(msecs, callback) {
    setTimeout(callback, msecs);
  }
  yield yfy(sleep_base)(time);
});

var sleep_example = cfy(function*() {
  yield sleep(3000); // sleeps for 3 seconds
  return 7;
});

sleep_example(function(x) { console.log(x) }); // 7

API

cfy

cfy creates a callback-style function from a generator

var cfy_example = cfy(function*() {
  var result = yield Promise.resolve(5); // 5
  return result;
});

cfy_example(function(x) { console.log(x) }); // 5

If the last argument is not a function, a promise will be returned instead:

cfy_example().then(function(x) { console.log(x) }); // 5

cfy_node

cfy_node creates a nodeback-style function from a generator

var cfy_node_example = cfy_node(function*() {
  var result = yield Promise.resolve(5); // 5
  return result;
});

cfy_node_example(function(err, x) { console.log(x) }); // 5

If the last argument is not a function, a promise will be returned instead:

cfy_node_example().then(function(x) { console.log(x) });

yfy

yfy transforms a callback-style function into a promise which can be yielded within a generator. If the callback has multiple results, only the first one will be output. (Use yfy_multi if you need all the results).

function add_async(x, y, callback) {
  setTimeout(function() {
    callback(x + y);
  }, 1000);
}

var yfy_example_with_arguments = cfy(function*(a, b) {
  var result = yield yfy(add_async)(5, 1); // 6
  return result + a + b;
});

yfy_example_with_arguments(2, 7, function(x) { console.log(x) }); // 15

yfy_node

yfy_node transforms a nodeback-style function into a promise which can be yielded within a generator. If the callback has multiple results, only the first one will be output (the error parameter will not be included). (Use yfy_multi_node if you need all the results).

function add_async_node(x, y, nodeback) {
  setTimeout(function() {
    nodeback(null, x + 1);
  }, 1000);
}

var yfy_node_example_with_arguments = cfy_node(function*(a, b) {
  var result = yield yfy_node(add_async_node)(5, 1); // 6
  return result + a + b;
});

yfy_node_example_with_arguments(2, 7, function(err, x) { console.log(x) }); // 15

yfy_multi

yfy_multi transforms a callback-style function into a promise which can be yielded within a generator. The promise will resolve to an array containing all the arguments to the callback function.

var yfy_multi_example = yfy_multi(function(x, callback) {
  callback(x + 1, x + 2);
})

yfy_multi_example(2).then(function(x) {console.log(x)}); // [3, 4]

yfy_multi_node

yfy_multi_node transforms a nodeback-style function into a promise which can be yielded within a generator. The promise will resolve to an array containing all the arguments to the callback function, except the first one (error parameter).

var yfy_multi_node_example = yfy_multi_node(function(x, callback) {
  callback(null, x + 1, x + 2);
})

yfy_multi_node_example(2).then(function(x) {console.log(x)}); // [3, 4]

More Examples

You will find more examples in example.js (for interop with normal callback-based async functions) and example_node.js (for interop with node-style nodeback-based async functions). The unit tests include examples of usage from Livescript.

Notes

Unhandled promise rejections

You sure ensure that unhandled promise rejections get printed or thrown, otherwise uncaught errors that occur in code that returns promises (ie, the body of cfy and yfy functions) will be silent (will not be printed). In nodejs, you can throw an Error when there is an unhandled rejection by adding to the top of your file:

process.on('unhandledRejection', function(reason, p) {
  throw new Error(reason);
});

In the browser, you can throw an Error when there is an unhandled rejection by adding to the top of your file:

window.addEventListener('unhandledrejection', function(evt) {
  throw evt.reason;
});

cfy with generator functions that take variable numbers of parameters

Note that cfy will always return a promise-style function if you are using it with generator functions that take variable numbers of arguments. This is because it is not possible to distinguish whether the last argument is intended to be used as a callback or another argument.

If you wish to use cfy to get a callback-style function from a generator function that takes variable numbers of arguments, or a generator function that does not have the .length property correctly set, you can use cfy(your_function, {varargs: true}). If you are using the varargs option, ensure that your generator function's last parameter is never a function, otherwise it will be mistakenly assumed to be a callback.

yfy with functions that take variable numbers of parameters

Note that yfy will always return a promise-style function if you are using it with functions that take variable numbers of arguments. This is because it is not possible to distinguish whether the last argument is intended to be used as a callback or another argument.

License

MIT

Credits

By Geza Kovacs