stax-xml

stax-xml

stax-xml

Classes

StaxXmlParser

High-performance asynchronous XML parser with circular buffer queue optimization.

This parser provides memory-efficient processing of large XML files through streaming with support for pull-based parsing, custom entity handling, and namespace processing.

OPTIMIZATION: Replaces array-based queue with circular buffer for O(1) operations. Achieved improvement: ~15% on large XML files (1GB+).

Remarks

The parser uses UTF-8 safe processing with Boyer-Moore-Horspool pattern search optimization and supports both single-event and batch processing modes for improved performance.

Example

Basic usage:

const xmlContent = '<root><item>Hello</item></root>';
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(new TextEncoder().encode(xmlContent));
    controller.close();
  }
});

const parser = new StaxXmlParser(stream);
for await (const event of parser) {
  console.log(event.type, event);
}

Implements

AsyncIterator<AnyXmlEvent>

Constructors

Constructor

new StaxXmlParser(xmlStream, options): StaxXmlParser

Defined in: StaxXmlParser.ts:206

Creates a new StaxXmlParser instance.

Parameters

xmlStream

ReadableStream<Uint8Array<ArrayBufferLike>>

The ReadableStream containing XML data as Uint8Array chunks

options

StaxXmlParserOptions = {}

Configuration options for the parser

Returns

StaxXmlParser

Throws

When xmlStream is not a valid ReadableStream

Example

const xmlData = '<root><item>content</item></root>';
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(new TextEncoder().encode(xmlData));
    controller.close();
  }
});

const parser = new StaxXmlParser(stream, {
  autoDecodeEntities: true,
  maxBufferSize: 64 * 1024,
  initialQueueCapacity: 2048
});

Accessors

XmlEventType

Get Signature

get XmlEventType(): object

Defined in: StaxXmlParser.ts:1176

Returns

object

START_DOCUMENT

readonly START_DOCUMENT: "START_DOCUMENT" = 'START_DOCUMENT'

END_DOCUMENT

readonly END_DOCUMENT: "END_DOCUMENT" = 'END_DOCUMENT'

START_ELEMENT

readonly START_ELEMENT: "START_ELEMENT" = 'START_ELEMENT'

END_ELEMENT

readonly END_ELEMENT: "END_ELEMENT" = 'END_ELEMENT'

CHARACTERS

readonly CHARACTERS: "CHARACTERS" = 'CHARACTERS'

CDATA

readonly CDATA: "CDATA" = 'CDATA'

ERROR

readonly ERROR: "ERROR" = 'ERROR'

Methods

nextBatch()

nextBatch(size?): Promise<AnyXmlEvent[]>

Defined in: StaxXmlParser.ts:563

Parameters

size?

number

Returns

Promise<AnyXmlEvent[]>

batchedIterator()

batchedIterator(batchSize?): AsyncGenerator<AnyXmlEvent[]>

Defined in: StaxXmlParser.ts:582

Parameters

batchSize?

number

Returns

AsyncGenerator<AnyXmlEvent[]>

next()

next(): Promise<IteratorResult<AnyXmlEvent, any>>

Defined in: StaxXmlParser.ts:837

Returns

Promise<IteratorResult<AnyXmlEvent, any>>

Implementation of

AsyncIterator.next

[asyncIterator]()

[asyncIterator](): AsyncIterator<AnyXmlEvent>

Defined in: StaxXmlParser.ts:856

Returns

AsyncIterator<AnyXmlEvent>

StaxXmlParserSync

Defined in: StaxXmlParserSync.ts:50

TRUE INCREMENTAL State Machine XML Parser

Eliminates Generator overhead while maintaining StAX pull-based API Parses exactly ONE event per next() call (true incremental)

Performance: +20.67% improvement vs Generator baseline

Implements

Iterable<AnyXmlEvent>
Iterator<AnyXmlEvent>

Constructors

Constructor

new StaxXmlParserSync(xml, options): StaxXmlParserSync

Defined in: StaxXmlParserSync.ts:104

Parameters

xml

string

options

StaxXmlParserSyncOptions = {}

Returns

StaxXmlParserSync

Methods

[iterator]()

[iterator](): Iterator<AnyXmlEvent>

Defined in: StaxXmlParserSync.ts:122

Symbol.iterator implementation - enables for…of loops Returns self to maintain single iterator state

Returns

Iterator<AnyXmlEvent>

Implementation of

Iterable.[iterator]

next()

