StreamReaderSync - Synchronous Current-Token XML Parsing

StreamReaderSync

StreamReaderSync is the synchronous current-token reader. It accepts a JavaScript string, one Uint8Array, or an Iterable<Uint8Array>.

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

const reader = new StreamReaderSync('<catalog><book id="b1">StAX</book></catalog>');
try {
  while (reader.next() !== null) {
    if (reader.eventType() === XmlEventType.START_ELEMENT) {
      console.log(reader.name(), reader.attributeValue('id'));
    }
  }
} finally {
  reader.close();
}

String input is scanned directly without first encoding it to bytes. Byte inputs use a fatal TextDecoder; encoding defaults to utf-8 and accepts labels supported by the host TextDecoder, including utf-16le and utf-16be. The label is not inferred from the XML declaration; callers must select the encoding that matches the byte source.

type StreamReaderSyncInput =
  | string
  | Uint8Array
  | Iterable<Uint8Array>;

interface StreamReaderSyncOptions {
  documentMode?: 'document' | 'fragment';
  namespaceAware?: boolean; // default: true
  autoDecodeEntities?: boolean; // default: true
  addEntities?: { entity: string; value: string }[];
  encoding?: string; // byte input only; default: 'utf-8'
}

namespaceAware defaults to true. Set it to false when consumers need raw qualified names only: namespace URIs are '', xmlns declarations are ordinary attributes, and undeclared prefixes are not rejected.

The reader emits START_DOCUMENT first and END_DOCUMENT last. Accessors include eventType(), name(), text(), localName(), prefix(), namespaceURI(), indexed attribute metadata, attributeValue(indexOrName), attributeValue(namespaceURI, localName), and namespaceURIForPrefix(). They describe only the current token.

Malformed XML, unsupported named entities, and invalid byte sequences for the selected encoding throw an error. autoDecodeEntities defaults to true and single-pass decodes predefined, numeric, and configured custom entities. Set it to false to return raw reference spelling while retaining validation. CDATA is always literal. addEntities supplies trusted, non-recursive internal definitions without DTD processing or external I/O.

Call reader.close() when stopping early. It is idempotent and closes an underlying byte iterator. Use EventReaderSync when stable event objects are more convenient.