AsyncAF

const promises = [1, 2, 3].map(n => Promise.resolve(n));


AsyncAF(promises).mapAF(n => n * 2).filterAF(n => n !== 4).forEachAF(n => console.log(n));
// logs 2 then 6

Methods

concatAF(…values) → {Promise.<Array>|Promise.<String>}

Since:

• 5.3.0

See:

• concat (alias)

Example

// arrays
const arr = Promise.resolve([1, 2]);
AsyncAF(arr).concatAF([3, 4]); // Promise that resolves to [1, 2, 3, 4]
AsyncAF(arr).concatAF([3, 4], [5, 6]); // Promise that resolves to [1, 2, 3, 4, 5, 6]

// nested arrays
const arr1 = Promise.resolve([1, 2]);
const arr2 = [3, [4, 5]];
AsyncAF(arr1).concatAF(arr2); // Promise that resolves to [1, 2, 3, [4, 5]]

// strings
const str = Promise.resolve('str');
AsyncAF(str).concatAF('ing'); // Promise that resolves to 'string'
AsyncAF(str).concatAF('ing', 'y'); // Promise that resolves to 'stringy'

// other instances of AsyncAF
const aaf1 = AsyncAF([1, 2]);
const aaf2 = AsyncAF(3);

aaf1.concatAF(aaf2); // Promise that resolves to [1, 2, 3];

const aaf3 = AsyncAF('stringy');
const aaf4 = AsyncAF('AF');

aaf3.concatAF(aaf4); // Promise that resolves to 'stringyAF'

// promises
const [p1, p2, p3] = [[1, 2], 3, [4, [5, 6]]].map(v => Promise.resolve(v));

AsyncAF(p1).concatAF(p2); // Promise that resolves to [1, 2, 3]
AsyncAF(p1).concatAF(p2, p3) // Promise that resolves to [1, 2, 3, 4, [5, 6]]

const pStr1 = Promise.resolve('str');
const pStr2 = Promise.resolve('ing');
const pStr3 = Promise.resolve('y');

AsyncAF(pStr1).concatAF(pStr2); // Promise that resolves to 'string'
AsyncAF(pStr1).concatAF(pStr2, pStr3); // Promise that resolves to 'stringy'

// Note: concatAF will not resolve deeply nested promises; if you need this behavior, concatAF can be used in a
// function; for example, this function recursively flattens an array of promises

const flattenAsync = arr => AsyncAF(arr).reduceAF(async (acc, val) => {
  return Array.isArray(await val)
    ? AsyncAF(acc).concatAF(flattenAsync(val))
    : AsyncAF(acc).concatAF(val), []);
};

Parameters:

Returns:

Type

Promise.<Array> | Promise.<String>

everyAF(callback, thisArgopt) → {Promise.<Boolean>}

Since:

• 3.2.0

See:

• every (alias)
• series.everyAF

Example

const promises = [1, 2, 3].map(n => Promise.resolve(n));


// basic usage
const allAreOdd = AsyncAF(promises).everyAF(n => n % 2);

console.log(allAreOdd); // Promise that resolves to false

AsyncAF.logAF(allAreOdd); // logs false


// using .then
AsyncAF(promises).everyAF(n => n % 2).then(allAreOdd => {
  console.log(allAreOdd); // logs false
});


// inside an async function
(async () => {
  const allAreNums = await AsyncAF(promises).everyAF(
    n => typeof n === 'number'
  );
  console.log(allAreNums); // logs true
})();

Parameters:

Returns:

Type

Promise.<Boolean>

filterAF(callback, thisArgopt) → {Promise.<Array>}

Since:

• 3.0.0

See:

• filter (alias)
• series.filterAF

Example

const promises = [1, 2, 3].map(n => Promise.resolve(n));


// basic usage
const odds = AsyncAF(promises).filterAF(n => n % 2);

console.log(odds); // Promise that resolves to [1, 3]

AsyncAF.logAF(odds); // logs [1, 3]


// using .then
AsyncAF(promises).filterAF(n => n % 2).then(odds => {
  console.log(odds); // logs [1, 3]
});


// inside an async function
(async () => {
  const odds = await AsyncAF(promises).filterAF(
    n => n % 2
  );
  console.log(odds); // logs [1, 3]
})();

Parameters:

Returns:

Type

Promise.<Array>

findAF(callback, thisArgopt) → {Promise.<any>}

Since:

• 3.5.0

See:

• find (alias)
• series.findAF

Example

const inventory = [
 {name: 'nuts', quantity: 2000},
 {name: 'bolts', quantity: 5000},
 {name: 'screws', quantity: 9001}
].map(part => Promise.resolve(part));

AsyncAF(inventory).findAF(part => part.name === 'screws');
// Promise that resolves to {name: 'screws', quantity: 9001}

Parameters:

