node-js 0.1.15

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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
//! node-js — JavaScript as a fusevm frontend.
//!
//! Pipeline: `lexer` → `parser` builds a JS AST → `compiler` lowers it to a
//! `fusevm::Chunk` (plus a table of function/arrow sub-chunks and try-block
//! chunks) → fusevm executes it, calling back into the `host` (through
//! registered builtins and the strict numeric hook) for every JS-specific
//! operation. There is no bespoke VM or JIT here — execution and codegen live in
//! fusevm.

pub mod aot;
pub mod aot_native;
pub mod arity;
pub mod ast;
pub mod banner;
pub mod builtins;
pub mod cache;
pub mod capture;
pub mod cli;
pub mod compiler;
pub mod core_arity;
pub mod dap;
pub mod datefmt;
pub mod embed;
pub mod esm;
pub mod host;
pub mod ieee754;
pub mod lexer;
pub mod lsp;
pub mod module;
pub mod numfmt;
pub mod parser;
pub mod proxy;
pub mod regexp;
pub mod regexp_syntax;
pub mod repl;
pub mod rust_ffi;
pub mod slots;
pub mod stdlib;
pub mod tiers;
pub mod tzif;
pub mod tznames;
pub mod utf16;

pub use embed::run_program;
pub use fusevm::Value;

/// Stack reserved for the thread JS runs on ([`run_on_js_stack`]).
///
/// A JS call is a Rust recursion (`host::run_user_func_nt` → `run_chunk_on` →
/// a fresh `fusevm::VM` on the stack), so recursion depth is bounded by the
/// native stack rather than by a frame counter. On the OS default 8 MiB this
/// bought only 83 frames in a debug build — measured, `node -e 'function
/// f(n){if(n<=0)return 0;return 1+f(n-1)} f(84)'` aborted — where node v26.7.0
/// reaches 9901. Reserving 256 MiB is virtual address space, faulted in only as
/// deep recursion actually uses it, and `host::stack_exhausted` still turns the
/// far end into a catchable `RangeError` rather than an abort. The reservation
/// is capped rather than sized to match node's depth exactly so that a runaway
/// recursion's peak RSS stays bounded; the resulting depth is documented in
/// BUGS.md.
pub const JS_STACK_SIZE: usize = 256 * 1024 * 1024;

/// Run `f` on a thread with [`JS_STACK_SIZE`] of stack, falling back to the
/// calling thread if the reservation is refused (a `ulimit`ed or memory-capped
/// environment must still run programs, just at a lower recursion ceiling —
/// `host::stack_exhausted` measures whatever stack it ends up on).
///
/// Takes a plain `fn` pointer, not a closure: `Builder::spawn` consumes what it
/// is given and does not hand it back on failure, and a `fn` is `Copy`, so the
/// fallback can still call the same entry point.
pub fn run_on_js_stack(f: fn() -> std::process::ExitCode) -> std::process::ExitCode {
    match std::thread::Builder::new()
        .name("node-js".into())
        .stack_size(JS_STACK_SIZE)
        .spawn(f)
    {
        // A panic on the JS thread has already written its message to stderr;
        // re-raising keeps the process dying exactly as it would have without
        // the hop, rather than turning an abort into a quiet exit code.
        Ok(h) => h.join().unwrap_or_else(|p| std::panic::resume_unwind(p)),
        Err(_) => f(),
    }
}

/// Compile a source string to a runnable program.
pub fn compile(src: &str) -> Result<compiler::Program, String> {
    let stmts = parser::parse(src)?;
    with_source(compiler::compile(&stmts, false), src)
}

/// Compile leaving the final top-level expression as the program's completion
/// value (for `vm.runInThisContext` / `eval`).
pub fn compile_completion(src: &str) -> Result<compiler::Program, String> {
    compile_completion_strict(src, false)
}

/// As [`compile_completion`], with the caller's strictness folded in — what a
/// direct `eval` inherits.
pub fn compile_completion_strict(
    src: &str,
    caller_strict: bool,
) -> Result<compiler::Program, String> {
    compile_completion_in(src, caller_strict, false, false)
}

