BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / asynckit / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 7.5 KiB Download Raw

asynckit NPM Module

Minimal async jobs utility library, with streams support.

PhantomJS Build Linux Build Windows Build

Coverage Status Dependency Status bitHound Overall Score

<!-- Readme -->

AsyncKit provides harness for parallel and serial iterators over list of items represented by arrays or objects. 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.

It ensures async operations to keep behavior more stable and prevent Maximum call stack size exceeded errors, from sync iterators.

compressionsize
asynckit.js12.34 kB
asynckit.min.js4.11 kB
asynckit.min.js.gz1.47 kB

Install

$ npm install --save asynckit

Examples

Parallel Jobs

Runs iterator over provided array in parallel. Stores output in the result array, on the matching positions. In unlikely event of an error from one of the jobs, will terminate rest of the active jobs (if abort function is provided) and return error along with salvaged data to the main callback function.

Input Array

var parallel = require('asynckit').parallel
  , assert   = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  , target         = []
  ;

parallel(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// async job accepts one element from the array
// and a callback function
function asyncJob(item, cb)
{
  // different delays (in ms) per item
  var delay = item * 25;

  // pretend different jobs take different time to finish
  // and not in consequential order
  var timeoutId = setTimeout(function() {
    target.push(item);
    cb(null, item * 2);
  }, delay);

  // allow to cancel "leftover" jobs upon error
  // return function, invoking of which will abort this job
  return clearTimeout.bind(null, timeoutId);
}

More examples could be found in test/test-parallel-array.js.

Input Object

Also it supports named jobs, listed via object.

var parallel = require('asynckit/parallel')
  , assert   = require('assert')
  ;

var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  , expectedKeys   = [ 'first', 'one', 'two', 'four', 'eight', 'sixteen', 'thirtyTwo', 'sixtyFour' ]
  , target         = []
  , keys           = []
  ;

parallel(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
  assert.deepEqual(keys, expectedKeys);
});

// supports full value, key, callback (shortcut) interface
function asyncJob(item, key, cb)
{
  // different delays (in ms) per item
  var delay = item * 25;

  // pretend different jobs take different time to finish
  // and not in consequential order
  var timeoutId = setTimeout(function() {
    keys.push(key);
    target.push(item);
    cb(null, item * 2);
  }, delay);

  // allow to cancel "leftover" jobs upon error
  // return function, invoking of which will abort this job
  return clearTimeout.bind(null, timeoutId);
}

More examples could be found in test/test-parallel-object.js.

Serial Jobs

Runs iterator over provided array sequentially. Stores output in the result array, on the matching positions. In unlikely event of an error from one of the jobs, will not proceed to the rest of the items in the list and return error along with salvaged data to the main callback function.

Input Array

var serial = require('asynckit/serial')
  , assert = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  , target         = []
  ;

serial(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// extended interface (item, key, callback)
// also supported for arrays
function asyncJob(item, key, cb)
{
  target.push(key);

  // it will be automatically made async
  // even it iterator "returns" in the same event loop
  cb(null, item * 2);
}

More examples could be found in test/test-serial-array.js.

Input Object

Also it supports named jobs, listed via object.

var serial = require('asynckit').serial
  , assert = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  , target         = []
  ;

var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  , expectedTarget = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , target         = []
  ;


serial(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// shortcut interface (item, callback)
// works for object as well as for the arrays
function asyncJob(item, cb)
{
  target.push(item);

  // it will be automatically made async
  // even it iterator "returns" in the same event loop
  cb(null, item * 2);
}

More examples could be found in test/test-serial-object.js.

_Note: Since _object_ is an _unordered_ collection of properties, it may produce unexpected results with sequential iterations. Whenever order of the jobs' execution is important please use serialOrdered method._

Ordered Serial Iterations

TBD

For example compare-property package.

Streaming interface

TBD

Want to Know More?

More examples can be found in test folder.

Or open an issue with questions and/or suggestions.

License

AsyncKit is licensed under the MIT license.

Source
1# asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)
2
3Minimal 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<!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](https://www.npmjs.com/package/reamde) -->
14
15AsyncKit provides harness for `parallel` and `serial` iterators over list of items represented by arrays or objects.
16Optionally 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
18It 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
37Runs iterator over provided array in parallel. Stores output in the `result` array,
38on the matching positions. In unlikely event of an error from one of the jobs,
39will terminate rest of the active jobs (if abort function is provided)
40and return error along with salvaged data to the main callback function.
41
42#### Input Array
43
44```javascript
45var parallel = require('asynckit').parallel
46 , assert = require('assert')
47 ;
48
49var 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
55parallel(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
63function 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
81More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).
82
83#### Input Object
84
85Also it supports named jobs, listed via object.
86
87```javascript
88var parallel = require('asynckit/parallel')
89 , assert = require('assert')
90 ;
91
92var 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
100parallel(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
108function 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
127More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).
128
129### Serial Jobs
130
131Runs iterator over provided array sequentially. Stores output in the `result` array,
132on the matching positions. In unlikely event of an error from one of the jobs,
133will not proceed to the rest of the items in the list
134and return error along with salvaged data to the main callback function.
135
136#### Input Array
137
138```javascript
139var serial = require('asynckit/serial')
140 , assert = require('assert')
141 ;
142
143var 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
149serial(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
157function 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
167More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).
168
169#### Input Object
170
171Also it supports named jobs, listed via object.
172
173```javascript
174var serial = require('asynckit').serial
175 , assert = require('assert')
176 ;
177
178var 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
184var 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
191serial(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
199function 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
209More 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,
212it may produce unexpected results with sequential iterations.
213Whenever order of the jobs' execution is important please use `serialOrdered` method._
214
215### Ordered Serial Iterations
216
217TBD
218
219For example [compare-property](compare-property) package.
220
221### Streaming interface
222
223TBD
224
225## Want to Know More?
226
227More examples can be found in [test folder](test/).
228
229Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.
230
231## License
232
233AsyncKit is licensed under the MIT license.