node-js 0.1.16

JavaScript as a fusevm frontend: a lexer/parser and compiler to fusevm::Chunk on a JsHost object heap, with no bespoke VM or JIT
Documentation
███╗   ██╗ ██████╗ ██████╗ ███████╗         ██╗███████╗
████╗  ██║██╔═══██╗██╔══██╗██╔════╝         ██║██╔════╝
██╔██╗ ██║██║   ██║██║  ██║█████╗█████╗     ██║███████╗
██║╚██╗██║██║   ██║██║  ██║██╔══╝╚════╝██   ██║╚════██║
██║ ╚████║╚██████╔╝██████╔╝███████╗    ╚█████╔╝███████║
╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚══════╝     ╚════╝ ╚══════╝

Rust Docs Built on status license

[JAVASCRIPT, COMPILED TO BYTECODE — ON A SHARED CRANELIFT JIT]

"V8 compiles JavaScript to its own bytecode and JITs it with its own engine. node-js lowers JavaScript to a shared machine that other languages already run on, and lets one Cranelift JIT compile the hot loops."

node-js is JavaScript as a fusevm frontend — a lexer/parser and compiler that lowers JavaScript to fusevm::Chunk bytecode running on fusevm's bytecode VM + Cranelift JIT, over a JsHost object heap. There is no bespoke interpreter loop: node-js is a pure front end; execution and codegen live in fusevm — the same engine every other fusevm frontend runs on.

The binary is node.

Read the Docs · Engineering Report · Builtin Reference · fusevm


Table of Contents


[0x00] OVERVIEW

node-js keeps JavaScript the language and throws away V8's execution model. It lexes and parses JavaScript to an AST, lowers the AST to fusevm bytecode, and runs it on the shared bytecode VM with a Cranelift JIT. Arithmetic and comparisons lower to native ops so the JIT can trace hot loops; JS-specific behavior — truthiness, == coercion, + overloading, ToInt32 bitwise wrap, number formatting, the builtin objects — is served by the JsHost object heap through fusevm's builtin dispatch and a strict numeric hook.

It carries no VM or JIT of its own. Bug fixes and JIT improvements in fusevm land once and benefit every hosted frontend at the same time.

[0x01] PIPELINE

source ──▶ lexer ──▶ parser ──▶ compiler ──▶ fusevm::Chunk ──▶ fusevm VM + JIT
              │         │           │                                  │
          tokens     JS AST    lower to bytecode              callbacks into JsHost
        (+ template  (funcs,   (native ops + CallBuiltin)     (builtins + numeric hook)
         re-lex)     arrows,
                     try/catch)
  • Primitives (number, boolean, null, undefined) ride through the VM as native fusevm::Values.
  • Objects, strings, and arrays are heap objects in JsHost; they travel as Value::Obj(u32) handles into that heap, and property insertion order is preserved (observable in iteration and JSON round-trips).
  • Locals that no other chunk can reach are addressed as fusevm frame slots (Op::GetSlot/SetSlot) instead of being looked up by name in the scope chain — see src/slots.rs for the rules that decide which ones qualify. A name a nested function, a try block or a direct eval can reach stays a real binding, because those run as their own chunks and resolve through the environment.
  • Loops are lowered rotated — the test emitted once as an entry guard and once at the bottom as a conditional backward branch, which is the shape fusevm's tracing JIT needs to close a trace. for (;;), having no test to branch on, closes with a constant-true conditional branch for the same reason: the trace compiler declines an unconditional Jump close. node --tiers reports which loops reached native code.
  • Arithmetic lowers to native fusevm ops so the JIT can trace hot loops; a strict numeric hook supplies JS coercion for the non-numeric operand cases (+ string concat, == matrix, ToInt32 for bitwise ops). An object operand goes through a real ToPrimitive first — which calls the user's Symbol.toPrimitive/valueOf/toString, so it runs before the host borrow the numeric hook takes. Everything JS-specific lowers to CallBuiltin handlers.

[0x02] USAGE

node script.js                       # run a file
node -e 'console.log(1 + 1)'         # evaluate a one-liner
node -p '6 * 7'                      # evaluate and print the result
echo 'console.log(6 * 7)' | node     # read a script from stdin
node --tiers script.js               # run it, then report which fusevm tiers took it
node --repl                          # interactive REPL
node --lsp                           # Language Server Protocol over stdio
node --dap                           # Debug Adapter Protocol over stdio
node --build script.js               # AOT-compile to a standalone native executable
node --dump-tokens script.js         # print the lexer token stream (also --dump-ast, --dump-bytecode, --disasm)

--no-warnings, --no-deprecation, --trace-warnings and --trace-deprecation are accepted with Node's meaning for process.emitWarning output.