Returns:

Type

Promise.<any>

findIndexAF(callback, thisArgopt) → {Promise.<Number>}

Since:

• 3.5.0

See:

• findIndex (alias)
• series.findIndexAF

Example

const inventory = [
 {name: 'nuts', quantity: 2000},
 {name: 'bolts', quantity: 5000},
 {name: 'screws', quantity: 9001}
].map(part => Promise.resolve(part));

AsyncAF(inventory).findIndexAF(part => part.name === 'screws');
// Promise that resolves to 2

Parameters:

Returns:

Type

Promise.<Number>

forEachAF(callback, thisArgopt) → {Promise.<undefined>}

Since:

• 3.0.0

See:

• forEach (alias)
• series.forEachAF

Example

const promises = [1, 2].map(n => Promise.resolve(n));


AsyncAF(promises).forEachAF(el => {
  console.log(el); // logs 1 then 2
});

Parameters:

Returns:

Type

Promise.<undefined>

includesAF(searchItem, fromIndexopt) → {Promise.<Boolean>}

Since:

• 3.4.0

See:

• includes (alias)
• series.includesAF

Example

// includesAF on an array of promises
const nums = [1, 2, 3].map(n => Promise.resolve(n));

AsyncAF(nums).includesAF(2); // Promise that resolves to true

AsyncAF(nums).includesAF(5); // Promise that resolves to false

AsyncAF(nums).includesAF(1, 1); // Promise that resolves to false

AsyncAF(nums).includesAF(3, -1); // Promise that resolves to true

// includesAF on a promise-wrapped string
const string = Promise.resolve('test string');

AsyncAF(string).includesAF('test'); // Promise that resolves to true

AsyncAF(string).includesAF('nope'); // Promise that resolves to false

AsyncAF(string).includesAF('test', 5); // Promise that resolves to false

AsyncAF(string).includesAF('string', -6); // Promise that resolves to true

// includesAF on an array-like object
(async function () {
  if (await AsyncAF(arguments).includesAF(2)) {
    console.log('2 is included');
  }
})(1, 2, 3); // logs '2 is included'

Parameters:

Returns:

Type

Promise.<Boolean>

indexOfAF(searchItem, fromIndexopt) → {Promise.<Number>}

Since:

• 3.5.0

See:

• indexOf (alias)
• series.indexOfAF

Example

// indexOfAF on an array of promises
const nums = [1, 2, 3].map(n => Promise.resolve(n));

AsyncAF(nums).indexOfAF(2); // Promise that resolves to 1

AsyncAF(nums).indexOfAF(5); // Promise that resolves to -1

AsyncAF(nums).indexOfAF(1, 1); // Promise that resolves to -1

AsyncAF(nums).indexOfAF(3, -1); // Promise that resolves to 2

// indexOfAF on a promise-wrapped string
const string = Promise.resolve('test string');

AsyncAF(string).indexOfAF('test'); // Promise that resolves to 0

AsyncAF(string).indexOfAF('nope'); // Promise that resolves to -1

AsyncAF(string).indexOfAF('test', 5); // Promise that resolves to -1

AsyncAF(string).indexOfAF('string', -6); // Promise that resolves to 5

// indexOfAF on an array-like object
(async function () {
  if (await AsyncAF(arguments).indexOfAF(2) > -1) {
    console.log('2 is included');
  }
})(1, 2, 3); // logs '2 is included'

Parameters:

Returns:

Type

Promise.<Number>

joinAF(separatoropt) → {Promise.<String>}

Since:

• 3.6.0

See:

• join (alias)

Example

const animals = ['cow', 'chicken', 'cat', 'dog'].map(a => Promise.resolve(a));

// joinAF separator defaults to ','
AsyncAF(animals).joinAF(); // Promise that resolves to 'cow,chicken,cat,dog'

// specifying separator
AsyncAF(animals).joinAF(' & '); // Promise that resolves to 'cow & chicken & cat & dog'

// a non-string separator will be converted to a string
AsyncAF(animals).joinAF(2); // Promise that resolves to 'cow2chicken2cat2dog'

// empty string separator
AsyncAF(animals).joinAF(''); // Promise that resolves to 'cowchickencatdog'

// joining an empty array resolves to an empty string
AsyncAF([]).joinAF('+'); // Promise that resolves to ''

// joinAF on an array-like object
(async function () {
 const list = await AsyncAF(arguments).joinAF(' - ');
 console.log(`Shopping List: ${list}`);
})('eggs', 'milk', 'butter', 'pancake mix');
// Shopping List: eggs - milk - butter - pancake mix

Parameters:

Returns:

Type

Promise.<String>

lastIndexOfAF(searchItem, fromIndexopt) → {Promise.<Number>}

Since:

• 3.6.0

See:

• lastIndexOf (alias)
• series.lastIndexOfAF

