fast-xml-parser 5.11.0: XMLParser

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 fast-xml-parser.XMLParser in pkg:npm/fast-xml-parser@5.11.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fast-xml-parser@5.11.0
Demonstrate these symbols/APIs:
  - fast-xml-parser.XMLParser
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:a54cb0e54bb7e72b99d864e4e3720ca9a659f67d8a5424ba80dec82e8077fb37","constraints":{"executionContext":"node"},"contract":["XMLParser instance parses standard XML document elements into JavaScript object hierarchy.","XMLParser preserves attributes when ignoreAttributes is set to false.","XMLParser wraps matching tags into arrays when configured with isArray predicate.","XMLParser parses tag text nodes according to textNodeName setting.","XMLParser parse method correctly handles numeric and boolean tag value conversions."],"goal":"verify fast-xml-parser.XMLParser in pkg:npm/fast-xml-parser@5.11.0","kind":"HOW","packages":["pkg:npm/fast-xml-parser@5.11.0"],"schemaVersion":1,"symbols":["fast-xml-parser.XMLParser"]},"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/fast-xml-parser@5.11.0"],"schemaVersion":1,"subject":"pkg:npm/fast-xml-parser@5.11.0","symbols":["fast-xml-parser.XMLParser"],"verifierAdapter":"node-typescript@1"}

const { XMLParser } = require('fast-xml-parser');

function createParser(options = {}) {
  return new XMLParser(options);
}

function parseXml(xmlData, options = {}) {
  const parser = new XMLParser(options);
  return parser.parse(xmlData);
}

module.exports = {
  XMLParser,
  createParser,
  parseXml,
};

{
  "name": "verify-fast-xml-parser",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-fast-xml-parser",
      "version": "1.0.0",
      "dependencies": {
        "fast-xml-parser": "5.11.0"
      }
    },
    "node_modules/@nodable/entities": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-3.0.0.tgz",
      "integrity": "sha512-8L9xFeTYKhm49xfIypoe2W5wV1m/3Z58kT+7kR9A8OyFxcPduI4VmxaUMQyKYrRjUoLLSXv6EKKID5Tvj9cUVw==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/nodable"
        }
      ],
      "license": "MIT"
    },
    "node_modules/anynum": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/anynum/-/anynum-1.0.1.tgz",
      "integrity": "sha512-N6//FLET/tXYNM/F6ABca1oH6fWB+KlTt909Le28WMDBk8oaT4vY17DCrwg2MvmuqUKt3Ni4N5dGJ/EoBgcO6A==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT"
    },
    "node_modules/fast-xml-builder": {
      "version": "1.3.1",
      "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.3.1.tgz",
      "integrity": "sha512-pIM/1n3ntFXKYrUZwW7QCK0gAW7XY+wzj1YMIV3tLDvPj/V+zTGJK5e3/4WJfwj0qWw2ElNXiTixda/R+3YSug==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "path-expression-matcher": "^1.6.2",
        "xml-naming": "^0.3.0"
      }
    },
    "node_modules/fast-xml-parser": {
      "version": "5.11.0",
      "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.11.0.tgz",
      "integrity": "sha512-9IGxMqvqLOnqP+Egi1nqDHKv5k8aZ7r9n558enxcucmyVGEBNPAU+MOg/8jPIS7rO7sSq4gFm1/nHtiaubMruw==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "@nodable/entities": "^3.0.0",
        "fast-xml-builder": "^1.2.0",
        "is-unsafe": "^2.0.0",
        "path-expression-matcher": "^1.6.2",
        "strnum": "^2.4.2",
        "xml-naming": "^0.3.0"
      },
      "bin": {
        "fxparser": "src/cli/cli.js"
      }
    },
    "node_modules/is-unsafe": {
      "version": "2.0.2",
      "resolved": "https://registry.npmjs.org/is-unsafe/-/is-unsafe-2.0.2.tgz",
      "integrity": "sha512-HgbIHPBH0KHHCcjLfGsCvhtPTVxjaAZlXjwdz7/GQC40SjSe4sfQsar8J5VFo8JOSbarkpV0OLG95bbaNd9aAQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT"
    },
    "node_modules/path-expression-matcher": {
      "version": "1.6.2",
      "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.6.2.tgz",
      "integrity": "sha512-enSlaiat05iasnzmgNxRj8reFdj3puY2QpNgP1aPIaVfT6nn9ICuPoFlKHk8EN22HcwewshO+mN2DGbkCEOtqQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    },
    "node_modules/strnum": {
      "version": "2.4.2",
      "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.4.2.tgz",
      "integrity": "sha512-rDG3Ah4TV0k1hWvLSzkZtMmLN9+eS+h3knq4MP6A42Y3Yh5qGNnOUs1jJkoSr8FG5dsL28c7KgkIBzSEykqtuw==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "anynum": "^1.0.1"
      }
    },
    "node_modules/xml-naming": {
      "version": "0.3.0",
      "resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.3.0.tgz",
      "integrity": "sha512-ghig2TBE/H11aOVgmahA3MhimvkBr6JIYknH/Dhdk10nXwdbIqBJsbfMxpvFPG8bAw77gN29aQWvKpmVoPlvPQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/NaturalIntelligence"
        }
      ],
      "license": "MIT",
      "engines": {
        "node": ">=16.0.0"
      }
    }
  }
}

