Timeout a promise after a specified amount of time
Go to file
Derrick Hammer 0076c9fb03
*Initial refactor to use typescript
2022-12-15 06:54:28 -05:00
.github Fix CI 2022-07-25 18:34:28 +02:00
src *Initial refactor to use typescript 2022-12-15 06:54:28 -05:00
.editorconfig Meta tweaks 2017-07-02 03:43:15 +02:00
.gitattributes Require Node.js 8, add TypeScript definition (#10) 2019-03-12 15:17:11 +07:00
.gitignore Meta tweaks 2017-07-02 03:43:15 +02:00
.npmrc Meta tweaks 2017-07-02 03:43:15 +02:00
.yarnrc.yml *Initial refactor to use typescript 2022-12-15 06:54:28 -05:00
index.d.ts Require Node.js 14 2022-07-25 18:26:31 +02:00
index.test-d.ts Require Node.js 14 2022-07-25 18:26:31 +02:00
license Move to GitHub Actions 2020-12-01 14:57:27 +07:00
package.json *Initial refactor to use typescript 2022-12-15 06:54:28 -05:00
readme.md Require Node.js 14 2022-07-25 18:26:31 +02:00
test.js Require Node.js 14 2022-07-25 18:26:31 +02:00
tsconfig.json *Initial refactor to use typescript 2022-12-15 06:54:28 -05:00

readme.md

p-timeout

Timeout a promise after a specified amount of time

Install

npm install p-timeout

Usage

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

const delayedPromise = setTimeout(200);

await pTimeout(delayedPromise, {
	milliseconds: 50,
});
//=> [TimeoutError: Promise timed out after 50 milliseconds]

API

pTimeout(input, options)

Returns a decorated input that times out after milliseconds time. It has a .clear() method that clears the timeout.

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.

input

Type: Promise

Promise to decorate.

options

Type: object

milliseconds

Type: number

Milliseconds before timing out.

Passing Infinity will cause it to never time out.

message

Type: string | Error
Default: 'Promise timed out after 50 milliseconds'

Specify a custom error message or error.

If you do a custom error, it's recommended to sub-class pTimeout.TimeoutError.

fallback

Type: Function

Do something other than rejecting with an error on timeout.

You could for example retry:

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);
	},
});
customTimers

Type: object with function properties setTimeout and clearTimeout

Custom implementations for the setTimeout and clearTimeout functions.

Useful for testing purposes, in particular to work around sinon.useFakeTimers().

Example:

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

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
	}
});

signal

Type: AbortSignal

You can abort the promise using AbortController.

Requires Node.js 16 or later.

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
});

TimeoutError

Exposed for instance checking and sub-classing.

  • delay - Delay a promise a specified amount of time
  • p-min-delay - Delay a promise a minimum amount of time
  • p-retry - Retry a promise-returning function
  • More…