Awesome

apr

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
- concat
- every
- filter
- find
- for-each
- map
- reduce
- reject
- some
- sort-by
Control Flow
- compose
- parallel
- seq
- series
- until
- waterfall
- whilst
Utilities
- apply
- asyncify
- awaitify
- constant
- intercept
- reflect
- times
- main
credits
license

Collections

Functions for manipulating collections, such as arrays and objects.

concat

packages/concat/index.js:30-35

<a id="concat"></a> Applies iteratee to each item in coll, concatenating the results. Returns the concatenated list.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/concat/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/concat/limit.js:13-23

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

every

packages/every/index.js:30-35

<a id="every"></a> Returns true if every element in coll satisfies an async test.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/every/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/every/limit.js:14-24

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

filter

packages/filter/index.js:31-31

<a id="filter"></a> Returns a new array of all the values in coll which pass an async truth test.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/filter/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/filter/limit.js:13-14

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

find

packages/find/index.js:30-35

<a id="find"></a> Returns the first value in coll that passes an async truth test.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/find/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/find/limit.js:13-23

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

for-each

packages/for-each/index.js:29-34

<a id="for-each"></a> Applies the function iteratee to each item in coll, in parallel.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/for-each/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/for-each/limit.js:13-23

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

map

packages/map/index.js:30-35

<a id="map"></a> Produces a new collection of values by mapping each value in coll through the iteratee function.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/map/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/map/limit.js:13-23

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

reduce

packages/reduce/index.js:23-33

<a id="reduce"></a> Reduces coll into a single value using an async iteratee to return each successive step.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

import reduce from 'apr-reduce';

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

Returns Promise

reject

packages/reject/index.js:31-31

<a id="reject"></a> The opposite of filter. Removes values that pass an async truth test.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/reject/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/reject/limit.js:13-14

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

some

packages/some/index.js:31-31

<a id="some"></a> Returns true if at least one element in the coll satisfies an async test.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

series

packages/some/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

series

packages/sort-by/series.js:11-11

Parameters

input (Array | Object | Iterable)
iteratee Function

Returns Promise

limit

packages/some/limit.js:13-13

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

sort-by

packages/sort-by/index.js:32-32

<a id="sort-by"></a> Sorts a list by the results of running each coll value through an async iteratee.

Parameters

input (Array | Object | Iterable)
iteratee Function

Examples

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

Returns Promise

limit

packages/sort-by/limit.js:13-14

Parameters

input (Array | Object | Iterable)
limit Number
iteratee Function

Returns Promise

Control Flow

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

compose

packages/compose/index.js:28-31

<a id="sompose"></a> 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())).

Parameters

function Function

Examples

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

Returns Function

parallel

packages/parallel/index.js:34-46

<a id="parallel"></a> Run the tasks collection of functions in parallel, without waiting until the previous function has completed.

Parameters

tasks (Array<Promise> | Object)

Examples

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 }

Returns Promise

seq

packages/seq/index.js:27-27

<a id="seq"></a> 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.

Parameters

tasks ...Function

Examples

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

Returns Function

series

packages/series/index.js:34-46

<a id="series"></a> Run the functions in the tasks in series, each one running once the previous function has completed.

Parameters

tasks (Array<Function> | Object)

Examples

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 }

Returns Promise

until

packages/until/index.js:33-38

<a id="until"></a> Repeatedly call fn until test returns true.

Parameters

test Function
fn Function

Examples

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

Returns Promise

waterfall

packages/waterfall/index.js:28-41

<a id="waterfall"></a> Runs the tasks array of functions in series, each passing their results to the next in the array.

Parameters

tasks (Array<Function> | Object)
initial Any?

Examples

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

Returns Promise

whilst

packages/whilst/index.js:32-37

<a id="whilst"></a> Repeatedly call fn, while test returns true.

Parameters

test Function
fn Function

Examples

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

Returns Promise

Utilities

A collection of awaitable utility functions.

apply

packages/apply/index.js:27-27

<a id="apply"></a> Creates a continuation function with some arguments already applied.

Parameters

function Function
arguments ...Any

Examples

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]

Returns Function

asyncify

packages/asyncify/index.js:26-33

<a id="asyncify"></a> Take a sync function and make it async. This is useful for plugging sync functions into a waterfall, series, or other async functions.

Parameters

function Function

Examples

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

Returns Function

awaitify

packages/awaitify/index.js:22-25

<a id="awaitify"></a> Transform a callback-based function into a promise-based one.

Parameters

function Function

Examples

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 Function

constant

packages/constant/index.js:22-22

<a id="constant"></a> Returns a promise that when called, then's with the values provided. Useful as the first function in a waterfall.

Parameters

arguments ...any

Examples

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

Returns Promise

intercept

packages/intercept/index.js:19-25

<a id="intercept"></a> Intercepts errors, the Go way!

Parameters

input Promise

Examples

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

Returns Promise

reflect

packages/reflect/index.js:28-37

<a id="reflect"></a> Wraps the function in another function that always returns data even when it errors. The object returned has either the property error or value.

Parameters

input Function

Examples

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 }]

Returns Function

times

packages/times/index.js:24-24

<a id="times"></a> Calls the iteratee function n times, and accumulates results in the same manner you would use with map.

Parameters

n Number
iteratee Function

Examples

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]

Returns Promise

series

packages/times/series.js:11-11

Parameters

n Number
iteratee Function

Returns Promise

limit

packages/times/limit.js:13-23

Parameters

n Number
limit Number
iteratee Function

Returns Promise

main

packages/main/index.js:27-27

<a id="main"></a> Catches a promise error, writes the stacktrace to stderr and exists

Parameters

input Promise

Examples

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

Returns Promise

credits

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

license

MIT

Awesome

apr

contents

Collections

concat

series

limit

every

series

limit

filter

series

limit

find

series

limit

for-each

series

limit

map

series

limit

reduce

reject

series

limit

some

series

series

limit

sort-by

limit

Control Flow

compose

parallel

seq

series

until

waterfall

whilst

Utilities

apply

asyncify

awaitify

constant

intercept

reflect

times

series

limit

main

credits

license