Static helpers

CancelablePromise.all, allSettled, race, resolve, reject and canceled. The static methods of Promise, returning promises that can be canceled.

GuideTypeScriptTry an example

The same methods, cancelable

CancelablePromise has the static methods you know from Promise. Each returns a CancelablePromise, and canceling it cancels the promises inside it.

Method	Resolves with	Canceling it
`CancelablePromise.all(values)`	Every result, in the order of the values	Cancels every promise
`CancelablePromise.allSettled(values)`	The outcome of every promise	Cancels every promise
`CancelablePromise.race(values)`	The first promise to settle	Cancels every promise
`CancelablePromise.resolve(value)`	The value	Nothing, already settled
`CancelablePromise.reject(reason)`	Never, it is rejected	Nothing, already settled
`CancelablePromise.canceled(reason)`	Never, it is canceled	Nothing, already settled

The values can be cancelable promises, native promises, plain values, or any mix of them.

all

all.ts

import { CancelablePromise } from 'easy-cancelable-promise';

const wait = <T>(value: T, milliseconds: number) =>
  new CancelablePromise<T>((resolve, _reject, { onCancel }) => {
    const timer = setTimeout(() => resolve(value), milliseconds);

    onCancel(() => clearTimeout(timer));
  });

export async function all() {
  // promises, cancelable promises and plain values, in any mix
  const results = await CancelablePromise.all([wait('user', 20), Promise.resolve(42), true]);

  return results; // ['user', 42, true], in the order of the values
}

export function cancelAll() {
  const first = wait('first', 5000);
  const second = wait('second', 5000);
  const both = CancelablePromise.all([first, second]);

  // canceling the result cancels every promise inside it
  both.cancel('Not needed');

  return [first.status, second.status, both.status]; // ['canceled', 'canceled', 'canceled']
}

export function oneIsCanceled() {
  const first = wait('first', 5000);
  const second = wait('second', 5000);
  const both = CancelablePromise.all([first, second]);

  // canceling one of the promises cancels the result, and with it the rest
  first.cancel('Not needed');

  return both.catch(() => [first.status, second.status, both.status]);
  // resolves with ['canceled', 'canceled', 'canceled']
}

The results keep the position of their values. The same promise can appear more than once.
An empty array resolves with [].
If one promise is rejected, the result is rejected with that reason.
If one promise is canceled, the result is canceled, and that cancels the rest.

allSettled

allSettled never rejects. It waits for every promise and reports how each one ended.

all-settled.ts

import { CancelablePromise } from 'easy-cancelable-promise';

export async function allSettled() {
  const canceled = new CancelablePromise<string>(() => {});

  canceled.cancel('Not needed');

  const results = await CancelablePromise.allSettled([
    CancelablePromise.resolve('ok'),
    CancelablePromise.reject(new Error('failed')),
    canceled,
  ]);

  // besides 'fulfilled' and 'rejected', a canceled promise is reported with the status 'canceled'
  return results.map((result) => result.status); // ['fulfilled', 'rejected', 'canceled']
}

race

race settles with the first promise that settles. The other promises keep running. Cancel them if you no longer need them.

race.ts

import { CancelablePromise } from 'easy-cancelable-promise';

const wait = <T>(value: T, milliseconds: number) =>
  new CancelablePromise<T>((resolve, _reject, { onCancel }) => {
    const timer = setTimeout(() => resolve(value), milliseconds);

    onCancel(() => clearTimeout(timer));
  });

export async function race() {
  const fast = wait('fast', 10);
  const slow = wait('slow', 5000);

  const winner = await CancelablePromise.race([fast, slow]);

  // the race is over, but the slow promise is still running: cancel what you no longer need
  slow.cancel();

  return [winner, slow.status]; // ['fast', 'canceled']
}

An empty array never settles, same as Promise.race([]).

resolve, reject and canceled

Shortcuts for a promise that is already settled.

shortcuts.ts

import { CancelablePromise } from 'easy-cancelable-promise';

export async function shortcuts() {
  const resolved = CancelablePromise.resolve('value');
  const rejected = CancelablePromise.reject(new Error('reason'));
  const canceled = CancelablePromise.canceled('reason');

  await rejected.catch(() => {});

  return [resolved.status, rejected.status, canceled.status]; // ['resolved', 'rejected', 'canceled']
}

Groups and concurrency: when you need to limit how many promises run at once.
API reference

Static helpers

The same methods, cancelable

all

allSettled

race

resolve, reject and canceled

Next