1 # asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)
3 Minimal async jobs utility library, with streams support.
5 [![PhantomJS Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=browser&style=flat)](https://travis-ci.org/alexindigo/asynckit)
6 [![Linux Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=linux:0.12-6.x&style=flat)](https://travis-ci.org/alexindigo/asynckit)
7 [![Windows Build](https://img.shields.io/appveyor/ci/alexindigo/asynckit/v0.4.0.svg?label=windows:0.12-6.x&style=flat)](https://ci.appveyor.com/project/alexindigo/asynckit)
9 [![Coverage Status](https://img.shields.io/coveralls/alexindigo/asynckit/v0.4.0.svg?label=code+coverage&style=flat)](https://coveralls.io/github/alexindigo/asynckit?branch=master)
10 [![Dependency Status](https://img.shields.io/david/alexindigo/asynckit/v0.4.0.svg?style=flat)](https://david-dm.org/alexindigo/asynckit)
11 [![bitHound Overall Score](https://www.bithound.io/github/alexindigo/asynckit/badges/score.svg)](https://www.bithound.io/github/alexindigo/asynckit)
13 <!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](https://www.npmjs.com/package/reamde) -->
15 AsyncKit provides harness for `parallel` and `serial` iterators over list of items represented by arrays or objects.
16 Optionally it accepts abort function (should be synchronously return by iterator for each item), and terminates left over jobs upon an error event. For specific iteration order built-in (`ascending` and `descending`) and custom sort helpers also supported, via `asynckit.serialOrdered` method.
18 It ensures async operations to keep behavior more stable and prevent `Maximum call stack size exceeded` errors, from sync iterators.
20 | compression | size |
21 | :----------------- | -------: |
22 | asynckit.js | 12.34 kB |
23 | asynckit.min.js | 4.11 kB |
24 | asynckit.min.js.gz | 1.47 kB |
30 $ npm install --save asynckit
37 Runs iterator over provided array in parallel. Stores output in the `result` array,
38 on the matching positions. In unlikely event of an error from one of the jobs,
39 will terminate rest of the active jobs (if abort function is provided)
40 and return error along with salvaged data to the main callback function.
45 var parallel = require('asynckit').parallel
46 , assert = require('assert')
49 var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
50 , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
51 , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
55 parallel(source, asyncJob, function(err, result)
57 assert.deepEqual(result, expectedResult);
58 assert.deepEqual(target, expectedTarget);
61 // async job accepts one element from the array
62 // and a callback function
63 function asyncJob(item, cb)
65 // different delays (in ms) per item
66 var delay = item * 25;
68 // pretend different jobs take different time to finish
69 // and not in consequential order
70 var timeoutId = setTimeout(function() {
75 // allow to cancel "leftover" jobs upon error
76 // return function, invoking of which will abort this job
77 return clearTimeout.bind(null, timeoutId);
81 More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).
85 Also it supports named jobs, listed via object.
88 var parallel = require('asynckit/parallel')
89 , assert = require('assert')
92 var source = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
93 , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
94 , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
95 , expectedKeys = [ 'first', 'one', 'two', 'four', 'eight', 'sixteen', 'thirtyTwo', 'sixtyFour' ]
100 parallel(source, asyncJob, function(err, result)
102 assert.deepEqual(result, expectedResult);
103 assert.deepEqual(target, expectedTarget);
104 assert.deepEqual(keys, expectedKeys);
107 // supports full value, key, callback (shortcut) interface
108 function asyncJob(item, key, cb)
110 // different delays (in ms) per item
111 var delay = item * 25;
113 // pretend different jobs take different time to finish
114 // and not in consequential order
115 var timeoutId = setTimeout(function() {
121 // allow to cancel "leftover" jobs upon error
122 // return function, invoking of which will abort this job
123 return clearTimeout.bind(null, timeoutId);
127 More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).
131 Runs iterator over provided array sequentially. Stores output in the `result` array,
132 on the matching positions. In unlikely event of an error from one of the jobs,
133 will not proceed to the rest of the items in the list
134 and return error along with salvaged data to the main callback function.
139 var serial = require('asynckit/serial')
140 , assert = require('assert')
143 var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
144 , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
145 , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
149 serial(source, asyncJob, function(err, result)
151 assert.deepEqual(result, expectedResult);
152 assert.deepEqual(target, expectedTarget);
155 // extended interface (item, key, callback)
156 // also supported for arrays
157 function asyncJob(item, key, cb)
161 // it will be automatically made async
162 // even it iterator "returns" in the same event loop
167 More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).
171 Also it supports named jobs, listed via object.
174 var serial = require('asynckit').serial
175 , assert = require('assert')
178 var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
179 , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
180 , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
184 var source = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
185 , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
186 , expectedTarget = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
191 serial(source, asyncJob, function(err, result)
193 assert.deepEqual(result, expectedResult);
194 assert.deepEqual(target, expectedTarget);
197 // shortcut interface (item, callback)
198 // works for object as well as for the arrays
199 function asyncJob(item, cb)
203 // it will be automatically made async
204 // even it iterator "returns" in the same event loop
209 More examples could be found in [test/test-serial-object.js](test/test-serial-object.js).
211 _Note: Since _object_ is an _unordered_ collection of properties,
212 it may produce unexpected results with sequential iterations.
213 Whenever order of the jobs' execution is important please use `serialOrdered` method._
215 ### Ordered Serial Iterations
219 For example [compare-property](compare-property) package.
221 ### Streaming interface
225 ## Want to Know More?
227 More examples can be found in [test folder](test/).
229 Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.
233 AsyncKit is licensed under the MIT license.