@ismail-elkorchi/html-parser

A standards-oriented HTML parser with explicit resource limits, structural queries, source-aware edits, and bounded text extraction.

This repository documents current development. Published packages are available from npm and JSR; use the README and TypeScript declarations shipped with the version you install. The project is pre-1.0, so minor releases may contain intentional breaking changes.

Use it when

• you need an immutable, namespace-aware HTML tree rather than a browser DOM;
• input can be untrusted and work must be constrained by explicit budgets;
• you need deterministic traversal, serialization, text extraction, or source-preserving edits across Node.js, Deno, Bun, and browsers.

It does not execute scripts, compute layout or accessibility trees, or sanitize HTML. Sanitize separately before rendering parser output.

Install

npm install @ismail-elkorchi/html-parser

deno add jsr:@ismail-elkorchi/html-parser

Quick start

import {
  findAllByTagName,
  parse
} from "@ismail-elkorchi/html-parser";

const document = parse("<main><h1>Hello</h1><p>World</p></main>");
const [heading] = findAllByTagName(document.tree, "h1");

console.log(document.tree.kind); // "document"
console.log(heading?.localName); // "h1"
console.log(document.tree.errors); // non-fatal HTML parse diagnostics

Document and fragment parsers accept scriptingMode: "disabled" when the source environment has scripting disabled. For untrusted input, combine the structural limits with deterministic budgets.maxSteps and a deadline or abort signal.

Full-document entry points return a ParsedDocument:

ParsedDocument
├── tree        immutable document tree and non-fatal parse errors
├── sourceText  decoded input when source retention was requested
└── metadata    input, encoding, and observed resource usage

parseFragment() returns a ParsedFragment with the immutable tree and the same successful resource evidence available for document parsing. It requires an explicit namespace-aware context:

import { HTML_NAMESPACE_URI, parseFragment } from "@ismail-elkorchi/html-parser";

const { tree: rows, metadata } = parseFragment("<tr><td>A<td>B", {
  namespaceUri: HTML_NAMESPACE_URI,
  localName: "tbody"
}, {
  budgets: { maxSteps: 10_000 }
});

console.log(rows.kind, metadata.resourceUsage.steps);

Find what you need

• Get started
• Parse documents, bytes, and fragments
• Read streams and handle encodings
• Query trees and extract text
• Modify source HTML safely
• Set limits and handle errors
• Understand the data model
• Browse API groups
• Run complete examples

The documentation index also points maintainers to the architecture, testing, corpus, and source-policy notes.

Runtime support

The npm surface supports Node.js 20, 22, and 24. Linux, macOS, and Windows run the cross-runtime contract in CI; Deno, Bun, and evergreen browsers are also covered by smoke tests. npm/Node and JSR expose the same runtime and TypeScript API, documented in the API guide.

Safety

All limits are opt-in: no parser budget is enabled by default. For untrusted input, set limits appropriate to the containing request, pass an AbortSignal, and classify operational failures with the exported structural error guards. See limits, errors, and safety.

Dependencies and implementation

No external runtime packages are installed: the npm dependencies field is empty and JSR imports only repository-owned modules. The parser is an independent standards-based TypeScript implementation; generated character reference data is reproducible from the pinned WHATWG snapshot. Provenance and implementation-source rules are recorded in the source policy and THIRD_PARTY_NOTICES.md.

Support and contributing

Use SUPPORT.md for usage questions and bug reports. Start code contributions with the repository's contribution guide. Report vulnerabilities through the private channel in SECURITY.md.

License

MIT