{
  "name": "verify-fast-xml-parser",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for fast-xml-parser.XMLParser",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "fast-xml-parser": "5.11.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify fast-xml-parser.XMLParser in pkg:npm/fast-xml-parser@5.11.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fast-xml-parser@5.11.0"
  ],
  "symbols": [
    "fast-xml-parser.XMLParser"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const assert = require('node:assert/strict');
const { XMLParser, createParser, parseXml } = require('../index.js');

// Contract 1: XMLParser instance parses standard XML document elements into JavaScript object hierarchy.
const basicParser = new XMLParser();
const xmlDoc = `
<root>
  <title>Sample Document</title>
  <description>Clean-room test</description>
  <count>42</count>
</root>
`;
const basicResult = basicParser.parse(xmlDoc);

assert.ok(basicResult.root, 'Root element should exist');
assert.equal(basicResult.root.title, 'Sample Document');
assert.equal(basicResult.root.description, 'Clean-room test');
assert.equal(basicResult.root.count, 42);

// Also verify via helper function
const helperResult = parseXml(xmlDoc);
assert.equal(helperResult.root.title, 'Sample Document');

// Contract 2: XMLParser preserves attributes when ignoreAttributes is set to false.
const attrParser = createParser({
  ignoreAttributes: false,
  attributeNamePrefix: '@_',
});
const attrXml = '<item id="sku-100" active="true" type="book"><name>Test Item</name></item>';
const attrResult = attrParser.parse(attrXml);

assert.ok(attrResult.item, 'Item element should exist');
assert.equal(attrResult.item['@_id'], 'sku-100');
assert.equal(attrResult.item['@_active'], 'true');
assert.equal(attrResult.item['@_type'], 'book');
assert.equal(attrResult.item.name, 'Test Item');

// Contract 3: XMLParser wraps matching tags into arrays when configured with isArray predicate.
const arrayParser = new XMLParser({
  isArray: (name, jpath, isLeafNode, isAttribute) => {
    return jpath === 'catalog.item';
  },
});
const singleItemXml = '<catalog><item><id>1</id><name>Single</name></item></catalog>';
const multiItemXml = '<catalog><item><id>1</id><name>First</name></item><item><id>2</id><name>Second</name></item></catalog>';

const singleResult = arrayParser.parse(singleItemXml);
assert.ok(Array.isArray(singleResult.catalog.item), 'Single item matching isArray should be an array');
assert.equal(singleResult.catalog.item.length, 1);
assert.equal(singleResult.catalog.item[0].id, 1);

const multiResult = arrayParser.parse(multiItemXml);
assert.ok(Array.isArray(multiResult.catalog.item), 'Multiple items should be an array');
assert.equal(multiResult.catalog.item.length, 2);
assert.equal(multiResult.catalog.item[1].name, 'Second');

// Contract 4: XMLParser parses tag text nodes according to textNodeName setting.
const textNodeParser = new XMLParser({
  ignoreAttributes: false,
  textNodeName: '#text',
});
const textNodeXml = '<message priority="high">Hello World</message>';
const textResult = textNodeParser.parse(textNodeXml);

assert.ok(textResult.message, 'Message element should exist');
assert.equal(textResult.message['@_priority'], 'high');
assert.equal(textResult.message['#text'], 'Hello World');

// Contract 5: XMLParser parse method correctly handles numeric and boolean tag value conversions.
const typeParser = new XMLParser({
  parseTagValue: true,
});
const typeXml = `
<data>
  <isVerified>true</isVerified>
  <isArchived>false</isArchived>
  <score>98.6</score>
  <counter>100</counter>
  <rawString>00123</rawString>
</data>
`;
const typeResult = typeParser.parse(typeXml);

assert.strictEqual(typeResult.data.isVerified, true);
assert.strictEqual(typeResult.data.isArchived, false);
assert.strictEqual(typeResult.data.score, 98.6);
assert.strictEqual(typeResult.data.counter, 100);

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