@xmldom/xmldom 0.8.14

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/%40xmldom/xmldom@0.8.14
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40xmldom/xmldom@0.8.14

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:74c01adf2a40a280182500192a38d1f4bb9bdeea4acf2fffc568ec7711cd2b7a","contract":["parseXml parses well-formed XML strings into DOM Document with elements, attributes, and text nodes","createXmlDocument creates a new DOM Document with root element and namespace support","serializeXml serializes DOM Document and Element nodes to XML string","serializeXml with requireWellFormed option validates XML output and throws on invalid QNames or injection tokens","DOMParser invokes custom errorHandler callbacks on malformed XML syntax"],"goal":"verify pkg:npm/%40xmldom/xmldom@0.8.14","kind":"HOW","packages":["pkg:npm/%40xmldom/xmldom@0.8.14"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40xmldom/xmldom@0.8.14"],"schemaVersion":1,"subject":"pkg:npm/%40xmldom/xmldom@0.8.14","verifierAdapter":"node-typescript@1"}

import { DOMParser, XMLSerializer, DOMImplementation } from '@xmldom/xmldom';

/**
 * Parse an XML string into a DOM Document.
 * @param {string} xmlString
 * @param {object} [options]
 * @returns {Document}
 */
export function parseXml(xmlString, options) {
  const parser = new DOMParser(options);
  return parser.parseFromString(xmlString, 'text/xml');
}

/**
 * Serialize a DOM Document or Node to an XML string.
 * @param {Node} node
 * @param {object} [options]
 * @returns {string}
 */
export function serializeXml(node, options) {
  const serializer = new XMLSerializer();
  return serializer.serializeToString(node, false, undefined, options);
}

/**
 * Create a new blank XML Document with a root element.
 * @param {string} rootTagName
 * @param {string|null} [namespaceURI]
 * @returns {Document}
 */
export function createXmlDocument(rootTagName, namespaceURI = null) {
  const impl = new DOMImplementation();
  return impl.createDocument(namespaceURI, rootTagName, null);
}

export { DOMParser, XMLSerializer, DOMImplementation };

{
  "name": "sample-xmldom-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-xmldom-verify",
      "version": "1.0.0",
      "dependencies": {
        "@xmldom/xmldom": "0.8.14"
      }
    },
    "node_modules/@xmldom/xmldom": {
      "version": "0.8.14",
      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.14.tgz",
      "integrity": "sha512-T4EDRUBVZYRldYApjEJiU0e1stYWaRAX7CuSnKzrpwdZKo53zGV8/pqfzV6FfwNl9YThD2OumQYvqtvjvgG7aQ==",
      "deprecated": "this version has critical issues, please update to the latest version",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      }
    }
  }
}

{
  "name": "sample-xmldom-verify",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@xmldom/xmldom": "0.8.14"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40xmldom/xmldom@0.8.14",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40xmldom/xmldom@0.8.14"
  ]
}

import assert from 'node:assert/strict';
import { parseXml, serializeXml, createXmlDocument, DOMParser, XMLSerializer, DOMImplementation } from '../index.mjs';

// 1. parseXml parses well-formed XML strings into DOM Document with elements, attributes, and text nodes
{
  const xml = '<bookstore><book id="b1" category="fiction"><title>Clean Code</title><price>29.99</price></book></bookstore>';
  const doc = parseXml(xml);
  assert.ok(doc, 'Parsed document should be defined');
  assert.strictEqual(doc.documentElement.nodeName, 'bookstore');

  const books = doc.getElementsByTagName('book');
  assert.strictEqual(books.length, 1);
  assert.strictEqual(books[0].getAttribute('id'), 'b1');
  assert.strictEqual(books[0].getAttribute('category'), 'fiction');

  const titles = doc.getElementsByTagName('title');
  assert.strictEqual(titles.length, 1);
  assert.strictEqual(titles[0].textContent, 'Clean Code');

  const prices = doc.getElementsByTagName('price');
  assert.strictEqual(prices.length, 1);
  assert.strictEqual(prices[0].textContent, '29.99');
}

// 2. createXmlDocument creates a new DOM Document with root element and namespace support
{
  const doc = createXmlDocument('library', 'http://example.com/ns/library');
  assert.strictEqual(doc.documentElement.nodeName, 'library');
  assert.strictEqual(doc.documentElement.namespaceURI, 'http://example.com/ns/library');

  const item = doc.createElementNS('http://example.com/ns/library', 'item');
  item.setAttribute('type', 'journal');
  const name = doc.createElement('name');
  name.appendChild(doc.createTextNode('Software Engineering'));
  item.appendChild(name);
  doc.documentElement.appendChild(item);

  assert.strictEqual(doc.documentElement.childNodes.length, 1);
  assert.strictEqual(doc.getElementsByTagName('item').length, 1);
  assert.strictEqual(doc.getElementsByTagName('name')[0].textContent, 'Software Engineering');
}

// 3. serializeXml serializes DOM Document and Element nodes to XML string
{
  const doc = createXmlDocument('root');
  const greeting = doc.createElement('greeting');
  greeting.setAttribute('lang', 'en');
  greeting.appendChild(doc.createTextNode('Hello World'));
  doc.documentElement.appendChild(greeting);

  const xmlOut = serializeXml(doc);
  assert.ok(typeof xmlOut === 'string');
  assert.ok(xmlOut.includes('<root><greeting lang="en">Hello World</greeting></root>'));

  const elemOut = serializeXml(greeting);
  assert.strictEqual(elemOut, '<greeting lang="en">Hello World</greeting>');
}

// 4. serializeXml with requireWellFormed option validates XML output and throws on invalid QNames or injection tokens
{
  const doc = createXmlDocument('root');
  const child = doc.createElement('validElement');
  child.setAttribute('key', 'value');
  doc.documentElement.appendChild(child);

  const validOut = serializeXml(doc, { requireWellFormed: true });
  assert.strictEqual(validOut, '<root><validElement key="value"/></root>');

  // Comment injection token (-->) must throw
  const commentDoc = createXmlDocument('root');
  commentDoc.documentElement.appendChild(commentDoc.createComment('inject --> close'));
  assert.throws(() => {
    serializeXml(commentDoc, { requireWellFormed: true });
  }, /Invalid state/);

  // Invalid QName element name must throw
  const invalidNameDoc = createXmlDocument('root');
  invalidNameDoc.documentElement.appendChild(invalidNameDoc.createElement('invalid name with spaces'));
  assert.throws(() => {
    serializeXml(invalidNameDoc, { requireWellFormed: true });
  }, /is not a valid XML QName/);
}

// 5. DOMParser invokes custom errorHandler callbacks on malformed XML syntax
{
  const errors = [];
  const errorHandler = {
    error: (msg) => { errors.push({ level: 'error', msg }); },
    fatalError: (msg) => { errors.push({ level: 'fatalError', msg }); },
    warning: (msg) => { errors.push({ level: 'warning', msg }); }
  };

  const malformedXml = '<root><unclosed></root>';
  const doc = parseXml(malformedXml, { errorHandler });
  assert.ok(doc, 'Parser should return a document even on errors with custom handler');
  assert.ok(errors.length > 0, 'Custom errorHandler should have recorded error messages');
}

console.log('All contracts passed successfully.');