Permalink
Browse files

Make return values available in a second parameter when an error is r…

…eturned.
  • Loading branch information...
1 parent debb718 commit ccc7be55c2b44cfebc417027853fcc4dc2690b24 @alexkwolfe committed Aug 16, 2010
Showing with 59 additions and 17 deletions.
  1. +24 −14 README.md
  2. +2 −2 lib/gang-bang.js
  3. +1 −1 package.json
  4. +16 −0 test/unit/chain_test.js
  5. +16 −0 test/unit/group_test.js
View
@@ -31,14 +31,12 @@ A flow control library for node.js for executing multiple functions as a group o
## Function results
-You must invoke the `done` function in each of your functions. This notifies the `group` or
-`chain` process that the function is done executing and provides an opportunity to return
-results.
+To retrieve "return values" from each of your functions, pass the return value the `done` callback.
+You must invoke `done` even if you don't want to return a value — it provides the execution flow
+control.
-Once all the `done` functions have been invoked, the callback is invoked with a parameter
-that contains an array of the function results. Note that the results are in the same order
-that the functions are declared, even for the `group` function. So if you're looking for the
-"return value" of the second function you can examine the results at the 1st array index.
+The return values are passed in an array to the callback in the same order that the functions
+are declared.
## Handling null and undefined results
@@ -48,7 +46,8 @@ If the `done` method is called with a `null` parameter or no parameter, then `nu
## Error handling
If an error occurs in a function, pass the error to the `done` method. When an error occurs
-execution stops and the error is returned to the callback. Other result values are discarded
+execution stops and the error is returned to the callback. Other result values collected up to that
+point are available in the second callback parameter.
It's up to you to check for errors in the values passed to the callback function and behave accordingly.
@@ -63,13 +62,24 @@ It's up to you to check for errors in the values passed to the callback function
function(done) { done('blue'); }
];
- // execute functions concurrently, and callback when all functions have been called
- gang.group(functions, function(colors) {
- puts("Colors is an error: " + colors);
+ // execute functions concurrently.
+ // stop execution and callback when an error occurs.
+ gang.group(functions, function(err, colors) {
+ if (err instanceof Error) {
+ puts("An error occurred: " + err);
+ puts("Here are the colors collected before the error: " + colors);
+ } else {
+ puts("No error occurred. Here are the colors: " + err);
+ }
});
// execute each one after the other, and callback when the error occurs
- // non-error results are discarded.
- gang.chain(functions, function(colors) {
- puts("Colors is an error: " + colors);
+ // non-error results are provided in the second parameter.
+ gang.chain(functions, function(err, colors) {
+ if (err instanceof Error) {
+ puts("An error occurred: " + err);
+ puts("Here are the colors collected before the error: " + colors);
+ } else {
+ puts("No error occurred. Here are the colors: " + err);
+ }
});
View
@@ -15,7 +15,7 @@ exports.group = function (fxns, cb) {
var callGroupFunction = function(i, fxn) {
var done = function(result) {
if (result instanceof Error)
- return cb(result);
+ return cb(result, results);
results[i] = result;
@@ -44,7 +44,7 @@ exports.chain = function (fxns, callback) {
var done = function(result) {
pos++;
if (result instanceof Error)
- return callback(result);
+ return callback(result, results);
results.push(result);
View
@@ -1,6 +1,6 @@
{ "name" : "gang-bang"
, "description" : "An execution flow-control utility."
-, "version" : "0.1.1"
+, "version" : "0.1.3"
, "homepage" : "http://github.com/alexkwolfe/gang-bang"
, "author" : "Alex Wolfe <alexkwolfe@gmail.com>"
, "contributors" : []
View
@@ -77,4 +77,20 @@ exports.testStopsOnError = function(assert) {
assert.equals('green', colors.message);
assert.done();
});
+};
+
+exports.testResultsAvailableOnError = function(assert) {
+ assert.expect(2);
+
+ var functions = [
+ function(done) { done('red'); },
+ function(done) { done(new Error('green')); },
+ function(done) { done('blue'); }
+ ];
+
+ gang.chain(functions, function(err, colors) {
+ assert.ok(err instanceof Error);
+ assert.same(['red'], colors);
+ assert.done();
+ });
};
View
@@ -79,4 +79,20 @@ exports.testStopsOnError = function(assert) {
assert.equals('green', colors.message);
assert.done();
});
+};
+
+exports.testResultsAvailableOnError = function(assert) {
+ assert.expect(2);
+
+ var functions = [
+ function(done) { done('red'); },
+ function(done) { done(new Error('green')); },
+ function(done) { done('blue'); }
+ ];
+
+ gang.chain(functions, function(err, colors) {
+ assert.ok(err instanceof Error);
+ assert.same(['red'], colors);
+ assert.done();
+ });
};

0 comments on commit ccc7be5

Please sign in to comment.