@types/js-yaml 4.0.9

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/%40types/js-yaml@4.0.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40types/js-yaml@4.0.9

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:e4d7242187b2df53a3898b09059cdba9e205562119c4058ef7fd9ad36c15d086","contract":["load parses YAML strings into JavaScript objects","dump serializes JavaScript data structures into formatted YAML strings","loadAll parses multiple documents from a YAML stream","dump with sortKeys formats object keys in deterministic alphabetical order","dump with indent and flowLevel controls indentation and nesting styles","load throws YAMLException when given malformed YAML input","custom Type and Schema extend parsing capabilities for custom tags"],"goal":"verify pkg:npm/%40types/js-yaml@4.0.9","kind":"HOW","packages":["pkg:npm/%40types/js-yaml@4.0.9"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"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/%40types/js-yaml@4.0.9"],"schemaVersion":1,"subject":"pkg:npm/%40types/js-yaml@4.0.9","verifierAdapter":"node-typescript@1"}

{
  "name": "types-js-yaml-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "types-js-yaml-sample",
      "version": "1.0.0",
      "dependencies": {
        "@types/js-yaml": "4.0.9",
        "js-yaml": "4.1.0"
      }
    },
    "node_modules/@types/js-yaml": {
      "version": "4.0.9",
      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
      "license": "MIT"
    },
    "node_modules/argparse": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
      "license": "Python-2.0"
    },
    "node_modules/js-yaml": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
      "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
      "license": "MIT",
      "dependencies": {
        "argparse": "^2.0.1"
      },
      "bin": {
        "js-yaml": "bin/js-yaml.js"
      }
    }
  }
}

{
  "name": "types-js-yaml-sample",
  "version": "1.0.0",
  "dependencies": {
    "@types/js-yaml": "4.0.9",
    "js-yaml": "4.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40types/js-yaml@4.0.9",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40types/js-yaml@4.0.9"
  ]
}

const yaml = require('js-yaml');

/**
 * Parses a YAML string into a JavaScript object.
 *
 * @param {string} str - YAML string to parse.
 * @param {object} [opts] - Load options.
 * @returns {unknown} Parsed JavaScript value.
 */
function parseYaml(str, opts) {
  return yaml.load(str, opts);
}

/**
 * Parses multiple YAML documents from a single stream.
 *
 * @param {string} str - Multi-document YAML string.
 * @param {Function|null} [iterator] - Optional callback per document.
 * @param {object} [opts] - Load options.
 * @returns {unknown[]} Array of parsed documents when iterator is not provided.
 */
function parseAllYaml(str, iterator, opts) {
  return yaml.loadAll(str, iterator, opts);
}

/**
 * Serializes a JavaScript value into a YAML string.
 *
 * @param {any} obj - Value to dump.
 * @param {object} [opts] - Dump options.
 * @returns {string} Serialized YAML string.
 */
function dumpYaml(obj, opts) {
  return yaml.dump(obj, opts);
}

/**
 * Creates a custom YAML Type definition.
 *
 * @param {string} tag - YAML tag name.
 * @param {object} [opts] - Type options.
 * @returns {yaml.Type}
 */
function createYamlType(tag, opts) {
  return new yaml.Type(tag, opts);
}

/**
 * Extends the default schema with custom types.
 *
 * @param {yaml.SchemaDefinition|yaml.Type[]|yaml.Type} types - Types to add.
 * @returns {yaml.Schema}
 */
function extendDefaultSchema(types) {
  return yaml.DEFAULT_SCHEMA.extend(types);
}

module.exports = {
  parseYaml,
  parseAllYaml,
  dumpYaml,
  createYamlType,
  extendDefaultSchema,
  load: yaml.load,
  loadAll: yaml.loadAll,
  dump: yaml.dump,
  Type: yaml.Type,
  Schema: yaml.Schema,
  FAILSAFE_SCHEMA: yaml.FAILSAFE_SCHEMA,
  JSON_SCHEMA: yaml.JSON_SCHEMA,
  CORE_SCHEMA: yaml.CORE_SCHEMA,
  DEFAULT_SCHEMA: yaml.DEFAULT_SCHEMA,
  YAMLException: yaml.YAMLException,
};

const assert = require('node:assert/strict');
const {
  parseYaml,
  parseAllYaml,
  dumpYaml,
  createYamlType,
  extendDefaultSchema,
  load,
  loadAll,
  dump,
  Type,
  Schema,
  FAILSAFE_SCHEMA,
  JSON_SCHEMA,
  CORE_SCHEMA,
  DEFAULT_SCHEMA,
  YAMLException,
} = require('../src/index.js');

