builder-util-runtime 9.2.10

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/builder-util-runtime@9.2.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/builder-util-runtime@9.2.10
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:47493e7a27ba81e6093c73a81dd40389f0d5adef81bb8e7c6350bec4709e731f","constraints":{"executionContext":"node"},"contract":["CancellationToken tracks cancelled state and rejects createPromise with CancellationError when cancelled","parseXml parses XML element trees, attributes, and text values into navigable XElement structures","UUID.v5 generates deterministic RFC 4122 v5 UUIDs from name strings and namespace buffers","parseDn parses RFC 2253 distinguished name strings into key-value maps","MemoLazy lazily evaluates and memoizes asynchronous values until the selector cache key changes","asArray normalizes single items into arrays and handles null or undefined values gracefully"],"goal":"verify pkg:npm/builder-util-runtime@9.2.10","kind":"HOW","packages":["pkg:npm/builder-util-runtime@9.2.10"],"schemaVersion":1},"contractCommand":["node","test/contract.cjs"],"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.2.10"],"schemaVersion":1,"subject":"pkg:npm/builder-util-runtime@9.2.10","verifierAdapter":"node-typescript@1"}

'use strict';

const {
  CancellationToken,
  CancellationError,
  parseXml,
  UUID,
  parseDn,
  MemoLazy,
  asArray
} = require('builder-util-runtime');

function createCancellationToken() {
  return new CancellationToken();
}

function parseXmlDocument(xmlContent) {
  return parseXml(xmlContent);
}

function generateDeterministicUuid(name, namespace = UUID.OID) {
  return UUID.v5(name, namespace).toString();
}

function parseDistinguishedName(dn) {
  return parseDn(dn);
}

function createMemoLazy(selector, creator) {
  return new MemoLazy(selector, creator);
}

function ensureArray(val) {
  return asArray(val);
}

module.exports = {
  CancellationToken,
  CancellationError,
  parseXml,
  UUID,
  parseDn,
  MemoLazy,
  asArray,
  createCancellationToken,
  parseXmlDocument,
  generateDeterministicUuid,
  parseDistinguishedName,
  createMemoLazy,
  ensureArray
};

{
  "name": "sample-builder-util-runtime",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-builder-util-runtime",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "builder-util-runtime": "9.2.10"
      }
    },
    "node_modules/builder-util-runtime": {
      "version": "9.2.10",
      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.2.10.tgz",
      "integrity": "sha512-6p/gfG1RJSQeIbz8TK5aPNkoztgY1q5TgmGFMAXcY8itsGW6Y2ld1ALsZ5UJn8rog7hKF3zHx5iQbNQ8uLcRlw==",
      "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": "sample-builder-util-runtime",
  "version": "1.0.0",
  "private": true,
  "description": "verify pkg:npm/builder-util-runtime@9.2.10",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "builder-util-runtime": "9.2.10"
  },
  "license": "MIT-0"
}

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

'use strict';

const assert = require('assert');
const {
  CancellationToken,
  CancellationError,
  parseXml,
  UUID,
  parseDn,
  MemoLazy,
  asArray,
  createCancellationToken,
  parseXmlDocument,
  generateDeterministicUuid,
  parseDistinguishedName,
  createMemoLazy,
  ensureArray
} = require('../index.js');

async function testCancellationToken() {
  // 1. Uncancelled token behavior
  const token = createCancellationToken();
  assert.strictEqual(token.cancelled, false, 'Token should initially be uncancelled');

  let cancelledCallbackFired = false;
  const promise = token.createPromise((resolve, reject, onCancel) => {
    const timer = setTimeout(() => resolve('completed'), 1000);
    onCancel(() => {
      cancelledCallbackFired = true;
      clearTimeout(timer);
    });
  });

  // 2. Cancellation behavior
  token.cancel();
  assert.strictEqual(token.cancelled, true, 'Token should be marked cancelled');
  assert.strictEqual(cancelledCallbackFired, true, 'onCancel callback must be invoked on cancel');

  await assert.rejects(
    promise,
    (err) => {
      assert(err instanceof CancellationError, 'Expected CancellationError instance');
      assert.strictEqual(err.message, 'cancelled', 'Error message should match cancelled');
      return true;
    },
    'createPromise must reject with CancellationError when token is cancelled'
  );
}