/// As [`compile_completion_strict`], for a direct `eval` that may be running
/// inside a method, where the evaluated code may use `super`.
pub fn compile_completion_in(
    src: &str,
    caller_strict: bool,
    allow_super: bool,
    in_with: bool,
) -> Result<compiler::Program, String> {
    let stmts = parser::parse_eval(src, allow_super, caller_strict)?;
    with_source(
        compiler::compile_completion_strict(&stmts, false, caller_strict, in_with),
        src,
    )
}

/// Compile with per-statement DAP line markers enabled (`node --dap`).
pub fn compile_debug(src: &str) -> Result<compiler::Program, String> {
    let stmts = parser::parse(src)?;
    with_source(compiler::compile(&stmts, true), src)
}

/// Attach the text a program was parsed from, which its functions' spans
/// index (`Function.prototype.toString`).
pub fn with_source(
    prog: Result<compiler::Program, String>,
    src: &str,
) -> Result<compiler::Program, String> {
    prog.map(|mut p| {
        p.source = Some(src.into());
        p
    })
}

/// Rebase a freshly compiled program's func/try ids above those already loaded
/// on the host, install its functions/tries, and return the (rebased) main
/// chunk to run.
pub fn load_merged(prog: compiler::Program) -> fusevm::Chunk {
    load_merged_from(prog, None)
}

/// [`load_merged`] for a program whose text node names `origin` — the name a
/// source arrow and a stack frame print for its positions (`<anonymous>` when
/// `None`).
pub fn load_merged_from(
    mut prog: compiler::Program,
    origin: Option<host::ScriptOrigin>,
) -> fusevm::Chunk {
    let (func_off, try_off) = host::with_host(|h| h.program_offsets());
    compiler::rebase_program(&mut prog, func_off, try_off);
    let compiler::Program {
        mut main,
        functions,
        mut tries,
        strict,
        source,
    } = prog;
    let mut funcs: Vec<host::FuncDef> = functions.into_iter().map(|(_, f)| f).collect();
    host::with_host(|h| {
        // Each span-carrying function learns which script its span indexes,
        // and every op's source position moves into the script's range of the
        // host's source address space. Without the text a position cannot be
        // resolved, so it is dropped.
        let base = match source {
            Some(text) => {
                let script = h.scripts.len() as u32;
                h.scripts.push(text);
                for f in funcs.iter_mut().filter(|f| f.span.1 != 0) {
                    f.script = Some(script);
                }
                let origin = origin.unwrap_or_else(|| host::ScriptOrigin::named("<anonymous>"));
                Some(h.register_source(script, origin))
            }
            None => None,
        };
        let mut chunks: Vec<&mut fusevm::Chunk> = vec![&mut main];
        chunks.extend(funcs.iter_mut().map(|f| &mut f.chunk));
        for t in &mut tries {
            chunks.push(&mut t.block);
            chunks.extend(t.handler.as_mut().map(|(_, c)| c));
            chunks.extend(t.finalizer.as_mut());
        }
        for c in chunks {
            compiler::rebase_positions(c, base);
        }
        h.load_program(funcs, tries);
        // A strict top level marks the frame it is about to run on, so a
        // refused write throws there the way it does inside a strict function.
        // A function's strictness rides in its `FuncDef`; the top level had
        // nowhere to put it, so the module frame stayed sloppy.
        if strict {
            h.set_current_strict();
        }
    });
    main
}

/// Run an already-compiled program on the current host.
pub fn run_compiled(prog: compiler::Program) -> Result<Value, String> {
    run_compiled_from(prog, None)
}

/// [`run_compiled`] for the entry script, named `origin` (see [`load_merged_from`]).
pub fn run_compiled_from(
    prog: compiler::Program,
    origin: Option<host::ScriptOrigin>,
) -> Result<Value, String> {
    host::run_main(load_merged_from(prog, origin))
}

/// `process.exitCode` as the program left it, or `None` if it was never set.
///
/// The binary reads this after a run completes to pick its own status — Node
/// exits with `process.exitCode` when the loop drains normally, so a script
/// that signals failure that way (rather than by throwing or calling
/// `process.exit`) is reported as a failure rather than as success.
pub fn exit_code() -> Option<i32> {
    host::with_host(|h| h.exit_code)
}

