node-html-parser

node-html-parser (published to npm as node-html-parser, developed under the taoqf/node-fast-html-parser repository) is a lightweight, high-performance HTML parser for Node.js and the browser. It parses raw HTML strings into a simplified DOM tree of HTMLElement, TextNode, and CommentNode instances, exposing a browser-like API — querySelector, querySelectorAll, closest, classList, innerHTML, and more — without needing a real DOM or headless browser.

Speed is the explicit design priority: the README ships its own benchmark suite comparing throughput against parse5, htmlparser2, cheerio, html5parser, and half a dozen other parsers. To get there it favors permissive parsing over strict HTML5-spec compliance — malformed markup such as unclosed tags or HTML4-style unclosed <td> elements is tolerated rather than rejected, which suits scraping and text-extraction workloads more than a spec-conformant renderer.

What You Get

• A DOM-like tree of HTMLElement, TextNode, and CommentNode objects with parentNode/childNodes, classList, and attribute accessors mirroring the browser DOM API.
• Full CSS3 selector support (querySelector, querySelectorAll, matches, closest, getElementsByTagName) powered by css-select through a custom adapter.
• DOM mutation helpers — appendChild, insertAdjacentHTML, replaceWith, setAttribute(s), removeAttribute, before/after/prepend/append — for editing markup in place.
• Configurable parse options (lowerCaseTagName, comment retention, void-tag lists, blockTextElements, nested-tag fixups) to trade strictness for speed depending on the input.
• Dual ESM/CJS builds with bundled TypeScript type definitions, published for both import and require consumers.

Common Use Cases

• Web scraping and crawler pipelines that need to extract text or links from HTML without booting a headless browser.
• Server-side rendering and static-site pipelines that post-process or rewrite generated HTML fragments.
• Data-extraction jobs (price/product scraping, RSS or feed HTML cleanup) that must handle large volumes of imperfect, real-world markup quickly.
• Test suites and build tooling that need to assert on or transform HTML output without a browser environment.

Under The Hood

Architecture

The public entry point (src/index.ts) exports a parse function and attaches the library’s other exports (HTMLElement, CommentNode, valid, Node, TextNode, NodeType) directly onto that function so both import { parse } and legacy require() consumers get the same surface; src/parse.ts is a one-line re-export of the parser from src/nodes/html.ts. The bulk of the logic lives in src/nodes/html.ts, a large hand-rolled state-machine-style tokenizer/builder that constructs the DOM tree directly rather than going through a separate lexer/AST stage. src/matcher.ts defines a local Adapter implementation (isTag, getChildren, getParent, existsOne, findAll, findOne, removeSubsets, etc.) matching css-select’s expected interface, which is the seam connecting the internal tree to css-select’s selectAll/selectOne/is functions that power querySelector and friends. Node types form a simple inheritance hierarchy off an abstract src/nodes/node.ts base, with src/nodes/text.ts and src/nodes/comment.ts as thin siblings to html.ts; src/void-tag.ts and src/back.ts are small focused helpers. It’s a flat, single-package architecture with no plugin system — clear node-type separation, but html.ts itself is dense, carrying both parsing and most of the public DOM API.

Tech Stack

Written in TypeScript and built with tsdown (esbuild-based) plus tsc --emitDeclarationOnly, producing a dual ESM/CJS distribution wired through package.json’s exports map. Runtime dependencies are minimal and deliberate: css-select (^5.1.0) for CSS selector matching and entities (^8.0.0) for HTML entity decode/encode. The project uses Bun as its primary tooling (declared packageManager, used for install/build/test scripts) alongside mocha, should, spec, and blanket for testing and ts-node for running tests directly against source. A test/benchmark harness pits the library against parse5, htmlparser2, cheerio, html5parser, htmljs-parser, and others. GitHub Actions runs a build/test matrix across Node 22, 24, and 26 on every push and PR, with a separate tag-triggered workflow for npm publishing.

Code Quality

test/tests/ contains dozens of focused test files covering the DOM API (clone, replaceWith, node-ranges, textcontent-encode, quoteattributes, unclosedtags, incomplete-blocktext) plus a dedicated test/tests/issues/ directory of regression tests tied to specific GitHub issues — a defensive, issue-driven suite rather than a purely feature-driven one. Both test:src (ts-node against source) and test:dist (compiled output) targets run in CI, catching build-artifact drift. The codebase is fully TypeScript with explicit interfaces (Options, Attributes, RawAttributes, KeyAttributes, and a locally redefined css-select Adapter type since css-select v5 doesn’t publicly export one), though some internal casts and non-null assumptions trade a bit of strictness for terseness. ESLint (typescript-eslint) and Prettier configs are present and enforced.

What Makes It Unique

The library’s stated differentiator is raw parsing speed — the README carries its own comparative benchmark against nine-plus competing HTML parsers and is explicitly tuned to stay near the front of that pack rather than targeting full HTML5-spec conformance; malformed markup is tolerated by design instead of rejected. It also goes further than most lightweight parsers toward genuine DOM ergonomics: a real DOMTokenList-style classList with validation, structure/structuredText tree-inspection helpers, node ranges, and insertAdjacentHTML, aiming to feel like document.querySelector in Node rather than a plain object tree. The core ideas (DOM-like tree, CSS selector queries) are well precedented by libraries like cheerio, so the differentiation is the speed/ergonomics tradeoff rather than a novel parsing technique.