TypeScript

The type arguments of each function, the exported types, how to narrow rejection reasons, and the entries of the package.

GuideTypeScriptTry an example

Types are included

The package ships its declarations. There is nothing to install from @types.

Type arguments

generics.ts

import { CancelablePromise, defer, groupAsCancelablePromise } from 'easy-cancelable-promise';

interface User {
  id: number;
  name: string;
}

// the type argument is the type of the result
const user = new CancelablePromise<User>((resolve) => resolve({ id: 1, name: 'Ada' }));

// then, catch and finally keep the CancelablePromise type
const name: CancelablePromise<string> = user.then((value) => value.name);
const safe: CancelablePromise<User | null> = user.catch(() => null);

// defer<T>() types resolve and the promise
const deferred = defer<User>();
deferred.resolve({ id: 2, name: 'Grace' });

// @ts-expect-error the result of this deferred is a User
deferred.resolve('Grace');

// a group resolves with the array you describe, or returns null for an empty list
const group: CancelablePromise<User[]> | null = groupAsCancelablePromise<User[]>([() => user]);

export { name, safe, group };

Function	Type arguments
`new CancelablePromise<T>(callback)`	`T`: the result. Default `void`
`defer<T>()`	`T`: the result
`groupAsCancelablePromise<T>(tasks)`	`T`: the array of results, for example `User[]`
`toCancelablePromise(source)`	Inferred from the source. `<S, T>` sets both by hand
`isCancelablePromise<T>(value)`	`T`: the result of the promise the value is narrowed to

Reasons are unknown

The reason of a rejection or a cancellation can be any value, so catch, onCancel and the rejection handler of then receive unknown. Narrow it before use.

reasons.ts

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

class TimeoutError extends Error {}

export async function load(request: CancelablePromise<string>) {
  try {
    return await request;
  } catch (reason) {
    // reasons are typed unknown: narrow them before use
    if (reason instanceof TimeoutError) return 'Took too long';
    if (reason instanceof Error) return reason.message;

    return String(reason);
  }
}

export { TimeoutError };

Exported types

types.ts

import { CancelablePromise } from 'easy-cancelable-promise';
import type {
  CancelablePromiseCallback,
  CancelablePromiseSettledResult,
  CancelablePromiseUtils,
  CancelCallback,
  OnProgressCallback,
  PromiseStatus,
  RejectCallback,
  ResolveCallback,
  Subscription,
  SubscriptionParams,
} from 'easy-cancelable-promise';

// the callback of the constructor, written on its own
const callback: CancelablePromiseCallback<number> = (
  resolve: ResolveCallback<number>,
  reject: RejectCallback,
  utils: CancelablePromiseUtils<number>,
) => {
  const unsubscribe: Subscription = utils.onCancel(() => reject(new Error('Stopped')));

  resolve(1);
  unsubscribe();
};

const onCancel: CancelCallback = (reason) => console.log(reason);
const onProgress: OnProgressCallback = (progress, metadata) => console.log(progress, metadata);
const options: SubscriptionParams = { signal: new AbortController().signal };

const promise = new CancelablePromise(callback).onCancel(onCancel, options).onProgress(onProgress, options);

export const status: PromiseStatus = promise.status; // 'pending' | 'resolved' | 'rejected' | 'canceled'

// one outcome of CancelablePromise.allSettled: 'fulfilled', 'rejected' or 'canceled'
export const describe = (result: CancelablePromiseSettledResult<number>) =>
  result.status === 'fulfilled' ? `value ${result.value}` : `${result.status}: ${String(result.reason)}`;

Type	Describes
`PromiseStatus`	`'pending'`, `'resolved'`, `'rejected'` or `'canceled'`
`CancelablePromiseCallback<T>`	The callback of the constructor
`CancelablePromiseUtils<T>`	The third parameter of that callback
`ResolveCallback<T>`	`resolve`
`RejectCallback`	`reject`
`CancelCallback`	A cancel listener
`OnProgressCallback`	A progress listener
`Subscription`	The function that removes a listener
`SubscriptionParams`	The options of `onCancel` and `onProgress`: `{ signal }`
`DeferredPromise<T>`	What `defer` returns
`CancelablePromiseSettledResult<T>`	One outcome of `allSettled`: fulfilled, rejected or canceled
`CancelablePromiseGroupConfig`	The configuration of `groupAsCancelablePromise`
`CancelablePromiseBuildCallback<T>`	A task of a group: a function that returns a promise
`CancelableAbortSignal`	The signal of a `CancelableAbortController`
`RemoveEventListener`	The function `signal.subscribe` returns

Entries of the package

Everything is exported from easy-cancelable-promise. Each module is also its own entry, with the same types.

subpaths.ts

// every module is also an entry of the package
import CancelablePromise from 'easy-cancelable-promise/CancelablePromise';
import { defer, type DeferredPromise } from 'easy-cancelable-promise/defer';
import { groupAsCancelablePromise } from 'easy-cancelable-promise/groupAsCancelablePromise';
import { toCancelablePromise } from 'easy-cancelable-promise/toCancelablePromise';
import { isCancelablePromise } from 'easy-cancelable-promise/isCancelablePromise';
import { isPromise } from 'easy-cancelable-promise/isPromise';
import { CancelableAbortController } from 'easy-cancelable-promise/CancelableAbortController';
import { isCancelableAbortSignal } from 'easy-cancelable-promise/isCancelableAbortSignal';
import type { PromiseStatus } from 'easy-cancelable-promise/types';

const deferred: DeferredPromise<number> = defer<number>();

// the class is the same one in every entry
export const sameClass = deferred.promise instanceof CancelablePromise; // true

export const status: PromiseStatus = deferred.promise.status;

export {
  groupAsCancelablePromise,
  toCancelablePromise,
  isCancelablePromise,
  isPromise,
  CancelableAbortController,
  isCancelableAbortSignal,
};

TypeScript

Types are included

Type arguments

Reasons are unknown

Exported types

Entries of the package

Next