onetime 5.1.2: ensure a function is only executed once and returns the result of the first call

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: ensure a function is only executed once and returns the result of the first call
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/onetime@5.1.2
Demonstrate these symbols/APIs:
  - onetime
  - onetime.callCount

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:51ea40b1e41443e052109ff525dbff6a8e2e1e1765d264b4ca12ef16f65c6a74","contract":["assert function executes once and returns initial result on subsequent calls","assert subsequent calls return cached result without re-executing underlying function","assert onetime.callCount accurately returns total invocations of wrapped function","assert onetime.callCount throws when invoked on unwrapped function","assert throw option raises Error on subsequent invocations","assert non-function target throws TypeError","assert wrapped function preserves name and metadata via mimicry"],"goal":"ensure a function is only executed once and returns the result of the first call","kind":"HOW","packages":["pkg:npm/onetime@5.1.2"],"schemaVersion":1,"symbols":["onetime","onetime.callCount"]},"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","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/onetime@5.1.2"],"schemaVersion":1,"subject":"pkg:npm/onetime@5.1.2","symbols":["onetime","onetime.callCount"],"verifierAdapter":"node-typescript@1"}

const onetime = require('onetime');

function createSingleExecutor(fn, options) {
  return onetime(fn, options);
}

function getInvocationCount(fn) {
  return onetime.callCount(fn);
}

module.exports = {
  onetime,
  createSingleExecutor,
  getInvocationCount,
};

{
  "name": "sample-onetime",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-onetime",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "onetime": "5.1.2"
      }
    },
    "node_modules/mimic-fn": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
      "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/onetime": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
      "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
      "license": "MIT",
      "dependencies": {
        "mimic-fn": "^2.1.0"
      },
      "engines": {
        "node": ">=6"
      }
    }
  }
}

{
  "name": "sample-onetime",
  "version": "1.0.0",
  "description": "Minimal clean-room sample verifying onetime execution guarantees and call counting",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "onetime": "5.1.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "ensure a function is only executed once and returns the result of the first call",
  "kind": "HOW",
  "packages": [
    "pkg:npm/onetime@5.1.2"
  ],
  "symbols": [
    "onetime",
    "onetime.callCount"
  ]
}

import assert from 'node:assert';
import onetime from 'onetime';
import { createSingleExecutor, getInvocationCount } from '../index.js';

// 1. Synchronous function runs once and caches return value across multiple invocations
let callCount = 0;
const onceFn = onetime((a, b) => {
  callCount += 1;
  return a + b;
});

assert.strictEqual(callCount, 0, 'wrapped function must not run before invocation');
assert.strictEqual(onceFn(2, 3), 5, 'first invocation computes and returns result');
assert.strictEqual(callCount, 1, 'underlying function executed once');

assert.strictEqual(onceFn(10, 20), 5, 'subsequent invocation returns cached initial result');
assert.strictEqual(callCount, 1, 'underlying function is not re-executed');

// 2. Helper createSingleExecutor adheres to onetime single-execution semantics
let helperCount = 0;
const helperFn = createSingleExecutor(() => {
  helperCount += 1;
  return 'initialized';
});
assert.strictEqual(helperFn(), 'initialized', 'helper executes target function once');
assert.strictEqual(helperFn(), 'initialized', 'helper returns cached result on repeat calls');
assert.strictEqual(helperCount, 1, 'helper target executed only once');

// 3. onetime.callCount accurately reports wrapper invocation count
assert.strictEqual(onetime.callCount(onceFn), 2, 'callCount reflects total wrapper calls');
assert.strictEqual(getInvocationCount(helperFn), 2, 'getInvocationCount reflects total wrapper calls');

const uncalledFn = onetime(() => 'unused');
assert.strictEqual(onetime.callCount(uncalledFn), 0, 'uncalled function has call count 0');

// 4. Calling onetime.callCount on a non-onetime function throws Error
assert.throws(
  () => {
    onetime.callCount(() => {});
  },
  {
    name: 'Error',
    message: /is not wrapped by the `onetime` package/,
  },
  'onetime.callCount on unwrapped function must throw'
);

// 5. Options { throw: true } raises Error on subsequent invocations
let throwTracker = 0;
const strictFn = onetime(
  function onlyOnce() {
    throwTracker += 1;
    return 'ok';
  },
  { throw: true }
);

assert.strictEqual(strictFn(), 'ok', 'first call succeeds when throw: true');
assert.strictEqual(throwTracker, 1, 'target function executed once');

assert.throws(
  () => {
    strictFn();
  },
  {
    name: 'Error',
    message: 'Function `onlyOnce` can only be called once',
  },
  'subsequent call throws descriptive error when throw: true'
);

assert.strictEqual(onetime.callCount(strictFn), 2, 'callCount increments even on throw');

// 6. Passing a non-function throws TypeError
assert.throws(
  () => {
    onetime(null);
  },
  {
    name: 'TypeError',
    message: 'Expected a function',
  },
  'passing non-function throws TypeError'
);

// 7. Function property mimicry and export shapes
function originalOperation(x) {
  return x;
}
const wrapped = onetime(originalOperation);
assert.strictEqual(wrapped.name, 'originalOperation', 'wrapper preserves function name');
assert.strictEqual(typeof onetime, 'function', 'onetime is a function');
assert.strictEqual(typeof onetime.callCount, 'function', 'onetime.callCount is a function');
assert.strictEqual(onetime.default, onetime, 'onetime.default points to onetime for interop');

console.log('All onetime contract assertions passed.');