Permalink
Browse files

Commit all files.

  • Loading branch information...
1 parent 3fba99e commit 5a5d8f8eaeafc21d038a36712102da2133b95d53 @nakamura-to committed Mar 18, 2012
Showing with 524 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +3 −0 .npmignore
  3. +4 −0 CHANGELOG.md
  4. +22 −0 LICENSE
  5. +168 −0 README.md
  6. +16 −0 examples/countDown.js
  7. +14 −0 examples/errorCheckSkipping.js
  8. +11 −0 examples/errorHandle.js
  9. +1 −0 examples/file1
  10. +1 −0 examples/file2
  11. +13 −0 examples/loop.js
  12. +24 −0 examples/mapping.js
  13. +11 −0 examples/setTimeout.js
  14. +12 −0 examples/simple.js
  15. +1 −0 index.js
  16. +97 −0 lib/gate.js
  17. +13 −0 package.json
  18. +112 −0 test/gate.js
View
@@ -0,0 +1 @@
+.idea/
View
@@ -0,0 +1,3 @@
+src/
+test/
+.idea/
View
@@ -0,0 +1,4 @@
+# Changelog
+
+ - 0.0.0 (2012/03/18)
+ - first release.
View
22 LICENSE
@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2011 Toshihiro Nakamura
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
View
168 README.md
@@ -0,0 +1,168 @@
+Gate — An utility to await multiple asynchronous calls
+=======================================================
+
+Gate is an utility to await multiple asynchronous calls in node.js.
+
+## Installing
+
+```
+$ npm install await
+```
+
+## Example
+
+```js
+var gate = require('gate');
+var fs = require('fs');
+
+var latch = gate.latch();
+fs.readFile('file1', 'utf8', latch({name: 'file1', data: 1}));
+fs.readFile('file2', 'utf8', latch({name: 'file2', data: 1}));
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
+```
+
+## API
+
+`gate` module provides following API.
+
+### latch([Number count]) -> Function
+
+Return a function which represents a latch. The returned function provides following API.
+
+* `count`: Optional. A number of times the returned function must be called before an awaiting callback can start.
+
+#### ([Object mapping][, Boolean skipErrorCheck]) -> Function
+
+Accept an argument mapping definition and return a callback.
+If a count is given with `gate.latch()`, the count is decremented.
+
+* `mapping`: Optional. An argument mapping definition. The `mappipng` must be a number or an object.
+If the `mapping` is a number, single callback argument is mapped.
+If the `mapping` is an object, multiple callback arguments can be mapped.
+If the `mapping` is `null` or `undefined`, all callback arguments are mapped as Array.
+
+* `skipErrorCheck`: Optional. Indicates whether error check is skipped or not. Default value is `false`.
+
+### count() -> Number
+
+Get a current count, if a count is given with `gate.latch()`.
+Otherwise, `-1` is returned.
+
+#### val(Object value) -> Object
+
+Wrap a value to distinguish between a value as argument and a mapping index.
+
+* `value`: Required. A value.
+
+#### await(Function callback(err, results)) -> Function
+
+Await all asynchronous calls completion and then run a `callback`.
+
+* `callback`: Required. A callback to run after all asynchronous calls completion.
+* `err`: Required. An error to indicate any asynhronous calls are failed.
+* `results`: Required. An array to contain each asynchronous call result as element.
+
+## More Examples
+
+### Arguments Mapping
+
+Pass an argument index or an object includes argument indexs to a function to be returned from `gate.latch()`.
+In the object, values except whose type is `number` are recognized arguments.
+To pass an number as argument, wrap it with `val` function.
+
+```js
+var gate = require('gate');
+var fs = require('fs');
+var exec = require('child_process').exec;
+
+var latch = gate.latch();
+
+// single mapping: arguments[1] in the callback will be result
+fs.readFile('file1', 'utf8', latch(1));
+
+// multiple mapping: arguments[1] and argments[2] in the callback will be result
+exec('cat *.js bad_file | wc -l', latch({stdout: 1, stderr: 2}));
+
+// all mapping: arguments will be result
+fs.readFile('file2', 'utf8', latch());
+
+latch.await(function (err, results) {
+ if (err !== null) {
+ console.log('exec error: ' + err);
+ }
+ console.log('file1: ' + results[0]);
+ console.log('stdout[1]: ' + results[1].stdout);
+ console.log('stderr[1]: ' + results[1].stderr);
+ console.log('file2: ' + results[2]);
+});
+```
+
+### Count Down
+
+Pass a count number to `gate.latch()` to wait until a set of callbacks being made.
+
+```js
+var gate = require('gate');
+var fs = require('fs');
+
+var files = ['file1', 'file2'];
+var latch = gate.latch(files.length);
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
+
+process.nextTick(function () {
+ files.forEach(function (file) {
+ fs.readFile(file, 'utf8', latch({name: file, data: 1}));
+ });
+});
+```
+
+### Error Check Skipping
+
+Pass `true` as 2nd argument to a function to be returned from `gate.latch()`.
+This is useful to check each error one by one.
+
+```js
+var gate = require('gate');
+var fs = require('fs');
+
+var latch = gate.latch();
+fs.readFile('non-existent1', 'utf8', latch({err: 0, data: 1}, true));
+fs.readFile('non-existent2', 'utf8', latch({err: 0, data: 1}, true));
+
+latch.await(function (err, results) {
+ results.forEach(function (result) {
+ if (result.err) {
+ console.log(result.err);
+ }
+ });
+});
+```
+
+### Loop
+
+Call a function to be returned from `gate.latch()` in a loop.
+
+```js
+var gate = require('gate');
+var fs = require('fs');
+
+var latch = gate.latch();
+['file1', 'file2'].forEach(function (file) {
+ fs.readFile(file, 'utf8', latch({name: file, data: 1}));
+});
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
+```
View
@@ -0,0 +1,16 @@
+var gate = require('../index');
+var fs = require('fs');
+
+var files = ['file1', 'file2'];
+var latch = gate.latch(files.length);
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
+
+process.nextTick(function () {
+ files.forEach(function (file) {
+ fs.readFile(file, 'utf8', latch({name: file, data: 1}));
+ });
+});
@@ -0,0 +1,14 @@
+var gate = require('../index');
+var fs = require('fs');
+
+var latch = gate.latch();
+fs.readFile('non-existent1', 'utf8', latch({err: 0, data: 1}, true));
+fs.readFile('non-existent2', 'utf8', latch({err: 0, data: 1}, true));
+
+latch.await(function (err, results) {
+ results.forEach(function (result) {
+ if (result.err) {
+ console.log(result.err);
+ }
+ });
+});
View
@@ -0,0 +1,11 @@
+var gate = require('../index');
+var fs = require('fs');
+
+var latch = gate.latch();
+fs.readFile('file1', 'utf8', latch({name: 'file1', data: 1}));
+fs.readFile('non-existent', 'utf8', latch({name: 'non-existent', data: 1}));
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results);
+});
View
@@ -0,0 +1 @@
+FILE1
View
@@ -0,0 +1 @@
+FILE2
View
@@ -0,0 +1,13 @@
+var gate = require('../index');
+var fs = require('fs');
+
+var latch = gate.latch();
+['file1', 'file2'].forEach(function (file) {
+ fs.readFile(file, 'utf8', latch({name: file, data: 1}));
+});
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
View
@@ -0,0 +1,24 @@
+var gate = require('../index');
+var fs = require('fs');
+var exec = require('child_process').exec;
+
+var latch = gate.latch();
+
+// single mapping: arguments[1] in the callback will be result
+fs.readFile('file1', 'utf8', latch(1));
+
+// multiple mapping: object including arguments[1] and argments[2] in the callback will be result
+exec('cat *.js bad_file | wc -l', latch({stdout: 1, stderr: 2}));
+
+// all mapping: all arguments in the callback will be result
+fs.readFile('file2', 'utf8', latch());
+
+latch.await(function (err, results) {
+ if (err !== null) {
+ console.log('exec error: ' + err);
+ }
+ console.log('file1: ' + results[0]);
+ console.log('stdout[1]: ' + results[1].stdout);
+ console.log('stderr[1]: ' + results[1].stderr);
+ console.log('file2: ' + results[2]);
+});
View
@@ -0,0 +1,11 @@
+var gate = require('../index');
+
+var latch = gate.latch();
+setTimeout(latch({val: 'a'}), 30);
+setTimeout(latch({val: 'b'}), 20);
+setTimeout(latch({val: 'c'}), 10);
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results);
+});
View
@@ -0,0 +1,12 @@
+var gate = require('../index');
+var fs = require('fs');
+
+var latch = gate.latch();
+fs.readFile('file1', 'utf8', latch({name: 'file1', data: 1}));
+fs.readFile('file2', 'utf8', latch({name: 'file2', data: 1}));
+
+latch.await(function (err, results) {
+ if (err) throw err;
+ console.log(results[0]); // { name: 'file1', data: 'FILE1' }
+ console.log(results[1]); // { name: 'file2', data: 'FILE2' }
+});
View
@@ -0,0 +1 @@
+module.exports = require('./lib/gate.js');
Oops, something went wrong.

0 comments on commit 5a5d8f8

Please sign in to comment.