node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »

metasync

Asynchronous Programming Library

TravisCI bitHound Codacy Badge NPM Version NPM Downloads/Month NPM Downloads

Installation

$ npm install metasync

Create a composed function from flow syntax

metasync.flow(fns)(data, done)

  • fns - array of callback-last functions, callback contranct err-first
  • data - input data
  • done - err-first callback
  • returns: composed callback-last / err-first function

composition

const f = metasync.flow(
  [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]]

Flow methods:

  • flow(data, callback) - composed flow, callback-last and err-first contracts
  • flow.timeout(msec) - set flow timeout
  • flow.cancel() - calcel flow
  • flow.clone() - clone flow
  • flow.pause() - pause flow
  • flow.resume() - resume flow

Collector

metasync.collect(expected)(key, error, value)

  • expected - count or array of string
  • returns: collector instance

Collector methods:

  • collector.collect(key, error, value) - pick or fail
  • collector.pick(key, value) - pick a key
  • collector.fail(key, error) - fail a key
  • collector.take(key, method, ...arguments) - take method result
  • collector.timeout(msec) - set timeout
  • collector.done(callback) - set done listener with err-first contract
  • collector.distinct(true/false) - deny unlisted keys

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);

Parallel execution

metasync.parallel(fns, data, callback)

  • fns - array of callback-last functions, callback contranct err-first
  • data - incoming data (optional)
  • callback - err-first function on done

Example: metasync.parallel([f1, f2, f3], (err, data) => {});

Sequential execution

metasync.sequential(fns, data, callback)

  • fns - array of callback-last functions, callback contranct err-first
  • data - incoming data (optional)
  • callback - err-first function on done

Example:

metasync.sequential([f1, f2, f3], (err, data) => {});

Executes all asynchronous functions and pass first result to callback

metasync.firstOf(fns, callback)

  • fns - array of callback-last functions, callback contranct err-first
  • callback - err-first function on done

Asynchronous map (iterate parallel)

metasync.map(items, fn, done)

  • items - incoming array
  • fn - callback-last (current, callback) => callback(err, value)
    • to be executed for each value in the array
    • current - current element being processed in the array
    • callback - err-first
  • done - optional err-first callback

Asynchrous filter (iterate parallel)

metasync.filter(items)

  • items - incoming array

Example:

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

Asynchronous reduce

metasync.reduce(items, callback, done, initial)

  • items - incoming array
  • callback - function to be executed for each value in array
    • previous - value previously returned in the last iteration
    • current - current element being processed in the array
    • callback - callback for returning value back to function reduce
    • counter - index of the current element being processed in array
    • items - the array reduce was called upon
  • done - optional on done callback function(err, result)
  • initial - optional value to be used as first arpument in first iteration

Asynchronous each (iterate in parallel)

metasync.each(items, fn, done)

  • items - incoming array
  • fn - callback-last (value, callback) => callback(err)
    • value - item from items array
    • callback - callback function(err)
  • done - optional on done callback function(err)

Example:

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

Asynchronous series

metasync.series(items, fn, done)

  • items - incoming array
  • fn - callback-last (value, callback) => callback(err)
    • value - item from items array
    • callback - callback (err)
  • done optional on done callback function(err)

Example:

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

Asynchronous find (iterate in series)

metasync.find(items, fn, done)

  • items - incoming array
  • fn - callback-last (value, callback) => callback(err, accepted)
    • value - item from items array
    • callback - callback function (err, accepted)
  • done - optional on done callback function(err, result)

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);
  }
);

Asynchronous every

metasync.every(items, fn, done)

  • items - incoming array
  • fn - callback-last (value, callback) => callback(err, fits)
    • value - item from items array
    • callback - callback function (err, fits)
  • done - optional on done callback function(err, result)

Asynchronous some (iterate in series)

metasync.some(items)

  • items - incoming array

Create an ArrayChain instance

metasync.for(array)

  • array - start mutations from this data

ConcurrentQueue

new metasync.ConcurrentQueue(concurrency, timeout)

  • concurrency - number of simultaneous and asynchronously executing tasks
  • timeout - process timeout (optional), for single item

Function throttling, executed once per interval

metasync.throttle(timeout, fn, args)

  • timeout - msec interval
  • fn - function to be throttled
  • args - arguments array for fn (optional)

Debounce function, delayed execution

metasync.debounce(timeout, fn, args)

  • timeout - msec
  • fn - function to be debounced
  • args - arguments array for fn (optional)

Set timeout for asynchronous function execution

metasync.timeout(timeout, fn, callback)

  • timeout - time interval
  • fn - async function to be executed
  • callback - callback function on done

Queue instantiation

metasync.queue(concurrency)

  • concurrency - number of simultaneous and asynchronously executing tasks

Transforms function with args arguments and callback

to function with args as separate values and callback metasync.toAsync(fn)

  • fn - function contract callback-last, callback contranct err-first
  • Returns: function with arguments gathered from args as separate values and callback

async function

metasync.asAsync(fn, ...args)

  • fn - function
  • ...args - its argumants

Contributors