yield-callback - run async/callback functions in a sync style, with generators
This library makes it easy to write code that makes serial calls to async
functions that use callbacks in the typical "Node.js" style - eg, cb(err, data)
.
Forget the Callback Hell - and write code that looks like it's synchronous,
but isn't. Thanks to the magic that is JavaScript Generators.
example
Say you want to write a function readFile()
which reads the contents of a file
using the fs
module. Here's how you would do it using Node.js's low-level
fs
module functions, in a fairly typical pyramid-of-callback-hell-doom:
{ fs}
With yield-callback
, you can write it like this instead:
{ const fd = fs if cberr return cberr const stats = fs if cberr return cberr const buffer = statssize const bytesReadBuffer = fs if cberr return cberr const bytesRead = bytesReadBuffer0 const bufferRead = bytesReadBuffer1 if bytesRead !== bufferlength return 'EMOREFILE' fs if cberr return cberr return bufferRead}
Your readFile()
function will actually be implemented as a generator function.
Note the generator function takes a cb
parameter at the end, but it it works
differently than a typical Node.js callback. You pass that cb
parameter as
the callback for async functions called inside the generator function, used
within yield expressions, and cb
arranges to yield the callback 'result'
argument(s) as the result, and sets the 'error' argument to cb.err
:
You can then invoke the generator as below. Note that you pass a "normal"
callback function in as the final parameter to run()
, which will be invoked
when the generator finally returns. If the generator returns an error, the
first argument will be that error. Otherwise, the second argument will be set
to the return value. Just like a typical Node.js async callback:
yieldCallback
Or you can wrap the generator to return a "typical errback" function; in this
case, with the same signature and behavior as the pyramid-of-doom readFile()
above:
const readFile =
install
npm install yield-callback
API
This module exports a function which takes a generator function as a parameter
and returns a new function with the same signature as the generator function.
For the remainder of this document, we'll refer to this function as
yieldCallback()
, as if you had done a:
const yieldCallback =
The returned function takes a callback which will be invoked when the generator
returns. The generator itself gets passed a cb
argument as it's final
parameter, which should be passed as the "callback" function on any async calls
that you make, which you should use as expressions in front of a yield
:
{ console console return a + b} const myWrapped =
You can also run a generator directly, via the run
function available on the
exported function (eg, yieldCallback.run()
).
The following are equivalent:
yieldCallback
is equivalent to
const wrapped =
API within the generator function
When the generator function is invoked, it's final argument is a special
callback function to be used with async callback functions called within the
generator. This function can be used as the callback function in an async
callback function, if the function is used in a yield
expression:
{ ... // code following this comment won't run for 1000 milliseconds ...}
The yield
expression returns a value, which is the "result" passed to the
callback. The "error" passed to the callback is available as cb.err
.
{ // fs.readFile()'s cb: (err, fileContents) const fileContents = fs // the `err` argument of the callback is available in `cb.err` if cberr return cberr console // print the file contents}
If the callback is invoked with a non-null first argument, eg cb(err)
, the
result will be null
, and cb.err
will be set to that argument.
If the callback is invoked with a single response value, eg cb(null, 1)
, the
result will be the single response value, and cb.err
will be null
.
If the callback is invoked with multiple response values, eg, cb(null, 1, 2)
,
the result will be an array of the response values, eg [1, 2]
, and cb.err
will be null
.
The value that the generator finally returns will be passed to the original
callback back passed into the wrapped (or run) function. That callback should
have the signature cb(err, data)
.
If the generator returns an instance of Error, the callback will be invoked with that error as the first parameter.
If the generator return anything else, the callback will be invoked with a null error, and that returned object as the second parameter.
In case you're not sure, or know, that the err
object you want to return from
a generator isn't an instance of Error, you can use the function
cb.errorResult()
to wrap your object so that it will be treated as an error
result, rather than a non-error object passed as the second callback parameter:
yieldCallback { const data = fs if cberr return cberr // calls outerCB(err) if cberr return cb // also calls outerCB(err), // even if `cb.err` isn't an // instance of Error return data // calls outerCB(null, data)}