Skip to content

feat(node): Node.js got only WebAssembly, slower and main-thread only - #218

Open
jamesconwaydev wants to merge 2 commits into
mainfrom
bindings-node
Open

jamesconwaydev wants to merge 2 commits into
mainfrom
bindings-node

Conversation

@jamesconwaydev

@jamesconwaydev jamesconwaydev commented Nov 22, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #177.

Problem. In Node, parsec-html is WebAssembly only. That costs speed: on the 13 pages in bench/ (24 MB), the WebAssembly parses 165 MB a second where a build for the machine does 249. And every parse blocks the main thread, so a server that parses the 15.8 MB HTML spec stops answering for 100 ms or so.

Change.

  • bindings/node: Parsec with napi-rs (napi 3.16.2, napi-derive 3.7.1, napi-build 2.6.0, pinned, in this crate only). src/lib.rs mirrors bindings/wasm/src/lib.rs: the same functions, classes, getters, options (maxSteps, maxDepth, transportEncoding...) and error messages, and missing values are undefined as wasm-bindgen gives, not Node-API's null. units.rs is the WebAssembly's, shared by path. It's its own workspace and publish = false, as bindings/wasm is, so cargo test --workspace and scripts/package-twice.sh leave it out.
  • parseAsync(html, options) parses on the libuv thread pool and resolves to the document. With the WebAssembly build it parses before returning, since that has no threads.
  • bindings/wasm/npm/index.cjs (with index.mjs and index.d.ts) is what Node now loads: the platform's package when npm installed it, the WebAssembly otherwise. backend says which loaded; PARSEC_BACKEND=wasm or native forces one. Browsers and bundlers get the same files as before. On the native build, free() and Symbol.dispose are no-ops, so code written with using keeps working.
  • Names live in one place: napi.packageName in bindings/wasm/npm/package.json. Platform packages are @parsec-web/binding-<platform>, the napi-rs convention (${packageName}-${platform}, as @oxc-parser/binding-* and @rspack/binding-* do); a bare @parsec-web/linux-x64-gnu would need a loader napi-rs doesn't use. The Publish as parsec-web from 0.3.0 #213 rename to parsec-web changes only the main package's name: the scope matches the GitHub org, which stays.
  • bindings/node/npm.mjs writes a platform's package.json (with os, cpu, libc) and, at release, the main package's optionalDependencies.
  • node.yml: lint (fmt, clippy -D warnings, cargo-deny), then eight native builds, each on its own runner, with the package's tests run against the native build and then the WebAssembly fallback. musl builds and tests run in Alpine (rust:1.99.1-alpine3.24, pinned by digest). Each platform's package is uploaded as an artifact node-<platform>. Actions are pinned by SHA.
  • release-npm.yml calls node.yml, and on a v* tag publishes the eight platform packages and then parsec-html, by trusted publishing with provenance, after release.yml's release exists, as before. ci(release): a release could ship with fewer conformance cases passing #212's gates job isn't on main yet; once it lands, publish should wait on it too.
  • Docs: bindings/node/README.md, a pointer in the WebAssembly README, a README row (marked as coming in the next release), CHANGELOG.

Bench. node bindings/node/bench.mjs, Node 22.14, Apple M2 Max, median of 30 parses of the string, MB/s:

Page MB Native WebAssembly Native / WebAssembly
bbc-news 0.40 624 379 1.65
ebay 0.53 495 366 1.35
github-rust 0.33 389 239 1.63
hacker-news 0.04 221 128 1.72
mdn-html 0.19 347 222 1.57
nytimes 1.57 639 498 1.28
python-stdtypes 0.77 213 112 1.90
reddit-programming 0.58 607 380 1.60
stackoverflow 1.16 381 243 1.57
whatwg-full 15.78 211 141 1.50
whatwg-parsing 0.83 242 166 1.46
wikipedia-html 0.81 317 212 1.49
wikipedia-population 1.39 385 257 1.50
all pages 24.36 249 165 1.51

Both take a JavaScript string and pay to make it UTF-8: on whatwg-full, Buffer.from(html) alone is 12 of the 69 ms.

