p-timeout/src/index.ts

import PCancelable from "p-cancelable";

export interface ClearablePromise<T> extends Promise<T> {
	/**
	Clear the timeout.
	 */
	clear: () => void;
}

export type Options<ReturnType> = {
	/**
	Milliseconds before timing out.

	Passing `Infinity` will cause it to never time out.
	 */
	milliseconds: number;

	/**
	Do something other than rejecting with an error on timeout.

	You could for example retry:

	@example
	```
	import {setTimeout} from 'node:timers/promises';
	import pTimeout from 'p-timeout';

	const delayedPromise = () => setTimeout(200);

	await pTimeout(delayedPromise(), {
		milliseconds: 50,
		fallback: () => {
			return pTimeout(delayedPromise(), {
				milliseconds: 300
			});
		},
	});
	```
	 */
	fallback?: () => ReturnType | Promise<ReturnType>;

	/**
	Specify a custom error message or error.

	If you do a custom error, it's recommended to sub-class `pTimeout.TimeoutError`.
	 */
	message?: string | Error;

	/**
	Custom implementations for the `setTimeout` and `clearTimeout` functions.

	Useful for testing purposes, in particular to work around [`sinon.useFakeTimers()`](https://sinonjs.org/releases/latest/fake-timers/).

	@example
	```
	import pTimeout from 'p-timeout';
	import sinon from 'sinon';

	const originalSetTimeout = setTimeout;
	const originalClearTimeout = clearTimeout;

	sinon.useFakeTimers();

	// Use `pTimeout` without being affected by `sinon.useFakeTimers()`:
	await pTimeout(doSomething(), {
		milliseconds: 2000,
		customTimers: {
			setTimeout: originalSetTimeout,
			clearTimeout: originalClearTimeout
		}
	});
	```
	 */
	readonly customTimers?: {
		setTimeout: typeof globalThis.setTimeout;
		clearTimeout: typeof globalThis.clearTimeout;
	};

	/**
	You can abort the promise using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).

	_Requires Node.js 16 or later._

	@example
	```
	import pTimeout from 'p-timeout';
	import delay from 'delay';

	const delayedPromise = delay(3000);

	const abortController = new AbortController();

	setTimeout(() => {
		abortController.abort();
	}, 100);

	await pTimeout(delayedPromise, {
		milliseconds: 2000,
		signal: abortController.signal
	});
	```
	 */
	signal?: globalThis.AbortSignal;
};

/**
Timeout a promise after a specified amount of time.

If you pass in a cancelable promise, specifically a promise with a `.cancel()` method, that method will be called when the `pTimeout` promise times out.

@param input - Promise to decorate.
@returns A decorated `input` that times out after `milliseconds` time. It has a `.clear()` method that clears the timeout.

@example
```
import {setTimeout} from 'node:timers/promises';
import pTimeout from 'p-timeout';

const delayedPromise = () => setTimeout(200);

await pTimeout(delayedPromise(), {
	milliseconds: 50,
	fallback: () => {
		return pTimeout(delayedPromise(), 300);
	}
});
```
 */

export class TimeoutError extends Error {
	readonly name: "TimeoutError";
	constructor(message?: string) {
		super(message);
		this.name = "TimeoutError";
	}
}

/**
An error to be thrown when the request is aborted by AbortController.
DOMException is thrown instead of this Error when DOMException is available.
*/
export class AbortError extends Error {
	readonly name: "AbortError";
	constructor(message?: string) {
		super();
		this.name = "AbortError";
		this.message = message as string;
	}
}

/**
TODO: Remove AbortError and just throw DOMException when targeting Node 18.
*/
const getDOMException = (errorMessage: string | undefined) =>
	globalThis.DOMException === undefined
		? new AbortError(errorMessage)
		: new DOMException(errorMessage);

/**
TODO: Remove below function and just 'reject(signal.reason)' when targeting Node 18.
*/
const getAbortedReason = (signal: AbortSignal) => {
	const reason =
		signal.reason === undefined
			? getDOMException("This operation was aborted.")
			: signal.reason;

	return reason instanceof Error ? reason : getDOMException(reason);
};

export default function pTimeout<ValueType, ReturnType = ValueType>(
	promise: PromiseLike<ValueType> | PCancelable<ValueType>,
	options: Options<ReturnType>
): ClearablePromise<ValueType | ReturnType> {
	const {
		milliseconds,
		fallback,
		message,
		customTimers = { setTimeout, clearTimeout },
	} = options;

	let timer: undefined | number;

	const cancelablePromise = new Promise((resolve, reject) => {
		if (typeof milliseconds !== "number" || Math.sign(milliseconds) !== 1) {
			throw new TypeError(
				`Expected \`milliseconds\` to be a positive number, got \`${milliseconds}\``
			);
		}

		if (milliseconds === Number.POSITIVE_INFINITY) {
			resolve(promise);
			return;
		}

		if (options.signal) {
			const { signal } = options;
			if (signal.aborted) {
				reject(getAbortedReason(signal));
			}

			signal.addEventListener("abort", () => {
				reject(getAbortedReason(signal));
			});
		}

		timer = customTimers.setTimeout.call(
			undefined,
			() => {
				if (fallback) {
					try {
						resolve(fallback());
					} catch (error) {
						reject(error);
					}

					return;
				}

				const errorMessage =
					typeof message === "string"
						? message
						: `Promise timed out after ${milliseconds} milliseconds`;
				const timeoutError =
					message instanceof Error ? message : new TimeoutError(errorMessage);

				if (typeof (promise as PCancelable<any>)?.cancel === "function") {
					(promise as PCancelable<any>)?.cancel();
				}

				reject(timeoutError);
			},
			milliseconds
		);

		(async () => {
			try {
				resolve(await promise);
			} catch (error) {
				reject(error);
			} finally {
				customTimers.clearTimeout.call(undefined, timer);
			}
		})();
	});

	(cancelablePromise as ClearablePromise<ValueType | ReturnType>).clear =
		() => {
			customTimers.clearTimeout.call(undefined, timer);
			timer = undefined;
		};

	return cancelablePromise as ClearablePromise<ValueType | ReturnType>;
}