@ende/xml

ende add jsr:@ende/xml

Version 2026.10.15 on JSR.

XML parsing and serialization for Ende.

This module implements a non-validating parser for XML 1.0 (Fifth Edition), with opt-in support for XML 1.1 (Second Edition) via the xmlVersion parsing option.

Parsing APIs

Three parsing APIs are provided for different use cases:

API Use Case Output
parse Parse a complete XML string Document tree
parseXmlStream Streaming with maximum throughput Direct callbacks
parseXmlRecords Streaming records assembled in callbacks AsyncGenerator<T>

Quick Examples

DOM-style parsing

import { parse } from "@ende/xml";
import { assertEquals } from "@ende/assert";

const doc = parse("<root><item>Hello</item></root>");
assertEquals(doc.root.name.local, "root");

High-performance streaming with callbacks

For maximum throughput when processing large files:

import { parseXmlStream } from "@ende/xml";

const response = await fetch("https://example.com/feed.xml");
const textStream = response.body!.pipeThrough(new TextDecoderStream());

let itemCount = 0;
await parseXmlStream(textStream, {
  onStartElement(name) {
    if (name === "item") itemCount++;
  },
});
console.log(`Found ${itemCount} items`);

Streaming with byte streams

For convenience with fetch responses:

import { parseXmlStreamFromBytes } from "@ende/xml";

const response = await fetch("https://example.com/feed.xml");

await parseXmlStreamFromBytes(response.body!, {
  onStartElement(name) {
    console.log(`Element: ${name}`);
  },
});

XML 1.1 mode

Pass xmlVersion: "1.1" to opt in to XML 1.1 parsing rules. The option is independent of the document's <?xml version="..."?> declaration.

import { parse } from "@ende/xml";
import { assertEquals, assertThrows } from "@ende/assert";

// Accepted in XML 1.1, rejected in XML 1.0:
const xml = "<root>&#x1;</root>";
const doc = parse(xml, { xmlVersion: "1.1" });
assertEquals(doc.root.name.local, "root");
assertThrows(() => parse(xml));

DOCTYPE handling

<!DOCTYPE ...> declarations are rejected by default to avoid processing hostile DTD content. Pass disallowDoctype: false to tolerate them in trusted input (e.g. legacy XHTML or RSS feeds). DTD contents are still ignored — only the five predefined entities (lt, gt, amp, apos, quot) are ever expanded.

Position Tracking

Both parsers support optional position tracking (line, column, offset) for debugging and error reporting:

  • DOM parser (parse): Position tracking is enabled by default to provide detailed error messages. Disable with { trackPosition: false } for a performance boost when parsing trusted XML.

  • Streaming parser (parseXmlStream): Position tracking is disabled by default for optimal streaming performance. Enable with { trackPosition: true } when you need position info.

Modules

Exports