once 1.4.0: strict

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/once@1.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/once@1.4.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@11.8.0
  - runtime: node@24.13.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:849bb44f457e993434eda73955764fbbceed08655169298b484e91ae85b3e8d2","constraints":{"executionContext":"node"},"contract":["once wraps a function to execute only once and returns the cached return value on subsequent calls","once passes arguments and preserves context (this) on the first execution","once exposes called boolean flag and value result property on the wrapped function","once.strict executes a named function once and throws an error with the function name on subsequent calls","once.strict executes an anonymous function once and throws an error on subsequent calls"],"goal":"verify pkg:npm/once@1.4.0","kind":"HOW","packages":["pkg:npm/once@1.4.0"],"schemaVersion":1,"symbols":["once","once.strict"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","ecosystem":"npm","os":"windows","osVersionBucket":"11","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/once@1.4.0"],"schemaVersion":1,"symbols":["once","once.strict"],"verifierAdapter":"node-typescript@1"}

const once = require('once');

/**
 * Creates a function that is restricted to invoking `fn` once.
 * Repeat calls return the value of the first invocation.
 * @param {Function} fn
 * @returns {Function}
 */
function runOnce(fn) {
  return once(fn);
}

/**
 * Creates a function that can only be invoked once, throwing an error on repeat calls.
 * @param {Function} fn
 * @returns {Function}
 */
function runOnceStrict(fn) {
  return once.strict(fn);
}

module.exports = {
  runOnce,
  runOnceStrict
};

{
  "name": "sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample",
      "version": "1.0.0",
      "dependencies": {
        "once": "1.4.0"
      }
    },
    "node_modules/once": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
      "license": "ISC",
      "dependencies": {
        "wrappy": "1"
      }
    },
    "node_modules/wrappy": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample",
  "version": "1.0.0",
  "dependencies": {
    "once": "1.4.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/once@1.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/once@1.4.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@11.8.0",
    "runtime": "node@24.13.1"
  }
}

const assert = require('node:assert/strict');
const once = require('once');

assert.equal(typeof once, 'function', 'once must be exported as a function');
assert.equal(typeof once.strict, 'function', 'once.strict must be exported as a function');

// Contract 1: once wraps a function to execute only once and returns the cached return value on subsequent calls
{
  let callCount = 0;
  const fn = (a, b) => {
    callCount += 1;
    return a + b;
  };
  const wrapped = once(fn);

  assert.equal(wrapped.called, false);
  assert.equal(callCount, 0);

  const res1 = wrapped(2, 3);
  assert.equal(res1, 5);
  assert.equal(callCount, 1);
  assert.equal(wrapped.called, true);
  assert.equal(wrapped.value, 5);

  const res2 = wrapped(10, 20);
  assert.equal(res2, 5);
  assert.equal(callCount, 1);
  assert.equal(wrapped.called, true);
  assert.equal(wrapped.value, 5);
}

// Contract 2: once passes arguments and preserves context (this) on the first execution
{
  const obj = {
    multiplier: 4,
    calculate: once(function (x, y) {
      return (x + y) * this.multiplier;
    })
  };

  const res1 = obj.calculate(3, 5);
  assert.equal(res1, 32);
  assert.equal(obj.calculate.called, true);
  assert.equal(obj.calculate.value, 32);

  const res2 = obj.calculate(100, 200);
  assert.equal(res2, 32);
}

// Contract 3: once exposes called boolean flag and value result property on the wrapped function
{
  const compute = (str) => str.toUpperCase();
  const wrapped = once(compute);

  assert.equal(wrapped.called, false);
  assert.equal(wrapped.value, undefined);

  const result = wrapped('codesamplex');
  assert.equal(result, 'CODESAMPLEX');
  assert.equal(wrapped.called, true);
  assert.equal(wrapped.value, 'CODESAMPLEX');
}

// Contract 4: once.strict executes a named function once and throws an error with the function name on subsequent calls
{
  let runs = 0;
  function processRecord(id) {
    runs += 1;
    return { id, processed: true };
  }

  const strictFn = once.strict(processRecord);
  assert.equal(strictFn.called, false);

  const res = strictFn(101);
  assert.deepEqual(res, { id: 101, processed: true });
  assert.equal(runs, 1);
  assert.equal(strictFn.called, true);
  assert.deepEqual(strictFn.value, { id: 101, processed: true });

  assert.throws(
    () => strictFn(102),
    (err) => err instanceof Error && err.message === "processRecord shouldn't be called more than once"
  );
  assert.equal(runs, 1);
}

// Contract 5: once.strict executes an anonymous function once and throws an error on subsequent calls
{
  let count = 0;
  const anonStrict = once.strict((n) => {
    count += 1;
    return n * 10;
  });

  assert.equal(anonStrict.called, false);
  assert.equal(anonStrict(7), 70);
  assert.equal(count, 1);
  assert.equal(anonStrict.called, true);

  assert.throws(
    () => anonStrict(8),
    (err) => err instanceof Error && /shouldn't be called more than once/.test(err.message)
  );
  assert.equal(count, 1);
}

console.log('All once contract assertions passed successfully.');