Skip to main content

nodejs/
lib.rs

1//! node-js — JavaScript as a fusevm frontend.
2//!
3//! Pipeline: `lexer` → `parser` builds a JS AST → `compiler` lowers it to a
4//! `fusevm::Chunk` (plus a table of function/arrow sub-chunks and try-block
5//! chunks) → fusevm executes it, calling back into the `host` (through
6//! registered builtins and the strict numeric hook) for every JS-specific
7//! operation. There is no bespoke VM or JIT here — execution and codegen live in
8//! fusevm.
9
10pub mod aot;
11pub mod aot_native;
12pub mod arity;
13pub mod ast;
14pub mod banner;
15pub mod builtins;
16pub mod cache;
17pub mod capture;
18pub mod cli;
19pub mod compiler;
20pub mod core_arity;
21pub mod dap;
22pub mod datefmt;
23pub mod embed;
24pub mod esm;
25pub mod host;
26pub mod ieee754;
27pub mod lexer;
28pub mod lsp;
29pub mod module;
30pub mod numfmt;
31pub mod parser;
32pub mod proxy;
33pub mod regexp;
34pub mod regexp_syntax;
35pub mod repl;
36pub mod rust_ffi;
37pub mod slots;
38pub mod stdlib;
39pub mod tiers;
40pub mod tzif;
41pub mod tznames;
42pub mod utf16;
43
44pub use embed::run_program;
45pub use fusevm::Value;
46
47/// Stack reserved for the thread JS runs on ([`run_on_js_stack`]).
48///
49/// A JS call is a Rust recursion (`host::run_user_func_nt` → `run_chunk_on` →
50/// a fresh `fusevm::VM` on the stack), so recursion depth is bounded by the
51/// native stack rather than by a frame counter. On the OS default 8 MiB this
52/// bought only 83 frames in a debug build — measured, `node -e 'function
53/// f(n){if(n<=0)return 0;return 1+f(n-1)} f(84)'` aborted — where node v26.7.0
54/// reaches 9901. Reserving 256 MiB is virtual address space, faulted in only as
55/// deep recursion actually uses it, and `host::stack_exhausted` still turns the
56/// far end into a catchable `RangeError` rather than an abort. The reservation
57/// is capped rather than sized to match node's depth exactly so that a runaway
58/// recursion's peak RSS stays bounded; the resulting depth is documented in
59/// BUGS.md.
60pub const JS_STACK_SIZE: usize = 256 * 1024 * 1024;
61
62/// Run `f` on a thread with [`JS_STACK_SIZE`] of stack, falling back to the
63/// calling thread if the reservation is refused (a `ulimit`ed or memory-capped
64/// environment must still run programs, just at a lower recursion ceiling —
65/// `host::stack_exhausted` measures whatever stack it ends up on).
66///
67/// Takes a plain `fn` pointer, not a closure: `Builder::spawn` consumes what it
68/// is given and does not hand it back on failure, and a `fn` is `Copy`, so the
69/// fallback can still call the same entry point.
70pub fn run_on_js_stack(f: fn() -> std::process::ExitCode) -> std::process::ExitCode {
71    match std::thread::Builder::new()
72        .name("node-js".into())
73        .stack_size(JS_STACK_SIZE)
74        .spawn(f)
75    {
76        // A panic on the JS thread has already written its message to stderr;
77        // re-raising keeps the process dying exactly as it would have without
78        // the hop, rather than turning an abort into a quiet exit code.
79        Ok(h) => h.join().unwrap_or_else(|p| std::panic::resume_unwind(p)),
80        Err(_) => f(),
81    }
82}
83
84/// Compile a source string to a runnable program.
85pub fn compile(src: &str) -> Result<compiler::Program, String> {
86    let stmts = parser::parse(src)?;
87    with_source(compiler::compile(&stmts, false), src)
88}
89
90/// Compile leaving the final top-level expression as the program's completion
91/// value (for `vm.runInThisContext` / `eval`).
92pub fn compile_completion(src: &str) -> Result<compiler::Program, String> {
93    compile_completion_strict(src, false)
94}
95
96/// As [`compile_completion`], with the caller's strictness folded in — what a
97/// direct `eval` inherits.
98pub fn compile_completion_strict(
99    src: &str,
100    caller_strict: bool,
101) -> Result<compiler::Program, String> {
102    compile_completion_in(src, caller_strict, false, false)
103}
104
105/// As [`compile_completion_strict`], for a direct `eval` that may be running
106/// inside a method, where the evaluated code may use `super`.
107pub fn compile_completion_in(
108    src: &str,
109    caller_strict: bool,
110    allow_super: bool,
111    in_with: bool,
112) -> Result<compiler::Program, String> {
113    let stmts = parser::parse_eval(src, allow_super, caller_strict)?;
114    with_source(
115        compiler::compile_completion_strict(&stmts, false, caller_strict, in_with),
116        src,
117    )
118}
119
120/// Compile with per-statement DAP line markers enabled (`node --dap`).
121pub fn compile_debug(src: &str) -> Result<compiler::Program, String> {
122    let stmts = parser::parse(src)?;
123    with_source(compiler::compile(&stmts, true), src)
124}
125
126/// Attach the text a program was parsed from, which its functions' spans
127/// index (`Function.prototype.toString`).
128pub fn with_source(
129    prog: Result<compiler::Program, String>,
130    src: &str,
131) -> Result<compiler::Program, String> {
132    prog.map(|mut p| {
133        p.source = Some(src.into());
134        p
135    })
136}
137
138/// Rebase a freshly compiled program's func/try ids above those already loaded
139/// on the host, install its functions/tries, and return the (rebased) main
140/// chunk to run.
141pub fn load_merged(prog: compiler::Program) -> fusevm::Chunk {
142    load_merged_from(prog, None)
143}
144
145/// [`load_merged`] for a program whose text node names `origin` — the name a
146/// source arrow and a stack frame print for its positions (`<anonymous>` when
147/// `None`).
148pub fn load_merged_from(
149    mut prog: compiler::Program,
150    origin: Option<host::ScriptOrigin>,
151) -> fusevm::Chunk {
152    let (func_off, try_off) = host::with_host(|h| h.program_offsets());
153    compiler::rebase_program(&mut prog, func_off, try_off);
154    let compiler::Program {
155        mut main,
156        functions,
157        mut tries,
158        strict,
159        source,
160    } = prog;
161    let mut funcs: Vec<host::FuncDef> = functions.into_iter().map(|(_, f)| f).collect();
162    host::with_host(|h| {
163        // Each span-carrying function learns which script its span indexes,
164        // and every op's source position moves into the script's range of the
165        // host's source address space. Without the text a position cannot be
166        // resolved, so it is dropped.
167        let base = match source {
168            Some(text) => {
169                let script = h.scripts.len() as u32;
170                h.scripts.push(text);
171                for f in funcs.iter_mut().filter(|f| f.span.1 != 0) {
172                    f.script = Some(script);
173                }
174                let origin = origin.unwrap_or_else(|| host::ScriptOrigin::named("<anonymous>"));
175                Some(h.register_source(script, origin))
176            }
177            None => None,
178        };
179        let mut chunks: Vec<&mut fusevm::Chunk> = vec![&mut main];
180        chunks.extend(funcs.iter_mut().map(|f| &mut f.chunk));
181        for t in &mut tries {
182            chunks.push(&mut t.block);
183            chunks.extend(t.handler.as_mut().map(|(_, c)| c));
184            chunks.extend(t.finalizer.as_mut());
185        }
186        for c in chunks {
187            compiler::rebase_positions(c, base);
188        }
189        h.load_program(funcs, tries);
190        // A strict top level marks the frame it is about to run on, so a
191        // refused write throws there the way it does inside a strict function.
192        // A function's strictness rides in its `FuncDef`; the top level had
193        // nowhere to put it, so the module frame stayed sloppy.
194        if strict {
195            h.set_current_strict();
196        }
197    });
198    main
199}
200
201/// Run an already-compiled program on the current host.
202pub fn run_compiled(prog: compiler::Program) -> Result<Value, String> {
203    run_compiled_from(prog, None)
204}
205
206/// [`run_compiled`] for the entry script, named `origin` (see [`load_merged_from`]).
207pub fn run_compiled_from(
208    prog: compiler::Program,
209    origin: Option<host::ScriptOrigin>,
210) -> Result<Value, String> {
211    host::run_main(load_merged_from(prog, origin))
212}
213
214/// `process.exitCode` as the program left it, or `None` if it was never set.
215///
216/// The binary reads this after a run completes to pick its own status — Node
217/// exits with `process.exitCode` when the loop drains normally, so a script
218/// that signals failure that way (rather than by throwing or calling
219/// `process.exit`) is reported as a failure rather than as success.
220pub fn exit_code() -> Option<i32> {
221    host::with_host(|h| h.exit_code)
222}
223
224/// Run the `exit` event for a program that died on an uncaught exception, and
225/// report the status to leave with.
226///
227/// Node fires `exit` on this path too, and an uncaught exception FORCES the
228/// code to 1 — overriding any `process.exitCode` the script had already set —
229/// while a code the handler itself assigns still wins. Verified on node
230/// v26.7.0: `process.exitCode = 3; process.on('exit', c => console.log(c));
231/// throw new Error('z')` prints `1` and exits 1, and
232/// `process.on('exit', () => { process.exitCode = 9 }); throw new Error('z')`
233/// exits 9.
234pub fn exit_code_after_failure() -> i32 {
235    // An `uncaughtException` listener that itself threw: node exits 7 and
236    // fires no `exit` event.
237    if host::with_host(|h| h.fatal_handler_failed) {
238        return 7;
239    }
240    host::with_host(|h| h.exit_code = Some(1));
241    let _ = stdlib::process::emit_exit_event(1);
242    host::with_host(|h| h.exit_code).unwrap_or(1)
243}
244
245/// Compile `src` and run it on the LIVE host — no reset, no event-loop drain —
246/// in the GLOBAL scope, returning its completion value.
247///
248/// This is the ONE runtime-source evaluator on this frontend. Every construct
249/// that turns a source string into a running program funnels through here:
250/// the CommonJS module wrapper (`module::compile_wrapper`), `vm.runInThisContext`
251/// / `vm.Script` / `vm.compileFunction`, `new Function` / `Function(...)`
252/// (`builtins::dynamic_function`), and the internal JS factories
253/// (`util.promisify`, `stream/promises`, `stream/consumers`,
254/// `performance.timerify`, `module.builtinModules`). Each of those used to carry
255/// its own `compile_completion` → `load_merged` → `run_chunk_on` triple — seven
256/// copies of the same three lines — and every one of them inherited the same
257/// bug: `run_chunk_on` executes on whatever frame is CURRENT, so nested source
258/// saw the calling function's locals. Measured against node v26.7.0,
259/// `function outer(){ let secret = 1; return require('./m.js'); }` with `m.js` =
260/// `module.exports = typeof secret` is `"undefined"` there and was `"number"`
261/// here; `vm.runInThisContext('typeof loc')` likewise. `run_chunk_in_global_scope`
262/// fixes it once, for all of them.
263pub fn eval_in_global_scope(src: &str) -> Result<Value, String> {
264    eval_in_global_scope_from(src, None)
265}
266
267/// [`eval_in_global_scope`] for the runtime's own JavaScript — the factories
268/// behind `util.promisify`, `events.on`, web streams and the rest. Its frames
269/// stay out of every stack trace (see [`host::ScriptOrigin::internal`]).
270pub fn eval_internal(src: &str) -> Result<Value, String> {
271    eval_in_global_scope_from(src, Some(host::ScriptOrigin::internal("node:internal")))
272}
273
274/// [`eval_in_global_scope`] for source node names `origin` (a CommonJS
275/// module's file; see [`load_merged_from`]).
276pub fn eval_in_global_scope_from(
277    src: &str,
278    origin: Option<host::ScriptOrigin>,
279) -> Result<Value, String> {
280    let prog = compile_completion(src)?;
281    let chunk = load_merged_from(prog, origin);
282    host::run_chunk_in_global_scope(chunk)
283}
284
285/// Transparent bytecode cache: return the cached compiled `Program` for `src`
286/// (skipping lex/parse/lower entirely), else compile it, store it in the
287/// `~/.node-js/scripts.rkyv` shard, and return it. This runs on EVERY ordinary
288/// `node foo.js` / `node -e` invocation, so scripts are rkyv-cached automatically
289/// — not only under `--build`. Set `NODE_JS_TRACE=1` to log hit/miss to stderr
290/// (silent otherwise; normal runs print nothing).
291pub fn compile_or_load(src: &str) -> Result<compiler::Program, String> {
292    if let Some(prog) = cache::load(src) {
293        if std::env::var_os("NODE_JS_TRACE").is_some() {
294            eprintln!(
295                "node-js: cache HIT ({} ops, {} functions) — skipped lex/parse/lower",
296                prog.main.ops.len(),
297                prog.functions.len()
298            );
299        }
300        return Ok(prog);
301    }
302    let prog = compile(src)?;
303    let _ = cache::store(src, &prog);
304    if std::env::var_os("NODE_JS_TRACE").is_some() {
305        eprintln!(
306            "node-js: cache MISS — compiled + stored ({} ops, {} functions)",
307            prog.main.ops.len(),
308            prog.functions.len()
309        );
310    }
311    Ok(prog)
312}
313
314/// Parse/load, compile, and run a JS source string on a fresh host (rkyv-cached).
315///
316/// This is the `node -e` entry point; [`eval_str_from`] names the other
317/// source-on-the-command-line one, which reports a different `__filename`.
318pub fn eval_str(src: &str) -> Result<Value, String> {
319    eval_str_from(src, "[eval]")
320}
321
322/// [`eval_str`] with the entry-point NAME node reports for it: `[eval]` for
323/// `-e`, `[stdin]` for source piped in. The two are observably different —
324/// `__filename`, `module.id` and a stack frame's file all carry it.
325pub fn eval_str_from(src: &str, origin: &str) -> Result<Value, String> {
326    host::reset_host();
327    // `node -e` resolves top-level `require` from the current working directory.
328    if let Ok(cwd) = std::env::current_dir() {
329        module::set_entry_dir(cwd);
330    }
331    match compile_or_load(src) {
332        Ok(prog) => {
333            module::install_entry_globals(origin);
334            run_compiled_from(prog, Some(host::ScriptOrigin::named(origin)))
335        }
336        // Syntax detection, as for a file of undeclared format: source that
337        // only parses as a module runs as one, named `[eval1]` in the
338        // current directory (node's name for `-e` and stdin alike).
339        Err(e) => {
340            let at = parser::take_error_pos();
341            if !esm::detect_module(src, &e) {
342                return Err(syntax_error(src, origin, e, at));
343            }
344            let cwd = std::env::current_dir().unwrap_or_default();
345            let entry = cwd.join("[eval1]").to_string_lossy().into_owned();
346            let main = esm::main_program(&entry, Some(src.to_string()), false);
347            run_compiled(compiler::compile(&main, false)?)
348        }
349    }
350}
351
352/// `node -p <src>`: evaluate as `-e` does, then write the program's COMPLETION
353/// value through the `console.log` formatter, exactly as Node's
354/// `--print` does (`node -p '[1,2]'` prints `[ 1, 2 ]`, `node -p '"s"'` prints
355/// the bare `s`). Side effects still happen, so `node -p 'console.log("x")'`
356/// prints `x` and then `undefined`.
357///
358/// Deliberately compiled with [`compile_completion`] rather than through the
359/// source-keyed rkyv cache: the cache is keyed by source TEXT alone, so a
360/// `-p`-shaped chunk and an `-e`-shaped chunk for the same string would alias.
361pub fn eval_str_print(src: &str, origin: &str) -> Result<(), String> {
362    host::reset_host();
363    if let Ok(cwd) = std::env::current_dir() {
364        module::set_entry_dir(cwd);
365    }
366    module::install_entry_globals(origin);
367    let value = run_compiled_from(
368        compile_completion(src)?,
369        Some(host::ScriptOrigin::named(origin)),
370    )?;
371    // One argument means no directive processing at all (node returns a lone
372    // argument as-is), so this call has nothing that can throw.
373    let line = stdlib::util::format(std::slice::from_ref(&value))?;
374    host::with_host(|h| h.write_out(&format!("{line}\n"), false));
375    Ok(())
376}
377
378/// Run a JS source string on a fresh host with `globals` bound and the
379/// program's output captured in-process, returning the program's outcome
380/// alongside everything it wrote.
381///
382/// This is the entry point for an embedder rather than for the `node` binary,
383/// and it exists because [`eval_str`] cannot serve one: it resets the host
384/// first, which wipes any global installed beforehand, and it lets
385/// `console.log` reach the real stdout, which corrupts a host that owns the
386/// terminal. Both are fixed here — the globals are seeded *after* the reset,
387/// and every write the program makes lands in the returned string.
388///
389/// The outcome and the output are returned separately (rather than the output
390/// only on success) because a program that prints and *then* throws produced
391/// both, and an embedder generally wants to show both.
392///
393/// Globals are given as text and interned as real JS strings here. They are
394/// deliberately *not* `Value`: strings live on this host's heap as
395/// `JsObj::Str`, so a `Value::Str` a caller builds is at best coerced and at
396/// worst method-less. Handing the host text and letting it intern removes that
397/// trap, and matches the sibling runtimes' embedder entry points.
398///
399/// ```no_run
400/// let (result, out) = nodejs::eval_str_captured("console.log(stdin.toUpperCase())", &[("stdin", "hi")]);
401/// assert!(result.is_ok());
402/// assert_eq!(out, "HI\n");
403/// ```
404pub fn eval_str_captured(src: &str, globals: &[(&str, &str)]) -> (Result<Value, String>, String) {
405    run_on_fresh_host(src, |h| {
406        for (name, text) in globals {
407            let value = h.new_str(*text);
408            h.set_global(name, value);
409        }
410        h.begin_capture();
411    })
412}
413
414/// Reset the host, let `setup` prepare it (globals, capture, stdin), run `src`
415/// to completion, and return the outcome with whatever capture collected.
416/// Shared by [`eval_str_captured`] and [`embed::run_program`].
417pub(crate) fn run_on_fresh_host(
418    src: &str,
419    setup: impl FnOnce(&mut host::JsHost),
420) -> (Result<Value, String>, String) {
421    host::reset_host();
422    if let Ok(cwd) = std::env::current_dir() {
423        module::set_entry_dir(cwd);
424    }
425    host::with_host(setup);
426    let result = compile_or_load(src).and_then(run_compiled);
427    let output = host::with_host(|h| h.end_capture());
428    (result, output)
429}
430
431/// Read and run a `.js` file (transparently rkyv-cached — see `compile_or_load`).
432pub fn eval_file(path: &str) -> Result<Value, String> {
433    let src = std::fs::read_to_string(path).map_err(|e| format!("cannot read {path}: {e}"))?;
434    host::reset_host();
435    // Top-level `require` in `node app.js` resolves from the entry file's dir.
436    let dir = std::path::Path::new(path)
437        .parent()
438        .filter(|p| !p.as_os_str().is_empty())
439        .map(std::path::Path::to_path_buf)
440        .or_else(|| std::env::current_dir().ok())
441        .unwrap_or_default();
442    let dir = std::fs::canonicalize(&dir).unwrap_or(dir);
443    module::set_entry_dir(dir);
444    // `__filename` is the entry script's REALPATH, not the path that was typed:
445    // Node's loader calls `toRealPath` on the main module, so a script reached
446    // through a symlinked directory reports the link TARGET. (`process.argv[1]`
447    // is the opposite — it keeps the spelling; both measured on node v26.7.0.)
448    let entry = std::fs::canonicalize(path)
449        .map(|p| p.to_string_lossy().into_owned())
450        .unwrap_or_else(|_| stdlib::path::resolve_one(path));
451    // An ES module entry point: by its `.mjs` extension or its package's
452    // `"type": "module"`, or — for a file of undeclared format — because it
453    // only parses as a module (node's syntax detection). It sees none of the
454    // CommonJS wrapper names.
455    let entry_path = std::path::Path::new(&entry);
456    let format = esm::file_format_declared(entry_path);
457    let is_module = match format {
458        Some(f) => f == esm::Format::Module,
459        None => match compile_or_load(&src) {
460            Ok(prog) => {
461                module::install_entry_globals(&entry);
462                return run_compiled_from(prog, Some(host::ScriptOrigin::named(&entry)));
463            }
464            Err(e) => {
465                let at = parser::take_error_pos();
466                if !esm::detect_module(&src, &e) {
467                    return Err(syntax_error(&src, &entry, e, at));
468                }
469                true
470            }
471        },
472    };
473    if is_module {
474        let main = esm::main_program(&entry, None, true);
475        return run_compiled(compiler::compile(&main, false)?);
476    }
477    module::install_entry_globals(&entry);
478    let prog = compile_or_load(&src).map_err(|e| {
479        let at = parser::take_error_pos();
480        syntax_error(&src, &entry, e, at)
481    })?;
482    run_compiled_from(prog, Some(host::ScriptOrigin::named(&entry)))
483}
484
485/// A SyntaxError (or other compile error) `e` from the entry script `src`,
486/// recorded so the report shows node's arrow at `at` (see
487/// `host::note_syntax_error`).
488fn syntax_error(src: &str, origin: &str, e: String, at: ast::Pos) -> String {
489    host::note_syntax_error(src, host::ScriptOrigin::named(origin), &e, at);
490    e
491}
492
493/// Read and run a `.js` file under the DAP debugger.
494pub fn eval_file_debug(path: &str) -> Result<Value, String> {
495    let src = std::fs::read_to_string(path).map_err(|e| format!("cannot read {path}: {e}"))?;
496    let prog = compile_debug(&src)?;
497    host::reset_host();
498    host::set_debug_mode(true);
499    let r = run_compiled(prog);
500    host::set_debug_mode(false);
501    r
502}