undici-retry

Common errors

• TypeError: (0 , undici_retry_1.sendWithRetry) is not a function

  cause Attempting to use `require()` to import `undici-retry` functions in a CommonJS context when the library is primarily designed for ESM.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { sendWithRetry } from 'undici-retry';`. If strictly bound to CommonJS, you might need a dynamic `import()` or transpilation.

• npm ERR! ERESOLVE unable to resolve dependency tree ... undici-retry@X.Y.Z requires a peer of undici@A.B.C but none is installed.

  cause The installed version of `undici` does not satisfy the peer dependency requirements of `undici-retry`.
  fix Install the correct version of `undici` that matches the peer dependency declared by your `undici-retry` version. For `undici-retry@7.x`, run `npm install undici@7`.

• Error: Request aborted by client. Reason: Aborted with cause: The connection was closed before the request could be completed.

  cause Likely due to unconsumed or undumped response bodies from `sendWithRetryReturnStream`, leading to `undici` connection pool exhaustion.
  fix Review all calls to `sendWithRetryReturnStream` and ensure that `result.result.body` is either fully consumed (e.g., `await stream.text()`) or explicitly dumped (`await stream.dump()`) after use.

Warnings

• breaking Major versions of `undici-retry` are tightly coupled to specific major versions of its `undici` peer dependency. For instance, `undici-retry@4.x` requires `undici@6.x`, and `undici-retry@7.x` requires `undici@7.x`.
  Fix: Always ensure your installed `undici` version matches the peer dependency requirement of `undici-retry` (e.g., `npm install undici@7`). Check the `package.json` for precise peer dependency ranges.
• breaking `undici-retry` versions 4.0.0 and above dropped support for Node.js 16. Newer versions require Node.js >=20.
  Fix: Upgrade your Node.js environment to version 20 or higher. Using `nvm` or a similar tool is recommended for managing Node.js versions.
• gotcha When using `sendWithRetryReturnStream`, the response body is returned as a Node.js `Readable` stream and is NOT automatically consumed. Failure to consume (e.g., by reading `stream.text()`, `stream.json()`, `stream.blob()`, or piping it) or explicitly dump (`stream.dump()`) the stream will lead to connection leaks and eventual `undici` resource exhaustion.
  Fix: Always ensure the returned `Readable` stream from `result.result.body` is fully consumed or explicitly `await result.result.body.dump()` if the content is not needed, to release the underlying connection.
• gotcha By default, `throwOnInternalError` is `false` in `RequestParams` and `StreamedResponseRequestParams`. This means network-level errors (like `ECONNREFUSED` or `ENOTFOUND`) will be captured and returned within the `result.error` object, rather than throwing an exception.
  Fix: If you prefer internal errors to be thrown as exceptions (e.g., for standard try-catch blocks), set `throwOnInternalError: true` in your `requestParams` or `streamParams`.

Install

• npm install undici-retry npm
• yarn add undici-retry yarn
• pnpm add undici-retry pnpm

Imports

• sendWithRetry
  wrong:

  const sendWithRetry = require('undici-retry').sendWithRetry

  correct:

  import { sendWithRetry } from 'undici-retry'

  The library is primarily ESM. Using CommonJS `require` with default Node.js settings will likely fail.
• sendWithRetryReturnStream
  wrong:

  const { sendWithRetryReturnStream } = require('undici-retry')

  correct:

  import { sendWithRetryReturnStream } from 'undici-retry'

  Used for requests where the response body needs to be processed as a Node.js Readable stream, rather than being automatically consumed.
• DEFAULT_RETRYABLE_STATUS_CODES
  wrong:

  import undiciRetry from 'undici-retry'; undiciRetry.DEFAULT_RETRYABLE_STATUS_CODES

  correct:

  import { DEFAULT_RETRYABLE_STATUS_CODES } from 'undici-retry'

  This is a named export for a common constant, not part of a default export.
• RetryConfig, RequestParams
  wrong:

  import { RetryConfig, RequestParams } from 'undici-retry'

  correct:

  import type { RetryConfig, RequestParams } from 'undici-retry'

  Always use `import type` for type-only imports to prevent bundling issues and improve clarity in TypeScript.

Quickstart

Demonstrates how to perform an HTTP GET request with retry logic using `sendWithRetry`, configure retry parameters, and handle the `Either` result for both success and failure scenarios.

import { sendWithRetry, DEFAULT_RETRYABLE_STATUS_CODES } from 'undici-retry';
import type { RetryConfig, RequestParams} from 'undici-retry'
import { Client } from 'undici';
import type { Dispatcher } from 'undici';

const client = new Client('http://localhost:3000', {}); // Replace with your target URL

async function makeRetriableRequest() {
    const request: Dispatcher.RequestOptions = {
        method: 'GET',
        path: '/',
        bodyTimeout: 500,
        headersTimeout: 500,
    };

    const retryConfig: RetryConfig = {
        maxAttempts: 3,
        statusCodesToRetry: [429, 500, 502, 503, 504], // Customize retryable status codes
        retryOnTimeout: true,
        // delayResolver: (response, statusCodesToRetry) => { /* custom logic */ return 1000; }
    };

    const requestParams: RequestParams = {
        safeParseJson: true,
        blobBody: false,
        throwOnInternalError: false,
    };

    console.log('Attempting request with retry logic...');
    const result = await sendWithRetry(client, request, retryConfig, requestParams);

    if (result.error) {
        console.error('Request failed after all retries:');
        console.error(JSON.stringify({
            body: result.error.body, // The last error response body
            headers: result.error.headers,
            statusCode: result.error.statusCode,
            message: result.error.error?.message, // Error message if an internal error occurred
        }, null, 2));
    } else if (result.result) {
        console.log('Request successful:');
        console.log(JSON.stringify({
            body: result.result.body,
            headers: result.result.headers,
            statusCode: result.result.statusCode,
        }, null, 2));
    }

    await client.close(); // Important: Close the client when no longer needed
}

makeRetriableRequest();