A failure to start (an unreadable file) goes to stderr in terse node: <reason> form; nothing else is printed. A program that ran to completion exits with process.exitCode if it set one, and the beforeExit/exit events fire as they do in Node. An uncaught exception (a top-level throw, a throwing timer or microtask, or an unhandled rejection) is offered to process.on('uncaughtException') and uncaughtExceptionMonitor first; a listener that throws exits 7. Otherwise it ends the process with Node's report: the file:line source arrow with a caret under the raise, the error's stack (at f (file:line:col) frames) and own properties, and the Node.js <version> line; exit 1. Runnable examples/*.js ship with the crate.

[0x03] SUPPORTED TODAY

A working core, grown outward from the sibling frontends. Implemented end-to-end (see examples/*.js and tests/parity.rs):

  • var / let / const; block scoping; var and function-declaration hoisting (a var is bound from scope entry, so a read above its declaration is undefined); expression and block statements.
  • Full operator surface: arithmetic (+ - * / % **), string +, comparison (== != === !== < > <= >=), logical (&& || !), nullish ??, bitwise (& | ^ ~ << >> >>>), typeof / void / delete / instanceof / in, conditional ?:, sequence ,, pre/post ++/--, compound assignment.
  • if / else, while, do … while, for, for … in, for … of, switch, break, continue, return, throw, try / catch / finally.
  • function declarations and expressions, arrow functions (with => lookahead detection), closures, recursion, new. Function.prototype.toString returns each function's and class's own source text, as V8 does: the lexer records token byte ranges and every FuncDef keeps the span of its definition.
  • Unicode source: identifiers may start with any letter (const é), the BOM, NBSP and the other Unicode spaces are whitespace, and a leading #! line is a comment in the entry script and in required modules.
  • Array and object literals, member (a.b) and index (a[i]) access, spread (...), template literals (`${...}` re-lexed from source).
  • Builtin objects and methods on the JsHost heap: console (log), Math (floor/ceil/round/trunc/abs/sign/max/min/pow/sqrt/cbrt/ random/hypot/log/log2/log10/exp/trig, PI/E), JSON (stringify/parse), Object (keys/values/entries/hasOwnProperty), Array, Number (MAX_SAFE_INTEGER/EPSILON/…), String, Boolean, parseInt/parseFloat/isNaN/isFinite, and a broad array/string method set (map/filter/reduce/forEach/find/every/some/push/pop/slice/ join/concat/includes/indexOf/flat/flatMap/reverse/fill/at, charAt/charCodeAt/padStart/padEnd/repeat/replace/replaceAll/ startsWith/endsWith, …).
  • Strings are indexed by UTF-16 code unit, as JS specifies, so a supplementary-plane character counts as two: "𝒳".length is 2 and "ab𝒳cd".indexOf("c") is 4. [Symbol.iterator] still yields code points ([..."𝒳"] is one element). src/utf16.rs is the single UTF-8 ⇄ UTF-16 boundary; see BUGS.md for the one remaining gap (a value holding an unpaired surrogate, which a Rust String cannot represent). The same unit count drives relational comparison and the default sort order (an astral character sorts BELOW every BMP character from U+E000 up), and the Buffer encodings defined over code units — utf16le/ucs2 and the low byte each unit contributes to latin1/ascii.
  • Annex B escape/unescape and ES2024 String.prototype.isWellFormed/toWellFormed.
  • class declarations and expressions: inheritance and super, static and instance fields, getters/setters, private # names, and a class body that evaluates in its own environment (so a static initializer can name its class).
  • async / await and the microtask queue, generators and yield / yield*, async generators and for await, Promise (including all/allSettled/race/any).
  • Destructuring patterns (array, object, nested, ...rest) with defaults; default and rest parameters; labeled break/continue.
  • RegExp (literals and constructor, named groups, the String.prototype regex methods), Map / Set / WeakMap / WeakSet, Symbol, BigInt, typed arrays and Buffer. Set carries the ES2025 set operations — union/intersection/difference/symmetricDifference/isSubsetOf/ isSupersetOf/isDisjointFrom — including the set-like operand form ({ size, has, keys }), so a user-written set works on the right of each.
  • Proxy — all thirteen traps plus Proxy.revocable — and the full Reflect namespace. A proxy intercepts the OPERATORS, not just the Reflect calls: reads, writes, in, delete, for-in, spread, JSON.stringify, iteration, calls, new, instanceof, and use as a prototype or a superclass. BUGS.md maps each trap to the syntax that reaches it, and states the two divergences.
  • CommonJS require and the Node standard library — see BUGS.md for the module-by-module coverage list and the honest not-implemented set.
  • The WHATWG Streams API (ReadableStream, WritableStream, TransformStream, readers, writers, controllers, queuing strategies, the text and compression streams) is node's own lib/internal/webstreams/, embedded as src/stdlib/webstreams.js behind a prelude supplying its primordials and internals: promise-driven start/pull/cancel, backpressure, byte streams with BYOB readers, tee, and pipeTo/pipeThrough with their options are node's code.
  • ES modules (ECMA-262 §16.2): static import/export in every form (default, named, string-named, namespace, export *, export * as ns, re-exports), live bindings, import cycles (a hoisted function of a module that has not started yet is callable; a const read too early is the TDZ ReferenceError), module namespace objects, top-level await with the spec's asynchronous evaluation order, import(), import.meta (url, filename, dirname, main, resolve), and the module early errors in V8's wording. A file is a module by .mjs, by its package's "type": "module", or — a .js file, -e or stdin of undeclared format — by node's syntax detection. Resolution is node's ESM resolver: no extension probing, package "exports" and "imports" with conditions and * patterns, self-reference, JSON modules behind with { type: "json" }. CommonJS interop goes both ways: importing CommonJS gives module.exports as default plus the named exports cjs-module-lexer would detect, and require() of a synchronous ES module graph returns its namespace. The module-record algorithms (Link, ResolveExport, Evaluate and the async evaluation steps) are ported from the spec in src/esm_loader.js; a module body is lowered (src/esm.rs) to one ordinary function whose scope is the module environment, so no VM change was needed. tests/esm.rs pins the behaviour against node v26.12.1.
  • The persistent bytecode cache runs on EVERY invocation (schema-versioned, so an older cached script never replays incompatible bytecode), and AOT native-executable emission is on the CLI as --build. The shard is read zero-copy: the archive is indexed in place and only the entry about to run is decoded, so a lookup costs the same whether the cache holds one script or a thousand. Measured interleaved against the previous read-and-deserialize-all design on a 2.3 MB shard (debug build), a cache-hit run went from 78.8 ms to 51.5 ms against a ±2.0 ms same-binary control.
  • An LSP server (--lsp) and a DAP debug adapter (--dap) — source-line and function breakpoints, stepping, call stack, locals, and expression evaluate — are wired.
  • Running out of stack is a catchable error. A JS call is a Rust recursion (each one builds a fusevm::VM on the stack), so the program runs on a dedicated deep-stack thread and every nested run checks the live stack pointer against the running stack's real bounds. Unbounded recursion — direct, through a recursive valueOf/toString, or inside a generator body on its own coroutine stack — raises RangeError: Maximum call stack size exceeded, the error V8 raises, rather than aborting the process. Depth is a byte budget, not a frame count, so it tracks the build's real frame size; BUGS.md records the measured numbers.

[0x04] NOT YET (LATER WAVES)

ES modules lack loader hooks (--import, --loader, module.register), data: URLs, --input-type, and WebAssembly / source-phase imports; the remaining divergences are listed in BUGS.md. Intl is absent by design rather than by omission — the reasoning is in BUGS.md, which also lists the remaining behavioural divergences from the reference node.

[0x05] PARITY HARNESS & FUZZER

Two differential tools check node-js against the reference node.

parity runs a fixed corpus through node-js and the reference node, diffing stdout. It is a development tool — generating expectations needs node on PATH, so CI never runs it; the frozen outputs live in tests/data/parity_expected.txt, which tests/parity.rs replays with no node installed.

parity-fuzz generates thousands of deterministic-output JS snippets and diffs node -e against the reference node -e, delta-debugging every divergence to a minimal repro. It is subprocess-only (never links the lib), std-only (no rand), and needs node on PATH, so CI never runs it.

gen-arity regenerates src/arity.rs, which holds four tables: the name and length of every ECMAScript intrinsic function, keyed the way this frontend names its builtins; the own members of every intrinsic prototype — string-keyed and symbol-keyed alike, the latter under the same internal @@name spelling; which of those members are ACCESSORS; and which are NON-WRITABLE. The last three are separate questions from the first: Map.prototype.size is an accessor and Array.prototype[Symbol.iterator] a symbol-keyed one, and neither is derivable from a list of functions. Those values are normative — ECMA-262 gives each intrinsic a length — so the reference engine is a transcription source here rather than an oracle to agree with, and the generated table is checked in (cargo run --bin gen-arity > src/arity.rs). The core-module surface is a different question: fs .readFileSync.length is a property of node's own JavaScript, not of any specification, so gen-core-arity MEASURES it from the reference binary into its own table, src/core_arity.rs (cargo run --bin gen-core-arity > src/core_arity.rs && cargo fmt), keyed <namespace>.<member>. The same run measures which of those functions own a prototype and which symbol-keyed properties each owns (setTimeout[util.promisify.custom]), each module's Object.keys order and its accessor exports (timers.promises), and — for the web and node classes modelled as native prototypes (AbortSignal, Performance, Crypto, EventEmitter, …) — each prototype's member order and its methods' name/length, plus which EventEmitter methods each emitter-backed class overrides rather than inherits.

The two tools deliberately drive DIFFERENT entry points — the corpus runs each case as a script FILE, the fuzzer through -e — because Node itself answers differently at each (__filename, module.id, process.argv, process.execArgv, top-level this). BUGS.md tabulates the full set; a case that touches any of it is measuring one entry point, not "node".

cargo build --bin parity --bin parity-fuzz
./target/debug/parity                          # run the corpus vs reference node
./target/debug/parity-fuzz --count 5000        # fuzz 5000 cases
./target/debug/parity-fuzz --once --seed 1234  # replay one case, show both sides

All three compare the exit STATUS exactly rather than as zero-vs-nonzero, and run both children with TZ=UTC and LANG=LC_ALL=en_US.UTF-8 pinned rather than inherited: reference node is not locale- or TZ-invariant, and a status collapsed to a boolean cannot see process.exitCode, which prints nothing. parity --bless re-records the frozen snapshot from the REFERENCE process — the only supported way to regenerate it, and never from node-js's own output.

A third harness, parity-scripts/run.sh, byte-compares every parity-scripts/**/*.js file against the reference node (stdout AND exit status) and prints the pass rate:

bash parity-scripts/run.sh      # byte-parity rate over the whole corpus
bash parity-scripts/run.sh -v   # plus a diff for each divergence

Fuzz generators are biased toward where a JS frontend is likely to disagree with the reference: float representation and the exponential-notation threshold, ToInt32 bitwise wrap, the == coercion matrix, + coercion, string/array methods, toFixed/toPrecision rounding, JSON round-trips and parse-error messages, property descriptors and the enumeration surface that depends on them, freeze/seal write and delete outcomes, builtin identity and prototype-chain reads, structuredClone's reference graph, error own-property shape, abrupt completions (unwind), and promise-resolution / async-iteration microtask ordering (thenable). Several modes read the SOURCE side of the language rather than its values: numlit (numeric-literal lexing), syntaxerr (early errors and the wording of each), regexsyntax and regexprotocol (pattern grammar errors, the ASCII-only class escapes, sticky/global lastIndex behaviour), and reflect, datefield, bigintwrap and typedcoerce (argument checks and coercions at the edge of each builtin). A further group covers Date parsing and formatting (dateparse), JSON.stringify/parse edges (jsonedge), Number formatting and parsing (numfmt), Unicode string methods (unicode), array holes, array-likes and species (arrspecies), Proxy invariants (proxyinv), microtask/timer ordering (asyncorder), class fields, private names and static blocks (classfield), iterator closing (iterclose), completion values (completion), accessors on prototype chains (protoget) and the Symbol.* protocols (symproto). parity-fuzz --help lists every mode. Select one with --mode <name>.

