yaml 2.9.0: create and resolve YAML aliases and anchors with Document and Alias

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: create and resolve YAML aliases and anchors with Document and Alias
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/yaml@2.9.0
Demonstrate these symbols/APIs:
  - Alias
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:08f968bd3ef5f58cb342dde68757ed27cf9598df2650ea63fc86f2f3d3feb5e2","constraints":{"executionContext":"node"},"contract":["parseDocument parses YAML alias nodes into Alias AST instances","Alias.resolve resolves an alias node to its referenced target AST node","Document.createAlias generates an anchor on the target node and returns an Alias AST instance","new Alias constructs an Alias AST instance referencing an anchor name","Document.toJS resolves aliases and returns fully populated JavaScript objects","Document.toString serializes Alias nodes with valid YAML anchor and alias syntax"],"goal":"create and resolve YAML aliases and anchors with Document and Alias","kind":"HOW","packages":["pkg:npm/yaml@2.9.0"],"schemaVersion":1,"symbols":["Alias"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","os":"windows","osVersionBucket":"11","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/yaml@2.9.0"],"schemaVersion":1,"symbols":["Alias"],"verifierAdapter":"node-typescript@1"}

import YAML, { Alias, Document, isAlias, parseDocument } from 'yaml';

/**
 * Creates a YAML Document AST containing an alias referencing an anchored target node.
 *
 * @param {object} initialData - Base data to populate the document with.
 * @param {string} targetKey - Top-level key to anchor.
 * @param {string} aliasKey - Top-level key where the alias will be attached.
 * @param {string} [anchorName] - Optional custom anchor name.
 * @returns {Document} The constructed YAML Document AST.
 */
export function createDocumentWithAlias(initialData, targetKey, aliasKey, anchorName) {
  const doc = new Document(initialData);
  const targetNode = doc.get(targetKey);
  if (!targetNode) {
    throw new Error(`Target key "${targetKey}" not found in document.`);
  }
  const alias = doc.createAlias(targetNode, anchorName);
  doc.set(aliasKey, alias);
  return doc;
}

export { Alias, Document, isAlias, parseDocument, YAML };

{
  "name": "sample-yaml-alias",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-yaml-alias",
      "version": "1.0.0",
      "dependencies": {
        "yaml": "2.9.0"
      }
    },
    "node_modules/yaml": {
      "version": "2.9.0",
      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
      "license": "ISC",
      "bin": {
        "yaml": "bin.mjs"
      },
      "engines": {
        "node": ">= 14.6"
      },
      "funding": {
        "url": "https://github.com/sponsors/eemeli"
      }
    }
  }
}

{
  "name": "sample-yaml-alias",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "yaml": "2.9.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "create and resolve YAML aliases and anchors with Document and Alias",
  "kind": "HOW",
  "packages": [
    "pkg:npm/yaml@2.9.0"
  ],
  "symbols": [
    "Alias"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@11.8.0",
    "runtime": "node@24.13.1"
  }
}

import assert from 'node:assert/strict';
import YAML, { Alias, Document, isAlias, parseDocument } from 'yaml';
import { createDocumentWithAlias } from '../index.mjs';

// 1. parseDocument parses YAML alias nodes into Alias AST instances
const yamlSource = `
server_template: &defaultServer
  host: 127.0.0.1
  port: 8080
  timeout: 30

primary_server: *defaultServer
`;

const doc = parseDocument(yamlSource);
assert.strictEqual(doc.errors.length, 0);

const aliasNode = doc.get('primary_server');
assert.ok(aliasNode instanceof Alias);
assert.strictEqual(isAlias(aliasNode), true);
assert.strictEqual(aliasNode.source, 'defaultServer');

// 2. Alias.resolve resolves an alias node to its referenced target AST node
const resolvedNode = aliasNode.resolve(doc);
assert.ok(resolvedNode !== undefined);
assert.strictEqual(resolvedNode.anchor, 'defaultServer');
assert.strictEqual(resolvedNode.get('host'), '127.0.0.1');
assert.strictEqual(resolvedNode.get('port'), 8080);
assert.strictEqual(resolvedNode.get('timeout'), 30);

// 3. Document.createAlias generates an anchor on the target node and returns an Alias AST instance
const newDoc = new Document({
  cacheDefaults: {
    ttl: 3600,
    maxItems: 1000
  }
});

const cacheNode = newDoc.get('cacheDefaults');
const cacheAlias = newDoc.createAlias(cacheNode, 'cacheConfig');
assert.ok(cacheAlias instanceof Alias);
assert.strictEqual(isAlias(cacheAlias), true);
assert.strictEqual(cacheNode.anchor, 'cacheConfig');
assert.strictEqual(cacheAlias.source, 'cacheConfig');

newDoc.set('sessionCache', cacheAlias);
assert.strictEqual(isAlias(newDoc.get('sessionCache')), true);

// 4. new Alias constructs an Alias AST instance referencing an anchor name
const manualAlias = new Alias('cacheConfig');
assert.ok(manualAlias instanceof Alias);
assert.strictEqual(isAlias(manualAlias), true);
assert.strictEqual(manualAlias.source, 'cacheConfig');
assert.strictEqual(manualAlias.resolve(newDoc), cacheNode);

newDoc.set('userCache', manualAlias);

// 5. Document.toJS resolves aliases and returns fully populated JavaScript objects
const jsData = newDoc.toJS();
assert.deepStrictEqual(jsData, {
  cacheDefaults: {
    ttl: 3600,
    maxItems: 1000
  },
  sessionCache: {
    ttl: 3600,
    maxItems: 1000
  },
  userCache: {
    ttl: 3600,
    maxItems: 1000
  }
});

const helperDoc = createDocumentWithAlias(
  { database: { engine: 'postgres', port: 5432 } },
  'database',
  'readReplica',
  'dbAnchor'
);
const helperJs = helperDoc.toJS();
assert.deepStrictEqual(helperJs, {
  database: { engine: 'postgres', port: 5432 },
  readReplica: { engine: 'postgres', port: 5432 }
});

// 6. Document.toString serializes Alias nodes with valid YAML anchor and alias syntax
const yamlOutput = newDoc.toString();
assert.ok(yamlOutput.includes('&cacheConfig'));
assert.ok(yamlOutput.includes('*cacheConfig'));

// Re-parsing the serialized output must yield valid document with aliases
const reparsedDoc = parseDocument(yamlOutput);
assert.strictEqual(reparsedDoc.errors.length, 0);
assert.strictEqual(isAlias(reparsedDoc.get('sessionCache')), true);
assert.strictEqual(isAlias(reparsedDoc.get('userCache')), true);

console.log('PASS: Alias and Document anchor/alias contract passed');