Asynchronous Programming Library

Installation

$ npm install metasync

Asynchronous functions composition

metasync(fns)(data, done)

• fns - array of callback-last functions, callback contranct err-first
• data - input data (optional)
• done - err-first callback
• Returns: composed callback-last / err-first function

const composed = metasync([f1, f2, f3, [[f4, f5, [f6, f7], f8]], f9]);

• Array of functions gives sequential execution: [f1, f2, f3]
• Double brackets array of functions gives parallel execution: [[f1, f2, f3]]

Example:

const metasync = require('metasync');
const fs = require('fs');

// Data collector (collect keys by count)
const dc = metasync.collect(4);

dc.pick('user', { name: 'Marcus Aurelius' });
fs.readFile('HISTORY.md', (err, data) => dc.collect('history', err, data));
dc.take('readme', fs.readFile, 'README.md');
setTimeout(() => dc.pick('timer', { date: new Date() }), 1000);

// Key collector (collect certain keys by names)
const kc = metasync
  .collect(['user', 'history', 'readme', 'timer'])
  .timeout(2000)
  .distinct()
  .done((err, data) => console.log(data));

kc.pick('user', { name: 'Marcus Aurelius' });
kc.take('history', fs.readFile, 'HISTORY.md');
kc.take('readme', fs.readFile, 'README.md');
setTimeout(() => kc.pick('timer', { date: new Date() }), 1000);

API

callbackify(fn)

• fn: [<Function>][function] promise-returning function

Returns: [<Function>][function]

Convert Promise-returning to callback-last / error-first contract

asyncify(fn)

• fn: [<Function>][function] regular synchronous function

Returns: [<Function>][function] with contract: callback-last / error-first

Convert sync function to callback-last / error-first contract

promiseToCallbackLast(promise, callback)

• promise: [<Promise>][promise]
• callback: [<Function>][function]

Convert Promise to callback-last

promisify(fn)

• fn: [<Function>][function] callback-last function

Returns: [<Function>][function] Promise-returning function

Convert async function to Promise-returning function

promisifySync(fn)

• fn: [<Function>][function] regular synchronous function

Returns: [<Function>][function] Promise-returning function

Convert sync function to Promise object

map(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function] to be executed for each value in the array
  • current: <any> current element being processed in the array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
    • value: <any>
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<Array>][array]

Asynchronous map (iterate parallel)

filter(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function] to be executed for each value in the array
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
    • accepted: [<boolean>][boolean]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<Array>][array]

Asynchrous filter (iterate parallel)

Example:

metasync.filter(
  ['data', 'to', 'filter'],
  (item, callback) => callback(item.length > 2),
  (err, result) => console.dir(result),
);

reduce(items, fn, done[, initial])

• items: [<Array>][array] incoming
• fn: [<Function>][function] to be executed for each value in array
  • previous: <any> value previously returned in the last iteration
  • current: <any> current element being processed in the array
  • callback: [<Function>][function] callback for returning value back to reduce function
    • err: [<Error>][error]|[<null>][null]
    • data: <any> resulting value
  • counter: [<number>][number] index of the current element being processed in array
  • items: [<Array>][array] the array reduce was called upon
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<Array>][array]
• initial: <any> optional value to be used as first argument in first iteration

Asynchronous reduce

reduceRight(items, fn, done[, initial])

• items: [<Array>][array] incoming
• fn: [<Function>][function] to be executed for each value in array
  • previous: <any> value previously returned in the last iteration
  • current: <any> current element being processed in the array
  • callback: [<Function>][function] callback for returning value back to reduce function
    • err: [<Error>][error]|[<null>][null]
    • data: <any> resulting value
  • counter: [<number>][number] index of the current element being processed in array
  • items: [<Array>][array] the array reduce was called upon
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<Array>][array]
• initial: <any> optional value to be used as first argument in first iteration

Asynchronous reduceRight

each(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function]
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • items: [<Array>][array]

Asynchronous each (iterate in parallel)

Example:

metasync.each(
  ['a', 'b', 'c'],
  (item, callback) => {
    console.dir({ each: item });
    callback();
  },
  (err, data) => console.dir('each done'),
);

series(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function]
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • items: [<Array>][array]

Asynchronous series

Example:

metasync.series(
  ['a', 'b', 'c'],
  (item, callback) => {
    console.dir({ series: item });
    callback();
  },
  (err, data) => {
    console.dir('series done');
  },
);

find(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function]
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
    • accepted: [<boolean>][boolean]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: <any>

Asynchronous find (iterate in series)

Example:

metasync.find(
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
  (item, callback) => callback(null, item % 3 === 0 && item % 5 === 0),
  (err, result) => {
    console.dir(result);
  },
);

every(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function]
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
    • accepted: [<boolean>][boolean]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<boolean>][boolean]

Asynchronous every

some(items, fn, done)

• items: [<Array>][array] incoming
• fn: [<Function>][function]
  • value: <any> item from items array
  • callback: [<Function>][function]
    • err: [<Error>][error]|[<null>][null]
    • accepted: [<boolean>][boolean]
• done: [<Function>][function] on done
  • err: [<Error>][error]|[<null>][null]
  • result: [<boolean>][boolean]

Asynchronous some (iterate in series)

asyncMap(items, fn[, options][, done])

• items: [<Array>][array] incoming dataset
• fn: [<Function>][function]
  • item: <any>
  • index: [<number>][number]
• options: [<Object>][object] map params, optional
  • min: [<number>][number] min number of items in one next call
  • percent: [<number>][number] ratio of map time to all time
• done: [<Function>][function] call on done, optional
  • err: [<Error>][error]|[<null>][null]
  • result: [<Array>][array]

Non-blocking synchronous map

asyncIter(base)

• base: [<Iterable>][iterable]|[<AsyncIterable>][asynciterable] an iterable that is wrapped in [<AsyncIterator>][asynciterator]

Returns: [<AsyncIterator>][asynciterator]

Create an AsyncIterator instance

class AsyncIterator

AsyncIterator.prototype.constructor(base)

async AsyncIterator.prototype.next()

async AsyncIterator.prototype.count()

async AsyncIterator.prototype.each(fn, thisArg)

async AsyncIterator.prototype.forEach(fn, thisArg)

async AsyncIterator.prototype.parallel(fn, thisArg)

async AsyncIterator.prototype.every(predicate, thisArg)

async AsyncIterator.prototype.find(predicate, thisArg)

async AsyncIterator.prototype.includes(element)

async As