Permalink
Browse files

Allow sync results, catch exceptions, and document everything.

  • Loading branch information...
1 parent df3520f commit a91b456aa79796a36c5bc6ce54647b0666b62b66 @creationix committed Apr 6, 2010
Showing with 156 additions and 2 deletions.
  1. +74 −0 README.markdown
  2. +28 −2 lib/step.js
  3. +54 −0 test.js
View
@@ -0,0 +1,74 @@
+# Step
+
+A simple control-flow library for node.JS that makes parallel execution, serial execution, and error handling painless.
+
+## How to install
+
+Simply copy or link the lib/step.js file into your `$HOME/.node_libraries` folder.
+
+## How to use
+
+The step library exports a single function I call `Step`. It accepts any number of functions as arguments and runs them in serial order using the passed in `this` context as the callback to the next step.
+
+ Step(
+ function readSelf() {
+ fs.readFile(__filename, this);
+ },
+ function capitalize(err, text) {
+ if (err) {
+ throw err;
+ }
+ return text.toUpperCase();
+ },
+ function showIt(err, newText) {
+ sys.puts(newText);
+ }
+ );
+
+Notice that we pass in `this` as the callback to `fs.readFile`. When the file read completes, step will send the result as the arguments to the next function in the chain. Then in the `capitalize` function we're doing synchronous work so we can simple return the new value and Step will route it as if we called the callback.
+
+The first parameter is reserved for errors since this is the node standard. Also any exceptions thrown are caught and passed as the first argument to the next function. As long as you don't nest callback functions inline your main functions this prevents there from ever being any uncaught exceptions. This is very important for long running node.JS servers since a single uncaught exception can bring the whole server down.
paulcarey
paulcarey Feb 15, 2011

"As long as you don't nest callback functions inline your main functions this prevents..." - I'm a little confused by this line.

+
+Also there is support for parallel actions:
+
+ Step(
+ // Loads two files in parallel
+ function loadStuff() {
+ fs.readFile(__filename, this.parallel());
+ fs.readFile("/etc/passwd", this.parallel());
+ },
+ // Show the result when done
+ function showStuff(err, code, users) {
+ if (err) throw err;
+ sys.puts(code);
+ sys.puts(users);
+ }
+ )
+
+Here we pass `this.parallel()` instead of `this` as the callback. It internally keeps track of the number of callbacks issued and preserves their order then giving the result to the next step after all have finished. If there is an error in any of the parallel actions, it will be passed as the first argument to the next step.
+
+Also you can use parallel with a dynamic number of common tasks.
+
+ Step(
+ function readDir() {
+ fs.readdir(__dirname, this);
+ },
+ function readFiles(err, results) {
+ if (err) throw err;
+ // Create a closure to the parallel helper
+ var parallel = this.parallel;
+ results.forEach(function (filename) {
+ if (/\.js$/.test(filename)) {
+ fs.readFile(__dirname + "/" + filename, parallel());
+ }
+ });
+ },
+ function showAll(err /*, file1, file2, ...*/) {
+ if (err) throw err;
+ var files = Array.prototype.slice.call(arguments, 1);
+ sys.p(files);
+ }
+ );
+
+
+Note that we had to create a reference to the `this.parallel` function since the `forEach` creates a new scope and changes `this`. Then using arguments surgery we can extract the contents of the files.
View
@@ -25,33 +25,59 @@ SOFTWARE.
function Step() {
var steps = Array.prototype.slice.call(arguments),
counter, results;
+
+ // Define the main callback that's given as `this` to the steps.
function next() {
+
+ // Check if there are no steps left
if (steps.length === 0) {
+ // Throw uncaught errors
+ if (arguments[0]) {
+ throw arguments[0];
+ }
return;
}
+
+ // Get the next step to execute
var fn = steps.shift();
counter = 0;
results = [];
+
+ // Run the step in a try..catch block so exceptions don't get out of hand.
try {
- fn.apply(next, arguments);
+ var result = fn.apply(next, arguments);
} catch (e) {
+ // Pass any exceptions on through the next callback
next(e);
}
+
+ // If a syncronous return is used, pass it to the callback
+ if (result !== undefined) {
+ next(undefined, result);
+ }
+
}
+
+ // Add a special callback generator `this.parallel()` that groups stuff.
next.parallel = function () {
var i = counter;
counter++;
return function () {
counter--;
+ // Compress the error from any result to the first argument
if (arguments[0]) {
results[0] = arguments[0];
- }
+ }
+ // Send the other results as arguments
results[i + 1] = arguments[1];
if (counter <= 0) {
+ // When they're all done, call the callback
next.apply(null, results);
}
};
};
+
+ // Start the engine an pass nothing to the first step.
next([]);
}
View
54 test.js
@@ -0,0 +1,54 @@
+var Step = require(__dirname + "/lib/step"),
+ fs = require('fs'),
+ sys = require('sys');
+
+Step(
+ function readSelf() {
+ fs.readFile(__filename, this);
+ },
+ function capitalize(err, text) {
+ if (err) {
+ throw err;
+ }
+ return text.toUpperCase();
+ },
+ function showIt(err, newText) {
+ sys.puts(newText);
+ }
+);
+
+
+Step(
+ // Loads two files in parallel
+ function loadStuff() {
+ fs.readFile(__filename, this.parallel());
+ fs.readFile("/etc/passwd", this.parallel());
+ },
+ // Show the result when done
+ function showStuff(err, code, users) {
+ if (err) throw err;
+ sys.puts(code);
+ sys.puts(users);
+ }
+)
+
+Step(
+ function readDir() {
+ fs.readdir(__dirname, this);
+ },
+ function readFiles(err, results) {
+ if (err) throw err;
+ // Create a closure to the parallel helper
+ var parallel = this.parallel;
+ results.forEach(function (filename) {
+ if (/\.js$/.test(filename)) {
+ fs.readFile(__dirname + "/" + filename, parallel());
+ }
+ });
+ },
+ function showAll(err /*, file1, file2, ...*/) {
+ if (err) throw err;
+ var files = Array.prototype.slice.call(arguments, 1);
+ sys.p(files);
+ }
+);

0 comments on commit a91b456

Please sign in to comment.