apr

Travis

Collection of tools to manage control flow of/with Promises - inspired by caolan/async.

Works with and without async/await. The lib itself only uses promises.

As someone beautifully put it:

this is like caolan/async which is like lodash but async, but awaitful

Collections

Functions for manipulating collections, such as arrays and objects.

Applies iteratee to each item in coll, concatenating the results. Returns the concatenated list.

concat(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import concat from 'apr-concat';

const readdir = awaitify(fs.readdir);
const dirs = [
  'dir1',
  'dir2',
  'dir3'
];

const files = await concat(dirs, async (dir) =>
  await readdir(dir)
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Returns true if every element in coll satisfies an async test.

every(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import every from 'apr-every';

const access = awaitify(fs.access);
const files = [
  'file1',
  'file2',
  'file3'
];

const allExist = await every(files, async (file) =>
  await access(file)
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Returns a new array of all the values in coll which pass an async truth test.

filter(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import filter from 'apr-filter';

const access = awaitify(fs.access);
const files = [
  'file1',
  'file2',
  'file3'
];

var existent = await filter(files, async (file) =>
  await access(file)
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Returns the first value in coll that passes an async truth test.

find(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import find from 'apr-find';

const access = awaitify(fs.access);
const files = [
  'file1',
  'file2',
  'file3'
];

const first = await find(files, async (file) =>
  await access(file)
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Applies the function iteratee to each item in coll, in parallel.

for-each(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import forEach from 'apr-for-each';

const writeFile = awaitify(fs.writeFile);
const files = [
  '/home/.vimrc',
  '/home/.zshrc'
];

await forEach(files, async (file) =>
  await writeFile(file, 'boom')
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Produces a new collection of values by mapping each value in coll through the iteratee function.

map(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import map from 'apr-map';

const stat = awaitify(fs.stat);
const files = [
  'file1',
  'file2',
  'file3'
];

const stats = await map(files, async (file) =>
  await stat(file);
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Reduces coll into a single value using an async iteratee to return each successive step.

reduce(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import reduce from 'apr-reduce';

const sum = await reduce([1, 2, 3], async (sum, item) =>
  new Promise((resolve) => resolve(sum + item))
);

The opposite of filter. Removes values that pass an async truth test.

reject(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import reject from 'apr-reject';

const access = awaitify(fs.access);
const files = [
  'file1',
  'file2',
  'file3'
];

var missing = await reject(files, async (file) =>
  await access(file)
);
Static Members
series(input, iteratee)
limit(input, limit, iteratee)

Returns true if at least one element in the coll satisfies an async test.

some(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import some from 'apr-some';

const access = awaitify(fs.access);
const files = [
  'file1',
  'file2',
  'file3'
];

const oneExist = await some(files, async (file) =>
  await access(file)
);
Static Members
series(input, iteratee)
series(input, iteratee)
limit(input, limit, iteratee)

Sorts a list by the results of running each coll value through an async iteratee.

sort-by(input: (Array | Object | Iterable), iteratee: Function): Promise
Parameters
input ((Array | Object | Iterable))
iteratee (Function)
Returns
Promise:
Example
import awaitify from 'apr-awaitify';
import sortBy from 'apr-sort-by';

const stat = awaitify(fs.stat);
const files = [
  'file1',
  'file2',
  'file3'
];

const sorted = await sortBy(files, await (file) => {
  const { mtime } = await stat(file);
  return mtime;
});
Static Members
limit(input, limit, iteratee)

Control Flow

A collection of async functions for controlling the flow through a script.

Creates a function which is a composition of the passed asynchronous functions. Each function consumes the return value of the function that follows. Composing functions f(), g(), and h() would produce the result of f(g(h())).

compose(function: Function): Function
Parameters
function (Function)
Returns
Function:
Example
import compose from 'apr-compose';

const then = (v) => new Promise((resolve) => resolve(v));

const composed = compose(
  async (v) => await then(v + 1),
  async (v) => await then(v + 2),
  async (v) => await then(v + 3)
);

const output = await composed(1); // 7

Run the tasks collection of functions in parallel, without waiting until the previous function has completed.

parallel(tasks: (Array<Promise> | Object)): Promise
Parameters
tasks ((Array<Promise> | Object))
Returns
Promise:
Example
import parallel from 'apr-parallel';

const then = (v) => new Promise((resolve) => resolve(v));

const withArray = await parallel([
  async () => await then(1),
  async () => await then(2)
]);

// withArray = [1, 2]

const withObject = await parallel({
  one: async () => await then(1),
  two: async () => await then(2)
});

// withObject = { one: 1, two: 2 }

Version of the compose function that is more natural to read. Each function consumes the return value of the previous function. It is the equivalent of compose with the arguments reversed.

seq(tasks: ...Function): Function
Parameters
tasks (...Function)
Returns
Function:
Example
import seq from 'apr-seq';

const then = (v) => new Promise((resolve) => resolve(v));

const seq = seq(
  async (v) => await then(v + 1),
  async (v) => await then(v + 2),
  async (v) => await then(v + 3)
);

const output = await seq(1); // 7

Run the functions in the tasks in series, each one running once the previous function has completed.

series(tasks: (Array<Function> | Object)): Promise
Parameters
tasks ((Array<Function> | Object))
Returns
Promise:
Example
import series from 'apr-series';

const then = (v) => new Promise((resolve) => resolve(v));

const withArray = await series([
  async () => await then(1),
  async () => await then(2)
]);

// withArray = [1, 2]

const withObject = await series({
  one: async () => await then(1),
  two: async () => await then(2)
});

// withObject = { one: 1, two: 2 }

Repeatedly call fn until test returns true.

until(test: Function, fn: Function): Promise
Parameters
test (Function)
fn (Function)
Returns
Promise:
Example
import until from 'apr-until';

const then = (v) => new Promise((resolve) => resolve(v));

const maxCalls = 10;
let calls = 0;


const output = await until(async () => {
  await then();
  return (calls += 1) >= maxCalls;
}, async () => (
  await then(calls)
);

// output = 10

Runs the tasks array of functions in series, each passing their results to the next in the array.

waterfall(tasks: (Array<Function> | Object), initial: Any?): Promise
Parameters
tasks ((Array<Function> | Object))
initial (Any?)
Returns
Promise:
Example
import waterfall from 'apr-waterfall';

const then = (v) => new Promise((resolve) => resolve(v));

const output = await waterfall([
  async () => await then(1),
  async (v) => await then(v + 2),
  async (v) => await then(v + 3)
]);

// output = 6

Repeatedly call fn, while test returns true.

whilst(test: Function, fn: Function): Promise
Parameters
test (Function)
fn (Function)
Returns
Promise:
Example
import whilst from 'apr-whilst';

const then = (v) => new Promise((resolve) => resolve(v));

const maxCalls = 10;
let calls = 0;

const output = await whilst(async () => {
  await then();
  return (calls += 1) < maxCalls;
}, async () => (
  await then(calls)
);

// output = 10

Utilities

A collection of awaitable utility functions.

Creates a continuation function with some arguments already applied.

apply(function: Function, arguments: ...Any): Function
Parameters
function (Function)
arguments (...Any)
Returns
Function:
Example
import parallel from 'apr-parallel';
import apply from 'apr-apply';

const then = (v) => new Promise((resolve) => resolve(v));

const output = await parallel([
  apply(then, 1)
  apply(then, 2)
  apply(then, 3)
]);

// output = [1, 2, 3]

Take a sync function and make it async. This is useful for plugging sync functions into a waterfall, series, or other async functions.

asyncify(function: Function): Function
Parameters
function (Function)
Returns
Function:
Example
import awaitify from 'apr-awaitify';
import asyncify from 'apr-asyncify';
import waterfall from 'apr-waterfall';
import apply from 'apr-apply';

const readFile = awaitify(require('fs').readFile);
const pkgPath = path.join(__dirname, './package.json');

const pkg = await waterfall([
  apply(readFile, pkgPath, 'utf8'),
  asyncify(JSON.parse)
]);

Transform a callback-based function into a promise-based one.

awaitify(function: Function): Function
Parameters
function (Function)
Returns
Function:
Example
import { readFile as readFileCb } from 'fs';
import awaitify from 'apr-awaitify';
import path from 'path';

const readFile = awaitify(readFileCb);
const pkgPath = path.join(__dirname, './package.json');

const pkg = await readFile(pkgPath, 'utf-8');

Returns a promise that when called, then's with the values provided. Useful as the first function in a waterfall.

constant(arguments: ...any): Promise
Parameters
arguments (...any)
Returns
Promise:
Example
import asyncify from 'apr-asyncify';
import waterfall from 'apr-waterfall';
import constant from 'apr-constant';

const pkg = await waterfall([
  constant('{"name": "apr"}'),
  asyncify(JSON.parse)
]);

Intercepts errors, the Go way!

intercept(input: Promise): Promise
Parameters
input (Promise)
Returns
Promise:
Example
import ctch from 'apr-intercept';

const [err1, res1] = await ctch(fn(1));
const [err2, res2] = await ctch(fn(1));
const [, res3] = await ctch(fn(3));

Wraps the function in another function that always returns data even when it errors. The object returned has either the property error or value.

reflect(input: Function): Function
Parameters
input (Function)
Returns
Function:
Example
import parallel from 'apr-parallel';
import reflect from 'apr-reflect';

const then = (v) => new Promise((resolve) => resolve(v));

const res = await parallel([
  async () => {
    throw new Error('heyo')
  },
  async () => await then(2)
]);

// res = [{ error: Error('heyo'), value: null }, { error: null, value: 2 }]

Calls the iteratee function n times, and accumulates results in the same manner you would use with map.

times(n: Number, iteratee: Function): Promise
Parameters
n (Number)
iteratee (Function)
Returns
Promise:
Example
import times from 'apr-times';

const then = (v) => new Promise((resolve) => resolve(v));

const res = await times(6, async (i) =>
  await then(i);
);

// res = [0, 1, 2, 3, 4, 5]
Static Members
series(n, iteratee)
limit(n, limit, iteratee)

Catches a promise error, writes the stacktrace to stderr and exists

main(input: Promise): Promise
Parameters
input (Promise)
Returns
Promise:
Example
import main from 'apr-main';

main(async () => 'hello') // writes nothing
main(async () => undefined) // writes nothing
main(async () => { throw new Error('uncaught error') }) // writes the stack trace to stderr and exists

credits

  • both the method signatures and descriptions are copied from caolan/async

license

MIT