tinypool 1.1.1: tinypool

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 tinypool in pkg:npm/tinypool@1.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinypool@1.1.1
Demonstrate these symbols/APIs:
  - tinypool

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:32a540482d10c09f2ba87d3a2b02ec393076404fe52dd333b8d6f501d4665cc6","contract":["Tinypool constructor initializes worker pool with specified thread limits and worker script","run executes default worker handler and returns processed payload","run with name option executes specific named export function in worker script","run with AbortSignal rejects with AbortError when cancellation is triggered","recycleWorkers refreshes worker threads without interrupting subsequent task processing","completed tracks total finished tasks across worker pool execution","destroy terminates active worker threads and shuts down pool"],"goal":"verify tinypool in pkg:npm/tinypool@1.1.1","kind":"HOW","packages":["pkg:npm/tinypool@1.1.1"],"schemaVersion":1,"symbols":["tinypool"]},"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/tinypool@1.1.1"],"schemaVersion":1,"subject":"pkg:npm/tinypool@1.1.1","symbols":["tinypool"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinypool",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinypool",
      "version": "1.0.0",
      "dependencies": {
        "tinypool": "1.1.1"
      }
    },
    "node_modules/tinypool": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
      "license": "MIT",
      "engines": {
        "node": "^18.0.0 || >=20.0.0"
      }
    }
  }
}

{
  "name": "sample-tinypool",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification of tinypool worker pool operations",
  "main": "src/index.js",
  "dependencies": {
    "tinypool": "1.1.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify tinypool in pkg:npm/tinypool@1.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinypool@1.1.1"
  ],
  "symbols": [
    "tinypool"
  ]
}

import { Tinypool } from 'tinypool';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

/**
 * Creates and initializes a Tinypool worker pool instance.
 * @param {object} [options] - Options passed to Tinypool constructor
 * @returns {Tinypool} Initialized worker pool
 */
export function createWorkerPool(options = {}) {
  const defaultWorker = path.resolve(__dirname, 'worker.js');
  return new Tinypool({
    filename: defaultWorker,
    minThreads: 1,
    maxThreads: 2,
    ...options
  });
}

/**
 * Executes default task handler on the worker pool.
 * @param {Tinypool} pool - Worker pool instance
 * @param {any} payload - Task payload
 * @returns {Promise<any>}
 */
export async function runTask(pool, payload) {
  return pool.run(payload);
}

/**
 * Executes a named export function in the worker.
 * @param {Tinypool} pool - Worker pool instance
 * @param {string} name - Export name
 * @param {any} payload - Task payload
 * @returns {Promise<any>}
 */
export async function runNamedTask(pool, name, payload) {
  return pool.run(payload, { name });
}

/**
 * Executes a cancellable task on the worker pool.
 * @param {Tinypool} pool - Worker pool instance
 * @param {string} name - Export name
 * @param {any} payload - Task payload
 * @param {AbortSignal} signal - AbortSignal instance
 * @returns {Promise<any>}
 */
export async function runCancellableTask(pool, name, payload, signal) {
  return pool.run(payload, { name, signal });
}

export { Tinypool };

export function sum({ numbers }) {
  if (!Array.isArray(numbers)) {
    throw new TypeError('numbers must be an array');
  }
  return numbers.reduce((acc, val) => acc + val, 0);
}

export function formatUpper({ text }) {
  if (typeof text !== 'string') {
    throw new TypeError('text must be a string');
  }
  return text.toUpperCase();
}

export async function delayedTask({ value, delayMs = 200 }) {
  await new Promise((resolve) => setTimeout(resolve, delayMs));
  return value;
}

export default function defaultHandler(task) {
  return { handled: true, payload: task };
}

import assert from 'node:assert';
import {
  Tinypool,
  createWorkerPool,
  runTask,
  runNamedTask,
  runCancellableTask
} from '../src/index.js';

// 1. Tinypool constructor initializes worker pool with specified thread limits and worker script
const pool = createWorkerPool();
assert.ok(pool instanceof Tinypool, 'pool should be an instance of Tinypool');
assert.strictEqual(typeof pool.run, 'function', 'pool should have a run method');

try {
  // 2. run executes default worker handler and returns processed payload
  const defaultResult = await runTask(pool, { message: 'hello tinypool' });
  assert.deepStrictEqual(
    defaultResult,
    { handled: true, payload: { message: 'hello tinypool' } },
    'default task handler should return processed payload'
  );

  // 3. run with name option executes specific named export function in worker script
  const sumResult = await runNamedTask(pool, 'sum', { numbers: [10, 20, 30] });
  assert.strictEqual(sumResult, 60, 'named task sum should return 60');

  const upperResult = await runNamedTask(pool, 'formatUpper', { text: 'tinypool' });
  assert.strictEqual(upperResult, 'TINYPOOL', 'named task formatUpper should return TINYPOOL');

  // 4. run with AbortSignal rejects with AbortError when cancellation is triggered
  const controller = new AbortController();
  const cancelPromise = runCancellableTask(
    pool,
    'delayedTask',
    { value: 'aborted-result', delayMs: 400 },
    controller.signal
  );
  setTimeout(() => controller.abort(), 30);

  await assert.rejects(
    async () => {
      await cancelPromise;
    },
    (err) => {
      return err.name === 'AbortError' || (err.message && err.message.includes('aborted'));
    },
    'Task should reject with AbortError when AbortSignal is aborted'
  );

  // 5. recycleWorkers refreshes worker threads without interrupting subsequent task processing
  await pool.recycleWorkers();
  const postRecycleResult = await runNamedTask(pool, 'formatUpper', { text: 'after-recycle' });
  assert.strictEqual(
    postRecycleResult,
    'AFTER-RECYCLE',
    'worker pool should process tasks normally after recycling'
  );

  // 6. completed tracks total finished tasks across worker pool execution
  assert.ok(
    pool.completed >= 4,
    'pool.completed should track total completed tasks'
  );

  // 7. destroy terminates active worker threads and shuts down pool
  assert.ok(pool.threads.length >= 1, 'pool should have active worker threads');
  await pool.destroy();
  assert.strictEqual(pool.threads.length, 0, 'pool threads should be empty after destroy');

  console.log('Contract tests passed successfully.');
} finally {
  if (pool.threads.length > 0) {
    await pool.destroy();
  }
}