/// Run the `exit` event for a program that died on an uncaught exception, and
/// report the status to leave with.
///
/// Node fires `exit` on this path too, and an uncaught exception FORCES the
/// code to 1 — overriding any `process.exitCode` the script had already set —
/// while a code the handler itself assigns still wins. Verified on node
/// v26.7.0: `process.exitCode = 3; process.on('exit', c => console.log(c));
/// throw new Error('z')` prints `1` and exits 1, and
/// `process.on('exit', () => { process.exitCode = 9 }); throw new Error('z')`
/// exits 9.
pub fn exit_code_after_failure() -> i32 {
    // An `uncaughtException` listener that itself threw: node exits 7 and
    // fires no `exit` event.
    if host::with_host(|h| h.fatal_handler_failed) {
        return 7;
    }
    host::with_host(|h| h.exit_code = Some(1));
    let _ = stdlib::process::emit_exit_event(1);
    host::with_host(|h| h.exit_code).unwrap_or(1)
}

/// Compile `src` and run it on the LIVE host — no reset, no event-loop drain —
/// in the GLOBAL scope, returning its completion value.
///
/// This is the ONE runtime-source evaluator on this frontend. Every construct
/// that turns a source string into a running program funnels through here:
/// the CommonJS module wrapper (`module::compile_wrapper`), `vm.runInThisContext`
/// / `vm.Script` / `vm.compileFunction`, `new Function` / `Function(...)`
/// (`builtins::dynamic_function`), and the internal JS factories
/// (`util.promisify`, `stream/promises`, `stream/consumers`,
/// `performance.timerify`, `module.builtinModules`). Each of those used to carry
/// its own `compile_completion` → `load_merged` → `run_chunk_on` triple — seven
/// copies of the same three lines — and every one of them inherited the same
/// bug: `run_chunk_on` executes on whatever frame is CURRENT, so nested source
/// saw the calling function's locals. Measured against node v26.7.0,
/// `function outer(){ let secret = 1; return require('./m.js'); }` with `m.js` =
/// `module.exports = typeof secret` is `"undefined"` there and was `"number"`
/// here; `vm.runInThisContext('typeof loc')` likewise. `run_chunk_in_global_scope`
/// fixes it once, for all of them.
pub fn eval_in_global_scope(src: &str) -> Result<Value, String> {
    eval_in_global_scope_from(src, None)
}

/// [`eval_in_global_scope`] for the runtime's own JavaScript — the factories
/// behind `util.promisify`, `events.on`, web streams and the rest. Its frames
/// stay out of every stack trace (see [`host::ScriptOrigin::internal`]).
pub fn eval_internal(src: &str) -> Result<Value, String> {
    eval_in_global_scope_from(src, Some(host::ScriptOrigin::internal("node:internal")))
}

/// [`eval_in_global_scope`] for source node names `origin` (a CommonJS
/// module's file; see [`load_merged_from`]).
pub fn eval_in_global_scope_from(
    src: &str,
    origin: Option<host::ScriptOrigin>,
) -> Result<Value, String> {
    let prog = compile_completion(src)?;
    let chunk = load_merged_from(prog, origin);
    host::run_chunk_in_global_scope(chunk)
}

/// Transparent bytecode cache: return the cached compiled `Program` for `src`
/// (skipping lex/parse/lower entirely), else compile it, store it in the
/// `~/.node-js/scripts.rkyv` shard, and return it. This runs on EVERY ordinary
/// `node foo.js` / `node -e` invocation, so scripts are rkyv-cached automatically
/// — not only under `--build`. Set `NODE_JS_TRACE=1` to log hit/miss to stderr
/// (silent otherwise; normal runs print nothing).
pub fn compile_or_load(src: &str) -> Result<compiler::Program, String> {
    if let Some(prog) = cache::load(src) {
        if std::env::var_os("NODE_JS_TRACE").is_some() {
            eprintln!(
                "node-js: cache HIT ({} ops, {} functions) — skipped lex/parse/lower",
                prog.main.ops.len(),
                prog.functions.len()
            );
        }
        return Ok(prog);
    }
    let prog = compile(src)?;
    let _ = cache::store(src, &prog);
    if std::env::var_os("NODE_JS_TRACE").is_some() {
        eprintln!(
            "node-js: cache MISS — compiled + stored ({} ops, {} functions)",
            prog.main.ops.len(),
            prog.functions.len()
        );
    }
    Ok(prog)
}

