parse5-sax-parser

Common errors

• ReferenceError: require is not defined

  cause 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

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

  cause 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).

Warnings

• breaking Starting 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.
• breaking As 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`.
• gotcha parse5-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`.
• breaking The 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.
• breaking In `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.

Install

• npm install parse5-sax-parser npm
• yarn add parse5-sax-parser yarn
• pnpm add parse5-sax-parser pnpm

Imports

• SAXParser
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

  import type { 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
  wrong:

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

  correct:

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

  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.

Quickstart

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('<!-- a comment --><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);