1 | # asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)
|
2 |
|
3 | Minimal async jobs utility library, with streams support.
|
4 |
|
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)
|
8 |
|
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)
|
12 |
|
13 |
|
14 |
|
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.
|
17 |
|
18 | It ensures async operations to keep behavior more stable and prevent `Maximum call stack size exceeded` errors, from sync iterators.
|
19 |
|
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 |
|
25 |
|
26 |
|
27 | ## Install
|
28 |
|
29 | ```sh
|
30 | $ npm install --save asynckit
|
31 | ```
|
32 |
|
33 | ## Examples
|
34 |
|
35 | ### Parallel Jobs
|
36 |
|
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.
|
41 |
|
42 | #### Input Array
|
43 |
|
44 | ```javascript
|
45 | var parallel = require('asynckit').parallel
|
46 | , assert = require('assert')
|
47 | ;
|
48 |
|
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 ]
|
52 | , target = []
|
53 | ;
|
54 |
|
55 | parallel(source, asyncJob, function(err, result)
|
56 | {
|
57 | assert.deepEqual(result, expectedResult);
|
58 | assert.deepEqual(target, expectedTarget);
|
59 | });
|
60 |
|
61 | // async job accepts one element from the array
|
62 | // and a callback function
|
63 | function asyncJob(item, cb)
|
64 | {
|
65 | // different delays (in ms) per item
|
66 | var delay = item * 25;
|
67 |
|
68 | // pretend different jobs take different time to finish
|
69 | // and not in consequential order
|
70 | var timeoutId = setTimeout(function() {
|
71 | target.push(item);
|
72 | cb(null, item * 2);
|
73 | }, delay);
|
74 |
|
75 | // allow to cancel "leftover" jobs upon error
|
76 | // return function, invoking of which will abort this job
|
77 | return clearTimeout.bind(null, timeoutId);
|
78 | }
|
79 | ```
|
80 |
|
81 | More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).
|
82 |
|
83 | #### Input Object
|
84 |
|
85 | Also it supports named jobs, listed via object.
|
86 |
|
87 | ```javascript
|
88 | var parallel = require('asynckit/parallel')
|
89 | , assert = require('assert')
|
90 | ;
|
91 |
|
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' ]
|
96 | , target = []
|
97 | , keys = []
|
98 | ;
|
99 |
|
100 | parallel(source, asyncJob, function(err, result)
|
101 | {
|
102 | assert.deepEqual(result, expectedResult);
|
103 | assert.deepEqual(target, expectedTarget);
|
104 | assert.deepEqual(keys, expectedKeys);
|
105 | });
|
106 |
|
107 | // supports full value, key, callback (shortcut) interface
|
108 | function asyncJob(item, key, cb)
|
109 | {
|
110 | // different delays (in ms) per item
|
111 | var delay = item * 25;
|
112 |
|
113 | // pretend different jobs take different time to finish
|
114 | // and not in consequential order
|
115 | var timeoutId = setTimeout(function() {
|
116 | keys.push(key);
|
117 | target.push(item);
|
118 | cb(null, item * 2);
|
119 | }, delay);
|
120 |
|
121 | // allow to cancel "leftover" jobs upon error
|
122 | // return function, invoking of which will abort this job
|
123 | return clearTimeout.bind(null, timeoutId);
|
124 | }
|
125 | ```
|
126 |
|
127 | More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).
|
128 |
|
129 | ### Serial Jobs
|
130 |
|
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.
|
135 |
|
136 | #### Input Array
|
137 |
|
138 | ```javascript
|
139 | var serial = require('asynckit/serial')
|
140 | , assert = require('assert')
|
141 | ;
|
142 |
|
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 ]
|
146 | , target = []
|
147 | ;
|
148 |
|
149 | serial(source, asyncJob, function(err, result)
|
150 | {
|
151 | assert.deepEqual(result, expectedResult);
|
152 | assert.deepEqual(target, expectedTarget);
|
153 | });
|
154 |
|
155 | // extended interface (item, key, callback)
|
156 | // also supported for arrays
|
157 | function asyncJob(item, key, cb)
|
158 | {
|
159 | target.push(key);
|
160 |
|
161 | // it will be automatically made async
|
162 | // even it iterator "returns" in the same event loop
|
163 | cb(null, item * 2);
|
164 | }
|
165 | ```
|
166 |
|
167 | More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).
|
168 |
|
169 | #### Input Object
|
170 |
|
171 | Also it supports named jobs, listed via object.
|
172 |
|
173 | ```javascript
|
174 | var serial = require('asynckit').serial
|
175 | , assert = require('assert')
|
176 | ;
|
177 |
|
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 ]
|
181 | , target = []
|
182 | ;
|
183 |
|
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 ]
|
187 | , target = []
|
188 | ;
|
189 |
|
190 |
|
191 | serial(source, asyncJob, function(err, result)
|
192 | {
|
193 | assert.deepEqual(result, expectedResult);
|
194 | assert.deepEqual(target, expectedTarget);
|
195 | });
|
196 |
|
197 | // shortcut interface (item, callback)
|
198 | // works for object as well as for the arrays
|
199 | function asyncJob(item, cb)
|
200 | {
|
201 | target.push(item);
|
202 |
|
203 | // it will be automatically made async
|
204 | // even it iterator "returns" in the same event loop
|
205 | cb(null, item * 2);
|
206 | }
|
207 | ```
|
208 |
|
209 | More examples could be found in [test/test-serial-object.js](test/test-serial-object.js).
|
210 |
|
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._
|
214 |
|
215 | ### Ordered Serial Iterations
|
216 |
|
217 | TBD
|
218 |
|
219 | For example [compare-property](compare-property) package.
|
220 |
|
221 | ### Streaming interface
|
222 |
|
223 | TBD
|
224 |
|
225 | ## Want to Know More?
|
226 |
|
227 | More examples can be found in [test folder](test/).
|
228 |
|
229 | Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.
|
230 |
|
231 | ## License
|
232 |
|
233 | AsyncKit is licensed under the MIT license.
|