Tests. bindings/wasm/tests/package.test.mjs is the one suite, run against each build with the same expectations. 17 tests; the new ones:

  • the build asked for is the one that loaded: fails if PARSEC_BACKEND=native got the WebAssembly.
  • parseAsync gives what parse gives, off the main thread when native: on a 5.4 MB page, counts event-loop turns while it parses (2,901 here); a parse on the main thread gives 0 and fails it. Also checks UTF-16 spans through parseAsync.
  • free and Symbol.dispose are there on either build: fails without the loader's no-ops.
  • parseBytes takes an array of numbers and a Buffer (the WebAssembly did; the first native draft didn't).
  • The types test checks index.d.ts declares parseAsync.

Locally: the suite passes 17/17 with PARSEC_BACKEND=native and with wasm; cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace, scripts/check-headers.sh and scripts/package-twice.sh pass; in bindings/node, fmt, clippy -D warnings and cargo deny check licenses bans sources pass.

Before the first release with this (npm, on your account). The @parsec-web scope (named for the 0.3.0 rename, #213, so there's only one to create) doesn't exist on npm yet (the registry has no @parsec-web organization), and trusted publishing can only be set on a package that exists:

  1. On npmjs.com, your avatar > Add Organization, name parsec-web, the free plan (public packages).
  2. Publish the eight placeholders I've prepared, 0.0.0 each:
    npm login
    for d in ~/Documents/GitHub/parsec-reserve/npm-binding/*; do (cd "$d" && npm publish --access public); done
  3. On each of the eight packages, Settings > Trusted Publisher > GitHub Actions: organization parsec-html, repository parsec, workflow release-npm.yml, environment release. Then, as on parsec-html, set publishing access to require two-factor and disallow tokens.

Add bindings/node, a napi-rs build of the npm package's API, and make
the package load it in Node when the platform's optional dependency is
installed, falling back to the WebAssembly otherwise.

- bindings/node/src/lib.rs mirrors bindings/wasm/src/lib.rs: the same
  names, options and error messages, plus parseAsync on the libuv pool.
- bindings/wasm/npm/index.cjs picks the build; PARSEC_BACKEND forces one.
- node.yml builds and tests eight platforms (glibc and musl Linux, macOS
  and Windows, x86-64 and ARM64), running the package's tests against
  both builds; release-npm.yml publishes the platform packages first.
@jamesconwaydev jamesconwaydev added wasm WebAssembly and npm platform Parsec as a toolkit: crates, positioning, how the pieces fit labels Nov 22, 2026
…0.3.0

The platform packages first ship in 0.3.0, the release that renames the
packages to parsec-web (#213). Naming them @parsec-web/binding-* from the
start means one npm organization to create, not one now and another for
the rename.
Comment thread bindings/node/src/lib.rs
/// Where something was written, as the WebAssembly build's `Span` has it.
#[napi]
#[derive(Clone, Copy)]
pub struct Span {
Comment thread bindings/node/src/lib.rs

/// A parse error the parser recovered from.
#[napi]
pub struct ParseError {
Comment thread bindings/node/src/lib.rs

/// A parsed document or fragment.
#[napi]
pub struct Document {
Comment thread bindings/node/src/lib.rs

/// A node in a [`Document`].
#[napi]
pub struct Node {
Comment thread bindings/node/src/lib.rs

/// Parses a document given as bytes a piece at a time.
#[napi]
pub struct ByteParser {
@jamesconwaydev

Copy link
Copy Markdown
Collaborator Author

CodeQL's five "access of invalid pointer" alerts are all on #[napi] structs (Span, ParseError, Document, Node, ByteParser, at bindings/node/src/lib.rs lines 88, 101, 152, 158 and 300). It's reading the FFI glue napi-rs's macro generates; bindings/node/src has no unsafe of its own. I'll dismiss them as false positives once this merges, when they exist as alerts on main. All eight native jobs pass.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

platform Parsec as a toolkit: crates, positioning, how the pieces fit wasm WebAssembly and npm

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A native Node.js package

2 participants