Example

// lastIndexOfAF on an array of promises
const nums = [1, 1, 2, 2, 3, 3].map(n => Promise.resolve(n));

AsyncAF(nums).lastIndexOfAF(2); // Promise that resolves to 3

AsyncAF(nums).lastIndexOfAF(5); // Promise that resolves to -1

AsyncAF(nums).lastIndexOfAF(2, -4); // Promise that resolves to 2

AsyncAF(nums).lastIndexOfAF(3, -3); // Promise that resolves to -1

// lastIndexOfAF on a promise-wrapped string
const string = Promise.resolve('test string to test');

AsyncAF(string).lastIndexOfAF('test'); // Promise that resolves to 15

AsyncAF(string).lastIndexOfAF('nope'); // Promise that resolves to -1

AsyncAF(string).lastIndexOfAF('test', -5); // Promise that resolves to 0

AsyncAF(string).lastIndexOfAF('to', -7); // Promise that resolves to -1

// lastIndexOfAF on an array-like object
(async function () {
  const lastIndexOf2 = await AsyncAF(arguments).lastIndexOfAF(2);
  console.log(`the last index of 2 in the arguments array-like object is ${lastIndexOf2}`)
})(1, 1, 2, 2, 3, 3); // the last index of 2 in the arguments array-like object is 3

Parameters:

Returns:

Type

Promise.<Number>

mapAF(callback, thisArgopt) → {Promise.<Array>}

Since:

• 3.0.0

See:

• map (alias)
• series.mapAF

Example

const promises = [1, 2].map(n => Promise.resolve(n));


// basic usage
const doubled = AsyncAF(promises).mapAF(el => el * 2);

console.log(doubled); // Promise that resolves to [2, 4]

AsyncAF.logAF(doubled); // logs [2, 4]


// using .then
AsyncAF(promises).mapAF(el => el * 3).then(tripled => {
  console.log(tripled); // logs [3, 6]
});


// inside an async function
(async () => {
  const quadrupled = await AsyncAF(promises).mapAF(
    el => el * 4
  );
  console.log(quadrupled); // logs [4, 8]
})();

Parameters:

Returns:

Type

Promise.<Array>

reduceAF(callback, initialValueopt) → {Promise.<any>}

Since:

• 3.1.0

See:

• reduce (alias)
• series.reduceAF

Example

const promises = [1, 2, 3].map(n => Promise.resolve(n));


// basic usage
const sum = AsyncAF(promises).reduceAF((sum, num) => sum + num);

console.log(sum); // Promise that resolves to 6

AsyncAF.logAF(sum); // logs 6


// using .then
AsyncAF(promises).reduceAF((sum, num) => sum + num).then(sum => {
  console.log(sum); // logs 6
});


// inside an async function
(async () => {
  const sum = await AsyncAF(promises).reduceAF((sum, num) => sum + num);
  console.log(sum); // logs 6
})();


// using an initial value
AsyncAF(promises).reduceAF((sum, num) => sum + num, 12) // Promise that resolves to 18

Parameters:

Returns:

Type

Promise.<any>

someAF(callback, thisArgopt) → {Promise.<Boolean>}

Since:

• 3.3.0

See:

• some (alias)
• series.someAF

Example

const promises = [1, 2, 3].map(n => Promise.resolve(n));


// basic usage
const someAreEven = AsyncAF(promises).someAF(n => n % 2 === 0);

console.log(someAreEven); // Promise that resolves to true

AsyncAF.logAF(someAreEven); // logs true


// using .then
AsyncAF(promises).someAF(n => n % 2 === 0).then(someAreEven => {
  console.log(someAreEven); // logs true
});


// inside an async function
(async () => {
  const someAreStrings = await AsyncAF(promises).someAF(
    n => typeof n === 'string'
  );
  console.log(someAreStrings); // logs false
})();

Parameters:

Returns:

Type

Promise.<Boolean>

(static) logAF(…items) → {Promise.<undefined>}

import { logAF } from 'async-af';

const promise = new Promise(resolve => setTimeout(
 () => resolve(2), 1000)
);

logAF(1, promise, 3);

// @filename.js:6:12:
// 1 2 3
// in 0.998 secs

logAF.options({ label: false, duration: false });

(async () => {
  console.log(1);
  // ...some code
  await logAF(promise);
  // ...some more code
  console.log(3);
})();

// 1
// 2
// 3

Since:

• 3.0.0

See:

• log (alias)
• logAF.options to turn the label off or change its format
• logAF.options.reset to reset options to default

Parameters:

Returns:

Type

Promise.<undefined>

(static) logAF.options(options: {labelopt, durationopt, labelFormatopt}) → {undefined}

const promise = new Promise(resolve => setTimeout(
  () => resolve(1), 1000)
);

logAF(promise, 2);