next(): IteratorResult<AnyXmlEvent>

Defined in: StaxXmlParserSync.ts:134

Main Iterator.next() implementation - TRUE INCREMENTAL parsing

Parses exactly ONE event per call without Generator overhead Uses state machine to track parsing progress

Performance: ~10ns/event overhead (vs ~95ns for Generator)

Returns

IteratorResult<AnyXmlEvent>

Implementation of

Iterator.next

StaxXmlWriter

Defined in: StaxXmlWriter.ts:131

High-performance asynchronous XML writer implementing the StAX (Streaming API for XML) pattern.

This writer provides efficient streaming XML generation using WritableStream for handling large XML documents with automatic buffering, backpressure management, and namespace support.

This is an optimized implementation with:

Optimization 1: Regex caching for entity escaping
Optimization 2: Attribute string batching
Optimization 3: Early entity check before regex execution

Remarks

The writer supports streaming output with configurable buffering, automatic entity encoding, pretty printing with customizable indentation, and comprehensive namespace handling.

Examples

Basic usage:

const writableStream = new WritableStream({
  write(chunk) {
    console.log(new TextDecoder().decode(chunk));
  }
});

const writer = new StaxXmlWriter(writableStream);
await writer.writeStartElement('root');
await writer.writeElement('item', { id: '1' }, 'Hello World');
await writer.writeEndElement();
await writer.close();

With pretty printing:

const options = {
  prettyPrint: true,
  indentString: '    ',
  autoEncodeEntities: true
};
const writer = new StaxXmlWriter(writableStream, options);

Constructors

Constructor

new StaxXmlWriter(stream, options): StaxXmlWriter

Defined in: StaxXmlWriter.ts:168

Parameters

stream

WritableStream<Uint8Array<ArrayBufferLike>>

options

StaxXmlWriterOptions = {}

Returns

StaxXmlWriter

Methods

writeStartDocument()

writeStartDocument(version, encoding?): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:273

Write XML declaration

Parameters

version

string = '1.0'

encoding?

string

Returns

Promise<StaxXmlWriter>

writeEndDocument()

writeEndDocument(): Promise<void>

Defined in: StaxXmlWriter.ts:298

End document (automatically close all elements)

Returns

Promise<void>

writeStartElement()

writeStartElement(localName, options?): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:319

Write start element

Parameters

localName

string

options?

WriteElementOptions

Returns

Promise<StaxXmlWriter>

writeEndElement()

writeEndElement(): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:402

Write end element

Returns

Promise<StaxXmlWriter>

writeCharacters()

writeCharacters(text): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:438

Write text

Parameters

text

string

Returns

Promise<StaxXmlWriter>

writeCData()

writeCData(cdata): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:460

Write CDATA section

Parameters

cdata

string

Returns

Promise<StaxXmlWriter>

writeComment()

writeComment(comment): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:480

Write comment

Parameters

comment

string

Returns

Promise<StaxXmlWriter>

writeRaw()

writeRaw(xml): Promise<StaxXmlWriter>

Defined in: StaxXmlWriter.ts:503

Write raw XML content without escaping

Parameters

xml

string

Raw XML string to write

Returns

Promise<StaxXmlWriter>

this (chainable)

flush()

flush(): Promise<void>

Defined in: StaxXmlWriter.ts:512

Manual flush

Returns

Promise<void>

getMetrics()

getMetrics(): object

Defined in: StaxXmlWriter.ts:519

Return metrics

Returns

object

totalBytesWritten

totalBytesWritten: number = 0

flushCount

flushCount: number = 0

lastFlushTime

lastFlushTime: number = 0

bufferUtilization

bufferUtilization: number

averageFlushSize

averageFlushSize: number

StaxXmlWriterSync

Defined in: StaxXmlWriterSync.ts:44

A class for writing XML similar to StAX XMLStreamWriter. This is an optimized implementation with:

Optimization 1: Regex caching for entity escaping
Optimization 2: Attribute string batching
Optimization 3: Early entity check before regex execution

Constructors

Constructor

new StaxXmlWriterSync(options): StaxXmlWriterSync

Defined in: StaxXmlWriterSync.ts:70

Parameters

options

StaxXmlWriterSyncOptions = {}

Returns

StaxXmlWriterSync

Methods

writeStartDocument()

writeStartDocument(version, encoding?): this

Defined in: StaxXmlWriterSync.ts:119

Writes the XML declaration (e.g., ). Should be called only once at the very beginning of the document.

