node-fetch-retry

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require('node-fetch-retry')` in an ECMAScript Module (ESM) file (e.g., a file with `"type": "module"` in `package.json` or a `.mjs` extension).
  fix Either convert your project or the specific file to CommonJS (`.js` extension without `"type": "module"`) or use dynamic `import()` if `node-fetch-retry` supports it, or use an alternative library designed for ESM.

• TypeError: fetch is not a function

  cause The `node-fetch-retry` package or its underlying `node-fetch` dependency was not correctly installed, resolved, or imported, leading to the `fetch` symbol being undefined.
  fix Ensure `node-fetch-retry` is correctly installed (`npm install node-fetch-retry`) and that the `require` statement is at the top level of your CommonJS module. Verify `node-fetch` is a compatible version with `node-fetch-retry` (likely `node-fetch@2`).

• ERR_REQUIRE_ESM

  cause This error occurs when a CommonJS `require()` call attempts to load an ESM-only module. If `node-fetch-retry` has an internal dependency on `node-fetch` v3+, and your project uses `require`, this conflict can arise.
  fix Downgrade your direct or indirect `node-fetch` dependency to version 2 (e.g., `npm install node-fetch@2`) if `node-fetch-retry` doesn't explicitly state ESM compatibility. Alternatively, migrate your project to ESM if feasible, or use `import('node-fetch').then(...)` for dynamic loading if supported.

Warnings

• gotcha This library explicitly uses `require` in its examples and is likely a CommonJS module. If `node-fetch-retry` internally depends on `node-fetch` version 3 or higher, it might lead to `ERR_REQUIRE_ESM` errors when imported via `require` in a CommonJS context, as `node-fetch` v3+ is ESM-only. Users should ensure compatibility with `node-fetch` v2 if sticking to CommonJS.
  Fix: If encountering `ERR_REQUIRE_ESM`, ensure your project and `node-fetch-retry` are compatible with `node-fetch@2`. Alternatively, rewrite your application to use ESM and consider `node-fetch` directly with custom retry logic or an ESM-compatible retry wrapper.
• gotcha The library's GitHub repository shows the last commit was several years ago. This indicates that the project is not actively maintained, which could mean no new features, bug fixes, or security patches. Users should consider this for long-term project stability and security.
  Fix: Assess the library's stability and feature set against your needs. For actively maintained alternatives with more advanced retry features (e.g., exponential backoff, retry on specific status codes), consider libraries like `fetch-retry` or `@adobe/node-fetch-retry`.
• gotcha Retrying non-idempotent HTTP methods (e.g., POST, PATCH) can lead to unintended side effects, such as duplicate resource creation or multiple charges, if the original request succeeded but the response was not received.
  Fix: Only use retry logic for idempotent methods like GET, PUT, and DELETE where repeating a request has no additional side effects. For non-idempotent requests, implement transactional logic or unique request IDs to ensure operations are only performed once.
• gotcha This library provides basic retry capabilities (fixed retries, fixed pause). It lacks more advanced features like exponential backoff, configurable retry conditions based on HTTP status codes, or custom error handling for different failure types, which are common in more robust retry solutions.
  Fix: For complex retry scenarios, consider libraries like `fetch-retry` which offer configurable `retryDelay` functions (for exponential backoff) and `retryOn` options for specific status codes.

Install

• npm install node-fetch-retry npm
• yarn add node-fetch-retry yarn
• pnpm add node-fetch-retry pnpm

Imports

• fetch
  wrong:

  import fetch from 'node-fetch-retry';

  correct:

  const fetch = require('node-fetch-retry');

  This library is primarily designed for CommonJS (`require`) environments. While Node.js supports ESM, the examples and common usage for this specific package are with `require`. Direct `import` might not work without specific ESM configuration or if the package itself does not provide an `exports` field for ESM.
• fetch (async import)
  wrong:

  import { fetch } from 'node-fetch-retry';

  correct:

  const fetch = (...args) => import('node-fetch-retry').then(({ default: fetch }) => fetch(...args));

  For using `node-fetch-retry` in an ESM module or to dynamically load it in a CommonJS module that might interact with ESM-only dependencies, an async `import()` call is generally required. However, this pattern is typically used when the underlying `node-fetch` dependency is ESM-only (v3+), which may conflict with this wrapper's CJS nature.

Quickstart

Demonstrates fetching a URL with a specified number of retries and a pause between attempts, including a callback to log each retry attempt.

import * as process from 'process';

const fetch = require('node-fetch-retry');

async function fetchDataWithRetry() {
  const targetUrl = 'https://httpstat.us/503?sleep=1000'; // Example URL that returns 503 after a delay
  const retries = 3;
  const pauseMs = 1000; // 1 second pause

  console.log(`Attempting to fetch from ${targetUrl} with ${retries} retries...`);

  try {
    let opts = {
      method: 'GET',
      retry: retries,
      pause: pauseMs,
      callback: (retryAttempt) => {
        console.log(`Retry attempt: ${retryAttempt}. Waiting ${pauseMs}ms before next attempt.`);
      },
      silent: false // Set to true to suppress pause messages
    };

    // Make the fetch request with retry options
    const res = await fetch(targetUrl, opts);

    if (res.ok) {
      const text = await res.text();
      console.log('Fetch successful after retries!');
      console.log('Response:', text.substring(0, 100) + '...');
    } else {
      console.error(`Fetch failed after all retries with status: ${res.status}`);
    }
  } catch (error) {
    console.error('An unhandled error occurred during fetch operation:', error.message);
  }
}

fetchDataWithRetry();