saxes

library6.0.0jsnpmunverified

Saxes is an evented, streaming XML parser for JavaScript, currently at version 6.0.0. It is a modern, stricter, and significantly faster fork of the original `sax` library, designed primarily for Node.js environments (requiring Node.js >=12.22.7) but also functional in browsers. Its core differentiator is a strong adherence to XML 1.0/1.1 and Namespaces in XML 1.0/1.1 well-formedness rules, unlike `sax` which tolerates malformed structures. This makes `saxes` unsuitable for HTML or pseudo-XML parsing, as it will explicitly report well-formedness errors. While it is a non-validating parser, it aims to catch all malformed constructs outside of thorough DTD validation. `saxes` does not include a `Stream` API, a notable departure from its `sax` predecessor, and its `onerror` handler defaults to throwing errors, which can be overridden. The project is actively maintained, with a focus on performance and strict conformance to XML specifications.

serialization

npm install saxes

github ↗package ↗

INSTALL

IMPORT

SIG · SAXES

saxes

serializationjavascriptv6.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SaxesParser

✓ import { SaxesParser } from 'saxes';

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

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

SaxesOptions

✓ import type { SaxesOptions } from 'saxes';

✗ import { 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

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

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

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.

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 & 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); }

Debug

Known issues

breakingSaxes 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.

affects: >=1.0.0

breakingSaxes 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaSaxes 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.

affects: >=1.0.0

breakingSaxes 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

XML Parsing Error: Malformed XML: unexpected end of document

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

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

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.

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/lddubeau/saxes ↗

packagehttps://www.npmjs.com/package/saxes ↗