A JavaScript utility for retrying async methods that reject errors
Installations
npm install @humanwhocodes/retry
Developer Guide
Typescript
Yes
Module System
ESM
Min. Node Version
>=18.18
Node Version
22.13.1
NPM Version
10.9.2
Score
99.7
Supply Chain
99.1
Quality
85.2
Maintenance
100
Vulnerability
100
License
Releases
Contributors
Languages
JavaScript (100%)
validate.email 🚀
Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.
Developer
humanwhocodes
Download Statistics
Total Downloads
294,667,537
Last Day
3,732,127
Last Week
20,286,178
Last Month
81,390,743
Last Year
294,663,373
GitHub Statistics
Apache-2.0 License
51 Stars
62 Commits
4 Forks
1 Watchers
11 Branches
4 Contributors
Updated on Feb 22, 2025
Bundle Size
3.19 kB
Minified
1.39 kB
Minified + Gzipped
Sponsor this package
Package Meta Information
Latest Version
0.4.2
Package Id
@humanwhocodes/retry@0.4.2
Unpacked Size
63.46 kB
Size
11.02 kB
File Count
9
NPM Version
10.9.2
Node Version
22.13.1
Published on
Feb 19, 2025
Total Downloads
Cumulative downloads
Total Downloads
294,667,537
Last Day
8.2%
3,732,127
Compared to previous day
Last Week
5.8%
20,286,178
Compared to previous week
Last Month
32%
81,390,743
Compared to previous month
Last Year
7,076,349.9%
294,663,373
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Retry utility
If you find this useful, please consider supporting my work with a donation or nominate me for a GitHub Star.
Description
A utility for retrying failed async JavaScript calls based on the error returned.
Usage
Node.js
npm install @humanwhocodes/retry
# or
yarn add @humanwhocodes/retry
Import into your Node.js project:
1// CommonJS 2const { Retrier } = require("@humanwhocodes/retry"); 3 4// ESM 5import { Retrier } from "@humanwhocodes/retry";
Deno
Install using JSR:
1deno add @humanwhocodes/retry 2 3#or 4 5jsr add @humanwhocodes/retry
Then import into your Deno project:
1import { Retrier } from "@humanwhocodes/retry";
Bun
Install using this command:
bun add @humanwhocodes/retry
Import into your Bun project:
1import { Retrier } from "@humanwhocodes/retry";
Browser
It's recommended to import the minified version to save bandwidth:
1import { Retrier } from "https://cdn.skypack.dev/@humanwhocodes/retry?min";
However, you can also import the unminified version for debugging purposes:
1import { Retrier } from "https://cdn.skypack.dev/@humanwhocodes/retry";
API
After importing, create a new instance of Retrier
and specify the function to run on the error. This function should return true
if you want the call retried and false
if not.
1// this instance will retry if the specific error code is found 2const retrier = new Retrier(error => { 3 return error.code === "ENFILE" || error.code === "EMFILE"; 4});
Then, call the retry()
method around the function you'd like to retry, such as:
1import fs from "fs/promises"; 2 3const retrier = new Retrier(error => { 4 return error.code === "ENFILE" || error.code === "EMFILE"; 5}); 6 7const text = await retrier.retry(() => fs.readFile("README.md", "utf8"));
The retry()
method will either pass through the result on success or wait and retry on failure. Any error that isn't caught by the retrier is automatically rejected so the end result is a transparent passing through of both success and failure.
Setting a Timeout
You can control how long a task will attempt to retry before giving up by passing the timeout
option to the Retrier
constructor. By default, the timeout is one minute.
1import fs from "fs/promises";
2
3const retrier = new Retrier(error => {
4 return error.code === "ENFILE" || error.code === "EMFILE";
5}, { timeout: 100_000 });
6
7const text = await retrier.retry(() => fs.readFile("README.md", "utf8"));
When a call times out, it rejects the first error that was received from calling the function.
Setting a Concurrency Limit
When processing a large number of function calls, you can limit the number of concurrent function calls by passing the concurrency
option to the Retrier
constructor. By default, concurrency
is 1000.
1import fs from "fs/promises"; 2 3const retrier = new Retrier(error => { 4 return error.code === "ENFILE" || error.code === "EMFILE"; 5}, { concurrency: 100 }); 6 7const filenames = getFilenames(); 8const contents = await Promise.all( 9 filenames.map(filename => retrier.retry(() => fs.readFile(filename, "utf8")) 10);
Aborting with AbortSignal
You can also pass an AbortSignal
to cancel a retry:
1import fs from "fs/promises";
2
3const controller = new AbortController();
4const retrier = new Retrier(error => {
5 return error.code === "ENFILE" || error.code === "EMFILE";
6});
7
8const text = await retrier.retry(
9 () => fs.readFile("README.md", "utf8"),
10 { signal: controller.signal }
11);
Developer Setup
- Fork the repository
- Clone your fork
- Run
npm install
to setup dependencies - Run
npm test
to run tests
Debug Output
Enable debugging output by setting the DEBUG
environment variable to "@hwc/retry"
before running.
License
Apache 2.0
Prior Art
This utility is inspired by, and contains code from graceful-fs
.

No vulnerabilities found.

No security vulnerabilities found.