@humanwhocodes/retry 0.4.3

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40humanwhocodes/retry@0.4.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40humanwhocodes/retry@0.4.3
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ca6058cf5b8c16f976c73c8d0d385acec523d1e5f01630eb019ebeed2d918344","constraints":{"executionContext":"node"},"contract":["Retrier executes async functions and resolves the return value on the first attempt when no error occurs","Retrier catches transient errors, retries when check predicate returns true, and resolves upon eventual success","Retrier immediately rejects without retrying when the error check predicate returns false","Retrier aborts queued or in-progress operations when an AbortSignal is triggered","Retrier enforces maximum concurrency limits and processes pending tasks in order"],"goal":"verify pkg:npm/%40humanwhocodes/retry@0.4.3","kind":"HOW","packages":["pkg:npm/%40humanwhocodes/retry@0.4.3"],"schemaVersion":1,"symbols":["Retrier","Retrier.prototype.retry"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40humanwhocodes/retry@0.4.3"],"schemaVersion":1,"subject":"pkg:npm/%40humanwhocodes/retry@0.4.3","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-retry",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-retry",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@humanwhocodes/retry": "0.4.3"
      }
    },
    "node_modules/@humanwhocodes/retry": {
      "version": "0.4.3",
      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz",
      "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=18.18"
      },
      "funding": {
        "type": "github",
        "url": "https://github.com/sponsors/nzakas"
      }
    }
  }
}

{
  "name": "sample-retry",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @humanwhocodes/retry",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@humanwhocodes/retry": "0.4.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40humanwhocodes/retry@0.4.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40humanwhocodes/retry@0.4.3"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

const { Retrier } = require('@humanwhocodes/retry');

/**
 * Creates a new Retrier instance configured with an error-checking predicate.
 * @param {Function} check - Predicate function returning true if the error should trigger a retry
 * @param {object} [options] - Configuration options for timeout, maxDelay, and concurrency
 * @returns {Retrier} Configured Retrier instance
 */
function createRetrier(check, options) {
  return new Retrier(check, options);
}

module.exports = {
  Retrier,
  createRetrier
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { Retrier, createRetrier } = require('../src/index.js');

// 1. Export verification
assert.equal(typeof Retrier, 'function', 'Retrier must be exported as a class or constructor function');
assert.equal(typeof createRetrier, 'function', 'createRetrier helper must be exported as a function');

// 2. Retrier executes async functions and resolves the return value on the first attempt when no error occurs
{
  const retrier = new Retrier(() => true);
  let callCount = 0;
  const result = await retrier.retry(async () => {
    callCount += 1;
    return 'immediate-success';
  });
  assert.equal(result, 'immediate-success');
  assert.equal(callCount, 1);
  assert.equal(retrier.retrying, 0);
  assert.equal(retrier.working, 0);
}

// 3. Retrier catches transient errors, retries when check predicate returns true, and resolves upon eventual success
{
  let attempts = 0;
  const retrier = createRetrier((err) => err.code === 'TRANSIENT_FAILURE', { maxDelay: 10 });
  const result = await retrier.retry(async () => {
    attempts += 1;
    if (attempts < 3) {
      const err = new Error('Temporary service unavailability');
      err.code = 'TRANSIENT_FAILURE';
      throw err;
    }
    return 'retry-success';
  });
  assert.equal(result, 'retry-success');
  assert.equal(attempts, 3);
  assert.equal(retrier.retrying, 0);
}

// 4. Retrier immediately rejects without retrying when the error check predicate returns false
{
  let attempts = 0;
  const retrier = new Retrier((err) => err.code === 'RETRYABLE_ERROR');
  await assert.rejects(
    async () => {
      await retrier.retry(async () => {
        attempts += 1;
        const err = new Error('Fatal client request validation failure');
        err.code = 'FATAL_ERROR';
        throw err;
      });
    },
    (err) => {
      assert.equal(err.code, 'FATAL_ERROR');
      return true;
    }
  );
  assert.equal(attempts, 1);
  assert.equal(retrier.retrying, 0);
}

// 5. Retrier aborts queued or in-progress operations when an AbortSignal is triggered
{
  const retrier = new Retrier(() => true, { maxDelay: 50 });
  const controller = new AbortController();
  const retryPromise = retrier.retry(
    async () => {
      throw new Error('transient-error-to-retry');
    },
    { signal: controller.signal }
  );

  // Allow the first attempt to fail and enter the retry queue
  await new Promise((resolve) => setTimeout(resolve, 10));
  controller.abort(new Error('Operation cancelled by signal'));

  await assert.rejects(
    async () => {
      await retryPromise;
    },
    (err) => {
      assert.equal(err.message, 'Operation cancelled by signal');
      return true;
    }
  );
}

// 6. Retrier enforces maximum concurrency limits and processes pending tasks in order
{
  const retrier = new Retrier(() => false, { concurrency: 2 });
  let activeCount = 0;
  let peakActive = 0;

  const runTask = async (id) => {
    return retrier.retry(async () => {
      activeCount += 1;
      peakActive = Math.max(peakActive, activeCount);
      await new Promise((resolve) => setTimeout(resolve, 20));
      activeCount -= 1;
      return id;
    });
  };

  const outputs = await Promise.all([runTask(1), runTask(2), runTask(3), runTask(4)]);
  assert.deepEqual(outputs, [1, 2, 3, 4]);
  assert.equal(peakActive, 2);
  assert.equal(retrier.working, 0);
  assert.equal(retrier.pending, 0);
}

console.log('Contract assertions passed.');