/// Parse/load, compile, and run a JS source string on a fresh host (rkyv-cached).
///
/// This is the `node -e` entry point; [`eval_str_from`] names the other
/// source-on-the-command-line one, which reports a different `__filename`.
pub fn eval_str(src: &str) -> Result<Value, String> {
    eval_str_from(src, "[eval]")
}

/// [`eval_str`] with the entry-point NAME node reports for it: `[eval]` for
/// `-e`, `[stdin]` for source piped in. The two are observably different —
/// `__filename`, `module.id` and a stack frame's file all carry it.
pub fn eval_str_from(src: &str, origin: &str) -> Result<Value, String> {
    host::reset_host();
    // `node -e` resolves top-level `require` from the current working directory.
    if let Ok(cwd) = std::env::current_dir() {
        module::set_entry_dir(cwd);
    }
    match compile_or_load(src) {
        Ok(prog) => {
            module::install_entry_globals(origin);
            run_compiled_from(prog, Some(host::ScriptOrigin::named(origin)))
        }
        // Syntax detection, as for a file of undeclared format: source that
        // only parses as a module runs as one, named `[eval1]` in the
        // current directory (node's name for `-e` and stdin alike).
        Err(e) => {
            let at = parser::take_error_pos();
            if !esm::detect_module(src, &e) {
                return Err(syntax_error(src, origin, e, at));
            }
            let cwd = std::env::current_dir().unwrap_or_default();
            let entry = cwd.join("[eval1]").to_string_lossy().into_owned();
            let main = esm::main_program(&entry, Some(src.to_string()), false);
            run_compiled(compiler::compile(&main, false)?)
        }
    }
}

/// `node -p <src>`: evaluate as `-e` does, then write the program's COMPLETION
/// value through the `console.log` formatter, exactly as Node's
/// `--print` does (`node -p '[1,2]'` prints `[ 1, 2 ]`, `node -p '"s"'` prints
/// the bare `s`). Side effects still happen, so `node -p 'console.log("x")'`
/// prints `x` and then `undefined`.
///
/// Deliberately compiled with [`compile_completion`] rather than through the
/// source-keyed rkyv cache: the cache is keyed by source TEXT alone, so a
/// `-p`-shaped chunk and an `-e`-shaped chunk for the same string would alias.
pub fn eval_str_print(src: &str, origin: &str) -> Result<(), String> {
    host::reset_host();
    if let Ok(cwd) = std::env::current_dir() {
        module::set_entry_dir(cwd);
    }
    module::install_entry_globals(origin);
    let value = run_compiled_from(
        compile_completion(src)?,
        Some(host::ScriptOrigin::named(origin)),
    )?;
    // One argument means no directive processing at all (node returns a lone
    // argument as-is), so this call has nothing that can throw.
    let line = stdlib::util::format(std::slice::from_ref(&value))?;
    host::with_host(|h| h.write_out(&format!("{line}\n"), false));
    Ok(())
}

/// Run a JS source string on a fresh host with `globals` bound and the
/// program's output captured in-process, returning the program's outcome
/// alongside everything it wrote.
///
/// This is the entry point for an embedder rather than for the `node` binary,
/// and it exists because [`eval_str`] cannot serve one: it resets the host
/// first, which wipes any global installed beforehand, and it lets
/// `console.log` reach the real stdout, which corrupts a host that owns the
/// terminal. Both are fixed here — the globals are seeded *after* the reset,
/// and every write the program makes lands in the returned string.
///
/// The outcome and the output are returned separately (rather than the output
/// only on success) because a program that prints and *then* throws produced
/// both, and an embedder generally wants to show both.
///
/// Globals are given as text and interned as real JS strings here. They are
/// deliberately *not* `Value`: strings live on this host's heap as
/// `JsObj::Str`, so a `Value::Str` a caller builds is at best coerced and at
/// worst method-less. Handing the host text and letting it intern removes that
/// trap, and matches the sibling runtimes' embedder entry points.
///
/// ```no_run
/// let (result, out) = nodejs::eval_str_captured("console.log(stdin.toUpperCase())", &[("stdin", "hi")]);
/// assert!(result.is_ok());
/// assert_eq!(out, "HI\n");
/// ```
pub fn eval_str_captured(src: &str, globals: &[(&str, &str)]) -> (Result<Value, String>, String) {
    run_on_fresh_host(src, |h| {
        for (name, text) in globals {
            let value = h.new_str(*text);
            h.set_global(name, value);
        }
        h.begin_capture();
    })
}

