// Cleans up and refactors a Node.js-compatible built-in module for improved code quality. Use when asked to clean up, simplify, refactor, or improve the coding style of an existing built-in module (e.g., node:buffer, node:path, node:crypto).
Guides development workflow for the embedded skeleton crate. Use when modifying files under crates/wasm-rquickjs/skeleton/, working on JavaScript runtime APIs, or troubleshooting skeleton build issues.
Scaffolds and registers a new Node.js-compatible built-in module in the skeleton. Use when asked to add a new node:X module, implement a new built-in, or create a new native+JS module pair.
Runs build, clippy, formatting, and lint checks across all targets before a PR. Use when asked to finalize, prepare, or clean up before submitting a pull request.
Tests a 3rd-party npm library against the wasm-rquickjs runtime. Use when asked to test an npm package, check library compatibility, or pick the next untested library from the tracker.
Fixes failing Node.js compatibility tests in the node_compat suite. Use when asked to make a node_compat test pass, unskip a test, fix a test-crypto/test-path/test-* failure, or implement missing Node.js API behavior to satisfy a vendored test.
Regenerates DTS goldenfiles after d.ts generation logic changes. Use when dts tests fail due to expected output changes, when asked to update goldenfiles, or after modifying the d.ts generator.
| name | cleaning-up-builtin-module |
| description | Cleans up and refactors a Node.js-compatible built-in module for improved code quality. Use when asked to clean up, simplify, refactor, or improve the coding style of an existing built-in module (e.g., node:buffer, node:path, node:crypto). |
Step-by-step workflow for analysing, simplifying, and refactoring an existing built-in module while preserving all test coverage.
Each built-in module consists of up to three parts:
crates/wasm-rquickjs/skeleton/src/builtin/<name>.rscrates/wasm-rquickjs/skeleton/src/builtin/<name>.jscrates/wasm-rquickjs/skeleton/src/builtin/internal/ that the module importsThe goal is to improve code quality — simplification, dead code removal, clearer naming, better structure, modern JS patterns — without changing observable behavior. The cleanup is best-effort — apply everything that passes tests. You may run the cleanup on the same module multiple times.
Important: Some files in builtin/ are vendored third-party libraries (e.g., ieee754.js, base64.js, fetch-blob-4.0.0.js, formdata-polyfill-4.0.10.js, web-streams-polyfill-4.1.0.js). NEVER clean up or modify vendored third-party JS files — only clean up our own wrappers and native bridges.
Some modules are JS-only — their .rs file contains only include_str!, re-export constants, and no native bridge. This is fine. If the cleanup reveals that moving logic to a Rust native bridge would improve the module, you may convert a JS-only module to a Rust+JS pair by creating the native bridge following the patterns in the adding-builtin-module skill.
Determine which module to clean up (e.g., buffer). Locate all its files:
crates/wasm-rquickjs/skeleton/src/builtin/<name>.rscrates/wasm-rquickjs/skeleton/src/builtin/<name>.jscrates/wasm-rquickjs/skeleton/src/builtin/mod.rs — look for the module's entries in add_module_resolvers, module_loader, and wire_builtins__wasm_rquickjs_builtin/internal/* paths and read those files too — these are in scope for cleanup if improvements are found, but must be validated carefully since they are shared across modules (run tests for all modules that import the changed helper)tests/runtime/<name>.rs — our own functional teststests/node_compat/config.jsonc for entries matching the module name (e.g., test-buffer-*, test-path-*)examples/runtime/ for an example that exercises this moduleBefore making any changes, verify all relevant tests pass:
# 1. Clean skeleton build artifacts (MANDATORY)
./cleanup-skeleton.sh
# 2. Run our runtime tests for this module
cargo test --test runtime <name> -- --nocapture 2>&1 | tee /tmp/cleanup-baseline-runtime.txt
# 3. Run node_compat tests for this module
cargo test --test node_compat parallel__test_<name> -- --nocapture 2>&1 | tee /tmp/cleanup-baseline-compat.txt
Save the baseline output. All tests must pass before proceeding. If any tests are already failing, note them and exclude them from your pass/fail tracking.
Use the librarian to read the corresponding module's implementation in the official Node.js repository (github.com/nodejs/node, branch v22.x, under lib/). This matches the v22.14.0 version our node_compat tests are vendored from. For example:
node:buffer → lib/buffer.js (and possibly lib/internal/buffer.js)node:path → lib/path.jsnode:crypto → lib/crypto.js + lib/internal/crypto/node:stream → lib/stream.js + lib/internal/streams/node:url → lib/url.js + lib/internal/url.jsnode:util → lib/util.js + lib/internal/util/node:events → lib/events.jsAsk the librarian to explain the module's structure, key design patterns, and how specific functions are implemented.
Compare the upstream implementation against our JS wrapper. Look for:
??, ?.) that we could adopt to reduce verbosity?Important: Only adopt upstream patterns when they lead to simpler, cleaner code in our context. Do NOT blindly copy Node.js internals — our environment (QuickJS + WASM) has different constraints. Specifically:
lib/internal/) that we may not needNote which upstream patterns are worth adopting and include them in the list of candidate improvements for Step 4.
Read the full Rust and JS source files. Then consult the oracle for a thorough code review, providing the upstream Node.js insights from Step 3 as additional context. Ask the oracle to identify:
typeof SharedArrayBuffer !== 'undefined' guards when we always have it)const/let, old-style var usage, unnecessary this binding patternsclone(), better error handling patternsWIRE_JS snippet can be moved into the JS wrapper module itself, leaving WIRE_JS as a minimal import-and-assign-to-globalThis (see "Minimizing WIRE_JS" below)Important constraints to tell the oracle:
Review the oracle's suggestions and classify each as:
This step applies to EVERY module, not just HTTP-related ones. Before applying any other improvements, scan the module for test-cheating code (see "Detecting Test-Cheating Workarounds" below). This is a separate, mandatory step — not just an item on the oracle's checklist — because cheating code must be removed regardless of risk category.
"Test-cheating" means any code whose primary purpose is making vendored node_compat tests pass rather than providing genuine functionality to real users. This can appear in any module — buffer, crypto, path, util, stream, etc. — not just networking modules.
"skip": true in config.jsonc with an explicit "reason" explaining the platform limitation (e.g., "reason": "QuickJS does not support this V8-specific behavior")
e. Never re-introduce the cheat — a skipped test with a clear reason is always preferable to faked behaviorThis step takes priority over all other cleanup work. Cheating code is a correctness issue, not a style issue.
Apply changes one category at a time, starting with the safest:
./cleanup-skeleton.sh
cargo test --test runtime <name> -- --nocapture 2>&1 | tee /tmp/cleanup-step-N.txt
cargo test --test node_compat parallel__test_<name> -- --nocapture 2>&1 | tee /tmp/cleanup-compat-step-N.txt
Group related safe changes (e.g., all dead code removals) into a single batch if they don't interact. But keep distinct logical changes separate so failures can be isolated.
After all improvements are applied:
cargo fmt
cargo clippy -- -Dwarnings
Fix any issues introduced by the changes.
Run tests for other modules that might be affected. Choose modules that:
buffer, also test string_decoder, fs, crypto, stream)# Run a selection of related module tests
./cleanup-skeleton.sh
cargo test --test runtime <related_module_1> -- --nocapture 2>&1 | tee /tmp/cleanup-regression-1.txt
cargo test --test runtime <related_module_2> -- --nocapture 2>&1 | tee /tmp/cleanup-regression-2.txt
# Run some related node_compat tests
cargo test --test node_compat parallel__test_<related> -- --nocapture 2>&1 | tee /tmp/cleanup-regression-compat.txt
Common cross-module dependencies to check:
| Module cleaned | Also test |
|---|---|
buffer | string_decoder, crypto, fs, stream, encoding |
stream | fs, http, crypto, zlib |
path | fs, url, module |
crypto / web-crypto | buffer, stream, https, tls |
events | stream, http, fs, process |
url | path, http, https, querystring |
util | nearly everything — test broadly |
encoding | buffer, string_decoder, fs |
If cross-module tests fail:
If you cannot isolate the cause:
Run the full set of tests one more time to confirm the final state is clean:
./cleanup-skeleton.sh
cargo test --test runtime <name> -- --nocapture 2>&1 | tee /tmp/cleanup-final-runtime.txt
cargo test --test node_compat parallel__test_<name> -- --nocapture 2>&1 | tee /tmp/cleanup-final-compat.txt
cargo fmt -- --check
cargo clippy -- -Dwarnings
The skeleton is always compiled to wasm32-wasip1. Never write conditional code that checks for unix/windows/macOS or any other host platform (e.g., #[cfg(unix)], #[cfg(windows)], #[cfg(target_os = "...")], process.platform === "win32", path.sep === "\\", etc.). Such checks are meaningless in the WASM target and add dead code complexity. If existing code has these, remove them as part of cleanup.
Our environment is QuickJS compiled to WASM — we always have Uint8Array, ArrayBuffer, Symbol, typed array support, etc. Guards like typeof Uint8Array !== 'undefined' or Buffer.TYPED_ARRAY_SUPPORT checks can often be simplified.
var with const/letUse const by default, let only when reassignment is needed. Never use var.
If the codebase uses function constructors with prototype assignments that could be expressed more clearly with classes or simpler patterns, consider it — but only if the prototype chain behavior is preserved.
.clone()Check for clones that can be replaced with references or moves.
? operatorReplace match result { Ok(v) => v, Err(e) => return Err(e) } with result?.
If an internal function or import is not used anywhere, remove it. But never remove public exports from the module's API surface.
WIRE_JS snippets run at module load time and wire things onto globalThis. They are embedded as Rust string literals in the .rs file, making them hard to read, edit, and review. The goal is to keep WIRE_JS as small as possible — ideally just an import and a globalThis assignment:
import { default as __x } from '__wasm_rquickjs_builtin/mymodule';
globalThis.myGlobal = __x;
How to minimize:
.js file. WIRE_JS should not define functions — those belong in the importable module..js file's default export. If WIRE_JS builds an object by iterating over exports, wrapping methods, or adding properties, do that work inside the .js module and export the finished object as default..js file. Getters that reference globalThis.process or other globals work fine in the .js module because they resolve at access time, not definition time.Constraints:
globalThis object must have the exact same property descriptors (enumerable, configurable, writable), method .name values, and prototype chain as before..js file and must stay in WIRE_JS.This section applies to ALL modules, not just HTTP. Verify that the module implementation does not cheat to pass vendored node_compat tests. "Cheating" means any code whose sole purpose is making test cases pass, with no actual value for real users. These workarounds produce asymmetric behavior — tests see one code path while real-world usage hits a different, inferior one.
The core question to ask about any suspicious code: "Would this code path ever execute for a real user, or does it only exist because a vendored test expects it?" If the answer is the latter, it's cheating.
General red flags to look for in ANY module:
0, return true, return empty string) instead of being properly unimplemented — making tests pass while real callers get silently wrong resultsgetCiphers() just returns a static list but the cipher doesn't actually work)globalThis.__wasm_rquickjs_*) used to pass data between components in a way that only works in the test environment (same-process) but not in real deploymentsprocess.getuid() by returning 0, pretending to support signals, faking file descriptors)HTTP-specific red flags (for node:http, node:https, and related modules):
localhost, 127.0.0.1, or ::1 and takes a special path (e.g., bypassing wasi:http with a direct socket connection)What to do when you find cheating code:
config.jsonc with an explicit reason (e.g., "reason": "QuickJS does not support this V8-specific behavior", "reason": "wasi:http does not expose status messages", "reason": "WASI does not provide OS user/group APIs")As part of the cleanup you may move logic between the native Rust bridge and the JS wrapper. This is a tradeoff between runtime performance and simplicity of expressing idiomatic JS patterns.
Moving from JS → Rust (prefer when):
this binding)Moving from Rust → JS (prefer when):
rquickjs bindings to express something trivial in JS (e.g., building complex objects, working with JS classes/prototypes, variadic arguments)code, message, and name properties — this is far more natural in JS using the shared error constructors from __wasm_rquickjs_builtin/internal/errorsGuidelines for boundary shifts:
#[rquickjs::module] block and update the JS import statement. Remember: JS must import using original Rust snake_case names, not renamed versionsu32 values may arrive in JS as signed — apply >>> 0 if neededWIRE_JS snippets should be kept as minimal as possible — they run at module load time and wire things to globalThis. If you can reduce or simplify a WIRE_JS snippet during cleanup, do so. But changes to WIRE_JS affect global state and can break any module — treat them as high-risk and test broadly after any changetests/node_compat/suite/./cleanup-skeleton.sh before any test runcargo test without a filter — always scope to the relevant modulebuiltin/ (e.g., ieee754.js, base64.js, fetch-blob-*.js, formdata-polyfill-*.js, web-streams-polyfill-*.js)