Parameters

version

string = '1.0'

XML version (default: “1.0”)

encoding?

string

Encoding (default: value set in constructor)

Returns

this

this (chainable)

Throws

Error when called in incorrect state

writeEndDocument()

writeEndDocument(): void

Defined in: StaxXmlWriterSync.ts:145

Indicates the end of the document and automatically closes all open elements.

Returns

void

Promise Promise that resolves when stream is flushed

getXmlString()

getXmlString(): string

Defined in: StaxXmlWriterSync.ts:162

Returns the written XML string. Should be called after writeEndDocument() to get the complete XML.

Returns

string

The written XML string

writeStartElement()

writeStartElement(localName, options?): this

Defined in: StaxXmlWriterSync.ts:173

Writes a start element (e.g., or prefix:element).

Parameters

localName

string

Local name of the element

options?

WriteElementOptions

Element writing options (prefix, uri, attributes, selfClosing)

Returns

this

this (chainable)

Throws

Error when called in incorrect state

writeAttribute()

writeAttribute(localName, value, prefix?): this

Defined in: StaxXmlWriterSync.ts:265

Writes an attribute. Can only be called immediately after writeStartElement().

Parameters

localName

string

Local name of the attribute

value

string

Attribute value

prefix?

string

Namespace prefix of the attribute (note: this implementation does not manage namespace mapping)

Returns

this

this (chainable)

Throws

Error when called in incorrect state

writeNamespace()

writeNamespace(prefix, uri): this

Defined in: StaxXmlWriterSync.ts:285

Writes a namespace declaration. Can only be called immediately after writeStartElement(). This implementation simply writes the string in the form xmlns:prefix=“uri” or xmlns=“uri”. Actual namespace validation/management logic is not included.

Parameters

prefix

string

Namespace prefix

uri

string

Namespace URI

Returns

this

this (chainable)

Throws

Error when called in incorrect state

writeCharacters()

writeCharacters(text): this

Defined in: StaxXmlWriterSync.ts:309

Writes text content.

Parameters

text

string

Text to write

Returns

this

this (chainable)

Throws

Error when called in incorrect state

writeCData()

writeCData(cdata): this

Defined in: StaxXmlWriterSync.ts:332

Writes a CDATA section.

Parameters

cdata

string

CDATA content

Returns

this

this (chainable)

Throws

Error when called in incorrect state (especially when containing ’]]>’ sequence)

writeComment()

writeComment(comment): this

Defined in: StaxXmlWriterSync.ts:359

Writes a comment.

Parameters

comment

string

Comment content

Returns

this

this (chainable)

Throws

Error when called in incorrect state (especially when containing ’—’ sequence)

writeProcessingInstruction()

writeProcessingInstruction(target, data?): this

Defined in: StaxXmlWriterSync.ts:382

Writes a processing instruction (Processing Instruction).

Parameters

target

string

PI target

data?

string

PI data (optional)

Returns

this

this (chainable)

Throws

Error when called in incorrect state (especially when containing ’?>’ sequence)

writeRaw()

writeRaw(xml): this

Defined in: StaxXmlWriterSync.ts:408

Writes raw XML content without escaping

Parameters

xml

string

Raw XML string to write

Returns

this

this (chainable)

writeEndElement()

writeEndElement(): this

Defined in: StaxXmlWriterSync.ts:419

Closes the currently open element (e.g., or </prefix:element>).

Returns

this

this (chainable)

Throws

Error when called with no open elements

setPrettyPrint()

setPrettyPrint(enabled): this

Defined in: StaxXmlWriterSync.ts:456

Enables/disables pretty print functionality.

Parameters

enabled

boolean

Whether to enable pretty print

Returns

this

this (chainable)

setIndentString()

setIndentString(indentString): this

Defined in: StaxXmlWriterSync.ts:466

Sets the indentation string.

Parameters

indentString

string

String to use for indentation (e.g., ’ ’, ‘\t’, ’ ‘)

Returns

this

this (chainable)

isPrettyPrintEnabled()

isPrettyPrintEnabled(): boolean

Defined in: StaxXmlWriterSync.ts:475

Returns the current pretty print setting.

Returns

boolean

Whether pretty print is enabled

getIndentString()

getIndentString(): string

Defined in: StaxXmlWriterSync.ts:483

Returns the current indentation string.

Returns

string

Currently set indentation string

Interfaces

StaxXmlParserOptions

Defined in: StaxXmlParser.ts:31