function testXmlParsing() {
  const sampleXml = '<feed version="2.0"><item id="entry-1"><title>First Item</title></item><item id="entry-2"><title>Second Item</title></item></feed>';
  const doc = parseXmlDocument(sampleXml);

  assert.strictEqual(doc.name, 'feed', 'Root element name should match');
  assert.strictEqual(doc.attributes.version, '2.0', 'Root element attribute version should match');

  const items = doc.getElements('item');
  assert.strictEqual(items.length, 2, 'Should find two item elements');
  assert.strictEqual(items[0].attributes.id, 'entry-1', 'First item id attribute should match');
  assert.strictEqual(items[0].elementValueOrEmpty('title'), 'First Item', 'First item title value should match');
  assert.strictEqual(items[1].attributes.id, 'entry-2', 'Second item id attribute should match');
  assert.strictEqual(items[1].elementValueOrEmpty('title'), 'Second Item', 'Second item title value should match');
}

function testUuidGeneration() {
  const uuidString = generateDeterministicUuid('sample-resource', UUID.OID);
  assert.strictEqual(typeof uuidString, 'string', 'UUID should be a string');

  const check = UUID.check(uuidString);
  assert.strictEqual(check.version, 5, 'UUID version must be 5');
  assert.strictEqual(check.variant, 'rfc4122', 'UUID variant must be rfc4122');

  const secondUuidString = generateDeterministicUuid('sample-resource', UUID.OID);
  assert.strictEqual(uuidString, secondUuidString, 'UUID v5 generation must be deterministic');
}

function testDistinguishedNameParsing() {
  const rawDn = 'CN=Example Service, OU=Operations, O=Example Inc, C=US';
  const dnMap = parseDistinguishedName(rawDn);

  assert.strictEqual(dnMap.get('CN'), 'Example Service', 'CN field should match');
  assert.strictEqual(dnMap.get('OU'), 'Operations', 'OU field should match');
  assert.strictEqual(dnMap.get('O'), 'Example Inc', 'O field should match');
  assert.strictEqual(dnMap.get('C'), 'US', 'C field should match');
}

async function testMemoLazy() {
  let cacheKey = 'v1';
  let computeInvocations = 0;

  const lazy = createMemoLazy(
    () => cacheKey,
    async (key) => {
      computeInvocations++;
      return `computed-${key}`;
    }
  );

  assert.strictEqual(lazy.hasValue, false, 'Lazy instance should not have value initially');

  const firstValue = await lazy.value;
  assert.strictEqual(firstValue, 'computed-v1', 'First computed value must match');
  assert.strictEqual(computeInvocations, 1, 'Creator should run once on initial access');
  assert.strictEqual(lazy.hasValue, true, 'Lazy instance should have value after computation');

  const cachedValue = await lazy.value;
  assert.strictEqual(cachedValue, 'computed-v1', 'Subsequent access must return cached value');
  assert.strictEqual(computeInvocations, 1, 'Creator should not run when cache key is unchanged');

  cacheKey = 'v2';
  const updatedValue = await lazy.value;
  assert.strictEqual(updatedValue, 'computed-v2', 'Value must be recomputed when cache key changes');
  assert.strictEqual(computeInvocations, 2, 'Creator must run again after cache key invalidation');
}

function testAsArrayUtility() {
  assert.deepStrictEqual(ensureArray(undefined), [], 'undefined should normalize to empty array');
  assert.deepStrictEqual(ensureArray(null), [], 'null should normalize to empty array');
  assert.deepStrictEqual(ensureArray('element'), ['element'], 'scalar string should be wrapped in array');
  assert.deepStrictEqual(ensureArray(['alpha', 'beta']), ['alpha', 'beta'], 'array should remain unchanged');
}

async function main() {
  await testCancellationToken();
  testXmlParsing();
  testUuidGeneration();
  testDistinguishedNameParsing();
  await testMemoLazy();
  testAsArrayUtility();
  console.log('Contract tests passed successfully.');
}

main().catch((err) => {
  console.error('Contract test execution failed:', err);
  process.exit(1);
});