xmllint.js (libxml2 Emscripten Port)

Common errors

• ReferenceError: xmllint is not defined

  cause Attempting to use `xmllint` in a modern ESM context without proper CommonJS interoperability or before the module has been loaded.
  fix If in a Node.js CJS environment, ensure `const xmllint = require('xmllint');` is used. In a browser or ESM context, ensure your bundler is correctly configured to handle CommonJS modules. Consider migrating to `xmllint-wasm` for better ESM support.

• TypeError: xmllint.validateXML is not a function

  cause This error typically occurs when `xmllint` is imported incorrectly, perhaps as a named import when it's a default export containing the method, or if the `xmllint` object itself is undefined.
  fix Verify that you are importing the entire `xmllint` module as a default (CommonJS `require`) and then calling the `validateXML` method on the imported object, e.g., `const xmllint = require('xmllint'); xmllint.validateXML(...)`.

• XML schema validation not working for large XML files or slow performance.

  cause The original `xmllint.js` package processes XML in a non-streaming fashion and as an Emscripten-compiled asm.js module, it can be less performant and memory-intensive for very large XML documents.
  fix For large XML files or performance-critical applications, consider using `xmllint-wasm`, which has introduced `--stream` option support and uses WebAssembly for improved performance and efficiency. Alternatively, offload validation to a server-side process using a native `xmllint` executable or a purpose-built XML parser.

Warnings

• breaking The `xmllint` package (kripken/xml.js) is effectively abandoned, with its last npm publish over 10 years ago and minimal GitHub activity for years. There will be no further updates, bug fixes, or security patches. Users are strongly advised to migrate to the `xmllint-wasm` fork, which is actively maintained, uses WebAssembly, and supports newer libxml2 versions.
  Fix: Migrate to `xmllint-wasm`. This typically involves `npm uninstall xmllint` and then `npm install xmllint-wasm`. Note that `xmllint-wasm` has a different API and requires Node.js 16+ or modern browsers with WebAssembly support.
• gotcha As an Emscripten port of a C library, `xmllint` can contribute significantly to JavaScript bundle size, impacting application load times and performance, especially in browser environments. This is compounded by the fact it outputs asm.js, not WebAssembly, further increasing bundle size compared to modern alternatives.
  Fix: For new projects or existing projects sensitive to bundle size, consider `xmllint-wasm` which outputs WebAssembly, resulting in a smaller combined library size (around 860KB for wasm and JS wrappers). Alternatively, explore server-side validation or more lightweight JavaScript XML parsing/validation libraries if your use case permits.
• gotcha The package was designed for older JavaScript module systems, primarily CommonJS, and explicitly mentions compatibility with Browserify via `browserify-shim`. Using it directly with modern ESM `import` statements in environments without transpilation or with modern bundlers (like Webpack 5+ or Rollup) might require specific configuration or may not work as expected without a proper CJS-to-ESM bridge.
  Fix: Ensure your build tooling (e.g., Webpack, Rollup) is configured to handle CommonJS modules when consuming this package. If you are using native ESM, you will likely need a transpilation step. For modern applications, `xmllint-wasm` offers better ESM compatibility.

Install

• npm install xmllint npm
• yarn add xmllint yarn
• pnpm add xmllint pnpm

Imports

• xmllint
  wrong:

  import xmllint from 'xmllint';

  correct:

  const xmllint = require('xmllint');

  This package primarily targets CommonJS environments. While bundlers might process ESM imports, direct ESM usage without transpilation is unlikely to work due to the package's age and `browserify-shim` integration.
• validateXML
  wrong:

  import { validateXML } from 'xmllint';

  correct:

  const xmllint = require('xmllint');
  xmllint.validateXML({ xml: '...', schema: '...' });

  The `xmllint` object is a default export containing the `validateXML` method. It is not a named export. Attempting to destructure `validateXML` directly will result in an undefined function.

Quickstart

Demonstrates how to use `xmllint.validateXML` to validate XML strings against single or multiple XSD schemas, showcasing both successful and erroneous validation scenarios.

const xmllint = require('xmllint');

const xmlString = `<root><item id="1">Value 1</item><item id="2">Value 2</item></root>`;
const validSchema = `<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="root">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="item" maxOccurs="unbounded">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:string">
                <xs:attribute name="id" type="xs:integer" use="required"/>
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>`;
const invalidSchema = `<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="root">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="bad_item" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>`;

// Example 1: Valid XML against a valid schema
let result1 = xmllint.validateXML({
  xml: xmlString,
  schema: validSchema
});

if (result1.errors) {
  console.log('Validation 1 (Expected Pass) Errors:', result1.errors);
} else {
  console.log('Validation 1 (Expected Pass): No errors found.');
}

// Example 2: Invalid XML against a valid schema
const invalidXmlString = `<root><bad_item>This is wrong</bad_item></root>`;
let result2 = xmllint.validateXML({
  xml: invalidXmlString,
  schema: validSchema
});

if (result2.errors) {
  console.log('Validation 2 (Expected Fail) Errors:', result2.errors[0]);
} else {
  console.log('Validation 2 (Expected Fail): No errors found (unexpected).');
}

// Example 3: Multiple schemas
const schemas = [
  `<?xml version="1.0" encoding="UTF-8"?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://example.com/ns" elementFormDefault="qualified">
    <xs:element name="document" type="tns:DocumentType"/>
    <xs:complexType name="DocumentType">
      <xs:sequence>
        <xs:element name="header" type="tns:HeaderType"/>
      </xs:sequence>
    </xs:complexType>
  </xs:schema>`,
  `<?xml version="1.0" encoding="UTF-8"?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://example.com/ns" targetNamespace="http://example.com/ns" elementFormDefault="qualified">
    <xs:complexType name="HeaderType">
      <xs:sequence>
        <xs:element name="title" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:schema>`
];
const xmlWithMultipleSchemas = `<document xmlns="http://example.com/ns"><header><title>My Document</title></header></document>`;
let result3 = xmllint.validateXML({
  xml: xmlWithMultipleSchemas,
  schema: schemas
});

if (result3.errors) {
  console.log('Validation 3 (Multiple Schemas - Expected Pass) Errors:', result3.errors);
} else {
  console.log('Validation 3 (Multiple Schemas - Expected Pass): No errors found.');
}