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}