You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

233 lines
7.5 KiB

  1. # asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)
  2. Minimal async jobs utility library, with streams support.
  3. [![PhantomJS Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=browser&style=flat)](https://travis-ci.org/alexindigo/asynckit)
  4. [![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)
  5. [![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)
  6. [![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)
  7. [![Dependency Status](https://img.shields.io/david/alexindigo/asynckit/v0.4.0.svg?style=flat)](https://david-dm.org/alexindigo/asynckit)
  8. [![bitHound Overall Score](https://www.bithound.io/github/alexindigo/asynckit/badges/score.svg)](https://www.bithound.io/github/alexindigo/asynckit)
  9. <!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](https://www.npmjs.com/package/reamde) -->
  10. AsyncKit provides harness for `parallel` and `serial` iterators over list of items represented by arrays or objects.
  11. 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.
  12. It ensures async operations to keep behavior more stable and prevent `Maximum call stack size exceeded` errors, from sync iterators.
  13. | compression | size |
  14. | :----------------- | -------: |
  15. | asynckit.js | 12.34 kB |
  16. | asynckit.min.js | 4.11 kB |
  17. | asynckit.min.js.gz | 1.47 kB |
  18. ## Install
  19. ```sh
  20. $ npm install --save asynckit
  21. ```
  22. ## Examples
  23. ### Parallel Jobs
  24. Runs iterator over provided array in parallel. Stores output in the `result` array,
  25. on the matching positions. In unlikely event of an error from one of the jobs,
  26. will terminate rest of the active jobs (if abort function is provided)
  27. and return error along with salvaged data to the main callback function.
  28. #### Input Array
  29. ```javascript
  30. var parallel = require('asynckit').parallel
  31. , assert = require('assert')
  32. ;
  33. var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  34. , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  35. , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  36. , target = []
  37. ;
  38. parallel(source, asyncJob, function(err, result)
  39. {
  40. assert.deepEqual(result, expectedResult);
  41. assert.deepEqual(target, expectedTarget);
  42. });
  43. // async job accepts one element from the array
  44. // and a callback function
  45. function asyncJob(item, cb)
  46. {
  47. // different delays (in ms) per item
  48. var delay = item * 25;
  49. // pretend different jobs take different time to finish
  50. // and not in consequential order
  51. var timeoutId = setTimeout(function() {
  52. target.push(item);
  53. cb(null, item * 2);
  54. }, delay);
  55. // allow to cancel "leftover" jobs upon error
  56. // return function, invoking of which will abort this job
  57. return clearTimeout.bind(null, timeoutId);
  58. }
  59. ```
  60. More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).
  61. #### Input Object
  62. Also it supports named jobs, listed via object.
  63. ```javascript
  64. var parallel = require('asynckit/parallel')
  65. , assert = require('assert')
  66. ;
  67. var source = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  68. , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  69. , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  70. , expectedKeys = [ 'first', 'one', 'two', 'four', 'eight', 'sixteen', 'thirtyTwo', 'sixtyFour' ]
  71. , target = []
  72. , keys = []
  73. ;
  74. parallel(source, asyncJob, function(err, result)
  75. {
  76. assert.deepEqual(result, expectedResult);
  77. assert.deepEqual(target, expectedTarget);
  78. assert.deepEqual(keys, expectedKeys);
  79. });
  80. // supports full value, key, callback (shortcut) interface
  81. function asyncJob(item, key, cb)
  82. {
  83. // different delays (in ms) per item
  84. var delay = item * 25;
  85. // pretend different jobs take different time to finish
  86. // and not in consequential order
  87. var timeoutId = setTimeout(function() {
  88. keys.push(key);
  89. target.push(item);
  90. cb(null, item * 2);
  91. }, delay);
  92. // allow to cancel "leftover" jobs upon error
  93. // return function, invoking of which will abort this job
  94. return clearTimeout.bind(null, timeoutId);
  95. }
  96. ```
  97. More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).
  98. ### Serial Jobs
  99. Runs iterator over provided array sequentially. Stores output in the `result` array,
  100. on the matching positions. In unlikely event of an error from one of the jobs,
  101. will not proceed to the rest of the items in the list
  102. and return error along with salvaged data to the main callback function.
  103. #### Input Array
  104. ```javascript
  105. var serial = require('asynckit/serial')
  106. , assert = require('assert')
  107. ;
  108. var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  109. , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  110. , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  111. , target = []
  112. ;
  113. serial(source, asyncJob, function(err, result)
  114. {
  115. assert.deepEqual(result, expectedResult);
  116. assert.deepEqual(target, expectedTarget);
  117. });
  118. // extended interface (item, key, callback)
  119. // also supported for arrays
  120. function asyncJob(item, key, cb)
  121. {
  122. target.push(key);
  123. // it will be automatically made async
  124. // even it iterator "returns" in the same event loop
  125. cb(null, item * 2);
  126. }
  127. ```
  128. More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).
  129. #### Input Object
  130. Also it supports named jobs, listed via object.
  131. ```javascript
  132. var serial = require('asynckit').serial
  133. , assert = require('assert')
  134. ;
  135. var source = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  136. , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  137. , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  138. , target = []
  139. ;
  140. var source = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  141. , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  142. , expectedTarget = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  143. , target = []
  144. ;
  145. serial(source, asyncJob, function(err, result)
  146. {
  147. assert.deepEqual(result, expectedResult);
  148. assert.deepEqual(target, expectedTarget);
  149. });
  150. // shortcut interface (item, callback)
  151. // works for object as well as for the arrays
  152. function asyncJob(item, cb)
  153. {
  154. target.push(item);
  155. // it will be automatically made async
  156. // even it iterator "returns" in the same event loop
  157. cb(null, item * 2);
  158. }
  159. ```
  160. More examples could be found in [test/test-serial-object.js](test/test-serial-object.js).
  161. _Note: Since _object_ is an _unordered_ collection of properties,
  162. it may produce unexpected results with sequential iterations.
  163. Whenever order of the jobs' execution is important please use `serialOrdered` method._
  164. ### Ordered Serial Iterations
  165. TBD
  166. For example [compare-property](compare-property) package.
  167. ### Streaming interface
  168. TBD
  169. ## Want to Know More?
  170. More examples can be found in [test folder](test/).
  171. Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.
  172. ## License
  173. AsyncKit is licensed under the MIT license.