Configuration options for the StaxXmlParser

Properties

encoding?

optional encoding: string

Defined in: StaxXmlParser.ts:36

Text encoding for the input stream

Default Value

'utf-8'

addEntities?

optional addEntities: object[]

Defined in: StaxXmlParser.ts:42

Additional custom entities to decode

entity

entity: string

value

value: string

Default Value

[]

autoDecodeEntities?

optional autoDecodeEntities: boolean

Defined in: StaxXmlParser.ts:48

Whether to automatically decode XML entities

Default Value

true

maxBufferSize?

optional maxBufferSize: number

Defined in: StaxXmlParser.ts:54

Maximum buffer size in bytes

Default Value

enableBufferCompaction?

optional enableBufferCompaction: boolean

Defined in: StaxXmlParser.ts:60

Whether to enable buffer compaction for memory efficiency

Default Value

true

batchSize?

optional batchSize: number

Defined in: StaxXmlParser.ts:66

Number of events to batch together

Default Value

batchTimeout?

optional batchTimeout: number

Defined in: StaxXmlParser.ts:72

Timeout for batch processing in milliseconds

Default Value

initialQueueCapacity?

optional initialQueueCapacity: number

Defined in: StaxXmlParser.ts:78

Initial event queue capacity (circular buffer size)

Default Value

StaxXmlParserSyncOptions

Defined in: StaxXmlParserSync.ts:25

Properties

autoDecodeEntities?

optional autoDecodeEntities: boolean

Defined in: StaxXmlParserSync.ts:26

addEntities?

optional addEntities: object[]

Defined in: StaxXmlParserSync.ts:27

entity

entity: string

value

value: string

StaxXmlWriterOptions

Defined in: StaxXmlWriter.ts:25

Configuration options for the StaxXmlWriter

Properties

encoding?

optional encoding: string

Defined in: StaxXmlWriter.ts:30

Text encoding for the output stream

Default Value

'utf-8'

prettyPrint?

optional prettyPrint: boolean

Defined in: StaxXmlWriter.ts:36

Whether to format output with indentation

Default Value

false

indentString?

optional indentString: string

Defined in: StaxXmlWriter.ts:42

String used for indentation when prettyPrint is true

Default Value

'  '

addEntities?

optional addEntities: object[]

Defined in: StaxXmlWriter.ts:48

Additional custom entities to encode

entity

entity: string

value

value: string

Default Value

[]

autoEncodeEntities?

optional autoEncodeEntities: boolean

Defined in: StaxXmlWriter.ts:54

Whether to automatically encode XML entities

Default Value

true

namespaces?

optional namespaces: NamespaceDeclaration[]

Defined in: StaxXmlWriter.ts:60

Namespace declarations to include

Default Value

[]

bufferSize?

optional bufferSize: number

Defined in: StaxXmlWriter.ts:66

Internal buffer size in bytes

Default Value

highWaterMark?

optional highWaterMark: number

Defined in: StaxXmlWriter.ts:72

WritableStream backpressure threshold

Default Value

flushThreshold?

optional flushThreshold: number

Defined in: StaxXmlWriter.ts:78

Automatic flush threshold (percentage of bufferSize)

Default Value

0.8

enableAutoFlush?

optional enableAutoFlush: boolean

Defined in: StaxXmlWriter.ts:84

Whether to enable automatic flushing

Default Value

true

StaxXmlWriterSyncOptions

Defined in: StaxXmlWriterSync.ts:27

Properties

encoding?

optional encoding: string

Defined in: StaxXmlWriterSync.ts:28

prettyPrint?

optional prettyPrint: boolean

Defined in: StaxXmlWriterSync.ts:29

indentString?

optional indentString: string

Defined in: StaxXmlWriterSync.ts:30

addEntities?

optional addEntities: object[]

Defined in: StaxXmlWriterSync.ts:31

entity

entity: string

value

value: string

autoEncodeEntities?

optional autoEncodeEntities: boolean

Defined in: StaxXmlWriterSync.ts:32

namespaces?

optional namespaces: NamespaceDeclaration[]

Defined in: StaxXmlWriterSync.ts:33

StartElementEvent

Defined in: types.ts:66

Event fired when an XML element starts

Properties

type

type: "START_ELEMENT"

Defined in: types.ts:67

name

name: string

Defined in: types.ts:68

localName?

optional localName: string

Defined in: types.ts:69

prefix?

optional prefix: string

Defined in: types.ts:70

