xmlsax-typescript

One-pass, streaming (SAX-style) XML parser for TypeScript — works in Node.js and browsers.

Highlights

Streaming — feed chunks of XML as they arrive; no need to buffer the whole document
Lightweight — zero runtime dependencies, tree-shakeable ESM + CJS
Type-safe — written in TypeScript with full type exports
Namespace-aware — resolves prefixes, URIs, and local names out of the box
Two-way — parse XML to a tree (parseXmlString) or serialize a tree back to XML (serializeXml)
Design-by-contract — invariant checks in development, stripped in production

Install

npm install xmlsax-typescript

API Selection Guide

Use parseXmlString(xml) when you already have the full XML string and need an XmlNode tree.
Use tokenizeXml(xml) for one-shot SAX tokenization of a full string.
Use tokenizeXmlAsync(chunks) for async chunk sources.
Use XmlSaxParser directly when you need fine-grained feed/close control.
Use buildObject(root) to project a parsed tree to a plain object.
Use ObjectBuilder to build objects while streaming tokens without materializing a tree.
Use objectToXml(obj, options) when converting plain objects directly back to XML.

Quick start

Token streaming (sync)

import { XmlSaxParser, dispatchToken } from "xmlsax-typescript";

const parser = new XmlSaxParser();

for (const token of parser.feed("<root>")) {
  dispatchToken(token, {
    openTag: (openTagToken) => {
      console.log("open", openTagToken.tag.name);
    }
  });
}
for (const token of parser.feed("Hello</root>")) {
  dispatchToken(token, {
    text: (textToken) => {
      console.log("text", textToken.text);
    },
    closeTag: (closeTagToken) => {
      console.log("close", closeTagToken.tag.name);
    }
  });
}
parser.close();

Token streaming (async)

import { OpenTagToken, tokenizeXmlAsync } from "xmlsax-typescript";

async function* chunks(): AsyncGenerator<string> {
  yield "<root><item>1</item>";
  yield "<item>2</item></root>";
}

for await (const token of tokenizeXmlAsync(chunks())) {
  if (token instanceof OpenTagToken) {
    console.log(token.depth, token.path.join("/"));
  }
}

Parse to tree

import { parseXmlString } from "xmlsax-typescript";

const root = parseXmlString("<root><a>1</a><b/></root>");
console.log(root.name); // "root"

Project to plain objects

import { buildObject, parseXmlString } from "xmlsax-typescript";

const root = parseXmlString("<root id='1'><item>1</item><item>2</item></root>");
const obj = buildObject(root);
// { "@_id": "1", item: ["1", "2"] }

Streaming object builder

import { ObjectBuilder, XmlSaxParser, dispatchToken } from "xmlsax-typescript";

const builder = new ObjectBuilder();
const parser = new XmlSaxParser();

const consume = (token: Parameters<typeof dispatchToken>[0]): void => {
  dispatchToken(token, {
    openTag: (openTagToken) => builder.onOpenTag(openTagToken.tag),
    text: (textToken) => builder.onText(textToken.text),
    cdata: (cdataToken) => builder.onCdata(cdataToken.text),
    closeTag: () => builder.onCloseTag()
  });
};

for (const token of parser.feed("<root><item>1</item>")) consume(token);
for (const token of parser.feed("<item>2</item></root>")) consume(token);
for (const token of parser.close()) consume(token);

const obj = builder.getResult();
// { item: ["1", "2"] }

Object to XML

import { objectToXml } from "xmlsax-typescript";

const xml = objectToXml({
  root: {
    "@_id": "1",
    item: ["1", "2"],
  }
});

// <root id="1"><item>1</item><item>2</item></root>

import { buildObject, objectToXml, parseXmlString } from "xmlsax-typescript";

const root = parseXmlString("<root id='1'><item>1</item></root>");
const obj = buildObject(root);
const xml = objectToXml(obj, { rootName: "root" });

// <root id="1"><item>1</item></root>

Serialize to XML

import { serializeXml } from "xmlsax-typescript";

const xml = serializeXml(
  {
    name: "root",
    attributes: { id: "1" },
    children: ["Hello", { name: "child", children: ["World"] }],
  },
  { pretty: true, xmlDeclaration: true },
);
// <?xml version="1.0" encoding="UTF-8"?>
// <root id="1">
//   Hello
//   <child>World</child>
// </root>

API

`XmlSaxParser`

new XmlSaxParser(options?: ParserOptions)

Method.	Description
`feed(chunk)`	Feed one XML chunk and return parsed tokens for that chunk
`close()`	Finalize parsing, validate state, and return remaining tokens plus `EndToken`
`drainTokens()`	Return and clear buffered tokens (usually empty if you consume `feed`/`close` return values)
`[Symbol.iterator]()`	Iterate currently buffered tokens
`iterateChunks(src)`	Async iterator over an `Iterable<string>` or `AsyncIterable<string>` chunk source

Example for iterateChunks(src):

import { OpenTagToken, XmlSaxParser } from "xmlsax-typescript";

