Control Flow Before `async/await`
A look at the tiny library cflow shows how Node developers wired asynchronous steps into a chain by hand, and why the missing error channel is the real lesson.
Control Flow Before async/await
Node 0.10 knows functions, callbacks and an event loop. What it does not know is a statement that says: “Do this, wait for the result, then do the next thing.” You have to establish this order yourself, step by step, by hand. And as soon as three or four steps build on each other, it becomes visible that “waiting” in a single-threaded environment is not a language feature but a design task.
For this I built myself a small library, cflow. It is so small that you can read it in one go, and that is exactly why it exposes the difference: between a nested callback chain and a pipeline whose transitions you have modeled once.
The problem: building order out of callbacks#
An asynchronous operation in Node follows a convention. It takes a callback as its last argument, and this callback receives a possible error as its first argument. This is called an error-first or node-style callback:
fs.readFile("config.json", function (err, data) {
if (err) return handle(err);
// continue with data
});
For one step that is unremarkable. It gets unpleasant as soon as the next step needs the result of the previous one. Then the second call ends up in the callback of the first, the third in the callback of the second, and so on:
loadUser(id, function (err, user) {
if (err) return done(err);
loadAccount(user.accountId, function (err, account) {
if (err) return done(err);
loadInvoices(account.id, function (err, invoices) {
if (err) return done(err);
done(null, summarize(user, account, invoices));
});
});
});
This shape has earned a fixed name: the pyramid of doom, sometimes also callback hell. The code wanders to the right, the closing brackets pile up, and the actual intent – load three things one after the other and summarize them – disappears behind the mechanics. That is not just a visual annoyance. Every level repeats the same error handling, and that is exactly where mistakes creep in.
The error case almost everyone hits at some point#
The error-first convention demands a discipline that the language itself does not enforce: after if (err) there has to be a return. If it is missing, the function keeps running:
loadUser(id, function (err, user) {
if (err) done(err); // Careful: no return
loadAccount(user.accountId, function (err, account) {
// ...
});
});
In the error case, two things happen here at the same time. done(err) is called, so the caller considers the work finished and reports an error. In the same breath, user.accountId accesses a user that is undefined, because there was an error after all. That throws a second, completely different exception, or done is called a second time – this time with a misleading result. A callback that fires twice is especially nasty, because the order of the messages is no longer guaranteed. Sometimes the real error comes first, sometimes the follow-up error. Such bugs are hard to read in the log, because cause and effect fall apart in time.
That does not mean callbacks are bad. The finding is a different one: if every step writes its error check and its transition to the next step by hand, then every one of these places is an opportunity to get it wrong. What is missing is one place that models the control flow once, instead of reinventing it at every level of nesting.
Libraries that take over the flow#
In 2014 you are not alone with this. Caolan McMahon’s async is the established toolbox and offers named functions for exactly these patterns. async.series runs tasks one after the other, async.parallel at the same time, and async.waterfall passes the result of each step on to the next:
async.waterfall([
function (next) { loadUser(id, next); },
function (user, next) { loadAccount(user.accountId, next); },
function (account, next) { loadInvoices(account.id, next); }
], function (err, invoices) {
if (err) return handle(err);
// done
});
That is flat instead of nested, and there is only one error exit. In parallel, a second approach is maturing: promises. The Promises/A+ specification has caught on, libraries like Q, when.js and bluebird are widespread, and you can write chains with .then(...). A built-in Promise, however, is not reliably available yet in the stable Node version 0.10; that only comes with the V8 update of the 0.11 line. If you want promises today, you add them as a dependency.
cflow: control flow reduced to the bare minimum#
cflow takes the waterfall route, but radically small. The entire library is a single function:
var Flow = function () {
this.args = Array.prototype.slice.call(arguments);
var next = function () {
if (this.args.length > 0) {
this.args.shift();
this.args[0].apply(next, Array.prototype.slice.call(arguments));
}
}.bind(this);
this.args[0].apply(next);
};
The trick is in two lines. Flow receives a list of functions. Each of these functions is called with this bound to next – that is, to the continuation. At the end of its work, a step simply calls this(...). That discards the current step (shift) and calls the next one with exactly the arguments passed to this. The values thus flow on from step to step.
In use, this looks like a straight list of phases instead of a pyramid:
var Flow = require("cflow");
new Flow(
function () {
slow("A", this); // this is the continuation
},
function (data) {
slow2(data + "B", "!!!", this); // data is "A"
},
function (data, data2) {
slow(data + "C" + data2, this); // data is "AB", data2 is "!!!"
},
function (data) {
console.log(data); // "ABC!!!"
}
);
function slow(value, callback) {
setTimeout(function () { callback(value); }, 200);
}
function slow2(value, value2, callback) {
setTimeout(function () { callback(value, value2); }, 300);
}
Each step passes this as the callback to its asynchronous operation. As soon as that is done, the next step becomes active, and the intermediate result is available directly as an argument. Notably, a step can also pass on several values – slow2 returns two, and the following step accepts two. That is exactly the waterfall pattern, just without an array, without options, without dependencies. The package.json simply lists nothing under dependencies.
Chain versus pipeline#
The difference between the two styles is easy to put side by side. The callback chain nests state and error handling deeper with every level. The pipeline lays the steps out next to each other and turns the transitions into a separate, named mechanism.
flowchart TB
subgraph Kette["Callback chain (nested)"]
direction TB
a1["Step 1"] --> a2[" Step 2"]
a2 --> a3[" Step 3"]
a3 --> a4[" Result"]
end
subgraph Pipeline["Pipeline (modeled)"]
direction LR
b1["Step 1"] --> b2["Step 2"]
b2 --> b3["Step 3"]
b3 --> b4["Result"]
endVisually, the pipeline is calmer. More important, though, is what changes structurally. In the pipeline, the transition from step to step exists in only one place, namely in the library. If you want to improve something there – logging, a timeout, a central error switch – you have exactly one place for it. In the nested chain, you would have to repeat the same change at every level.
Where cflow reaches its limit#
And this is where the most honest lesson of this small piece of code lies. cflow models the order cleanly, but it does not model errors. There is no error-first channel, no abort, no try. If a step throws an exception or calls this with an error object, Flow does not handle it – the error is simply passed on as the next argument or falls through. Exactly what the callback convention at least provides for with its err argument is missing here entirely.
That is intentional, the consequence of “as simple as possible.” For a demonstration of control flow it is enough. For a service running under load it is not. With that, the library itself names the limit at which you have to keep thinking: a control flow is only complete once the error path is part of the model too. If you build your own flow function, you should therefore design the next step so that an error aborts the chain and is routed to a single endpoint instead of blindly running on. async.waterfall shows how, by jumping straight to the final callback when there is an error in the first argument.
Looking back from a later time#
Editorial note (July 2026): The following retrospective was added later. The main part of the article describes the state of 2014; the references to ES2015 and ES2017 do not belong to the original time perspective.
If you read this text years later, you know how it resolved. ES2015 brought generators, which together with libraries like co allowed asynchronous code that looked synchronous. And with ES2017, async/await became part of the language. With that, the question that carries this article almost completely disappears from everyday work: you write the order from top to bottom again, the error path is a normal try/catch, and waiting is a keyword.
That does not make the old exercise worthless, though. On the contrary. An await looks harmless and synchronous, but behind it there is still a non-blocking call that can hold resources. The things you had to make clear to yourself by hand in 2014 – where the order is enforced, where an error aborts the chain, where a timeout is missing, what happens with continuations that fire twice – are all still there. They are just hidden under a convenient syntax. If you have built explicit control flow yourself once, you still recognize these limits when the language no longer puts them in front of your eyes.
Further reading#
- Repository cflow: https://github.com/MikeBild/cflow
- caolan/async, documentation of the control flow functions: https://github.com/caolan/async
- Promises/A+ specification: https://promisesaplus.com/
Revised and translated from German with the help of AI.