xmldoc: Lightweight XML Document Parser

Common errors

• TypeError: XmlDocument is not a constructor

  cause Attempting to use `require('xmldoc')` directly without destructuring, or `import XmlDocument from 'xmldoc'` in v2.0+ (where `XmlDocument` is a named export).
  fix For CommonJS, use `const { XmlDocument } = require('xmldoc');`. For ESM, use `import { XmlDocument } from 'xmldoc';`.

• ReferenceError: GLOBAL is not defined

  cause Running an older version of `xmldoc` (specifically pre-0.5.1) in Node.js v6 or later, which deprecated/removed the global `GLOBAL` object.
  fix Upgrade `xmldoc` to version `0.5.1` or higher to resolve the `GLOBAL` deprecation warning/error in newer Node.js environments. Alternatively, ensure your Node.js version is compatible with the `xmldoc` version in use.

• Output XML is missing comments or has incorrect escaping for '<' or '>' characters when calling toString().

  cause Comments are explicitly not preserved by `xmldoc`'s `toString()` method. Incorrect escaping (e.g., for `<` and `>`) was a bug in older versions (pre-0.5.0).
  fix Comments are not preserved by design. If you are experiencing incorrect character escaping, upgrade `xmldoc` to `v0.5.0` or newer, which fixed the incorrect escaping issue.

Warnings

• breaking Prior to v0.3.1, `xmldoc` methods returning optional values (e.g., `firstChild`, `childNamed`, `attr` for non-existent attributes) would return `null`. As of v0.3.1, these methods now consistently return `undefined`.
  Fix: Update code to check for `undefined` instead of `null` or use loose equality `== null` to catch both `null` and `undefined`.
• breaking Version 2.0 introduced full TypeScript support and updated CommonJS/ESM compatibility. This changed the primary export pattern from potentially a default export (or other patterns in older versions) to named exports for `XmlDocument`. Older `require('xmldoc')` or `import XmlDocument from 'xmldoc'` patterns may no longer work.
  Fix: For CommonJS, use `const { XmlDocument } = require('xmldoc');`. For ESM and TypeScript, use `import { XmlDocument } from 'xmldoc';`.
• gotcha When converting an `XmlDocument` or `XmlElement` back to an XML string using `toString()`, XML comments are not preserved in the output. This is a design decision of the library.
  Fix: If comment preservation is critical, `xmldoc` is not suitable for round-trip XML modification that must retain comments. Consider alternative XML libraries or pre-process/post-process comments if possible.
• gotcha While `xmldoc` generally attempts to maintain the order of child elements, there have been reports (e.g., GitHub Issue #41) where the order of elements might be unexpectedly altered, particularly in specific scenarios or during internal transformations.
  Fix: Do not rely strictly on the exact original order of sibling elements if your application is sensitive to it. Test thoroughly and consider alternative parsers if strict order preservation is paramount for all operations.

Install

• npm install xmldoc npm
• yarn add xmldoc yarn
• pnpm add xmldoc pnpm

Imports

• XmlDocument
  wrong:

  import XmlDocument from 'xmldoc';

  correct:

  import { XmlDocument } from 'xmldoc';

  ESM and TypeScript environments use named import since v2.0.
• XmlDocument
  wrong:

  const XmlDocument = require('xmldoc');

  correct:

  const { XmlDocument } = require('xmldoc');

  CommonJS environments use named destructuring since v2.0.
• XmlElement

  import { XmlElement } from 'xmldoc';

  XmlElement is typically accessed via XmlDocument instances, but can be imported directly if needed for type hinting or specific use cases.

Quickstart

This quickstart demonstrates parsing an XML string, traversing elements, accessing attributes and text content, and converting the document back to a string.

import { XmlDocument, XmlElement } from "xmldoc";

const xmlString = `
<bookstore>
  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
    <!-- A comment about Italian cuisine -->
  </book>
  <book category="children">
    <title lang="en">Harry Potter</title>
    <author>J.K. Rowling</author>
    <year>2005</year>
    <price>29.99</price>
  </book>
  <magazine>
    <title>National Geographic</title>
  </magazine>
</bookstore>
`;

// Parse the XML string
const document = new XmlDocument(xmlString);

// Find all books
const books = document.childrenNamed("book");
console.log(`Found ${books.length} books.`);

// Access attributes and text content of the first book
const firstBook = books[0];
if (firstBook) {
  console.log(`First book title: ${firstBook.childNamed("title")?.val} (Lang: ${firstBook.childNamed("title")?.attr.lang})`);
  console.log(`First book author: ${firstBook.childNamed("author")?.val}`);
  console.log(`First book category: ${firstBook.attr.category}`);
}

// Find a specific element by path
const harryPotterTitle = document.childNamed("bookstore")
                                  ?.childrenNamed("book")
                                  .find(book => book.childNamed("title")?.val === "Harry Potter")
                                  ?.childNamed("title");

if (harryPotterTitle) {
  console.log(`Harry Potter title found: ${harryPotterTitle.val}`);
}

// Convert back to string (note: comments might be lost depending on version)
const serializedXml = document.toString({ compressed: true }); // compressed option for brevity
console.log("Serialized XML (compressed):", serializedXml.substring(0, 100) + "..."); // show first 100 chars