p-limit 7.3.1

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/p-limit@7.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/p-limit@7.3.1

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:92ed1fbdb58ffd134e19c64339c663a3eba6d41a95abeb92493e6d3ca098eca8","contract":["pLimit restricts concurrent execution of async tasks to the specified concurrency limit","limit tracks activeCount and pendingCount reflecting real-time queue state","limit passes through arguments to the wrapped async function and resolves with return value","limit.clearQueue discards pending tasks while allowing active tasks to complete","limit.clearQueue with rejectOnClear rejects pending tasks with an AbortError","limit.concurrency getter and setter dynamically adjust active task capacity","limit.map concurrently maps iterable items with the concurrency limit","limitFunction wraps a function with a shared concurrency limiter","pLimit throws a TypeError when given invalid concurrency or rejectOnClear options"],"goal":"verify pkg:npm/p-limit@7.3.1","kind":"HOW","packages":["pkg:npm/p-limit@7.3.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/p-limit@7.3.1"],"schemaVersion":1,"subject":"pkg:npm/p-limit@7.3.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-p-limit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-p-limit",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "p-limit": "7.3.1"
      }
    },
    "node_modules/p-limit": {
      "version": "7.3.1",
      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-7.3.1.tgz",
      "integrity": "sha512-0trZaiG7Y7kN/Egy9a8j47t9osC0Tch4PaIWd9yGF6bvmlk7muExRvGNYb8sXBwEKMoNKsbNN9P8EefuQekE4Q==",
      "license": "MIT",
      "dependencies": {
        "yocto-queue": "^1.2.1"
      },
      "engines": {
        "node": ">=20"
      }
    },
    "node_modules/yocto-queue": {
      "version": "1.2.2",
      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz",
      "integrity": "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==",
      "license": "MIT",
      "engines": {
        "node": ">=12.20"
      }
    }
  }
}

{
  "name": "sample-p-limit",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "p-limit": "7.3.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/p-limit@7.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/p-limit@7.3.1"
  ]
}

import pLimit, { limitFunction } from 'p-limit';

/**
 * Creates a concurrency limiter function.
 * @param {number|object} options Concurrency count or options object.
 * @returns {Function} Limiter function.
 */
export function createLimiter(options) {
  return pLimit(options);
}

/**
 * Concurrently maps an iterable through an async mapper with a specified concurrency limit.
 * @param {Iterable} iterable Input items.
 * @param {Function} mapper Async mapper function (item, index).
 * @param {number|object} [options=2] Concurrency or options.
 * @returns {Promise<Array>} Resolved array of results.
 */
export async function mapWithLimit(iterable, mapper, options = 2) {
  const limit = pLimit(options);
  return limit.map(iterable, mapper);
}

/**
 * Wraps a function with limited concurrency across all calls.
 * @param {Function} fn Async function to wrap.
 * @param {number|object} options Concurrency or options.
 * @returns {Function} Wrapped rate-limited function.
 */
export function wrapLimitedFunction(fn, options) {
  return limitFunction(fn, options);
}

export { pLimit, limitFunction };
export default pLimit;

import assert from 'node:assert/strict';
import pLimit, { limitFunction } from 'p-limit';
import { createLimiter, mapWithLimit, wrapLimitedFunction } from '../src/index.mjs';

// 1. pLimit restricts concurrent execution of async tasks to the specified concurrency limit
{
  const limit = pLimit(2);
  let active = 0;
  let maxActive = 0;

  const runTask = (val) => limit(async () => {
    active++;
    maxActive = Math.max(maxActive, active);
    await new Promise(resolve => setTimeout(resolve, 25));
    active--;
    return val * 2;
  });

  const results = await Promise.all([runTask(1), runTask(2), runTask(3), runTask(4)]);
  assert.deepEqual(results, [2, 4, 6, 8]);
  assert.equal(maxActive, 2);
}

// 2. limit tracks activeCount and pendingCount reflecting real-time queue state
{
  const limit = pLimit(1);
  let release;
  const p1 = limit(async () => {
    await new Promise(resolve => { release = resolve; });
    return 'first';
  });
  const p2 = limit(async () => 'second');

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(limit.activeCount, 1);
  assert.equal(limit.pendingCount, 1);

  release();
  const res = await Promise.all([p1, p2]);
  assert.deepEqual(res, ['first', 'second']);
  assert.equal(limit.activeCount, 0);
  assert.equal(limit.pendingCount, 0);
}

