builder-util-runtime 9.7.0: MemoLazy

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 builder-util-runtime.MemoLazy in pkg:npm/builder-util-runtime@9.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/builder-util-runtime@9.7.0
Demonstrate these symbols/APIs:
  - builder-util-runtime.MemoLazy
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:a006e9d81e40a4ba7135e826fb60f3dce2b16ee98ad2eec5739cd31b6b9d9cfa","constraints":{"executionContext":"node"},"contract":["assert MemoLazy defers evaluation until value is accessed and hasValue is initially false","assert MemoLazy caches resolved promise and avoids recomputation for equal selector output","assert MemoLazy recomputes value when selector output changes","assert MemoLazy allows updating cached value and reflects hasValue true"],"goal":"verify builder-util-runtime.MemoLazy in pkg:npm/builder-util-runtime@9.7.0","kind":"HOW","packages":["pkg:npm/builder-util-runtime@9.7.0"],"schemaVersion":1,"symbols":["builder-util-runtime.MemoLazy"]},"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/builder-util-runtime@9.7.0"],"schemaVersion":1,"subject":"pkg:npm/builder-util-runtime@9.7.0","symbols":["builder-util-runtime.MemoLazy"],"verifierAdapter":"node-typescript@1"}

import { MemoLazy } from 'builder-util-runtime';

/**
 * Creates a memoized lazy loader.
 * @template S, V
 * @param {() => S} selector
 * @param {(selected: S) => Promise<V>} creator
 * @returns {MemoLazy<S, V>}
 */
export function createMemoLazy(selector, creator) {
  return new MemoLazy(selector, creator);
}

export { MemoLazy };

{
  "name": "builder-util-runtime-memo-lazy-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "builder-util-runtime-memo-lazy-sample",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "builder-util-runtime": "9.7.0"
      }
    },
    "node_modules/builder-util-runtime": {
      "version": "9.7.0",
      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.3.4",
        "sax": "^1.2.4"
      },
      "engines": {
        "node": ">=12.0.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/sax": {
      "version": "1.6.1",
      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.1.tgz",
      "integrity": "sha512-42tBVwLWnaQvW5zc4HbZrTuWccECCZfBi92FDuwtqxasH+JbPB3/FOKb1m222K42R4WxuxzzMsTswfzgtSu64Q==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=11.0.0"
      }
    }
  }
}

{
  "name": "builder-util-runtime-memo-lazy-sample",
  "version": "1.0.0",
  "description": "Demonstrate builder-util-runtime.MemoLazy usage and behavior",
  "main": "index.mjs",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "builder-util-runtime": "9.7.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify builder-util-runtime.MemoLazy in pkg:npm/builder-util-runtime@9.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/builder-util-runtime@9.7.0"
  ],
  "symbols": [
    "builder-util-runtime.MemoLazy"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import { MemoLazy } from 'builder-util-runtime';
import { createMemoLazy } from '../index.mjs';

// 1. assert MemoLazy defers evaluation until value is accessed and hasValue is initially false
{
  let callCount = 0;
  const lazy = createMemoLazy(
    () => ({ id: 10 }),
    async (sel) => {
      callCount++;
      return `data-${sel.id}`;
    }
  );

  assert.ok(lazy instanceof MemoLazy, 'Must be instance of MemoLazy');
  assert.equal(lazy.hasValue, false, 'hasValue must be false prior to value access');
  assert.equal(callCount, 0, 'creator must not be invoked during construction');

  const valPromise = lazy.value;
  assert.equal(lazy.hasValue, true, 'hasValue must be true once value getter is invoked');
  const val = await valPromise;
  assert.equal(val, 'data-10');
  assert.equal(callCount, 1, 'creator must be invoked once');
}

// 2. assert MemoLazy caches resolved promise and avoids recomputation for equal selector output
{
  let callCount = 0;
  const state = { config: 'production' };
  const lazy = createMemoLazy(
    () => ({ config: state.config }),
    async (sel) => {
      callCount++;
      return `result-${sel.config}`;
    }
  );

  const promise1 = lazy.value;
  const promise2 = lazy.value;
  assert.equal(promise1, promise2, 'Consecutive accesses with equal selector values must return the same promise reference');
  assert.equal(callCount, 1, 'creator must only be called once across reads');

  const [val1, val2] = await Promise.all([promise1, promise2]);
  assert.equal(val1, 'result-production');
  assert.equal(val2, 'result-production');
}

// 3. assert MemoLazy recomputes value when selector output changes
{
  let callCount = 0;
  let currentKey = 'v1';
  const lazy = createMemoLazy(
    () => currentKey,
    async (key) => {
      callCount++;
      return `payload-${key}`;
    }
  );

  const val1 = await lazy.value;
  assert.equal(val1, 'payload-v1');
  assert.equal(callCount, 1);

  currentKey = 'v2';
  const val2 = await lazy.value;
  assert.equal(val2, 'payload-v2');
  assert.equal(callCount, 2, 'creator must be called again when selector output changes');
}

// 4. assert MemoLazy allows updating cached value and reflects hasValue true
{
  const lazy = createMemoLazy(
    () => 'item-key',
    async (key) => `auto-${key}`
  );
  assert.equal(lazy.hasValue, false);

  const autoVal = await lazy.value;
  assert.equal(autoVal, 'auto-item-key');
  assert.equal(lazy.hasValue, true);

  lazy.value = Promise.resolve('manual-override');
  assert.equal(lazy.hasValue, true);

  const overriddenVal = await lazy.value;
  assert.equal(overriddenVal, 'manual-override');
}

console.log('All contract tests passed.');