twitst4tz

twitter statistics web application
Log | Files | Refs | README | LICENSE

README.md (7640B)


      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 <!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](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.