Saxes Streaming XML Parser

Common errors

• XML Parsing Error: Malformed XML: unexpected end of document

  cause The input XML string is not well-formed according to XML 1.0/1.1 specifications. Saxes is very strict and will reject documents that `sax` might parse.
  fix Review your XML input for any structural errors, unclosed tags, invalid characters, or incorrect entity usage. Ensure it's valid XML, not HTML.

• TypeError: SaxesParser is not a constructor

  cause Incorrect import statement, often due to mixing CommonJS `require` with ES Module `import` syntax or attempting a default import when `SaxesParser` is a named export.
  fix For ES Modules: `import { SaxesParser } from 'saxes';`. For CommonJS: `const { SaxesParser } = require('saxes');`.

• TypeError: parser.resume is not a function

  cause Attempting to call `parser.resume()` after an error, a method that existed in the original `sax` library but is not present in `saxes` due to the removal of the `Stream` API and different error handling philosophy.
  fix Handle errors in your `parser.on('error', ...)` listener. Saxes throws errors by default; if you catch them, you typically just let the parser continue or stop processing the input, as there's no `resume` mechanism.

Warnings

• breaking Saxes is significantly stricter with XML well-formedness than its predecessor, `sax`. It will report errors for malformed XML that `sax` might silently accept. This is a deliberate design choice for compliance.
  Fix: Ensure all input XML strictly adheres to XML 1.0/1.1 and Namespaces specifications. Do not feed HTML or pseudo-XML to saxes.
• breaking Saxes does not expose a `Stream` API. If you were relying on `sax`'s `Stream` functionality, you will need to adapt your code to use the `parser.write()` method directly with character chunks.
  Fix: Replace `Stream` usage with direct calls to `parser.write(chunk)` and `parser.close()` for input termination.
• gotcha The `onerror` handler in `saxes` throws errors by default. In `sax`, errors would often be emitted and require explicit `parser.error = null` and `parser.resume()` calls. This behavior change means unhandled errors will halt execution.
  Fix: Implement a custom `parser.on('error', handlerFunction)` to catch and handle parsing errors gracefully. If your handler does nothing, there is no `resume` method to call.
• gotcha Saxes is a non-validating parser. It does not thoroughly parse DTDs, meaning most malformedness errors within DTDs cannot be reported. Basic XML entities (`&`, `<`, etc.) are handled, but custom DTD-defined entities are not automatically processed.
  Fix: For DTD-defined entities, you must manually listen to the `doctype` event, fetch the DTD content, parse it, and add custom entities to `parser.ENTITIES` if you require their resolution.
• breaking Saxes dropped support for antiquated platforms, including Node versions older than 10 and IE11. The library is built with modern JavaScript (ES6+).
  Fix: Ensure your runtime environment meets the minimum Node.js requirement of v12.22.7 or a modern browser environment. Transpilation to ES5 is not supported in the default build.
• gotcha The internal implementation and non-public API of `saxes` are subject to change without warning. The documentation explicitly advises against using anything not formally public, protected, or documented in JSDOC as public.
  Fix: Rely strictly on the documented public API. Consult the JSDOC comments in the source code for the definitive public interface.

Install

• npm install saxes npm
• yarn add saxes yarn
• pnpm add saxes pnpm

Imports

• SaxesParser
  wrong:

  import SaxesParser from 'saxes';
  // OR
  const SaxesParser = require('saxes').SaxesParser;

  correct:

  import { SaxesParser } from 'saxes';

  SaxesParser is a named export. While the README example uses require('./lib/saxes'), the standard npm import path is 'saxes'.
• SaxesOptions
  wrong:

  import { SaxesOptions } from 'saxes';

  correct:

  import type { SaxesOptions } from 'saxes';

  SaxesOptions is a type export. Use `import type` for clarity and to prevent runtime issues in some bundlers or environments without proper type stripping.
• CommonJS require
  wrong:

  const saxes = require('saxes');
  const parser = new saxes.SaxesParser();

  correct:

  const { SaxesParser } = require('saxes');

  While `saxes.SaxesParser` works, direct destructuring is often preferred for named exports in CommonJS modules, aligning with modern JavaScript practices. The original README uses a local path which is uncommon for npm packages.

Quickstart

Demonstrates basic parsing of an XML string, handling open tags, text content, close tags, and errors using event listeners. It shows both attributes and CDATA sections.

import { SaxesParser } from 'saxes';

const xmlString = `<root>
  <item id="1">Hello &amp; World!</item>
  <item id="2"><![CDATA[<tag>content</tag>]]></item>
</root>`;

const parser = new SaxesParser();

parser.on('error', (err) => {
  console.error('XML Parsing Error:', err.message);
  // The default onerror handler throws, so subsequent data calls might not happen if not caught.
});

parser.on('opentag', (node) => {
  console.log(`Opened tag: ${node.name} with attributes:`, node.attributes);
});

parser.on('text', (text) => {
  if (text.trim().length > 0) {
    console.log(`Text content: '${text.trim()}'`);
  }
});

parser.on('closetag', (nodeName) => {
  console.log(`Closed tag: ${nodeName}`);
});

parser.on('end', () => {
  console.log('Finished parsing XML.');
});

try {
  parser.write(xmlString).close();
} catch (e) {
  // Catch errors if the default onerror handler is active and throws
  console.error('Caught error during write/close:', e.message);
}