// @filename.js:24:1:
// 1 2
// in 0.998 secs

logAF.options({ label: false });
logAF(promise, 2);

// 1 2
// in 0.999 secs

logAF.options({ duration: false });
logAF(promise, 2);

// @filename.js:24:1:
// 1 2

logAF.options({ labelFormat: 'file' });
logAF(promise, 2);

// @filename.js:24:1:
// 1 2
// in 0.998 secs

logAF.options({ labelFormat: 'path' });
logAF(promise, 2);

// @/Path/to/current/directory/filename.js:24:1:
// 1 2
// in 0.997 secs

logAF.options({ labelFormat: 'parent' });
logAF(promise, 2);

// @parentDirectory/filename.js:24:1:
// 1 2
// in 0.998 secs

logAF.options({ labelFormat: 'arrow' });
logAF(promise, 2);

// ========================> 1 2
// in 0.999 secs

logAF.options({
 labelFormat: 'I logged this:'
});
logAF(promise, 2);

// I logged this: 1 2
// in 1.000 secs

logAF.options({
 labelFormat: ({file, line, col}) => `${file}:${line}:${col} =>`
});
logAF(promise, 2);

// filename.js:24:1 => 1 2
// in 0.998 secs

logAF.options({
  labelFormat: ({arrow, line, col, parent, file, path}) =>
`${arrow}
line: ${line}
col: ${col}
parent: ${parent}
file: ${file}
path: ${path}
`
});
logAF(promise, 2);

// ========================>
// line: 24
// col: 1
// parent: parentDirectory/
// file: filename.js
// path: /Full/path/to/the/parentDirectory/
// 1 2
// in 0.998 secs

logAF.options.reset();

// options are now:
// label: true,
// duration: true,
// labelFormat: 'file'

See:

• logAF
• logAF.options.reset to reset options to default

Parameters:

Returns:

Type

undefined

series → {AsyncAF.<any>}

AsyncAF(promises).series.forEachAF(callback)

Since:

• 7.0.0

See:

• io (alias)

Example

import delay from 'delay'; // https://www.npmjs.com/package/delay

const nums = [2, 1];

// perform a serial forEach by chaining series and forEachAF
(async () => {
  const start = Date.now();

  await AsyncAF(nums).series.forEachAF(async num => {
    await delay(num * 1000);
    console.log(num, `at ~${Date.now() - start} ms`);
  });

  console.log(`total: ~${Date.now() - start} ms`);
})();

// logs:
// 2  'at ~2000 ms'
// 1  'at ~3000 ms'
// total: ~3000 ms


// perform a parallel forEach by omitting series
(async () => {
  const start = Date.now();

  await AsyncAF(nums).forEachAF(async num => {
    await delay(num * 1000);
    console.log(num, `at ~${Date.now() - start} ms`);
  });

  console.log(`total: ~${Date.now() - start} ms`);
})();

// logs:
// 1  'at ~1000 ms'
// 2  'at ~2000 ms'
// total: ~2000 ms

Returns:

Type

AsyncAF.<any>

io → {AsyncAF.<any>}

AsyncAF(promises).io.forEachAF(callback)

Since:

• 7.0.0

See:

• series (alias)

Returns:

Type

AsyncAF.<any>

splitAF(separatoropt, limitopt) → {Promise.<Array.<String>>}

Since:

• 5.1.0

See:

• split (alias)

Example

// basic usage
const str = Promise.resolve('s; p; l; i; t');

AsyncAF(str).splitAF('; '); // Promise that resolves to ['s', 'p', 'l', 'i', 't']

// no separator specified or separator not found
const str = Promise.resolve('splat');

AsyncAF(str).splitAF(); // Promise that resolves to ['splat']
AsyncAF(str).splitAF('n/a'); // Promise that resolves to ['splat']

// split to individual characters
const str = Promise.resolve('splitAF');

AsyncAF(str).splitAF(''); // Promise that resolves to ['s', 'p', 'l', 'i', 't', 'A', 'F']

// split on a regular expression
const str = Promise.resolve('splittedAF');

AsyncAF(str).splitAF(/sp|ted/); // Promise that resolves to ['', 'lit', 'AF']

// and w/ capturing parentheses

AsyncAF(str).splitAF(/(lit|AF)/); // Promise that resolves to ['sp', 'lit', '', 'AF', '']

// setting limit
const str = Promise.resolve('splitted');

AsyncAF(str).splitAF('', 5); // Promise that resolves to ['s', 'p', 'l', 'i', 't']
AsyncAF(str).splitAF('', 12); // Promise that resolves to ['s', 'p', 'l', 'i', 't', 't', 'e', 'd']
AsyncAF(str).splitAF('', 0); // Promise that resolves to []

Parameters:

Returns:

Type

Promise.<Array.<String>>