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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SAXParser
✓ import { SAXParser } from 'sax-ts';
✗ const { SAXParser } = require('sax-ts');
For Node.js projects, use ESM imports. While the package might offer dual CommonJS exports, ESM is the recommended and type-safe approach for modern Node.js and TypeScript.
SAXParser (Deno)
✓ import { SAXParser } from 'https://deno.land/x/sax_ts@1.2.13/mod.ts';
✗ import { SAXParser } from 'https://deno.land/x/sax_ts/src/sax.ts';
For Deno, import directly from `deno.land/x`. Use the `mod.ts` entry point which is standard for Deno third-party modules, and pin the exact version for stable, immutable imports.
SAXParser (JSR)
✓ import { SAXParser } from '@maxim-mazurok/sax_ts';
✗ import { SAXParser } from 'sax-ts';
When using JSR (for Deno, Node.js, Bun), import using the scoped package name as published to JSR. JSR packages are distinct from npm packages.
EVENTS
✓ import { EVENTS } from 'sax-ts';
The `EVENTS` array lists all supported event names as strings, useful for programmatic event registration.
This quickstart demonstrates how to instantiate `SAXParser`, configure its strictness and options, register event handlers for common XML elements (tags, text, errors), and parse a multi-line XML string to extract structured data. It highlights the event-driven nature of the parser and proper error handling.
import { SAXParser, EVENTS } from 'sax-ts';
// Example XML string to parse
const xmlString = `
<bookstore xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2205</year>
<price>30.00</price>
</book>
<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>
</bookstore>
`;
const strict: boolean = false; // Set to true for strict XML parsing; false for more permissive (HTML-like) parsing
const options = {
trim: true, // Trim text and comment nodes
normalize: true, // Turn any whitespace into a single space
lowercase: true, // Lowercase tag and attribute names in loose mode
xmlns: true, // Support namespaces
position: true, // Track line/col/position
strictEntities: true // Only parse predefined XML entities: & ' > < "
};
const parser = new SAXParser(strict, options);
let currentTag: string | null = null;
let currentText: string = '';
const parsedBooks: any[] = [];
let currentBook: any = {};
parser.onerror = function (e: Error) {
console.error(`Parser error: ${e.message}`);
// Crucially, you must clear the error and resume to continue parsing.
(this as SAXParser).error = null;
(this as SAXParser).resume();
};
parser.onopentag = function (node) {
currentTag = node.name;
if (node.name === 'book') {
currentBook = { attributes: node.attributes, content: {} };
}
};
parser.onclosetag = function (tagName) {
if (currentTag && currentText.trim()) {
if (currentBook.content) {
currentBook.content[currentTag] = currentText.trim();
}
}
currentText = '';
currentTag = null;
if (tagName === 'book') {
parsedBooks.push(currentBook);
currentBook = {};
}
};
parser.ontext = function (t) {
if (currentTag) {
currentText += t;
}
};
parser.onend = function () {
console.log('XML parsing completed.');
console.log('Parsed Books:', JSON.stringify(parsedBooks, null, 2));
};
console.log(`Starting XML parsing. Supported events: ${EVENTS.join(', ')}`);
parser.write(xmlString).close();
Errors
Common errors & fixes
TypeError: SAXParser is not a constructor
Attempting to use `require()` for an ESM-first or ESM-only package in a CommonJS context, or incorrect named import syntax.
fixEnsure your Node.js project uses ESM imports: `import { SAXParser } from 'sax-ts';`. If you must use CommonJS, ensure your environment and package configuration correctly support dual ESM/CJS or try dynamic import: `import('sax-ts').then(({ SAXParser }) => { /* ... */ });`. Parser error: Invalid character in tag name
The input XML/HTML contains characters in tag names that are not allowed by the XML specification, and the parser is running in `strict` mode.
fixEither correct the malformed XML input, or initialize `SAXParser` with `strict: false` to enable a more forgiving parsing mode for HTML or less strict XML documents.
Parsing suspended: error occurred
An error was encountered during parsing (e.g., malformed XML in strict mode), and the `onerror` handler did not clear the internal error state or call `resume()`.
fixIn your `onerror` handler, set `(this as SAXParser).error = null;` to clear the error, and then call `(this as SAXParser).resume();` to allow the parser to continue processing the stream.
Audit
Dependencies
No dependency data recorded yet.