ts-xml

A fast, dependency-free XML parser, builder, and validator for TypeScript and Bun. Character-by-character parsing with charCodeAt comparisons for maximum performance.

Features

• Zero Dependencies - only Bun as a runtime
• XMLParser - parse XML strings to JavaScript objects
• XMLBuilder - build XML strings from JavaScript objects
• XMLValidator - validate XML structure with detailed error reporting
• Entity Handling - XML, HTML, numeric, and hex entity decoding/encoding
• Namespace Support - optional namespace prefix removal
• Preserve Order - array-based output to maintain element ordering
• Stop Nodes - skip parsing of specific tag contents
• Unpaired Tags - support for HTML-style void elements (e.g., <br>, <hr>)
• CDATA & Comments - optionally capture CDATA sections and comments as properties
• Processing Instructions - capture <?xml?> declarations and custom PIs
• Value Parsing - automatic number, boolean, hex, and scientific notation parsing
• Custom Processors - tag value, attribute value, and tag name transformation callbacks
• Fully Typed - complete TypeScript type definitions

Get Started

Installation

bun install ts-xml

Parsing XML

import { XMLParser } from 'ts-xml'

const parser = new XMLParser()
const result = parser.parse('<root><item>Hello</item></root>')
// { root: { item: 'Hello' } }

Parsing with Attributes

import { XMLParser } from 'ts-xml'

const parser = new XMLParser({ ignoreAttributes: false })
const result = parser.parse('<book isbn="978-0-123"><title>XML Guide</title></book>')
// { book: { '@_isbn': '978-0-123', title: 'XML Guide' } }

Building XML

import { XMLBuilder } from 'ts-xml'

const builder = new XMLBuilder({ format: true, indentBy: '  ' })
const xml = builder.build({
  root: {
    item: ['one', 'two', 'three'],
  },
})

Validating XML

import { XMLValidator } from 'ts-xml'

const result = XMLValidator('<root><child/></root>')
if (result === true) {
  console.log('Valid XML')
}
else {
  console.log(`Error: ${result.err.msg} at line ${result.err.line}`)
}

Preserve Element Order

import { XMLParser, XMLBuilder } from 'ts-xml'

const parser = new XMLParser({ preserveOrder: true })
const ordered = parser.parse('<root><a>1</a><b>2</b><a>3</a></root>')
// Maintains original element order as arrays

const builder = new XMLBuilder({ preserveOrder: true })
const xml = builder.build(ordered) // Round-trips correctly

Configuration

Parser Options

Builder Options

Benchmarks

Benchmarked on Apple M3 Pro using mitata, comparing against fast-xml-parser, xml2js, and sax.

Parsing

Building

Validation

Round-trip

Run benchmarks yourself: bun run bench

Testing

bun test

724 tests across 6 test files covering parser, builder, validator, entities, and edge cases.

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