@brianmcallister/sequential-promise

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
• Usage
• API
  • Functions
    • sequential
    • sequentialAllSettled
  • Types
    • Result<T>

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 to 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, similar (but not exactly!) 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'),
  () => Promise.resolve('two'),
];

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 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