@particle/async-utils

@particle/async-utils

Collection of promise-based async utility functions.

Installation

npm install @particle/async-utils --save

const asyncUtils = require('@particle/async-utils');
const {
  delay,
  delayForAtLeast,
  timeout,
  TimeoutError,
  retry,
  retryWithBackoff,
  asyncFilter,
  asyncMap,
  asyncReduceSeries,
  asyncMapSeries,
  execAsPromise,
  upon,
  isPromise
} = asyncUtils;

API

@particle/async-utils

• @particle/async-utils
  • .TimeoutError ⇐ Error
  • .delay(ms, [value]) ⇒ Promise.<(undefined|Value)>
  • .delayForAtLeast(ms, promise) ⇒ Promise.<*>
  • .timeout(promise, ms, [Err]) ⇒ Promise.<*>
  • .retry(fn, [options]) ⇒ Promise.<*>
  • .retryWithBackoff(fn, [options]) ⇒ Promise.<*>
  • .asyncFilter(array, filter, [concurrency]) ⇒ Promise.<(array|Error)>
  • .asyncMap(array, fn, [concurrency]) ⇒ Promise.<(array|Error)>
  • .asyncReduceSeries(array, fn, [initial]) ⇒ Promise.<(value|Error)>
  • .asyncMapSeries(array, fn) ⇒ Promise.<(array|Error)>
  • .execAsPromise(fn, ...args) ⇒ Promise.<*>
  • .upon(promise) ⇒ Promise.<Array.<{error: Error, value: *}>>
  • .isPromise(x) ⇒ boolean

asyncUtils.TimeoutError ⇐ Error

Kind: static class of @particle/async-utils
Extends: Error
Properties

Name	Type	Default	Description
[msg]	string	"The operation timed out"	The error message

asyncUtils.delay(ms, [value]) ⇒ Promise.<(undefined|Value)>

Create a promise which resolves after a given delay

Kind: static method of @particle/async-utils
Returns: Promise.<(undefined|Value)> - A resolved promise

Param	Type	Description
ms	number	Duration of delay in milliseconds
[value]	*	Value to resolve the returned promise with (optional)

Example

delay(10).then(() => 'done!');
const value = await delay(10, 'done!');

asyncUtils.delayForAtLeast(ms, promise) ⇒ Promise.<*>

Enforce a minimum delay for any async function

Kind: static method of @particle/async-utils
Returns: Promise.<*> - The result of your async function

Param	Type	Description
ms	number	Duration of delay in milliseconds
promise	Promise.<*>	Promise generated by your async function

Example

let value;

try {
  value = await delayForAtLeast(200, myFn());
  value // whatever `myFn()` resolved with
} catch (error){
  error // whatever `myFn()` rejected with
}

asyncUtils.timeout(promise, ms, [Err]) ⇒ Promise.<*>

Enforce a timeout for any asnyc function

Kind: static method of @particle/async-utils
Returns: Promise.<*> - The result of your async function or a timeout error rejection

Param	Type	Description
promise	Promise.<*>	Promise generated by your async function
ms	number	Duration of timeout window in milliseconds
[Err]	string | function	custom error message or type (optional)

Example

let value;

try {
  value = await timeout(myFn(), 1000);
} catch (error){
  error.message; // 'The operation timed out'
  error instanceof asyncUtils.TimeoutError; // true
}

// with a custom error message

try {
  value = await timeout(myFn(), 1000, 'custom message');
} catch (error){
  error.message; // 'custom message'
  error instanceof asyncUtils.TimeoutError; // true
}

// with a custom error constructor

try {
  value = await timeout(myFn(), 1000, MyCustomError);
} catch (error){
  error instanceof MyCustomError; // true
}

asyncUtils.retry(fn, [options]) ⇒ Promise.<*>

Retries a given function an arbitrary number of times optionally delaying retry attempts and / or executing a given function before each retry attempt

Kind: static method of @particle/async-utils
Returns: Promise.<*> - The result of your function

Param	Type	Default	Description
fn	function		The function you would like to execute and retry upon failure
[options]	object
[options.maxAttempts]	number	1	Number of tries to attempt
[options.delayMS]	number		Delay before retrying in milliseconds (optional)
[options.beforeRetry]	function		Function to exectute before retrying (optional)

Example

let value;

