@particle/async-utils

    4.0.1 • Public • Published

    @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


    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

    Keywords

    none

    Install

    npm i @particle/async-utils

    DownloadsWeekly Downloads

    452

    Version

    4.0.1

    License

    UNLICENSED

    Unpacked Size

    32.1 kB

    Total Files

    4

    Last publish

    Collaborators

    • amaury.particle
    • cole-abbeduto-particle
    • pedrosordo
    • rowan.hamilton
    • guohui
    • sbrust
    • busticated
    • particlebot
    • no1089
    • carlos.hdez
    • keeramis5
    • monkbroc
    • suda
    • mstan
    • sergeuz
    • debbie23
    • avtolstoy
    • mlauer
    • wraithan
    • toolboxbot
    • azenk
    • shewy
    • bwalach
    • parteberseth
    • rickkas7
    • mrlambchop_particle
    • hugo.montero
    • toddparticle
    • mphsi
    • zachary_russell_particle
    • davidbbe