async function* chunks(): AsyncGenerator<string> {
  yield "<root><item>1</item>";
  yield "<item>2</item></root>";
}

const parser = new XmlSaxParser();
for await (const token of parser.iterateChunks(chunks())) {
  if (token instanceof OpenTagToken) {
    console.log(token.tag.name);
  }
}

`ParserOptions`

Option	Type	Default	Description
`xmlns`	`boolean`	`true`	Enable namespace resolution
`includeNamespaceAttributes`	`boolean`	`false`	Include `xmlns:*` attributes in tag output
`allowDoctype`	`boolean`	`true`	Allow `<!DOCTYPE …>` declarations
`coalesceText`	`boolean`	`true`	Merge adjacent text tokens into a single token
`trackPosition`	`boolean`	`true`	Track line/column; disable for faster parsing

By default (coalesceText: true), adjacent text chunks are merged and emitted as one TextToken per structural boundary. Set coalesceText: false to keep chunk-level text tokenization.

trackPosition controls line/column tracking for parser errors. When set to false, parsing is faster and XmlSaxError still reports offset, while line and column are set to 0.

Token payload note: with xmlns: false, OpenTagToken and CloseTagToken use plain-mode tag shapes aligned with saxes performance semantics.

OpenTagToken.tag.attributes values are strings (not XmlAttribute objects)
OpenTagToken.tag and CloseTagToken.tag omit prefix, local, and uri
With xmlns: true, full namespace metadata remains present

Tokens

Token classes:

OpenTagToken
CloseTagToken
TextToken
CdataToken
CommentToken
ProcessingInstructionToken
DoctypeToken
EndToken

All token classes derive from XmlToken and include:

kind
position ({ offset, line, column } when trackPosition is enabled)

OpenTagToken and CloseTagToken also include:

depth
path

`dispatchToken(token, handlers)`

Typed utility to route any token to kind-specific callbacks without instanceof chains.

import { dispatchToken } from "xmlsax-typescript";

dispatchToken(token, {
  openTag: (openTagToken) => console.log(openTagToken.tag.name),
  text: (textToken) => console.log(textToken.text),
  otherwise: (unknownToken) => console.log(unknownToken.kind)
});

`isBuildToken(token)`

Type guard for structural tokens accepted by TreeBuilder.consume and ObjectBuilder.consume (open-tag, text, cdata, close-tag).

`tokenizeXml(xml, options?)`

Convenience helper for one-shot tokenization of a complete XML string.

`tokenizeXmlAsync(chunks, options?)`

Convenience async generator for iterating tokens from an Iterable<string> or AsyncIterable<string> source.

`parseXmlString(xml, options?)`

Convenience function that parses a complete XML string into an XmlNode tree using XmlSaxParser + TreeBuilder internally.

`TreeBuilder`

Low-level tree builder. Consume parser tokens via consume(token) and call getRoot() to retrieve the resulting XmlNode.

`buildObject(root, options?)`

Projects an XmlNode tree into a plain object. Attributes are prefixed (default @_), text is stored under #text, repeated elements are arrays, and elements with only text return the text directly.

`ObjectBuilder`

Streaming builder that produces the same object shape as buildObject without building a full XmlNode tree. Consume parser tokens via consume(token).

Methods:

Method	Description
`consume(...)`	Consume token-based events (`OpenTag`, `Text`, `Cdata`, `CloseTag`)
`onOpenTag(...)`	Handle an open tag event directly
`onText(...)`	Handle a text event directly
`onCdata(...)`	Handle a CDATA event directly
`onCloseTag()`	Handle a close-tag event directly
`getResult()`	Get the built object
`getRootName()`	Get the root element name

`ObjectBuilderOptions`

Option	Type	Default	Description
`attributePrefix`	`string`	`"@_"`	Prefix for attribute keys
`textKey`	`string`	`"#text"`	Key used for text nodes
`stripNamespaces`	`boolean`	`false`	Strip namespace prefixes from names
`arrayElements`	`Set\<string\> \| (name: string, path: string[]) => boolean`	—	Force specific elements to always be arrays
`coalesceText`	`boolean`	`true`	Merge adjacent text nodes into a single string

`buildXmlNode(obj, options?)`

Converts a plain object into an XmlNode tree using the same attribute/text conventions as buildObject.

`objectToXml(obj, options?)`

Builds an XmlNode with buildXmlNode and serializes it with serializeXml.

`stripNamespace(name)`

Removes namespace prefix from a qualified name.

stripNamespace("p:item"); // "item"
stripNamespace("item"); // "item"

`resolveName(value)`

Normalizes either a qualified string or a tag-like object into a unified name representation.

resolveName("p:item");
// { name: "p:item", localName: "item", prefix: "p", uri: "" }

resolveName({ name: "p:item", prefix: "p", local: "item", uri: "urn:p" });
// { name: "p:item", localName: "item", prefix: "p", uri: "urn:p" }

`XmlBuilderOptions`

