Repository navigation
feat(node): Node.js got only WebAssembly, slower and main-thread only - #218
Open
jamesconwaydev wants to merge 2 commits into
Open
jamesconwaydev wants to merge 2 commits into
jamesconwaydev wants to merge 2 commits into
Conversation
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
enabled auto-merge
November 22, 2026 04:08
…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.
| /// Where something was written, as the WebAssembly build's `Span` has it. | ||
| #[napi] | ||
| #[derive(Clone, Copy)] | ||
| pub struct Span { |
|
|
||
| /// A parse error the parser recovered from. | ||
| #[napi] | ||
| pub struct ParseError { |
|
|
||
| /// A parsed document or fragment. | ||
| #[napi] | ||
| pub struct Document { |
|
|
||
| /// A node in a [`Document`]. | ||
| #[napi] | ||
| pub struct Node { |
|
|
||
| /// Parses a document given as bytes a piece at a time. | ||
| #[napi] | ||
| pub struct ByteParser { |
Collaborator
Author
|
CodeQL's five "access of invalid pointer" alerts are all on |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #177.
Problem. In Node,
parsec-htmlis WebAssembly only. That costs speed: on the 13 pages inbench/(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 (napi3.16.2,napi-derive3.7.1,napi-build2.6.0, pinned, in this crate only).src/lib.rsmirrorsbindings/wasm/src/lib.rs: the same functions, classes, getters, options (maxSteps,maxDepth,transportEncoding...) and error messages, and missing values areundefinedas wasm-bindgen gives, not Node-API'snull.units.rsis the WebAssembly's, shared by path. It's its own workspace andpublish = false, asbindings/wasmis, socargo test --workspaceandscripts/package-twice.shleave 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(withindex.mjsandindex.d.ts) is what Node now loads: the platform's package when npm installed it, the WebAssembly otherwise.backendsays which loaded;PARSEC_BACKEND=wasmornativeforces one. Browsers and bundlers get the same files as before. On the native build,free()andSymbol.disposeare no-ops, so code written withusingkeeps working.napi.packageNameinbindings/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-gnuwould need a loader napi-rs doesn't use. The Publish as parsec-web from 0.3.0 #213 rename toparsec-webchanges only the main package's name: the scope matches the GitHub org, which stays.bindings/node/npm.mjswrites a platform'spackage.json(withos,cpu,libc) and, at release, the main package'soptionalDependencies.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 artifactnode-<platform>. Actions are pinned by SHA.release-npm.ymlcallsnode.yml, and on av*tag publishes the eight platform packages and thenparsec-html, by trusted publishing with provenance, afterrelease.yml's release exists, as before. ci(release): a release could ship with fewer conformance cases passing #212'sgatesjob isn't onmainyet; once it lands,publishshould wait on it too.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: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.mjsis 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 ifPARSEC_BACKEND=nativegot 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 throughparseAsync.free and Symbol.dispose are there on either build: fails without the loader's no-ops.parseBytestakes an array of numbers and aBuffer(the WebAssembly did; the first native draft didn't).index.d.tsdeclaresparseAsync.Locally: the suite passes 17/17 with
PARSEC_BACKEND=nativeand withwasm;cargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace,scripts/check-headers.shandscripts/package-twice.shpass; inbindings/node, fmt, clippy-D warningsandcargo deny check licenses bans sourcespass.Before the first release with this (npm, on your account). The
@parsec-webscope (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-weborganization), and trusted publishing can only be set on a package that exists:parsec-web, the free plan (public packages).0.0.0each:parsec-html, repositoryparsec, workflowrelease-npm.yml, environmentrelease. Then, as onparsec-html, set publishing access to require two-factor and disallow tokens.