ff: Concise, Powerful Asynchronous JavaScript Flow Control
ff simplifies the most common use cases for series, parallel, and promise utilities.
Installation
$ npm install ff
In the browser, simply add a script tag pointing to lib/ff.js
in your HTML page.
Table of Contents
Quick Start
ff()
accepts a list of functions to be run in sequential order, and returns an object
that can be used to manage the flow of data between these functions. You may also pass in a
context object as the first parameter, which FF will bind to all function calls.
var ff = ; var f = ;
FF is also Promises/A+ compliant. For more information about using FF promises, see below.
var f = ; f;
A typical Express web handler looks like this. (Note that even if an exception gets thrown during one of these handlers, the .onError() handler will be called.
{ var f = ; // call next() *only* on error}
API Documentation
ff
and save its return value (as f
, perhaps).
First, call var f =
The ff()
function takes a context and any number of
functions, which we call "steps". Each step is run one at a time. Use
ff
's return value (often called f
) to manage the flow of data between
functions.
f
object inside each step function.
Second, use the returned Within your step functions, pass f.slot()
as the callback parameter to
any async function. This reserves a "slot" in the next step's
function arguments. For instance:
fs; // the file contents will be passed to the next function
Most often, that's all you'll need, but there are other ways to leverage FF to handle the flow of data.
f; // pass data synchronously to the next functionfs; // fs.exists doesn't pass (err, result), just (result)emitter; // just wait for the "close" event, don't pass any data
f
:
All Methods on f.slot()
aliased as f()
Calling f.slot()
reserves a slot in the next step's function arguments,
and returns a callback that you should pass into an async function.
The async function should be called with an error as in callback(err, result)
.
f.pass(arg1, arg2...)
aliased as f(arg1, arg2...)
If you call f.pass()
, the arguments will be passed into
the next step. This can be useful when you need to pass along a value
directly to the next function synchronously.
f.wait()
Sometimes you don't want to pass any arguments to the next function,
but you just want to wait until an async call completes successfully.
This behaves exactly like f.slot()
, handling errors, but no data is
passed to the next step.
f.slotPlain()
This is like f.slot()
, except that the resulting callback must not
accept an error, as in callback(result)
. Node's fs.exists
doesn't
return an error, for instance, and so you must use f.slotPlain()
for
its callback instead. (If you had used f.slot()
, it would have
thought fs.exists
had passed an error as the first argument.
f.waitPlain()
See f.slotPlain()
. Like f.wait()
, this does not pass any
arguments to the next step.
f.slotMulti(n)
Like f.slot()
, except that the resulting callback will pass n
arguments
to the next step instead of just one. For instance, calling var cb = f.slotMulti(2)
followed by cb(err, rsp, body)
would pass both rsp
and body
as two arguments to the next step.
f.group()
This reserves exactly one slot in the next step, and returns a group object that has all of the above methods. Anything you slot or pass into the group gets passed into the next function's argument list as an array. (See the Groups example.)
f.succeed(successArgs...)
This causes the chain of steps to end successfully (after you return
from the current function). The result handlers (.onSuccess()
and
.onComplete()
) will be called as soon as the current step returns. No other
steps will be executed afterward.
f.fail(err)
This causes the chain of steps to end as though the given error had
occurred (after you return from the current function). The result
handlers (.onError()
and .onComplete()
) will be called as soon as the
current step returns. No other steps will be executed afterward.
f.next(fn)
You can add additional steps after calling ff()
using f.next(fn)
.
Internally, we pass the arguments through this function initially.
f.timeout(milliseconds)
Set a timeout; if the ff
chain of steps do not finish after this
many milliseconds, fail with a timeout Error. Works with both deferred
and normal ff
steps.
.onComplete
, .onError
, .onSuccess
)
Finally, remember to handle the result! (After you've called ff()
with your steps, you'll want to handle the
final result that gets passed down the end of the function. We often
do this like so:
var f = ;
That final callback will be passed arguments node-style: onComplete(err, results...)
. The number of arguments after err
depends on how many
slots you passed from the last function in the chain.
There are three ways you can handle the final result (and you can mix and match):
f.onComplete( function (err, results...) { } )
A .onComplete()
result handler will always be called, whether or not an
error occurred. An error object will be passed first (null if there
was no error.)
f.onSuccess( function (results...) {} )
A .onSuccess()
handler will only be called if no error occured.
Additionally, an error object will not be passed. Only results.
f.onError( function (err) {} )
A .onError()
result handler will only be called if an error occured.
In this case, err
will never be null. (If you're using Express,
often we use .onError(next)
to propagate whenever we didn't reach a
call to res.send()
.)
Always remember to add one of these result handlers after your
ff()
call, so that errors propagate! You can add multiple result
handlers and they will each be called in the order in which they were registered.
Error Handling
If any function throws an exception, or an error gets passed to one of
the callbacks (as in callback(err, result)
), the error will be
propagated immediately to your result handlers (.onComplete()
and
.onError()
). If a result handler throws an exception, that exception
will bubble up into Node's unhandledException
handler or the
browser's developer console.
Advanced Usage
Groups (for processing arrays)
The f.group()
method reserves exactly one slot in the next step and
returns an object just like f
. Anything you slot or pass into the
group gets passed into the next function's argument list as an
array. This is useful for processing arrays of items. Here's an example:
var allMyFiles = "one.txt" "two.txt" "three.txt"; var f = ;
Implementation Details
The following are equivalent:
var f = ;
var f = ;fnextone;fnexttwo;f;
Error handling is actually quite simple: If an error occurs in any
step, it gets passed down to the onComplete
or onError
handler, skipping over any .next
handlers.
Promise API (Deferreds)
ff
can also be used as a promise library. If you are intersted in managing your own promises,
you can use the defer
helper.
var f = ffdefer; // set callbacks:f; // now trigger the result (or rejection); // or f.fail(err);
To trigger success or failure:
// successf // failure
In addition to using then
to attach completion handlers, you can also use the regular
ff .onSuccess()
, .onError()
, and .onComplete()
to do so.
And just like regular ff
, you can pass functions into ff.defer(...)
:
var f = ffdefer { // do something with result } { // ...etc... }; f; // now fire the result into the first step!;
If you want to know more about how ff promises work, see the Promises/A+ spec.
Quick Reference / Cheat Sheet
The API Documentation provides a much more thorough tutorial.
Control Flow API Summary
// Create a chain of steps with the `ff` function:var f = ; // <-- usually you'll have someone else handle a (err, result...) callback // Add a timeout (which would result in a failure with a timeout Errorf; // Don't forget all the result handler options (attach as many as you like!)f; // triggered on both success and errorf; // only on successf; // only on error
Promise API Summary
// Create a deferredvar f = ffdefer; // Add result handlers:f; // Trigger results: ; // fulfillf; // reject
Acknowledgements
Made by Marcus Cavanaugh and Michael Henretty.
This code was originally based on Tim Caswell's sketch of a reimagined Step library.