README.md (7640B)
1 # asynckit [](https://www.npmjs.com/package/asynckit) 2 3 Minimal async jobs utility library, with streams support. 4 5 [](https://travis-ci.org/alexindigo/asynckit) 6 [](https://travis-ci.org/alexindigo/asynckit) 7 [](https://ci.appveyor.com/project/alexindigo/asynckit) 8 9 [](https://coveralls.io/github/alexindigo/asynckit?branch=master) 10 [](https://david-dm.org/alexindigo/asynckit) 11 [](https://www.bithound.io/github/alexindigo/asynckit) 12 13 <!-- [](https://www.npmjs.com/package/reamde) --> 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.