async function main() {
  // Contract 1: load parses YAML strings into JavaScript objects
  {
    const yamlStr = `
name: sample-service
version: 1.0.0
enabled: true
port: 8080
tags:
  - api
  - production
`;
    const parsed = parseYaml(yamlStr);
    assert.deepStrictEqual(parsed, {
      name: 'sample-service',
      version: '1.0.0',
      enabled: true,
      port: 8080,
      tags: ['api', 'production'],
    });

    const direct = load('key: value');
    assert.deepStrictEqual(direct, { key: 'value' });
  }

  // Contract 2: dump serializes JavaScript data structures into formatted YAML strings
  {
    const data = {
      title: 'Configuration',
      retries: 3,
      debug: false,
    };
    const dumped = dumpYaml(data);
    assert.strictEqual(typeof dumped, 'string');
    const parsedBack = load(dumped);
    assert.deepStrictEqual(parsedBack, data);
  }

  // Contract 3: loadAll parses multiple documents from a YAML stream
  {
    const multiDoc = `
doc: first
id: 1
---
doc: second
id: 2
---
doc: third
id: 3
`;
    const docs = parseAllYaml(multiDoc);
    assert.strictEqual(Array.isArray(docs), true);
    assert.strictEqual(docs.length, 3);
    assert.deepStrictEqual(docs[0], { doc: 'first', id: 1 });
    assert.deepStrictEqual(docs[1], { doc: 'second', id: 2 });
    assert.deepStrictEqual(docs[2], { doc: 'third', id: 3 });

    const collected = [];
    loadAll(multiDoc, (doc) => {
      collected.push(doc);
    });
    assert.deepStrictEqual(collected, docs);
  }

  // Contract 4: dump with sortKeys formats object keys in deterministic alphabetical order
  {
    const unordered = {
      z: 26,
      a: 1,
      m: 13,
      b: 2,
    };
    const sortedDump = dumpYaml(unordered, { sortKeys: true });
    const lines = sortedDump.trim().split('\n');
    assert.strictEqual(lines[0], 'a: 1');
    assert.strictEqual(lines[1], 'b: 2');
    assert.strictEqual(lines[2], 'm: 13');
    assert.strictEqual(lines[3], 'z: 26');
  }

  // Contract 5: dump with indent and flowLevel controls indentation and nesting styles
  {
    const nested = {
      parent: {
        child: {
          item: 'value',
        },
      },
    };
    const customIndent = dumpYaml(nested, { indent: 4 });
    assert.strictEqual(customIndent.includes('    child:'), true);
    assert.strictEqual(customIndent.includes('        item: value'), true);

    const flowDump = dump(nested, { flowLevel: 0 });
    assert.strictEqual(flowDump.trim().startsWith('{'), true);
  }

  // Contract 6: load throws YAMLException when given malformed YAML input
  {
    const badYaml = `
key: [unclosed list
  another: value
`;
    assert.throws(
      () => {
        load(badYaml);
      },
      (err) => {
        assert.strictEqual(err instanceof YAMLException, true);
        assert.strictEqual(typeof err.message, 'string');
        return true;
      }
    );
  }

  // Contract 7: custom Type and Schema extend parsing capabilities for custom tags
  {
    class Point {
      constructor(x, y) {
        this.x = x;
        this.y = y;
      }
    }

    const PointType = createYamlType('!point', {
      kind: 'sequence',
      resolve: (data) => Array.isArray(data) && data.length === 2 && typeof data[0] === 'number' && typeof data[1] === 'number',
      construct: (data) => new Point(data[0], data[1]),
      instanceOf: Point,
      represent: (point) => [point.x, point.y],
    });

    const customSchema = extendDefaultSchema([PointType]);

    const yamlWithTag = 'location: !point [10, 20]';
    const parsedWithSchema = load(yamlWithTag, { schema: customSchema });
    assert.strictEqual(parsedWithSchema.location instanceof Point, true);
    assert.strictEqual(parsedWithSchema.location.x, 10);
    assert.strictEqual(parsedWithSchema.location.y, 20);

    const dumpedTag = dump(parsedWithSchema, { schema: customSchema });
    assert.strictEqual(dumpedTag.includes('!point'), true);
  }

  console.log('All pkg:npm/@types/js-yaml@4.0.9 contracts passed successfully.');
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});