uri?

optional uri: string

Defined in: types.ts:71

attributes

attributes: Record<string, string>

Defined in: types.ts:72

attributesWithPrefix?

optional attributesWithPrefix: Record<string, AttributeInfo>

Defined in: types.ts:73

CharactersEvent

Defined in: types.ts:84

Properties

type

type: "CHARACTERS"

Defined in: types.ts:85

value

value: string

Defined in: types.ts:86

CdataEvent

Defined in: types.ts:89

Properties

type

type: "CDATA"

Defined in: types.ts:90

value

value: string

Defined in: types.ts:91

ErrorEvent

Defined in: types.ts:94

Properties

type

type: "ERROR"

Defined in: types.ts:95

error

error: Error

Defined in: types.ts:96

XmlAttribute

Defined in: types.ts:114

Attribute interface (for Writer)

Properties

prefix?

optional prefix: string

Defined in: types.ts:115

localName

localName: string

Defined in: types.ts:116

uri?

optional uri: string

Defined in: types.ts:117

value

value: string

Defined in: types.ts:118

WriteElementOptions

Defined in: types.ts:354

Element writing options interface (for Writer)

Properties

prefix?

optional prefix: string

Defined in: types.ts:355

uri?

optional uri: string

Defined in: types.ts:356

attributes?

optional attributes: Record<string, string | AttributeInfo>

Defined in: types.ts:357

selfClosing?

optional selfClosing: boolean

Defined in: types.ts:358

comment?

optional comment: string

Defined in: types.ts:359

Type Aliases

XmlEventType

XmlEventType = typeof XmlEventType[keyof typeof XmlEventType]

Defined in: types.ts:6

AnyXmlEvent

AnyXmlEvent = StartDocumentEvent | EndDocumentEvent | StartElementEvent | EndElementEvent | CharactersEvent | CdataEvent | ErrorEvent

Defined in: types.ts:102

Discriminated Union type for developer use

Variables

XmlEventType

const XmlEventType: object

Defined in: types.ts:6

Enumeration of XML stream event types used by the StAX parser

Type Declaration

START_DOCUMENT

readonly START_DOCUMENT: "START_DOCUMENT" = 'START_DOCUMENT'

END_DOCUMENT

readonly END_DOCUMENT: "END_DOCUMENT" = 'END_DOCUMENT'

START_ELEMENT

readonly START_ELEMENT: "START_ELEMENT" = 'START_ELEMENT'

END_ELEMENT

readonly END_ELEMENT: "END_ELEMENT" = 'END_ELEMENT'

CHARACTERS

readonly CHARACTERS: "CHARACTERS" = 'CHARACTERS'

CDATA

readonly CDATA: "CDATA" = 'CDATA'

ERROR

readonly ERROR: "ERROR" = 'ERROR'

Functions

isStartElement()

isStartElement(event): event is StartElementEvent

Defined in: types.ts:297

Type guard function - Check if the event is a START_ELEMENT event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is StartElementEvent

true if the event is a START_ELEMENT event, false otherwise

isEndElement()

isEndElement(event): event is EndElementEvent

Defined in: types.ts:306

Type guard function - Check if the event is an END_ELEMENT event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is EndElementEvent

true if the event is an END_ELEMENT event, false otherwise

isCharacters()

isCharacters(event): event is CharactersEvent

Defined in: types.ts:315

Type guard function - Check if the event is a CHARACTERS event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is CharactersEvent

true if the event is a CHARACTERS event, false otherwise

isCdata()

isCdata(event): event is CdataEvent

Defined in: types.ts:323

Type guard function - Check if the event is a CDATA event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is CdataEvent

true if the event is a CDATA event, false otherwise

isError()

isError(event): event is ErrorEvent

Defined in: types.ts:331

Type guard function - Check if the event is an ERROR event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is ErrorEvent

true if the event is an ERROR event, false otherwise

isStartDocument()

isStartDocument(event): event is StartDocumentEvent

Defined in: types.ts:339

Type guard function - Check if the event is a START_DOCUMENT event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is StartDocumentEvent

true if the event is a START_DOCUMENT event, false otherwise

isEndDocument()

isEndDocument(event): event is EndDocumentEvent

Defined in: types.ts:347

Type guard function - Check if the event is an END_DOCUMENT event

Parameters

event

AnyXmlEvent

XML event to check

Returns

event is EndDocumentEvent

true if the event is an END_DOCUMENT event, false otherwise