From 6816c6b495e3b1a44ce917c721af2b5b8141a1fe Mon Sep 17 00:00:00 2001 From: Blaine Bublitz Date: Mon, 27 Jun 2016 13:21:27 -0700 Subject: [PATCH] Scaffold: Normalize project (closes #10) --- .editorconfig | 12 ++++ .gitignore | 8 ++- LICENSE | 4 +- README.md | 184 +++++++++++++++++++++++++++++--------------------- appveyor.yml | 25 +++++++ package.json | 8 +-- 6 files changed, 155 insertions(+), 86 deletions(-) create mode 100644 .editorconfig create mode 100644 appveyor.yml diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..5760be5 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,12 @@ +# http://editorconfig.org +root = true + +[*] +indent_style = space +indent_size = 2 +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.gitignore b/.gitignore index da23d0d..bfb1212 100644 --- a/.gitignore +++ b/.gitignore @@ -16,10 +16,14 @@ coverage # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) .grunt +# node-waf configuration +.lock-wscript + # Compiled binary addons (http://nodejs.org/api/addons.html) build/Release # Dependency directory -# Deployed apps should consider commenting this line out: -# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git +# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git node_modules + +.DS_Store diff --git a/LICENSE b/LICENSE index 406d1e6..0b2955a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2014 Blaine Bublitz +Copyright (c) 2014 Blaine Bublitz, Eric Schoffstall and other contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ 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. \ No newline at end of file +SOFTWARE. diff --git a/README.md b/README.md index 8829ad1..6d30806 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,38 @@ -bach -==== +

+ + + +

-[![build status](https://secure.travis-ci.org/gulpjs/bach.png)](http://travis-ci.org/gulpjs/bach) +# bach -Compose your async functions with elegance +[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url] + +Compose your async functions with elegance. ## Usage -With Bach, it is very easy to compose async functions to run in series or parallel. +With `bach`, it is very easy to compose async functions to run in series or parallel. ```js var bach = require('bach'); -function fn1(cb){ +function fn1(cb) { cb(null, 1); } -function fn2(cb){ +function fn2(cb) { cb(null, 2); } -function fn3(cb){ +function fn3(cb) { cb(null, 3); } var seriesFn = bach.series(fn1, fn2, fn3); // fn1, fn2, and fn3 will be run in series -seriesFn(function(err, res){ - if(err){ // in this example, err is undefined +seriesFn(function(err, res) { + if (err) { // in this example, err is undefined // handle error } // handle results @@ -36,8 +41,8 @@ seriesFn(function(err, res){ var parallelFn = bach.parallel(fn1, fn2, fn3); // fn1, fn2, and fn3 will be run in parallel -parallelFn(function(err, res){ - if(err){ // in this example, err is undefined +parallelFn(function(err, res) { + if (err) { // in this example, err is undefined // handle error } // handle results @@ -45,13 +50,13 @@ parallelFn(function(err, res){ }); ``` -Since the composer functions just return a function that can be called, you can combine them. +Since the composer functions return a function, you can combine them. ```js var combinedFn = bach.series(fn1, bach.parallel(fn2, fn3)); // fn1 will be executed before fn2 and fn3 are run in parallel -combinedFn(function(err, res){ - if(err){ // in this example, err is undefined +combinedFn(function(err, res) { + if (err) { // in this example, err is undefined // handle error } // handle results @@ -59,26 +64,25 @@ combinedFn(function(err, res){ }); ``` -Functions are called with [async-done](https://github.com/gulpjs/async-done), so you can return a stream or promise. -The function will complete when the stream ends/closes/errors or the promise fulfills/rejects. +Functions are called with [async-done], so you can return a stream, promise, observable or child process. See [`async-done` completion and error resolution][completions] for more detail. ```js // streams var fs = require('fs'); -function streamFn1(){ +function streamFn1() { return fs.createReadStream('./example') .pipe(fs.createWriteStream('./example')); } -function streamFn2(){ +function streamFn2() { return fs.createReadStream('./example') .pipe(fs.createWriteStream('./example')); } var parallelStreams = bach.parallel(streamFn1, streamFn2); -parallelStreams(function(err){ - if(err){ // in this example, err is undefined +parallelStreams(function(err) { + if (err) { // in this example, err is undefined // handle error } // all streams have emitted an 'end' or 'close' event @@ -89,17 +93,17 @@ parallelStreams(function(err){ // promises var when = require('when'); -function promiseFn1(){ +function promiseFn1() { return when.resolve(1); } -function promiseFn2(){ +function promiseFn2() { return when.resolve(2); } var parallelPromises = bach.parallel(promiseFn1, promiseFn2); -parallelPromises(function(err, res){ - if(err){ // in this example, err is undefined +parallelPromises(function(err, res) { + if (err) { // in this example, err is undefined // handle error } // handle results @@ -107,22 +111,22 @@ parallelPromises(function(err, res){ }); ``` -All errors are caught in a [domain](http://nodejs.org/api/domain.html) and passed to the final callback as the first argument. +All errors are caught in a [domain] and passed to the final callback as the first argument. ```js -function success(cb){ - setTimeout(function(){ +function success(cb) { + setTimeout(function() { cb(null, 1); }, 500); } -function error(){ +function error() { throw new Error('Thrown Error'); } var errorThrownFn = bach.parallel(error, success); -errorThrownFn(function(err, res){ - if(err){ +errorThrownFn(function(err, res) { + if (err) { // handle error // in this example, err is an error caught by the domain } @@ -131,25 +135,24 @@ errorThrownFn(function(err, res){ }); ``` -Something that may be encountered when an error happens in a parallel composition is the callback -will be called as soon as the error happens. If you want to continue on error and wait until all -functions have finished before calling the callback, use `settleSeries` or `settleParallel`. +When an error happens in a parallel composition, the callback will be called as soon as the error happens. +If you want to continue on error and wait until all functions have finished before calling the callback, use `settleSeries` or `settleParallel`. ```js -function success(cb){ - setTimeout(function(){ +function success(cb) { + setTimeout(function() { cb(null, 1); }, 500); } -function error(cb){ +function error(cb) { cb(new Error('Async Error')); } var parallelSettlingFn = bach.settleParallel(success, error); -parallelSettlingFn(function(err, res){ +parallelSettlingFn(function(err, res) { // all functions have finished executing - if(err){ + if (err) { // handle error // in this example, err is an error passed to the callback } @@ -160,65 +163,90 @@ parallelSettlingFn(function(err, res){ ## API -__All bach APIs return an invoker function that takes a single callback as its only parameter. -The function signature is `function(error, results)`.__ +### `series(fns..., [extensions])` + +Takes a variable amount of functions (`fns`) to be called in series when the returned function is +called. Optionally, takes an [extensions](#extensions) object as the last argument. + +Returns an `invoker(cb)` function to be called to start the serial execution. The invoker function takes a callback (`cb`) with the `function(error, results)` signature. + +If all functions complete successfully, the callback function will be called with all `results` as the second argument. + +If an error occurs, execution will stop and the error will be passed to the callback function as the first parameter. The error parameter will always be a single error. + +### `parallel(fns..., [extensions])` + +Takes a variable amount of functions (`fns`) to be called in parallel when the returned function is +called. Optionally, takes an [extensions](#extensions) object as the last argument. + +Returns an `invoker(cb)` function to be called to start the parallel execution. The invoker function takes a callback (`cb`) with the `function(error, results)` signature. + +If all functions complete successfully, the callback function will be called with all `results` as the second argument. + +If an error occurs, the callback function will be called with the error as the first parameter. Any async functions that have not completed, will still complete, but their results will __not__ be available. The error parameter will always be a single error. + +### `settleSeries(fns..., [extensions])` + +Takes a variable amount of functions (`fns`) to be called in series when the returned function is +called. Optionally, takes an [extensions](#extensions) object as the last argument. + +Returns an `invoker(cb)` function to be called to start the serial execution. The invoker function takes a callback (`cb`) with the `function(error, results)` signature. + +All functions will always be called and the callback will receive all settled errors and results. If any errors occur, the error parameter will be an array of errors. + +### `settleParallel(fns..., [extensions])` -Each method can optionally be passed an object of [extension point functions](#extension-points) -as the last argument. +Takes a variable amount of functions (`fns`) to be called in parallel when the returned function is +called. Optionally, takes an [extensions](#extensions) object as the last argument. -### `series(fns..., [extensions])` => Function +Returns an `invoker(cb)` function to be called to start the parallel execution. The invoker function takes a callback (`cb`) with the `function(error, results)` signature. -All functions (`fns`) passed to this function will be called in series when the returned function is -called. If an error occurs, execution will stop and the error will be passed to the callback function -as the first parameter. +All functions will always be called and the callback will receive all settled errors and results. If any errors occur, the error parameter will be an array of errors. -__The error parameter will always be a single error.__ +### `extensions` -### `parallel(fns..., [extensions])` => Function +The `extensions` object is used for specifying functions that give insight into the lifecycle of each function call. The possible extension points are `create`, `before`, `after` and `error`. If an extension point is not specified, it defaults to a no-op function. -All functions (`fns`) passed to this function will be called in parallel when the returned -function is called. If an error occurs, the error will be passed to the callback function -as the first parameter. Any async functions that have not completed, will still complete, -but their results will __not__ be available. +##### `extensions.create(fn, index)` -__The error parameter will always be a single error.__ +Called at the very beginning of each function call with the function (`fn`) being executed and the `index` from the array/arguments. If `create` returns a value (`storage`), it is passed to the `before`, `after` and `error` extension points. -### `settleSeries(fns..., [extensions])` => Function +If a value is not returned, an empty object is used as `storage` for each other extension point. -All functions (`fns`) passed to this function will be called in series when the returned function is -called. All functions will always be called and the callback will receive all settled errors and results. +This is useful for tracking information across an iteration. -__The error parameter will always be an array of errors.__ +##### `extensions.before(storage)` -### `settleParallel(fns..., [extensions])` => Function +Called immediately before each function call with the `storage` value returned from the `create` extension point. -All functions (`fns`) passed to this function will be called in parallel when the returned function is -called. All functions will always be called and the callback will receive all settled errors and results. +##### `extensions.after(result, storage)` -__The error parameter will always be an array of errors.__ +Called immediately after each function call with the `result` of the function and the `storage` value returned from the `create` extension point. -### Extension Points +##### `extensions.error(error, storage)` -An extension point object can contain: +Called immediately after a failed function call with the `error` of the function and the `storage` value returned from the `create` extension point. -#### `create(fn, key)` => `storage` object +## License -Called before the async function or extension points are called. Receives the function and key to be -executed in the future. The return value should be any object and will be passed to the other extension -point methods. The storage object can keep any information needed between extension points and can -be mutated within extension points. +MIT -#### `before(storage)` +[domain]: http://nodejs.org/api/domain.html +[async-done]: https://github.com/gulpjs/async-done +[completions]: https://github.com/gulpjs/async-done#completion-and-error-resolution -Called before the async function is executed. Receives the storage object returned from the `create` -extension point. +[downloads-image]: http://img.shields.io/npm/dm/bach.svg +[npm-url]: https://www.npmjs.com/package/bach +[npm-image]: http://img.shields.io/npm/v/bach.svg -#### `after(storage)` +[travis-url]: https://travis-ci.org/gulpjs/bach +[travis-image]: http://img.shields.io/travis/gulpjs/bach.svg?label=travis-ci -Called after the async function is executed and completes successfully. Receives the storage object -returned from the `create` extension point. +[appveyor-url]: https://ci.appveyor.com/project/gulpjs/bach +[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/bach.svg?label=appveyor -#### `error(storage)` +[coveralls-url]: https://coveralls.io/r/gulpjs/bach +[coveralls-image]: http://img.shields.io/coveralls/gulpjs/bach/master.svg -Called after the async function is executed and errors. Receives the storage object returned from -the `create` extension point. +[gitter-url]: https://gitter.im/gulpjs/gulp +[gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 0000000..625fc10 --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,25 @@ +# http://www.appveyor.com/docs/appveyor-yml +# http://www.appveyor.com/docs/lang/nodejs-iojs + +environment: + matrix: + # node.js + - nodejs_version: "0.10" + - nodejs_version: "0.12" + - nodejs_version: "4" + - nodejs_version: "5" + - nodejs_version: "6" + +install: + - ps: Install-Product node $env:nodejs_version + - npm install + +test_script: + - node --version + - npm --version + - cmd: npm test + +build: off + +# build version format +version: "{build}" diff --git a/package.json b/package.json index 89f4166..9f29835 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,12 @@ { "name": "bach", "version": "0.5.0", - "description": "Compose your async functions with elegance", - "author": "Blaine Bublitz (http://iceddev.com/)", + "description": "Compose your async functions with elegance.", + "author": "Gulp Team (http://gulpjs.com/)", "contributors": [ - "Blaine Bublitz (http://iceddev.com/)", + "Blaine Bublitz ", "Pawel Kozlowski ", - "Benjamin Tan (https://d10.github.io/)" + "Benjamin Tan " ], "repository": "gulpjs/bach", "license": "MIT",