Class CancellablePromise<T>

A promise with an attached method for cancelling long-running operations (see CancellablePromise#cancel). Cancellation can optionally be bound to an AbortSignal for better composability (see CancellablePromise#cancelOn).

Cancelling a pending promise will result in an immediate rejection with an instance of CancelError as reason, but whoever started the promise will be responsible for actually aborting the underlying operation. To this purpose, the constructor and all chaining methods accept optional cancellation callbacks.

If a CancellablePromise still resolves after having been cancelled, the result will be discarded. If it rejects, the reason will be reported as an unhandled rejection, wrapped in a CancelledRejectionError instance. To facilitate the handling of cancellation requests, cancelled CancellablePromises will not report unhandled CancelErrors whose cause field is the same as the one with which the current promise was cancelled.

All usual promise methods are defined and return a CancellablePromise whose cancel method will cancel the parent operation as well, propagating the cancellation reason upwards through promise chains. Conversely, cancelling a promise will not automatically cancel dependent promises downstream:

let root = new CancellablePromise((resolve, reject) => { ... });
let child1 = root.then(() => { ... });
let child2 = child1.then(() => { ... });
let child3 = root.catch(() => { ... });
child1.cancel(); // Cancels child1 and root, but not child2 or child3

Cancelling a promise that has already settled is safe and has no consequence.

The cancel method returns a promise that always fulfills after the whole chain has processed the cancel request and all attached callbacks up to that moment have run.

All ES2024 promise methods (static and instance) are defined on CancellablePromise, but actual availability may vary with OS/webview version.

In line with the proposal at https://github.com/tc39/proposal-rm-builtin-subclassing, CancellablePromise does not support transparent subclassing. Extenders should take care to provide their own method implementations. This might be reconsidered in case the proposal is retired.

CancellablePromise is a wrapper around the DOM Promise object and is compliant with the Promises/A+ specification (it passes the compliance suite) if so is the underlying implementation.

Type Parameters

Hierarchy

Promise<T>
- CancellablePromise

Implements

Index

Constructors

constructor

new CancellablePromise<T>(
executor: CancellablePromiseExecutor<T>,
oncancelled?: CancellablePromiseCanceller,
): CancellablePromise<T>
Creates a new CancellablePromise.
Type Parameters
- T
Parameters
- executor: CancellablePromiseExecutor<T>
  A callback used to initialize the promise. This callback is passed two arguments: a resolve callback used to resolve the promise with a value or the result of another promise (possibly cancellable), and a reject callback used to reject the promise with a provided reason or error. If the value provided to the resolve callback is a thenable and cancellable object (it has a then and a cancel method), cancellation requests will be forwarded to that object and the oncancelled will not be invoked anymore. If any one of the two callbacks is called after the promise has been cancelled, the provided values will be cancelled and resolved as usual, but their results will be discarded. However, if the resolution process ultimately ends up in a rejection that is not due to cancellation, the rejection reason will be wrapped in a CancelledRejectionError and bubbled up as an unhandled rejection.
- Optionaloncancelled: CancellablePromiseCanceller
  It is the caller's responsibility to ensure that any operation started by the executor is properly halted upon cancellation. This optional callback can be used to that purpose. It will be called synchronously with a cancellation cause when cancellation is requested, after the promise has already rejected with a CancelError, but before any then/catch/finally callback runs. If the callback returns a thenable, the promise returned from cancel will only fulfill after the former has settled. Unhandled exceptions or rejections from the callback will be wrapped in a CancelledRejectionError and bubbled up as unhandled rejections. If the resolve callback is called before cancellation with a cancellable promise, cancellation requests on this promise will be diverted to that promise, and the original oncancelled callback will be discarded.
Returns CancellablePromise<T>
Overrides Promise<T>.constructor
- Defined in src/cancellable.ts:186

Properties

`Readonly`[toStringTag]

"[toStringTag]": string

Methods

cancel

cancel(cause?: any): CancellablePromise<void>
Cancels immediately the execution of the operation associated with this promise. The promise rejects with a CancelError instance as reason, with the CancelError#cause property set to the given argument, if any.

Has no effect if called after the promise has already settled; repeated calls in particular are safe, but only the first one will set the cancellation cause.

The CancelError exception need not be handled explicitly on the promises that are being cancelled: cancelling a promise with no attached rejection handler does not trigger an unhandled rejection event. Therefore, the following idioms are all equally correct:
```
new CancellablePromise((resolve, reject) => { ... }).cancel();
new CancellablePromise((resolve, reject) => { ... }).then(...).cancel();
new CancellablePromise((resolve, reject) => { ... }).then(...).catch(...).cancel();
```
Whenever some cancelled promise in a chain rejects with a CancelError with the same cancellation cause as itself, the error will be discarded silently. However, the CancelError will still be delivered to all attached rejection handlers added by then and related methods:
```
let cancellable = new CancellablePromise((resolve, reject) => { ... });
cancellable.then(() => { ... }).catch(console.log);
cancellable.cancel(); // A CancelError is printed to the console.
```
If the CancelError is not handled downstream by the time it reaches a non-cancelled promise, it will trigger an unhandled rejection event, just like normal rejections would:
```
let cancellable = new CancellablePromise((resolve, reject) => { ... });
let chained = cancellable.then(() => { ... }).then(() => { ... }); // No catch...
cancellable.cancel(); // Unhandled rejection event on chained!
```
Therefore, it is important to either cancel whole promise chains from their tail, as shown in the correct idioms above, or take care of handling errors everywhere.
Parameters
- Optionalcause: any
Returns CancellablePromise<void>
A cancellable promise that fulfills after the cancel callback (if any) and all handlers attached up to the call to cancel have run. If the cancel callback returns a thenable, the promise returned by cancel will also wait for that thenable to settle. This enables callers to wait for the cancelled operation to terminate without being forced to handle potential errors at the call site.
```
cancellable.cancel().then(() => {
    // Cleanup finished, it's safe to do something else.
}, (err) => {
    // Unreachable: the promise returned from cancel will never reject.
});
```
Note that the returned promise will not handle implicitly any rejection that might have occurred already in the cancelled chain. It will just track whether registered handlers have been executed or not. Therefore, unhandled rejections will never be silently handled by calling cancel.
Implementation of CancellablePromiseLike.cancel
- Defined in src/cancellable.ts:293

cancelOn

cancelOn(signal: AbortSignal): CancellablePromise<T>
Binds promise cancellation to the abort event of the given AbortSignal. If the signal has already aborted, the promise will be cancelled immediately. When either condition is verified, the cancellation cause will be set to the signal's abort reason (see AbortSignal.reason).

Has no effect if called (or if the signal aborts) after the promise has already settled. Only the first signal to abort will set the cancellation cause.

For more details about the cancellation process, see cancel and the CancellablePromise constructor.

This method enables awaiting cancellable promises without having to store them for future cancellation, e.g.:
```
await longRunningOperation().cancelOn(signal);
```
instead of:
```
let promiseToBeCancelled = longRunningOperation();
await promiseToBeCancelled;
```
Parameters
- signal: AbortSignal
Returns CancellablePromise<T>
This promise, for method chaining.
- Defined in src/cancellable.ts:329

catch

catch<TResult = never>(
onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
oncancelled?: CancellablePromiseCanceller,
): CancellablePromise<T | TResult>
Attaches a callback for only the rejection of the Promise.

The optional oncancelled argument will be invoked when the returned promise is cancelled, with the same semantics as the oncancelled argument of the constructor. When the parent promise rejects or is cancelled, the onrejected callback will run, even after the returned promise has been cancelled: in that case, should it reject or throw, the reason will be wrapped in a CancelledRejectionError and bubbled up as an unhandled rejection.

It is equivalent to
```
cancellablePromise.then(undefined, onrejected, oncancelled);
```
and the same caveats apply.
Type Parameters
- TResult = never
Parameters
- Optionalonrejected: ((reason: any) => TResult | PromiseLike<TResult>) | null
- Optionaloncancelled: CancellablePromiseCanceller
Returns CancellablePromise<T | TResult>
A Promise for the completion of the callback. Cancellation requests on the returned promise will propagate up the chain to the parent promise, but not in the other direction.

The promise returned from cancel will fulfill only after all attached handlers up the entire promise chain have been run.

If onrejected returns a cancellable promise, cancellation requests will be diverted to it, and the specified oncancelled callback will be discarded. See then for more details.
Overrides Promise.catch
- Defined in src/cancellable.ts:450

finally

finally(
onfinally?: (() => void) | null,
oncancelled?: CancellablePromiseCanceller,
): CancellablePromise<T>
Attaches a callback that is invoked when the CancellablePromise is settled (fulfilled or rejected). The resolved value cannot be accessed or modified from the callback. The returned promise will settle in the same state as the original one after the provided callback has completed execution, unless the callback throws or returns a rejecting promise, in which case the returned promise will reject as well.

The optional oncancelled argument will be invoked when the returned promise is cancelled, with the same semantics as the oncancelled argument of the constructor. Once the parent promise settles, the onfinally callback will run, even after the returned promise has been cancelled: in that case, should it reject or throw, the reason will be wrapped in a CancelledRejectionError and bubbled up as an unhandled rejection.

This method is implemented in terms of then and the same caveats apply. It is polyfilled, hence available in every OS/webview version.
Parameters
- Optionalonfinally: (() => void) | null
- Optionaloncancelled: CancellablePromiseCanceller
Returns CancellablePromise<T>
A Promise for the completion of the callback. Cancellation requests on the returned promise will propagate up the chain to the parent promise, but not in the other direction.

The promise returned from cancel will fulfill only after all attached handlers up the entire promise chain have been run.

If onfinally returns a cancellable promise, cancellation requests will be diverted to it, and the specified oncancelled callback will be discarded. See then for more details.
Overrides Promise.finally
- Defined in src/cancellable.ts:485

then

then<TResult1 = T, TResult2 = never>(
    onfulfilled?:
        | (
            (
                value: T,
            ) => TResult1 | PromiseLike<TResult1> | CancellablePromiseLike<TResult1>
        )
        | null,
    onrejected?:
        | (
            (
                reason: any,
            ) => TResult2 | PromiseLike<TResult2> | CancellablePromiseLike<TResult2>
        )
        | null,
    oncancelled?: CancellablePromiseCanceller,
): CancellablePromise<TResult1 | TResult2>
Attaches callbacks for the resolution and/or rejection of the CancellablePromise.

The optional oncancelled argument will be invoked when the returned promise is cancelled, with the same semantics as the oncancelled argument of the constructor. When the parent promise rejects or is cancelled, the onrejected callback will run, even after the returned promise has been cancelled: in that case, should it reject or throw, the reason will be wrapped in a CancelledRejectionError and bubbled up as an unhandled rejection.
Type Parameters
- TResult1 = T
- TResult2 = never
Parameters
- Optionalonfulfilled:
      | (
          (
              value: T,
          ) => TResult1 | PromiseLike<TResult1> | CancellablePromiseLike<TResult1>
      )
      | null
  The callback to execute when the Promise is resolved.
- Optionalonrejected:
      | (
          (
              reason: any,
          ) => TResult2 | PromiseLike<TResult2> | CancellablePromiseLike<TResult2>
      )
      | null
  The callback to execute when the Promise is rejected.
- Optionaloncancelled: CancellablePromiseCanceller
Returns CancellablePromise<TResult1 | TResult2>
A CancellablePromise for the completion of whichever callback is executed. The returned promise is hooked up to propagate cancellation requests up the chain, but not down:
- if the parent promise is cancelled, the onrejected handler will be invoked with a CancelError and the returned promise will resolve regularly with its result;
- conversely, if the returned promise is cancelled, the parent promise is cancelled too; the onrejected handler will still be invoked with the parent's CancelError, but its result will be discarded and the returned promise will reject with a CancelError as well.
The promise returned from cancel will fulfill only after all attached handlers up the entire promise chain have been run.

If either callback returns a cancellable promise, cancellation requests will be diverted to it, and the specified oncancelled callback will be discarded.
Implementation of CancellablePromiseLike.then
Overrides Promise.then
- Defined in src/cancellable.ts:368

`Static`try

try<T, U extends unknown[]>(
callbackFn: (...args: U) => T | PromiseLike<T>,
...args: U,
): Promise<Awaited<T>>
Takes a callback of any kind (returns or throws, synchronously or asynchronously) and wraps its result in a Promise.
Type Parameters
- T
- U extends unknown[]
Parameters
- callbackFn: (...args: U) => T | PromiseLike<T>
  A function that is called synchronously. It can do anything: either return a value, throw an error, or return a promise.
- ...args: U
  Additional arguments, that will be passed to the callback.
Returns Promise<Awaited<T>>
A Promise that is:
- Already fulfilled, if the callback synchronously returns a value.
- Already rejected, if the callback synchronously throws an error.
- Asynchronously fulfilled or rejected, if the callback returns a promise.
Inherited from Promise.try
- Defined in node_modules/typescript/lib/lib.esnext.promise.d.ts:33

Static Methods

`Static`all

all<T>(values: Iterable<T | PromiseLike<T>>): CancellablePromise<Awaited<T>[]>
Creates a CancellablePromise that is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

Every one of the provided objects that is a thenable and cancellable object will be cancelled when the returned promise is cancelled, with the same cause.
Type Parameters
- T
Parameters
- values: Iterable<T | PromiseLike<T>>
Returns CancellablePromise<Awaited<T>[]>
Overrides Promise.all
- Defined in src/cancellable.ts:524
all<T extends [] | readonly unknown[]>(
    values: T,
): CancellablePromise<
    { -readonly [P in string
    | number
    | symbol]: Awaited<T[P]> },
>
Creates a Promise that is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.
Type Parameters
- T extends [] | readonly unknown[]
Parameters
- values: T
  An array of Promises.
Returns CancellablePromise<{ -readonly [P in string | number | symbol]: Awaited<T[P]> }>
A new Promise.
Overrides Promise.all
- Defined in src/cancellable.ts:525

`Static`allSettled

allSettled<T>(
values: Iterable<T | PromiseLike<T>>,
): CancellablePromise<PromiseSettledResult<Awaited<T>>[]>
Creates a CancellablePromise that is resolved with an array of results when all of the provided Promises resolve or reject.

Every one of the provided objects that is a thenable and cancellable object will be cancelled when the returned promise is cancelled, with the same cause.
Type Parameters
- T
Parameters
- values: Iterable<T | PromiseLike<T>>
Returns CancellablePromise<PromiseSettledResult<Awaited<T>>[]>
Overrides Promise.allSettled
- Defined in src/cancellable.ts:545
allSettled<T extends [] | readonly unknown[]>(
    values: T,
): CancellablePromise<
    {
        -readonly [P in string
        | number
        | symbol]: PromiseSettledResult<Awaited<T[P]>>
    },
>
Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.
Type Parameters
- T extends [] | readonly unknown[]
Parameters
- values: T
  An array of Promises.
Returns CancellablePromise<
    {
        -readonly [P in string
        | number
        | symbol]: PromiseSettledResult<Awaited<T[P]>>
    },
>
A new Promise.
Overrides Promise.allSettled
- Defined in src/cancellable.ts:546

`Static`any

any<T>(values: Iterable<T | PromiseLike<T>>): CancellablePromise<Awaited<T>>
The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.

Every one of the provided objects that is a thenable and cancellable object will be cancelled when the returned promise is cancelled, with the same cause.
Type Parameters
- T
Parameters
- values: Iterable<T | PromiseLike<T>>
Returns CancellablePromise<Awaited<T>>
Overrides Promise.any
- Defined in src/cancellable.ts:568
any<T extends [] | readonly unknown[]>(
values: T,
): CancellablePromise<Awaited<T[number]>>
The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.
Type Parameters
- T extends [] | readonly unknown[]
Parameters
- values: T
  An array or iterable of Promises.
Returns CancellablePromise<Awaited<T[number]>>
A new Promise.
Overrides Promise.any
- Defined in src/cancellable.ts:569

`Static`cancel

cancel<T = never>(cause?: any): CancellablePromise<T>
Creates a new cancelled CancellablePromise for the provided cause.
Type Parameters
- T = never
Parameters
- Optionalcause: any
Returns CancellablePromise<T>
- Defined in src/cancellable.ts:603

`Static`race

race<T>(values: Iterable<T | PromiseLike<T>>): CancellablePromise<Awaited<T>>
Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.

Every one of the provided objects that is a thenable and cancellable object will be cancelled when the returned promise is cancelled, with the same cause.
Type Parameters
- T
Parameters
- values: Iterable<T | PromiseLike<T>>
Returns CancellablePromise<Awaited<T>>
Overrides Promise.race
- Defined in src/cancellable.ts:588
race<T extends [] | readonly unknown[]>(
values: T,
): CancellablePromise<Awaited<T[number]>>
Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.
Type Parameters
- T extends [] | readonly unknown[]
Parameters
- values: T
  An array of Promises.
Returns CancellablePromise<Awaited<T[number]>>
A new Promise.
Overrides Promise.race
- Defined in src/cancellable.ts:589

`Static`reject

reject<T = never>(reason?: any): CancellablePromise<T>
Creates a new rejected CancellablePromise for the provided reason.
Type Parameters
- T = never
Parameters
- Optionalreason: any
Returns CancellablePromise<T>
Overrides Promise.reject
- Defined in src/cancellable.ts:655

`Static`resolve

resolve(): CancellablePromise<void>
Creates a new resolved CancellablePromise.

Returns CancellablePromise<void>
Overrides Promise.resolve
- Defined in src/cancellable.ts:664
resolve<T>(value: T): CancellablePromise<Awaited<T>>
Creates a new resolved CancellablePromise for the provided value.
Type Parameters
- T
Parameters
- value: T
Returns CancellablePromise<Awaited<T>>
Overrides Promise.resolve
- Defined in src/cancellable.ts:670
resolve<T>(value: T | PromiseLike<T>): CancellablePromise<Awaited<T>>
Creates a new resolved CancellablePromise for the provided value.
Type Parameters
- T
Parameters
- value: T | PromiseLike<T>
Returns CancellablePromise<Awaited<T>>
Overrides Promise.resolve
- Defined in src/cancellable.ts:676

`Static`sleep

sleep(milliseconds: number): CancellablePromise<void>
Creates a new CancellablePromise that resolves after the specified timeout. The returned promise can be cancelled without consequences.
Parameters
- milliseconds: number
Returns CancellablePromise<void>
- Defined in src/cancellable.ts:635
sleep<T>(milliseconds: number, value: T): CancellablePromise<T>
Creates a new CancellablePromise that resolves after the specified timeout, with the provided value. The returned promise can be cancelled without consequences.
Type Parameters
- T
Parameters
- milliseconds: number
- value: T
Returns CancellablePromise<T>
- Defined in src/cancellable.ts:643

`Static`timeout

timeout<T = never>(milliseconds: number, cause?: any): CancellablePromise<T>
Creates a new CancellablePromise that cancels after the specified timeout, with the provided cause.

If the AbortSignal.timeout factory method is available, it is used to base the timeout on active time rather than elapsed time. Otherwise, timeout falls back to setTimeout.
Type Parameters
- T = never
Parameters
- milliseconds: number
- Optionalcause: any
Returns CancellablePromise<T>
- Defined in src/cancellable.ts:619

`Static`withResolvers

withResolvers<T>(): CancellablePromiseWithResolvers<T>
Creates a new CancellablePromise and returns it in an object, along with its resolve and reject functions and a getter/setter for the cancellation callback.

This method is polyfilled, hence available in every OS/webview version.
Type Parameters
- T
Returns CancellablePromiseWithResolvers<T>
Overrides Promise.withResolvers
- Defined in src/cancellable.ts:693

Class CancellablePromise<T>

Type Parameters

Hierarchy

Implements

Index

Constructors

Properties

Methods

Static Methods

Constructors

constructor

Type Parameters

Parameters

Returns CancellablePromise<T>

Properties

Readonly[toStringTag]

Methods

cancel

Parameters

Returns CancellablePromise<void>

cancelOn

Parameters

Returns CancellablePromise<T>

catch

Type Parameters

Parameters

Returns CancellablePromise<T | TResult>

finally

Parameters

Returns CancellablePromise<T>

then

Type Parameters

Parameters

Returns CancellablePromise<TResult1 | TResult2>

Statictry

Type Parameters

Parameters

Returns Promise<Awaited<T>>

Static Methods

Staticall

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T>[]>

Type Parameters

Parameters

Returns CancellablePromise<{ -readonly [P in string | number | symbol]: Awaited<T[P]> }>

StaticallSettled

Type Parameters

Parameters

Returns CancellablePromise<PromiseSettledResult<Awaited<T>>[]>

Type Parameters

Parameters

Returns CancellablePromise< { -readonly [P in string | number | symbol]: PromiseSettledResult<Awaited<T[P]>> },>

Staticany

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T>>

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T[number]>>

Staticcancel

Type Parameters

Parameters

Returns CancellablePromise<T>

Staticrace

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T>>

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T[number]>>

Staticreject

Type Parameters

Parameters

Returns CancellablePromise<T>

Staticresolve

Returns CancellablePromise<void>

Type Parameters

Parameters

Returns CancellablePromise<Awaited<T>>

`Readonly`[toStringTag]

`Static`try

`Static`all

`Static`allSettled

Returns CancellablePromise<
{
-readonly [P in string
| number
| symbol]: PromiseSettledResult<Awaited<T[P]>>
},
>

`Static`any

`Static`cancel

`Static`race

`Static`reject

`Static`resolve

`Static`sleep

`Static`timeout

`Static`withResolvers