Option	Type	Default	Description
`attributePrefix`	`string`	`"@_"`	Prefix for attribute keys
`textKey`	`string`	`"#text"`	Key used for text nodes
`stripNamespaces`	`boolean`	`false`	Strip namespace prefixes from names
`arrayElements`	`Set\<string\> \| (name: string, path: string[]) => boolean`	—	Force specific elements to always be arrays
`rootName`	`string`	—	Root element name when object has multiple keys

`serializeXml(node, options?)`

Serializes an XmlNode back to an XML string.

`SerializeOptions`

Option	Type	Default	Description
`xmlDeclaration`	`boolean`	`false`	Prepend `<?xml …?>` declaration
`pretty`	`boolean`	`false`	Enable indented output
`indent`	`string`	`" "`	Indentation string (when `pretty`)
`newline`	`string`	`"\n"`	Newline string (when `pretty`)

`XmlSaxError`

Custom error class thrown on parse errors. Includes offset, line, and column properties for precise error location.

`XmlSaxBuildError`

Structured build-time error thrown by TreeBuilder, ObjectBuilder, and XML object-to-node conversion helpers when consumed in an invalid state.

`XmlSaxInvariantError`

Debug-only invariant error thrown when an internal design-by-contract check fails.

`XmlSaxLibraryError`

Base class for non-parse library errors (XmlSaxBuildError, XmlSaxInvariantError).

Error Handling

Typical error handling splits into parser errors and build/usage errors:

import {
  parseXmlString,
  XmlSaxBuildError,
  XmlSaxError,
  XmlSaxLibraryError
} from "xmlsax-typescript";

try {
  parseXmlString("<root><broken></root>");
} catch (error) {
  if (error instanceof XmlSaxError) {
    console.error(`Parse error at ${error.line}:${error.column} (offset ${error.offset})`);
  } else if (error instanceof XmlSaxBuildError) {
    console.error(`Builder usage error (${error.phase})`);
  } else if (error instanceof XmlSaxLibraryError) {
    console.error(`Library error code: ${error.code}`);
  } else {
    throw error;
  }
}

Compatibility and Security Notes

Runtime support: Node.js 20+ and modern browsers.
XML input is parsed from JavaScript strings.
For untrusted XML input, disable doctype parsing:

import { parseXmlString } from "xmlsax-typescript";

const root = parseXmlString(inputXml, { allowDoctype: false });

Keep xmlns: true when namespace correctness matters.

Performance Tuning

Set trackPosition: false for faster parse throughput if line/column reporting is not required.
Keep coalesceText: true when you want fewer text-token allocations.
Use streaming APIs (XmlSaxParser, tokenizeXmlAsync) for large inputs.
Run npm run bench:parser to compare common parser modes on your machine.

Exported types

XmlTokenKind · XmlAnyToken · XmlBuildToken · XmlTokenHandlers · OpenTag · CloseTag · XmlAttribute · ProcessingInstruction · Doctype · XmlNode · XmlChild · XmlPosition · XmlChunkIterable · ParserOptions · SerializeOptions · ObjectBuilderOptions · ArrayElementSelector · XmlObjectMap · XmlObjectValue · XmlBuilderOptions · XmlInputObject · XmlInputValue · ObjectToXmlOptions

Features

Namespace resolution (xmlns)
CDATA sections
Entity decoding (named + numeric)
Processing instructions
DOCTYPE handling (parse + emit)
Comments
Precise error positions (line, column, offset)
Pretty-print serialization with XML declaration

Design-by-contract

Internal invariants are checked during development. Set NODE_ENV=production to strip them from production bundles — no runtime overhead.

Development

npm install           # install dependencies
npm run build         # build ESM + CJS with tsup
npm test              # run tests with vitest
npm run test:coverage # run tests with coverage report
npm run test:watch    # run tests in watch mode
npm run bench:parser  # run parser throughput benchmark scenarios
npm run lint          # eslint + tsc type check
npm run typecheck     # run TypeScript type-check only
npm run lint:fix      # auto-fix lint issues
npm run verify        # lint + tests + build + package dry-run

Name		Name	Last commit message	Last commit date
.github		.github
benchmarks		benchmarks
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
AUTHORS		AUTHORS
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

xmlsax-typescript

Highlights

Install

API Selection Guide

Quick start

Token streaming (sync)

Token streaming (async)

Parse to tree

Project to plain objects

Streaming object builder

Object to XML

Serialize to XML

API

XmlSaxParser

ParserOptions

Tokens

dispatchToken(token, handlers)

isBuildToken(token)

tokenizeXml(xml, options?)

tokenizeXmlAsync(chunks, options?)

parseXmlString(xml, options?)

TreeBuilder

buildObject(root, options?)

ObjectBuilder

ObjectBuilderOptions

buildXmlNode(obj, options?)

objectToXml(obj, options?)

stripNamespace(name)

resolveName(value)

XmlBuilderOptions

serializeXml(node, options?)

SerializeOptions

XmlSaxError

XmlSaxBuildError

XmlSaxInvariantError

XmlSaxLibraryError