ff simplifies the most common use cases for series, parallel, and promise utilities.
$ npm install ff
In the browser, simply add a script tag pointing to
lib/ff.js in your HTML page.
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 = require"ff";var f = ffthisfsreadFile"1.txt" fslot;fsreadFile"2.txt" fslot;thissortFileContentsfileA fileB fslot;fpassresulttoUpperCase;onCompletenextFn;
var f = ffthisfsreadFile"1.txt" fslot;;fthen;
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 = ffauthenticateUserreq fslot;fpassuser; // pass the user along synchronouslyusergetFriendsfslot;resjson user: user friends: friends ;onErrornext; // call next() *only* on error
var f = ffcontext stepFunctions
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
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:
fsreadFile"1.txt" fslot; // 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.
fpassdata; // pass data synchronously to the next functionfsexists"1.txt" fslotPlain; // fs.exists doesn't pass (err, result), just (result)emitteronce"close" fwait; // just wait for the "close" event, don't pass any data
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
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.
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.
This is like
f.slot(), except that the resulting callback must not
accept an error, as in
return an error, for instance, and so you must use
its callback instead. (If you had used
f.slot(), it would have
fs.exists had passed an error as the first argument.
f.wait(), this does not pass any
arguments to the next step.
f.slot(), except that the resulting callback will pass
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
body as two arguments to the next step.
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.)
This causes the chain of steps to end successfully (after you return
from the current function). The result handlers (
.onComplete()) will be called as soon as the current step returns. No other
steps will be executed afterward.
This causes the chain of steps to end as though the given error had
occurred (after you return from the current function). The result
.onComplete()) will be called as soon as the
current step returns. No other steps will be executed afterward.
You can add additional steps after calling
Internally, we pass the arguments through this function initially.
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
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 = ff// steps here...onCompleteresultHandler;
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):
.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.)
.onSuccess() handler will only be called if no error occured.
Additionally, an error object will not be passed. Only results.
.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
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.
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 (
.onError()). If a result handler throws an exception, that exception
will bubble up into Node's
unhandledException handler or the
browser's developer console.
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 = ffvar group = fgroup;allMyFilesforEachfsreadFilefile group;;// allFiles is an array of 3 items (the contents of each file).// If any call had returned an err, this function would not be// called, and the error would have been passed down to `onComplete`.onCompletenextFn;
The following are equivalent:
var f = ffthisonetwoonCompletethree;
var f = ffthis;fnextone;fnexttwo;fonCompletethree;
Error handling is actually quite simple: If an error occurs in any
step, it gets passed down to the
onError handler, skipping over any
ff can also be used as a promise library. If you are intersted in managing your own promises,
you can use the
var f = ffdefer;// set callbacks:fthen;// now trigger the result (or rejection)fresult result2; // or f.fail(err);
To trigger success or failure:
farg1 arg2 // successffailerr // failure
In addition to using
then to attach completion handlers, you can also use the regular
.onComplete() to do so.
And just like regular
ff, you can pass functions into
var f = ffdefer// do something with result// ...etc...;fthen;;// now fire the result into the first step!fresult "something else";
If you want to know more about how ff promises work, see the Promises/A+ spec.
The API Documentation provides a much more thorough tutorial.
// Create a chain of steps with the `ff` function:var f = ffcontext// Within each method, use the `f` object.// Most common uses:farg1 arg2; // pass multiple arguments synchronouslyfsreadFile"file1.txt" f; // use f() for async callbacksfsreadFile"file2.txt" fwait; // just wait for the result// without putting it in args// To process arrays, use groups:var group = fgroup;allFilesforEach // use any `f` function on arraysfsreadFileitem groupslot; // and the result gets stored as; // an array in the next step// Less common uses for atypical functionsfsexists"file3.txt" fslotPlain; // fs.exists doesn't pass an errorfsexists"file4.txt" fwaitPlain; // ditto, and I don't care if it failsvar cb = fslotMulti2; // slot and pass two arguments to the next function// for example, cb(null, 1, 2);// Aborting the chain of steps early:fsucceedresult1 ; // after this function, skip the other stepsffailerr; // after this function, fail with this errorftimeout200; // abort if it doesn't finish before 200 milliseconds// Do something amazing here!onCompletenextFn; // <-- usually you'll have someone else handle a (err, result...) callback// Add a timeout (which would result in a failure with a timeout Errorftimeoutmilliseconds;// Don't forget all the result handler options (attach as many as you like!)fonComplete ; // triggered on both success and errorfonSuccess ; // only on successfonError ; // only on error
// Create a deferredvar f = ffdefer;// Add result handlers:fthen;;// Trigger results:farg1 ; // fulfillffailerr; // reject