apr

apr - async promise resolve

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

contents

• contents
• api
  • collections
    • concat (series, limit)
    • find (series, limit)
    • forEach (series, limit)
    • every (series, limit)
    • filter (series, limit)
    • map (series, limit)
    • reduce
    • reject (series, limit)
    • some (some, limit)
    • sortBy (some, limit)
  • control flow
    • compose
    • parallel
    • seq
    • series
    • times (some, limit)
    • until
    • waterfall
    • whilst
  • utils
    • apply
    • asyncify
    • constant
• todo
• caolan/async parity
• credits
• license

api

collections

You can use arrays, objects and iterables as the input for all the collection functions.

concat(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import concat from 'apr-concat'

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

const files = await concat(dirs, async (dir) => 
  await readdir(dir)
);

concatSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import concatSeries from 'apr-concat/series'
// import { series as concatSeries } from 'apr-concat/series'

concatLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import concatLimit from 'apr-concat/limit'
// import { limit as concatLimit } from 'apr-concat/limit'

find(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import find from 'apr-find'

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

const first = await find(files, async (file) =>
  await access(file)
);

findSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import findSeries from 'apr-find/series'
// import { series as findSeries } from 'apr-find/series'

findLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import findLimit from 'apr-find/limit'
// import { limit as findLimit } from 'apr-find/limit'

forEach(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import forEach from 'apr-for-each'

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

await each(files, async (file) => 
  await writeFile(file, 'boom')
);

forEachSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import forEachSeries from 'apr-for-each/series'
// import { series as forEachSeries } from 'apr-for-each/series'

forEachLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import forEachLimit from 'apr-for-each/limit'
// import { limit as forEachLimit } from 'apr-for-each/limit'

every(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import every from 'apr-every'

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

const allExist = await every(files, async (file) => 
  await access(file)
);

everySeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import everySeries from 'apr-every/series'
// import { series as everySeries } from 'apr-every/series'

everyLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import everyLimit from 'apr-every/limit'
// import { limit as everyLimit } from 'apr-every/limit'

filter(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import filter from 'apr-filter'

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

var existent = await filter(files, async (file) => 
  await access(file)
);

filterSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import filterSeries from 'apr-filter/series'
// import { series as filterSeries } from 'apr-filter/series'

filterLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import filterLimit from 'apr-filter/limit'
// import { limit as filterLimit } from 'apr-filter/limit'

map(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import map from 'apr-map'

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

const stats = await map(files, async (file) => 
  await stat(file);
);

mapSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import mapSeries from 'apr-map/series'
// import { series as mapSeries } from 'apr-map/series'

mapLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import mapLimit from 'apr-map/limit'
// import { limit as mapLimit } from 'apr-map/limit'

reduce(coll: array | Iterable | Object, iteratee: Promise, initialValue: any): Promise

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

import reduce from 'apr-reduce'

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

reject(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import reject from 'apr-reject'

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

var missing = await reject(files, async (file) => 
  await access(file)
);

rejectSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import rejectSeries from 'apr-reject/series'
// import { series as rejectSeries } from 'apr-reject/series'

rejectLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import rejectLimit from 'apr-reject/limit'
// import { limit as rejectLimit } from 'apr-reject/limit'

some(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import some from 'apr-some'

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

const oneExist = await some(files, async (file) => 
  await access(file)
);

someSeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import someSeries from 'apr-some/series'
// import { series as someSeries } from 'apr-some/series'

someLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import someLimit from 'apr-some/limit'
// import { limit as someLimit } from 'apr-some/limit'

sortBy(coll: array | Iterable | Object, iteratee: Promise): Promise

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

import sortBy from 'apr-sort-by'

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

const sorted = await sortBy(files, await (file) => {
  const { mtime } = await stat(file);
  return mtime;
});

sortBySeries(coll: array | Iterable | Object, iteratee: Promise): Promise

import sortBySeries from 'apr-sort-by/series'
// import { series as sortBySeries } from 'apr-sort-by/series'

sortByLimit(coll: array | Iterable | Object, limit: number, iteratee: Promise): Promise

import sortByLimit from 'apr-sort-by/limit'
// import { limit as sortByLimit } from 'apr-sort-by/limit'

control flow

compose(...tasks: Array): (input: any): Promise

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())).

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

parallel(tasks: Array | Object): Promise

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

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 }

seq(tasks: Array): (input: any): Promise

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.

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

series(tasks: Array | Object): Promise

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

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 }

until(test: Promise, fn: Promise): Promise

Repeatedly call fn until test returns true.

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

waterfall(tasks: Array | Object): Promise

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

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

whilst(test: Promise, fn: Promise): Promise

Repeatedly call fn, while test returns true.

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

utils

apply(fn: Function): Promise

Creates a continuation function with some arguments already applied.

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]

asyncify(fn: Function)

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

import asyncify from 'apr-asyncify'
import waterfall from 'apr-waterfall'
import apply from 'apr-apply'

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

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

constant(...args: any): Promise

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

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

todo

• finish caolan/async feature parity
• come up with a solution for generating readme and website from source
• flow annotations

caolan/async feature parity

Eventually it should have feature parity with caolan/async.

collections


• concat
• concatSeries
• detect
• detectLimit
• detectSeries
• each
• eachLimit
• eachOf
• eachOfLimit
• eachOfSeries
• eachSeries
• every
• everyLimit
• everySeries
• filter
• filterLimit
• filterSeries
• map
• mapLimit
• mapSeries
• mapValues
• mapValuesLimit
• mapValuesSeries
• reduce
• reduceRight
• reject
• rejectLimit
• rejectSeries
• some
• someLimit
• someSeries
• sortBy
• transform

control flow

• applyEach
• applyEachSeries
• auto
• autoInject
• cargo
• compose
• doDuring
• doUntil
• doWhilst
• during
• forever
• parallel
• parallelLimit
• priorityQueue
• queue
• race
• retry
• retryable
• seq
• series
• times
• timesLimit
• timesSeries
• until
• waterfall
• whilst

utils

• apply
• asyncify
• constant
• dir
• ensureAsync
• log
• memoize
• nextTick
• reflect
• reflectAll
• setImmediate
• timeout
• unmemoize

credits

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

license

MIT