255 lines
5.8 KiB
TypeScript
255 lines
5.8 KiB
TypeScript
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>;
|
|
}
|