xmlchars 2.2.0

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/xmlchars@2.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/xmlchars@2.2.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - 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:75c9992d692ffb866550106cf61b2126106630eb3bbe21f44fc89ea881515235","constraints":{"executionContext":"node"},"contract":["isChar validates XML 1.0 character code points including valid Unicode ranges and rejects disallowed code points","isS identifies XML whitespace characters space, tab, line feed, and carriage return","isNameStartChar and isNameChar determine valid XML name starter and continuation characters","isNCNameStartChar and isNCNameChar validate XML namespace non-colonized name characters","NAME_RE and NC_NAME_RE validate full XML Name and NCName strings according to XML and XML Namespaces specifications"],"goal":"verify pkg:npm/xmlchars@2.2.0","kind":"HOW","packages":["pkg:npm/xmlchars@2.2.0"],"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/xmlchars@2.2.0"],"schemaVersion":1,"subject":"pkg:npm/xmlchars@2.2.0","verifierAdapter":"node-typescript@1"}

{
  "name": "xmlchars-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "xmlchars-sample",
      "version": "1.0.0",
      "dependencies": {
        "xmlchars": "2.2.0"
      }
    },
    "node_modules/xmlchars": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
      "license": "MIT"
    }
  }
}

{
  "name": "xmlchars-sample",
  "version": "1.0.0",
  "dependencies": {
    "xmlchars": "2.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/xmlchars@2.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/xmlchars@2.2.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

const xml10ed5 = require('xmlchars/xml/1.0/ed5');
const xmlns10ed3 = require('xmlchars/xmlns/1.0/ed3');

/**
 * Checks whether a Unicode code point is a valid XML 1.0 character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if the code point is a valid XML character.
 */
function isValidXmlChar(codePoint) {
  return xml10ed5.isChar(codePoint);
}

/**
 * Checks whether a Unicode code point is an XML whitespace character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if the code point is XML whitespace (space, tab, CR, LF).
 */
function isXmlWhitespace(codePoint) {
  return xml10ed5.isS(codePoint);
}

/**
 * Checks whether a code point is a valid XML Name start character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if valid XML Name start character.
 */
function isValidNameStartChar(codePoint) {
  return xml10ed5.isNameStartChar(codePoint);
}

/**
 * Checks whether a code point is a valid XML Name continuation character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if valid XML Name character.
 */
function isValidNameChar(codePoint) {
  return xml10ed5.isNameChar(codePoint);
}

/**
 * Checks whether a code point is a valid XML NCName start character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if valid XML NCName start character.
 */
function isValidNCNameStartChar(codePoint) {
  return xmlns10ed3.isNCNameStartChar(codePoint);
}

/**
 * Checks whether a code point is a valid XML NCName continuation character.
 *
 * @param {number} codePoint - The Unicode code point to test.
 * @returns {boolean} True if valid XML NCName character.
 */
function isValidNCNameChar(codePoint) {
  return xmlns10ed3.isNCNameChar(codePoint);
}

/**
 * Validates whether a string is a valid XML Name.
 *
 * @param {string} str - String to validate.
 * @returns {boolean} True if valid XML Name.
 */
function isValidXmlName(str) {
  return xml10ed5.NAME_RE.test(str);
}

/**
 * Validates whether a string is a valid XML NCName (non-colonized name).
 *
 * @param {string} str - String to validate.
 * @returns {boolean} True if valid XML NCName.
 */
function isValidXmlNCName(str) {
  return xmlns10ed3.NC_NAME_RE.test(str);
}

/**
 * Validates whether a string is a valid XML NMTOKEN.
 *
 * @param {string} str - String to validate.
 * @returns {boolean} True if valid XML NMTOKEN.
 */
function isValidXmlNmtoken(str) {
  return xml10ed5.NMTOKEN_RE.test(str);
}

module.exports = {
  isValidXmlChar,
  isXmlWhitespace,
  isValidNameStartChar,
  isValidNameChar,
  isValidNCNameStartChar,
  isValidNCNameChar,
  isValidXmlName,
  isValidXmlNCName,
  isValidXmlNmtoken,
  xml10ed5,
  xmlns10ed3,
};

const assert = require('node:assert/strict');
const {
  isValidXmlChar,
  isXmlWhitespace,
  isValidNameStartChar,
  isValidNameChar,
  isValidNCNameStartChar,
  isValidNCNameChar,
  isValidXmlName,
  isValidXmlNCName,
  isValidXmlNmtoken,
} = require('../src/index.js');

function testXmlCharValidation() {
  // Valid XML characters (0x9, 0xA, 0xD, 0x20-0xD7FF, 0xE000-0xFFFD, 0x10000-0x10FFFF)
  assert.strictEqual(isValidXmlChar(0x9), true);
  assert.strictEqual(isValidXmlChar(0xa), true);
  assert.strictEqual(isValidXmlChar(0xd), true);
  assert.strictEqual(isValidXmlChar(0x20), true);
  assert.strictEqual(isValidXmlChar(0x41), true);
  assert.strictEqual(isValidXmlChar(0xd7ff), true);
  assert.strictEqual(isValidXmlChar(0xe000), true);
  assert.strictEqual(isValidXmlChar(0xfffd), true);
  assert.strictEqual(isValidXmlChar(0x10000), true);
  assert.strictEqual(isValidXmlChar(0x10ffff), true);

  // Disallowed XML characters
  assert.strictEqual(isValidXmlChar(0x0), false);
  assert.strictEqual(isValidXmlChar(0x1), false);
  assert.strictEqual(isValidXmlChar(0x8), false);
  assert.strictEqual(isValidXmlChar(0xb), false);
  assert.strictEqual(isValidXmlChar(0xc), false);
  assert.strictEqual(isValidXmlChar(0xd800), false);
  assert.strictEqual(isValidXmlChar(0xdfff), false);
  assert.strictEqual(isValidXmlChar(0xfffe), false);
  assert.strictEqual(isValidXmlChar(0xffff), false);
  assert.strictEqual(isValidXmlChar(0x110000), false);
}

function testWhitespaceValidation() {
  // XML whitespace: 0x20 (space), 0x9 (tab), 0xD (CR), 0xA (LF)
  assert.strictEqual(isXmlWhitespace(0x20), true);
  assert.strictEqual(isXmlWhitespace(0x9), true);
  assert.strictEqual(isXmlWhitespace(0xd), true);
  assert.strictEqual(isXmlWhitespace(0xa), true);

  // Non-whitespace
  assert.strictEqual(isXmlWhitespace(0x0), false);
  assert.strictEqual(isXmlWhitespace(0x41), false);
  assert.strictEqual(isXmlWhitespace(0xa0), false);
  assert.strictEqual(isXmlWhitespace(0x3000), false);
}

function testNameCharacters() {
  // Start characters: letters, '_', ':'
  assert.strictEqual(isValidNameStartChar('a'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameStartChar('Z'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameStartChar('_'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameStartChar(':'.charCodeAt(0)), true);

  // Invalid start characters: digits, hyphen, period, space
  assert.strictEqual(isValidNameStartChar('0'.charCodeAt(0)), false);
  assert.strictEqual(isValidNameStartChar('-'.charCodeAt(0)), false);
  assert.strictEqual(isValidNameStartChar('.'.charCodeAt(0)), false);
  assert.strictEqual(isValidNameStartChar(' '.charCodeAt(0)), false);

  // Continuation characters: start chars + digits, hyphen, period
  assert.strictEqual(isValidNameChar('a'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameChar('0'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameChar('-'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameChar('.'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameChar(':'.charCodeAt(0)), true);
  assert.strictEqual(isValidNameChar('_'.charCodeAt(0)), true);

  // Disallowed in NameChar
  assert.strictEqual(isValidNameChar(' '.charCodeAt(0)), false);
  assert.strictEqual(isValidNameChar('/'.charCodeAt(0)), false);
  assert.strictEqual(isValidNameChar('@'.charCodeAt(0)), false);
}

function testNCNameCharacters() {
  // NCName (Namespaces in XML) cannot contain colon ':'
  assert.strictEqual(isValidNCNameStartChar('a'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameStartChar('_'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameStartChar(':'.charCodeAt(0)), false);
  assert.strictEqual(isValidNCNameStartChar('1'.charCodeAt(0)), false);

  assert.strictEqual(isValidNCNameChar('a'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameChar('1'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameChar('-'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameChar('.'.charCodeAt(0)), true);
  assert.strictEqual(isValidNCNameChar(':'.charCodeAt(0)), false);
}

function testNameRegexes() {
  // XML Name
  assert.strictEqual(isValidXmlName('root'), true);
  assert.strictEqual(isValidXmlName('ns:element'), true);
  assert.strictEqual(isValidXmlName('_item-1.0'), true);
  assert.strictEqual(isValidXmlName('1item'), false);
  assert.strictEqual(isValidXmlName('-item'), false);
  assert.strictEqual(isValidXmlName('foo bar'), false);

  // XML NCName (no colons)
  assert.strictEqual(isValidXmlNCName('element'), true);
  assert.strictEqual(isValidXmlNCName('_privateAttr'), true);
  assert.strictEqual(isValidXmlNCName('ns:element'), false);
  assert.strictEqual(isValidXmlNCName('item-2'), true);

  // XML NMTOKEN
  assert.strictEqual(isValidXmlNmtoken('123'), true);
  assert.strictEqual(isValidXmlNmtoken('-custom-val'), true);
  assert.strictEqual(isValidXmlNmtoken('token.name:sub'), true);
  assert.strictEqual(isValidXmlNmtoken('bad token'), false);
}

function main() {
  testXmlCharValidation();
  testWhitespaceValidation();
  testNameCharacters();
  testNCNameCharacters();
  testNameRegexes();

  console.log('All pkg:npm/xmlchars@2.2.0 contracts passed successfully.');
}

main();