Registry / serialization / parse5-sax-parser

parse5-sax-parser

library8.0.0jsnpmunverified

parse5-sax-parser is a streaming SAX-style HTML parser, designed for efficient, event-driven processing of HTML documents without building a full Document Object Model (DOM). It is part of the comprehensive `parse5` toolset, known for its high conformance to the WHATWG HTML Living Standard. The current stable version is 8.0.1. The project maintains an active release cadence, with major versions (like v7.0.0 and v8.0.0) introducing significant architectural changes and features, complemented by frequent patch and minor releases for dependency updates and bug fixes. Its key differentiators include its streaming nature, SAX (Simple API for XML) event model, and robust HTML5 spec compliance, making it suitable for scenarios where memory efficiency and raw content inspection are prioritized over DOM manipulation. It's often used in conjunction with other `parse5` modules or as a standalone component for tasks like data extraction or sanitization.

serialization http-networking web-framework

npm install parse5-sax-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PARSE5-SAX-PARSER

parse5-sax-parser

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

SAXParser

✓ import { SAXParser } from 'parse5-sax-parser';

✗ const SAXParser = require('parse5-sax-parser').SAXParser;

Since v7.0.0, parse5 and its sub-packages are ECMAScript Modules (ESM) first. CommonJS `require()` is generally discouraged or requires specific bundler/Node.js configurations. Always prefer named ESM imports.

SAXParserOptions

✓ import type { SAXParserOptions } from 'parse5-sax-parser';

✗ import { SAXParserOptions } from 'parse5-sax-parser';

Import types using `import type` for better tree-shaking and clarity, especially when the library ships its own TypeScript definitions.

StartTag

✓ import type { StartTag } from 'parse5-sax-parser';

✗ import { StartTag } from 'parse5-sax-parser/lib/tokens';

Specific token types like `StartTag`, `EndTag`, `Text`, `Comment`, and `Doctype` are exported as types directly from the main package entry point for convenience since v7.0.0, consolidating module exports.

Demonstrates how to use parse5-sax-parser as a streaming event emitter, piping HTML data through it and listening for SAX-style events like startTag, endTag, text, and comment.

import { SAXParser } from 'parse5-sax-parser'; import { Readable } from 'stream'; // Simulate an HTML input stream const htmlStream = new Readable({ read() { this.push('<!DOCTYPE html><html><head><title>Test</title></head><body>'); this.push('<h1>Hello, <b>world</b>!</h1><p>This is a <a href="#">link</a>.</p>'); this.push('<br>'); this.push('</body></html>'); this.push(null); // No more data } }); const parser = new SAXParser(); parser.on('doctype', (doctype) => { console.log('DOCTYPE:', doctype.name); }); parser.on('startTag', (tag) => { console.log(`Start Tag: <${tag.name}> Attributes:`, tag.attrs.map(attr => `${attr.name}="${attr.value}"`).join(' ')); }); parser.on('endTag', (tag) => { console.log(`End Tag: </${tag.name}>`); }); parser.on('text', (text) => { if (text.text.trim().length > 0) { console.log('Text:', JSON.stringify(text.text)); } }); parser.on('comment', (comment) => { console.log('Comment:', comment.text); }); parser.on('error', (err) => { console.error('Parsing error:', err); }); parser.on('finish', () => { console.log('Parsing finished!'); }); // Pipe the HTML stream through the parser. SAXParser is a passthrough stream. // It emits events but passes the original data unchanged, allowing further piping. htmlStream.pipe(parser); // If you wanted to, you could pipe it further, e.g., parser.pipe(anotherWritableStream);

Debug

Known issues

breakingStarting with v7.0.0, all `parse5` packages, including `parse5-sax-parser`, are published as ECMAScript Modules (ESM) only. Direct CommonJS `require()` statements are no longer supported by default.

fix

Migrate your project to use native ESM imports (`import ... from '...'`). For Node.js, ensure your package.json specifies `"type": "module"` or use `.mjs` file extensions. Older Node.js versions or specific bundler configurations might require additional setup.

affects: >=7.0.0

breakingAs of v7.0.0, `parse5` and its sub-packages now ship their own TypeScript definitions. You should remove any `@types/parse5-sax-parser` package from your project as it is no longer needed and can cause type conflicts.

fix

Remove `@types/parse5-sax-parser` from your `devDependencies` in `package.json` and run `npm install` or `yarn install`.

affects: >=7.0.0

gotchaparse5-sax-parser is a pass-through transform stream. It emits events but does *not* modify the HTML content itself. If you pipe data through it, the output will be identical to the input. This means it cannot be used for HTML sanitization or rewriting directly; for that, consider `parse5-html-rewriting-stream` or building a DOM with `parse5` and then serializing.

fix

Understand its purpose: event-driven analysis without content modification. For transformation, use `parse5-html-rewriting-stream` or a full DOM parser/serializer from `parse5`.

affects: >=1.0.0

breakingThe underlying `parse5` core package, upon which `parse5-sax-parser` relies, received significant updates in v7.0.0 to catch up with the latest HTML Living Standard specification. This might lead to subtle differences in parsing results for certain edge cases compared to previous versions.

fix

Thoroughly test your application's HTML parsing behavior after upgrading to v7.0.0 or later to ensure no unexpected changes in token streams or parsing outcomes occur, especially with malformed or complex HTML.

affects: >=7.0.0

breakingIn `parse5` v6.0.0 (and therefore affecting the broader parse5 ecosystem), the `TreeAdapter` interface introduced a new mandatory method, `updateNodeSourceCodeLocation`. While `parse5-sax-parser` does not directly build a DOM tree, applications that heavily integrate custom `TreeAdapter` implementations with the core `parse5` functionality might need to update their adapters if they are also using `parse5-sax-parser` in the same project context.

fix

If using custom tree adapters with `parse5`, ensure they implement the `updateNodeSourceCodeLocation` method. If only using `parse5-sax-parser` for events, this warning is less critical but indicates a change in the underlying ecosystem.

affects: >=6.0.0 <7.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require()` to import `parse5-sax-parser` in an ECMAScript Module (ESM) context or a Node.js environment configured for ESM.

fix

Change `const { SAXParser } = require('parse5-sax-parser');` to `import { SAXParser } from 'parse5-sax-parser';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for ESM files.

TypeError: SAXParser is not a constructor

Incorrectly importing `SAXParser` as a default import, or attempting to use a CommonJS `require()` pattern in a project that expects ESM named exports, or vice-versa.

fix

Verify your import statement. For ESM, use `import { SAXParser } from 'parse5-sax-parser';`. For older CommonJS projects (pre-v7), it would have been `const { SAXParser } = require('parse5-sax-parser');`.

My parser isn't emitting all expected events or seems to hang after processing some input.

Forgetting to signal the end of the input stream to the SAXParser, especially when manually `write()`-ing chunks instead of piping from another stream.

fix

If you are writing data manually using `parser.write(chunk)`, ensure you call `parser.end()` when all data has been written. If using `pipe()`, ensure the source stream correctly signals its end (e.g., by pushing `null` for `Readable` streams).

Upgrade

Version history

8.0.0latest on npm

Audit

Dependencies

parse5requiredCore HTML parsing logic and utilities are provided by the main parse5 package.

entitiesrequiredUsed for HTML entity decoding, a transitive dependency often updated.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/inikulin/parse5 ↗

packagehttps://www.npmjs.com/package/parse5-sax-parser ↗

homepagehttps://parse5.js.org ↗