The run summary reports four counts next to the divergence total: ref timeout (the reference timed out, so the case is skipped entirely), ref failed (the reference exited non-zero), ref silent (the reference printed nothing on stdout) and ref inert (both — the only condition under which a case observed nothing at all). A mode scoring zero divergences while ref inert is high is comparing nothing; ref failed on its own is not that signal any more, since the exit code is itself a compared value and the exit mode consists of programs that print nothing and exit non-zero deliberately.

[0x06] BUILD

cargo build
cargo test

node-js is a standalone crate (an explicit empty [workspace] stops cargo walking up to the meta parent). fusevm is pulled from crates.io with the jit, jit-disk-cache, aot, and ffi features.

[0x06a] EMBEDDING

The nodejs library crate exposes one string-in/string-out entry point for Rust hosts:

pub fn run_program(src: &str, input: &str) -> Result<String, String>
  • Each call runs on its own thread (JS_STACK_SIZE stack) with a freshly reset host; no state carries over between calls, and concurrent calls never share an output buffer.
  • input is the program's standard input: process.stdin (events, read(), async iteration), fs.readFileSync(0), fs.readSync(0, …) and readline.
  • Returns everything written to stdout (console.log, process.stdout.write, readline cursor writes). stderr (console.error) still goes to the process stderr.
  • Compile errors, uncaught exceptions, a nonzero process.exitCode, process.exit(n) with n != 0, process.abort() and runtime panics return Err(message). process.exit(0) returns Ok with the output written so far; the process is never exited.
let out = nodejs::run_program(
    r#"console.log(require("fs").readFileSync(0, "utf8").trim().toUpperCase())"#,
    "hi\n",
)?;
assert_eq!(out, "HI\n");

eval_str_captured(src, globals) is the lower-level variant: it binds string globals, captures stdout and stderr together, and returns the completion value alongside the output.

[0x07] DOCUMENTATION

[0xFF] LICENSE

MIT — free and open source. See LICENSE.