/// Reset the host, let `setup` prepare it (globals, capture, stdin), run `src`
/// to completion, and return the outcome with whatever capture collected.
/// Shared by [`eval_str_captured`] and [`embed::run_program`].
pub(crate) fn run_on_fresh_host(
    src: &str,
    setup: impl FnOnce(&mut host::JsHost),
) -> (Result<Value, String>, String) {
    host::reset_host();
    if let Ok(cwd) = std::env::current_dir() {
        module::set_entry_dir(cwd);
    }
    host::with_host(setup);
    let result = compile_or_load(src).and_then(run_compiled);
    let output = host::with_host(|h| h.end_capture());
    (result, output)
}

/// Read and run a `.js` file (transparently rkyv-cached — see `compile_or_load`).
pub fn eval_file(path: &str) -> Result<Value, String> {
    let src = std::fs::read_to_string(path).map_err(|e| format!("cannot read {path}: {e}"))?;
    host::reset_host();
    // Top-level `require` in `node app.js` resolves from the entry file's dir.
    let dir = std::path::Path::new(path)
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .map(std::path::Path::to_path_buf)
        .or_else(|| std::env::current_dir().ok())
        .unwrap_or_default();
    let dir = std::fs::canonicalize(&dir).unwrap_or(dir);
    module::set_entry_dir(dir);
    // `__filename` is the entry script's REALPATH, not the path that was typed:
    // Node's loader calls `toRealPath` on the main module, so a script reached
    // through a symlinked directory reports the link TARGET. (`process.argv[1]`
    // is the opposite — it keeps the spelling; both measured on node v26.7.0.)
    let entry = std::fs::canonicalize(path)
        .map(|p| p.to_string_lossy().into_owned())
        .unwrap_or_else(|_| stdlib::path::resolve_one(path));
    // An ES module entry point: by its `.mjs` extension or its package's
    // `"type": "module"`, or — for a file of undeclared format — because it
    // only parses as a module (node's syntax detection). It sees none of the
    // CommonJS wrapper names.
    let entry_path = std::path::Path::new(&entry);
    let format = esm::file_format_declared(entry_path);
    let is_module = match format {
        Some(f) => f == esm::Format::Module,
        None => match compile_or_load(&src) {
            Ok(prog) => {
                module::install_entry_globals(&entry);
                return run_compiled_from(prog, Some(host::ScriptOrigin::named(&entry)));
            }
            Err(e) => {
                let at = parser::take_error_pos();
                if !esm::detect_module(&src, &e) {
                    return Err(syntax_error(&src, &entry, e, at));
                }
                true
            }
        },
    };
    if is_module {
        let main = esm::main_program(&entry, None, true);
        return run_compiled(compiler::compile(&main, false)?);
    }
    module::install_entry_globals(&entry);
    let prog = compile_or_load(&src).map_err(|e| {
        let at = parser::take_error_pos();
        syntax_error(&src, &entry, e, at)
    })?;
    run_compiled_from(prog, Some(host::ScriptOrigin::named(&entry)))
}

/// A SyntaxError (or other compile error) `e` from the entry script `src`,
/// recorded so the report shows node's arrow at `at` (see
/// `host::note_syntax_error`).
fn syntax_error(src: &str, origin: &str, e: String, at: ast::Pos) -> String {
    host::note_syntax_error(src, host::ScriptOrigin::named(origin), &e, at);
    e
}

/// Read and run a `.js` file under the DAP debugger.
pub fn eval_file_debug(path: &str) -> Result<Value, String> {
    let src = std::fs::read_to_string(path).map_err(|e| format!("cannot read {path}: {e}"))?;
    let prog = compile_debug(&src)?;
    host::reset_host();
    host::set_debug_mode(true);
    let r = run_compiled(prog);
    host::set_debug_mode(false);
    r
}