StAX-XML

A StAX-style, pull-based XML parser and writer for JavaScript and TypeScript, designed for bounded memory and strong performance. The package is intentionally pure JavaScript: the parser core, stream readers, event readers, converter, and writer all run without binary parser modules or backend selection.

Goals

• Keep memory usage low for large XML documents.
• Parse XML that is larger than JavaScript's single-string comfort zone by consuming streams and byte batches.
• Provide a StAX-style pull API so applications do not need to keep deep SAX state machines in user code.
• Keep async work at I/O ingress boundaries. Once a byte batch has arrived, tokenization and event draining stay synchronous.
• Stay portable across Node, Bun, Deno, browsers, and edge runtimes.

Why Pure JavaScript?

We explored native and Wasm tokenizer acceleration first. Native code can scan XML bytes very quickly, but the public stax-xml contract is JavaScript consumption: callers read names, text, attributes, events, and objects as JavaScript values.

That boundary adds decode, allocation, wrapper, and ownership costs. It also adds native heap or Wasm linear memory to RSS. Because this package is optimized for low memory, very large XML, and pull-based JavaScript consumption, the native experiment was moved out of this package.

Install

npm install stax-xml

The package is ESM-only.

import { EventReaderSync, XmlEventType } from 'stax-xml';

const reader = new EventReaderSync('<root><item id="1">hello</item></root>');

for (const event of reader) {
  if (event.type === XmlEventType.START_ELEMENT) {
    console.log(event.name, event.attributes);
  }
}

Public Surfaces

• stax-xml: StreamReaderSync, EventReaderSync, StreamReader, EventReader, and the writers.
• stax-xml/converter: recommended schema-driven XML-to-object parsing and XML writing.
• StreamReaderSync / StreamReader: allocation-sensitive current-token readers.
• EventReaderSync / EventReader: stable event-object readers built over the same token core.
• Writer, WriterSync, WriterSyncSink: XML output APIs, including a sync sink path for large output.

Both synchronous readers accept string, Uint8Array, or Iterable<Uint8Array>. Strings are scanned directly as JavaScript strings; they are never re-encoded to bytes. Both asynchronous readers accept ReadableStream<Uint8Array> or AsyncIterable<Uint8Array> and decode bytes incrementally with a fatal TextDecoder; encoding defaults to UTF-8. For known object output, start with the converter.

These are the only public package entry points. The package has no default export, runtime adapters, tree/DOM helpers, or backend-selection API.

Benchmarks

Benchmark scripts live under packages/benchmark. The maintained runtime comparison is:

pnpm --dir packages/benchmark bench:runtime-matrix

It compares the same JavaScript reader workload across Node, Bun, and Deno when those runtimes are installed.

Release Guides

• Migrating from v0.x maps older application code to the pure JavaScript 1.0 reader and writer surfaces.
• Web Server Integration shows request streaming patterns for Express, Fastify, Hono, Next.js, Bun, Deno, and edge runtimes.
• Release Readiness records the packaging, benchmark, docs, and merge checklist used before publishing.

License

MIT