try {
  value = await retry(myFn, { maxAttempts: 3 });
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

// with a delay

try {
  value = await retry(myFn, { delayMS: 100, maxAttempts: 3 }); // each retry is delayed for 100ms
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

// executing a function before each retry attempt

try {
  value = await retry(myFn, { beforeRetry: cleanUpThing, maxAttempts: 3 }); // cleanUpThing() is called before each retry
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

asyncUtils.retryWithBackoff(fn, [options]) ⇒ Promise.<*>

Retries a given function an arbitrary number of times exponentially delaying retry attempts and optionally executing a given function before each retry attempt

Kind: static method of @particle/async-utils
Returns: Promise.<*> - The result of your function

Param	Type	Default	Description
fn	function		The function you would like to execute and retry upon failure
[options]	object
[options.maxAttempts]	number	1	Number of tries to attempt
[options.factor]	number	2	The exponential factor to use - cannot be less than 1 (optional)
[options.initialDelayMS]	number	250	Base delay in milliseconds from which to calculate retry wait time (optional)
[options.maxDelayMS]	number	Infinity	Maximum delay in milliseconds to enforce after calculating retry wait time (optional)
[options.beforeRetry]	function		Function to exectute before retrying (optional)

Example

let value;

try {
  value = await retryWithBackoff(myFn, { maxAttempts: 3 });
  // assuming `myFn` resolves on the 3rd and final attempt, call timing is:
  // call 0 - immediately
  // call 1 - 250ms wait
  // call 2 - 1000ms wait
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

// with a customized wait

try {
  value = await retryWithBackoff(myFn, { factor: 3, initialDelayMS: 100, maxAttempts: 4 });
  // assuming `myFn` resolves on the 4th and final attempt, call timing is:
  // call 0 - immediately
  // call 1 - 100ms wait
  // call 2 - 800ms wait
  // call 3 - 2700ms wait
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

// with a maximum delay limit

try {
  value = await retryWithBackoff(myFn, { maxAttempts: 3, maxDelayMS: 500 });
  // assuming `myFn` resolves on the 3rd and final attempt, call timing is:
  // call 0 - immediately
  // call 1 - 250ms wait
  // call 2 - 500ms wait
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

// executing a function before each retry attempt

try {
  value = await retryWithBackoff(myFn, { beforeRetry: cleanUpThing, maxAttempts: 3 }); // cleanUpThing() is called before each retry
} catch (error){
  error; // the error thrown by your function on it's last attempt
}

asyncUtils.asyncFilter(array, filter, [concurrency]) ⇒ Promise.<(array|Error)>

Filters an array using an async callback

Kind: static method of @particle/async-utils
Returns: Promise.<(array|Error)> - Your filtered array or an error

Param	Type	Default	Description
array	array		The array to filter
filter	function		Filtering function applied to each element of the array. Return true to keep the element, false otherwise.
[concurrency]	number	Infinity	The max number of concurrent operations to run

Example

let values;

try {
  values = await asyncFilter([1, 2, 3], async (n) => n % 2 === 0);
  values; // [2]
} catch (error){
  error; // the first error thrown by your filter function
}

asyncUtils.asyncMap(array, fn, [concurrency]) ⇒ Promise.<(array|Error)>

Map array values using an async callback

Kind: static method of @particle/async-utils
Returns: Promise.<(array|Error)> - New array with mapped values or an error

Param	Type	Default	Description
array	array		The array to filter
fn	function		Function that produces an element of the new Array.
[concurrency]	number	Infinity	The max number of concurrent operations to run

Example

let values;

try {
  values = await asyncMap([1, 2, 3], async (n) => n + 1);
  values; // [2, 3, 4]
} catch (error){
  error; // the first error thrown by your mapper function
}

asyncUtils.asyncReduceSeries(array, fn, [initial]) ⇒ Promise.<(value|Error)>

Reduce array values using an async callback executed in series

Kind: static method of @particle/async-utils
Returns: Promise.<(value|Error)> - New reduced valued or an error

Param	Type	Description
array	array	The array to reduce
fn	function	Function to execute on each element in the array
[initial]	*	Value used as the 1st argument to the 1st call of the callback (optional)

Example

let values;

try {
  value = await asyncReduceSeries([1, 2, 3], async (out, n) => out + n, 0);
  value; // 6
} catch (error){
  error; // the first error thrown by your callback function
}

asyncUtils.asyncMapSeries(array, fn) ⇒ Promise.<(array|Error)>

Map array values using an async callback executed in series

Kind: static method of @particle/async-utils
Returns: Promise.<(array|Error)> - New array with mapped values or an error

Param	Type	Description
array	array	The array to map
fn	function	Function that produces an element of the new Array.

Example

let values;

try {
  values = await asyncMapSeries([1, 2, 3], async (n) => n + 1);
  values; // [2, 3, 4]
} catch (error){
  error; // the first error thrown by your mapper function
}

asyncUtils.execAsPromise(fn, ...args) ⇒ Promise.<*>

Execute a given function ensuring that its return value or thrown error is transformed into a promise.

Kind: static method of @particle/async-utils
Returns: Promise.<*> - The result of calling your function as a promise

Param	Type	Description
fn	function	Function to execute.
...args	*	Arguments to pass to your function.

Example

let values;

try {
  values = await execAsPromise((n) => n + 1, 1, 2, 3);
  values; // [2, 3, 4]
} catch (error){
  error; // the error thrown by your function
}

asyncUtils.upon(promise) ⇒ Promise.<Array.<{error: Error, value: *}>>

Resolve a promise using await without try / catch.

Kind: static method of @particle/async-utils
Returns: Promise.<Array.<{error: Error, value: *}>> - The result of your promise as an array like: [error, value]

Param	Type	Description
promise	Promise	Promise to handle

Example

let [error, value] = await upon(myFn());

if (error){
    // handle error
}

console.log(value); // whatever `myFn()` resolved with

asyncUtils.isPromise(x) ⇒ boolean

Determine if input looks like a spec-compliant promsie

Kind: static method of @particle/async-utils
Returns: boolean - Whether or not the given input is a promise

Param	Type	Description
x	*	Value to check

Example

if (isPromise(x)){
    // it's a promise!
} else {
    // not a promise!
}

NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in tests