// 3. limit passes through arguments to the wrapped async function and resolves with return value
{
  const limit = pLimit(2);
  const result = await limit((a, b, c) => a + b + c, 'foo', '-', 'bar');
  assert.equal(result, 'foo-bar');
}

// 4. limit.clearQueue discards pending tasks while allowing active tasks to complete
{
  const limit = pLimit(1);
  let release;
  let secondRan = false;

  const activeTask = limit(async () => {
    await new Promise(resolve => { release = resolve; });
    return 'active-done';
  });
  const pendingTask = limit(async () => {
    secondRan = true;
    return 'pending-done';
  });

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(limit.pendingCount, 1);

  limit.clearQueue();
  assert.equal(limit.pendingCount, 0);

  release();
  const activeRes = await activeTask;
  assert.equal(activeRes, 'active-done');

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(secondRan, false);
}

// 5. limit.clearQueue with rejectOnClear rejects pending tasks with an AbortError
{
  const limit = pLimit({ concurrency: 1, rejectOnClear: true });
  let release;
  let rejectedError;

  const activeTask = limit(async () => {
    await new Promise(resolve => { release = resolve; });
    return 'done';
  });

  const pendingTask = limit(async () => 'never').catch(err => {
    rejectedError = err;
  });

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(limit.pendingCount, 1);

  limit.clearQueue();
  assert.equal(limit.pendingCount, 0);

  release();
  await activeTask;
  await pendingTask;

  assert.equal(rejectedError?.name, 'AbortError');
}

// 6. limit.concurrency getter and setter dynamically adjust active task capacity
{
  const limit = pLimit(1);
  assert.equal(limit.concurrency, 1);

  let release1;
  let release2;
  let startedCount = 0;

  const t1 = limit(async () => {
    startedCount++;
    await new Promise(resolve => { release1 = resolve; });
  });
  const t2 = limit(async () => {
    startedCount++;
    await new Promise(resolve => { release2 = resolve; });
  });

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(startedCount, 1);

  limit.concurrency = 2;
  assert.equal(limit.concurrency, 2);

  await new Promise(resolve => setImmediate(resolve));
  assert.equal(startedCount, 2);

  release1();
  release2();
  await Promise.all([t1, t2]);
}

// 7. limit.map concurrently maps iterable items with the concurrency limit
{
  const limit = pLimit(2);
  const items = [10, 20, 30, 40];
  const mapped = await limit.map(items, async (item, index) => {
    await new Promise(resolve => setTimeout(resolve, 10));
    return item + index;
  });
  assert.deepEqual(mapped, [10, 21, 32, 43]);

  // Helper mapWithLimit
  const helperMapped = await mapWithLimit([1, 2, 3], async (x) => x * 10, 2);
  assert.deepEqual(helperMapped, [10, 20, 30]);
}

// 8. limitFunction wraps a function with a shared concurrency limiter
{
  let concurrentExecutions = 0;
  let peakExecutions = 0;

  const limitedFn = limitFunction(async (x) => {
    concurrentExecutions++;
    peakExecutions = Math.max(peakExecutions, concurrentExecutions);
    await new Promise(resolve => setTimeout(resolve, 20));
    concurrentExecutions--;
    return x * 10;
  }, 2);

  const results = await Promise.all([limitedFn(1), limitedFn(2), limitedFn(3), limitedFn(4)]);
  assert.deepEqual(results, [10, 20, 30, 40]);
  assert.equal(peakExecutions, 2);

  // Helper wrapLimitedFunction
  const wrapped = wrapLimitedFunction(async (x) => x + 5, 2);
  assert.equal(await wrapped(10), 15);
}

// 9. pLimit throws a TypeError when given invalid concurrency or rejectOnClear options
{
  assert.throws(() => pLimit(0), TypeError);
  assert.throws(() => pLimit(-1), TypeError);
  assert.throws(() => pLimit(1.5), TypeError);
  assert.throws(() => pLimit('invalid'), TypeError);
  assert.throws(() => pLimit({ concurrency: 1, rejectOnClear: 'not-a-bool' }), TypeError);
  assert.throws(() => createLimiter(0), TypeError);
}

console.log('Contract tests passed successfully.');