Basic Parsing API

Relevant source files

The following files were used as context for generating this wiki page:

• src/Parser.ts
• src/index.ts
• README.md
• src/Tokenizer.ts
• src/WritableStream.ts
• src/WebWritableStream.ts

The Basic Parsing API in htmlparser2 provides a high-performance, event-driven interface for consuming HTML and XML documents. It is designed to be "forgiving," allowing it to handle malformed markup while maintaining high throughput. The core of this API is the Parser class, which transforms raw string input into a series of structured events via a user-defined handler.

This API serves as the foundation for the higher-level Getting a DOM features, which aggregate these events into a tree structure. It supports standard HTML5 behavior, including implicit tag closing and foreign context handling (SVG/MathML), as well as a dedicated xmlMode for strict XML processing.

Sources: README.md:1-12, src/Parser.ts:250-258

Core Components and Architecture

The parsing process is split into two primary layers: the Tokenizer and the Parser. The Tokenizer handles low-level character scanning and identifies logical segments (tokens) such as tag names, attributes, and text blocks. The Parser consumes these tokens, manages the element stack, handles HTML-specific logic (like void elements and auto-closing tags), and emits high-level events to the Handler.

The Parser Class

The Parser class is the main entry point for the basic API. It implements the Callbacks interface required by the Tokenizer and manages the state of the document being parsed.

Key Methods

Method	Description
write(chunk: string)	Parses a chunk of data. Events are emitted synchronously as tokens are identified.
end(chunk?: string)	Signals the end of the document. Flushes remaining data and closes open tags.
parseComplete(data: string)	Resets the parser and parses the entire string in one operation.
pause()	Halts the tokenizer; no further events will be emitted until resumed.
resume()	Resumes processing from the point where it was paused.
reset()	Clears the internal state, stack, and buffers, preparing for a new document.

Sources: src/Parser.ts:608-683

Parser Configuration (ParserOptions)

The Parser constructor accepts an options object to toggle specific behaviors:

Option	Type	Default	Description
xmlMode	boolean	false	Enables XML-specific rules for entities, CDATA, and self-closing tags.
decodeEntities	boolean	true	Decodes HTML entities (e.g., & to &).
lowerCaseTags	boolean	!xmlMode	Automatically lowercases all tag names.
lowerCaseAttributeNames	boolean	!xmlMode	Automatically lowercases all attribute names.
recognizeSelfClosing	boolean	xmlMode	Allows tags to be closed with /> in HTML mode.

Sources: src/Parser.ts:182-225, README.md:120-135

Event Handlers

Users interact with the parser by providing a Handler object. All methods in the handler are optional.

Event Definitions

• onopentag(name, attribs, isImplied): Fired when a tag is fully opened. The attribs object contains all parsed attributes.
• ontext(data): Fired for text content. Note: This can fire multiple times for a single text node depending on buffering and entity decoding.
• onclosetag(name, isImplied): Fired when a tag is closed. In HTML mode, isImplied is true if the parser closed the tag based on structural rules (e.g., a <li> closing a previous <li>).
• onprocessinginstruction(name, data): Fired for constructs like <?xml ...?> or <!DOCTYPE ...>.

Sources: src/Parser.ts:227-268, README.md:95-115

Streaming Support

The library provides two specific wrappers for different streaming environments, ensuring compatibility with native stream APIs while maintaining the high-performance parsing logic.

Node.js Writable Streams

The WritableStream class extends node:stream.Writable. It handles Buffer to string decoding internally using StringDecoder.
Sources: src/WritableStream.ts:16-43

Web Streams API

The WebWritableStream class implements the standard WritableStream interface (part of the Web Streams API), allowing for direct integration with fetch() responses using .pipeTo().
Sources: src/WebWritableStream.ts:23-48

import { WebWritableStream } from "htmlparser2/WebWritableStream";

const stream = new WebWritableStream({
    onopentag(name) {
        console.log("Found tag:", name);
    },
});

const response = await fetch("https://example.com");
await response.body.pipeTo(stream);

Sources: src/WebWritableStream.ts:7-21

HTML-Specific Logic

In HTML mode (xmlMode: false), the Parser applies several specialized rules derived from the HTML specification:

1. Implicit Closing: Certain tags automatically close others. For example, a <tr> will close an open <tr>, <th>, or <td>.
2. Void Elements: Tags like <img>, <br>, and <input> are recognized as self-closing and do not expect a closing tag.
3. Foreign Contexts: The parser tracks when it enters <svg> or <math> namespaces, switching to specific casing rules (e.g., adjusting viewbox to viewBox).
4. Special Tags: The contents of <script>, <style>, and <title> are treated as raw text or RCDATA, meaning internal markup is ignored until the corresponding end tag is found.

Sources: src/Parser.ts:10-142, src/Parser.ts:413-440, src/Tokenizer.ts:509-548

The Basic Parsing API offers a low-level, high-speed foundation for HTML/XML processing, prioritizing performance and flexibility through its event-driven architecture and streaming support.