@brianmcallister/sequential-promise
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    @brianmcallister/sequential-promise

    codecov CircleCI npm version

    Run Promises that depend on each other sequentially

    sequential-promise allows for running a series of promises sequentially, where each promise in the list depends on the previous promise having settled. There are two functions in this package, one that mirrors the behavior of Promise#all, and one mirroring Promise#allSettled (but which does not require Promise#allSettled to exist in your environment).

    Table of contents

    Installation

    npm install @brianmcallister/sequential-promise
    ⇡ Top

    Usage

    The main concept to understand here is that you'll need to create an array of functions that create Promises, not an array of Promises (if you're using TypeScript, then the compiler will yell at you if you pass Promise<unknown>[]).

    The functions in this package iterate over the array of functions you pass, calls each one, and then waits for each returned promise settle before continuing on.

    import sequential from '@brianmcallister/sequential-promise';
    
    const asyncRequests = [
      () => fetchUser({ id: 1 }),
      (user1) => fetchOrderDetails(user1.orders),
    ];
    
    sequential(asyncRequests).then(([user1, userOrderDetails]) => {
      renderOrderDetails(userOrderDetails);
    });
    
    // ...or with async/await:
    const [user1, userOrderDetails] = await sequential(asyncRequests);
    
    renderOrderDetails(userOrderDetails);
    ⇡ Top

    API

    Functions

    sequential

    import sequential from '@brianmcallister/sequential-promise';

    sequential is the default export. It iterates over an array of functions that return promises. If one of the promises rejects, then everything will stop, and sequential will return a rejected promise, just like how Promise#all behaves.

    sequential: <T>(funcs: ((list: T[]) => Promise<T>)[]) => Promise<T[]>;

    All promises resolving:

    import sequential from '@brianmcallister/sequential-promise';
    
    const promises = [
      () => Promise.resolve('one'),
      () => Promise.resolve('two'),
    ];
    
    const results = await sequential(promises);
    // #=> ['one', 'two'];

    Some promises rejecting:

    import sequential from '@brianmcallister/sequential-promise';
    
    const promises = [
      () => Promise.resolve('one'),
      () => Promise.reject('oops'),
    ];
    
    try {
      await sequential(promises)
    } catch (err) {
      console.log(err);
      // #=> 'oops';
    }

    sequentialAllSettled

    import { sequentialAllSettled } from '@brianmcallister/sequential-promise';

    sequentialAllSettled attempts to behave the same way the forthcoming `Promise#allSettled behaves.

    Even if one of the promises rejects, the iteration won't stop. Instead, the results of every promise are gathered up and the final promise resolves with a summary of all the promises settled values as Result<T>[] (See: Result<T> below.

    sequentialAllSettled: <T>(funcs: ((list: Result<T>[]) => Promise<T>)[]) => Promise<Result<T>[]>;

    Example:

    import { sequentialAllSettled } from '@brianmcallister/sequential-promise';
    
    const promises = [
      () => Promise.resolve('one'),
      () => Promise.reject('oops'),
    ];
    
    const results = await sequentialAllSettled(promises);
    // #=> [{ status: 'fulfilled', value: 'one' }, { status: 'rejected', reason: 'oops' }];
    ⇡ Top

    Types

    Result<T>

    Settled value when using sequentialAllSettled.

    import { Result } from '@brianmcallister/sequential-promise';
    interface Fulfilled<T> {
        status: 'fulfilled';
        value: T;
    }
    
    interface Rejected {
        status: 'rejected';
        reason: unknown;
    }
    
    type Result<T> = Fulfilled<T> | Rejected;
    ⇡ Top

    Install

    npm i @brianmcallister/sequential-promise

    DownloadsWeekly Downloads

    170

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    17.8 kB

    Total Files

    9

    Last publish

    Collaborators

    • brianmcallister