mirror of https://github.com/jkjoy/sunpeiwen.git
152 lines
3.6 KiB
TypeScript
152 lines
3.6 KiB
TypeScript
export class TimeoutError extends Error {
|
||
readonly name: 'TimeoutError';
|
||
constructor(message?: string);
|
||
}
|
||
|
||
export type ClearablePromise<T> = {
|
||
/**
|
||
Clear the timeout.
|
||
*/
|
||
clear: () => void;
|
||
} & Promise<T>;
|
||
|
||
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 to throw when it times out:
|
||
|
||
- `message: 'too slow'` will throw `TimeoutError('too slow')`
|
||
- `message: new MyCustomError('it’s over 9000')` will throw the same error instance
|
||
- `message: false` will make the promise resolve with `undefined` instead of rejecting
|
||
|
||
If you do a custom error, it's recommended to sub-class `TimeoutError`:
|
||
|
||
```
|
||
import {TimeoutError} from 'p-timeout';
|
||
|
||
class MyCustomError extends TimeoutError {
|
||
name = "MyCustomError";
|
||
}
|
||
```
|
||
*/
|
||
message?: string | Error | false;
|
||
|
||
/**
|
||
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(), {milliseconds: 300});
|
||
}
|
||
});
|
||
```
|
||
*/
|
||
export default function pTimeout<ValueType, ReturnType = ValueType>(
|
||
input: PromiseLike<ValueType>,
|
||
options: Options<ReturnType> & {message: false}
|
||
): ClearablePromise<ValueType | ReturnType | undefined>;
|
||
export default function pTimeout<ValueType, ReturnType = ValueType>(
|
||
input: PromiseLike<ValueType>,
|
||
options: Options<ReturnType>
|
||
): ClearablePromise<ValueType | ReturnType>;
|