node-js 0.1.0

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

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="color-scheme" content="dark light">
  <meta name="description" content="node-js — JavaScript in Rust. A compiled JavaScript runtime: source lexed and parsed to an AST, lowered to fusevm bytecode, and run on the shared bytecode VM with a Cranelift JIT over a JsHost object heap. The binary is node. MIT licensed.">
  <title>node-js — Documentation</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;600;700;900&amp;family=Share+Tech+Mono&amp;display=swap" rel="stylesheet">
  <link rel="stylesheet" href="hud-static.css">
  <link rel="stylesheet" href="tutorial.css">
  <style>
    .tutorial-main { max-width: 68rem; }
    .docs-build-line { margin: 0.35rem 0 0; font-family: 'Share Tech Mono', ui-monospace, monospace; font-size: 11px; color: var(--text-dim); letter-spacing: 0.03em; max-width: 48rem; opacity: 0.75; }
    .hub-scheme-strip { border-bottom: 1px dashed var(--border); background: color-mix(in srgb, var(--bg-secondary) 85%, transparent); padding: 0.55rem 1.5rem 0.65rem; position: relative; }
    .hub-scheme-strip-inner { max-width: 68rem; margin: 0 auto; display: flex; align-items: center; gap: 0.85rem; }
    .hub-scheme-strip .hud-scheme-label { flex: 0 0 auto; font-family: 'Orbitron', sans-serif; font-size: 9px; font-weight: 700; letter-spacing: 2px; text-transform: uppercase; color: var(--accent); text-align: left; }
    .hub-scheme-strip .scheme-grid { flex: 1 1 auto; display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 6px; }
    @media (max-width: 720px) { .hub-scheme-strip-inner { flex-direction: column; align-items: stretch; } .hub-scheme-strip .scheme-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
    .cat-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr)); gap: 0.6rem; margin: 0.7rem 0; }
    .cat-card { border: 1px solid var(--border); border-left: 2px solid var(--cyan); padding: 0.6rem 0.8rem; background: color-mix(in srgb, var(--bg-card) 92%, transparent); border-radius: 2px; }
    .cat-card h4 { font-family: 'Orbitron', sans-serif; font-size: 11px; font-weight: 700; letter-spacing: 1.5px; text-transform: uppercase; color: var(--cyan); margin: 0 0 0.35rem; }
    .cat-card p { margin: 0; font-size: 11.5px; color: var(--text-dim); line-height: 1.5; }
    .cat-card code { font-size: 11px; color: var(--accent-light); }
    .reflection-table { width: 100%; border-collapse: collapse; margin: 0.6rem 0 0.2rem; font-size: 12px; }
    .reflection-table th { background: var(--bg-secondary); color: var(--cyan); font-family: 'Orbitron', sans-serif; font-size: 10px; font-weight: 700; letter-spacing: 1px; text-transform: uppercase; text-align: left; padding: 6px 10px; border: 1px solid var(--border); }
    .reflection-table td { padding: 6px 10px; border: 1px solid var(--border); color: var(--text-dim); vertical-align: top; }
    .reflection-table td code { color: var(--accent-light); background: var(--bg); }
    .status-pill { display: inline-block; font-family: 'Orbitron', sans-serif; font-size: 9px; font-weight: 700; letter-spacing: 1px; text-transform: uppercase; padding: 2px 7px; border-radius: 2px; border: 1px solid var(--border); }
    .status-implemented { color: var(--green); border-color: var(--green); }
    .status-progress { color: var(--accent-light); }
    .status-planned { color: var(--text-muted); }
  </style>
</head>
<body>
  <div class="app tutorial-app" id="docsApp">
    <div class="crt-scanline" id="crtH" aria-hidden="true"></div>
    <div class="crt-scanline-v" id="crtV" aria-hidden="true"></div>

    <header class="tutorial-header">
      <div class="tutorial-header-inner">
        <div>
          <h1 class="tutorial-brand">// NODE-JS — JAVASCRIPT IN RUST</h1>
          <nav class="tutorial-crumbs" aria-label="Breadcrumb">
            <span class="current">Docs</span>
            <span class="sep">/</span>
            <a href="report.html">Engineering Report</a>
            <span class="sep">/</span>
            <a href="https://github.com/MenkeTechnologies/node-js" target="_blank" rel="noopener noreferrer">GitHub</a>
          </nav>
          <p class="docs-build-line">node-js v0.1.0 · JavaScript on fusevm · lex/parse → AST → bytecode → Cranelift JIT · JsHost object heap · binary <code>node</code> · a fusevm language host (with zshrs, stryke, awkrs, pythonrs, rubylang) · MIT · in active development</p>
        </div>
        <div class="tutorial-toolbar">
          <button type="button" class="btn btn-secondary" id="btnTheme" title="Toggle light/dark">Theme</button>
          <button type="button" class="btn btn-secondary active" id="btnCrt" title="CRT scanline overlay">CRT</button>
          <button type="button" class="btn btn-secondary active" id="btnNeon" title="Neon border pulse">Neon</button>
          <a class="btn btn-secondary" href="report.html">Report</a>
          <a class="btn btn-secondary" href="https://github.com/MenkeTechnologies/node-js" target="_blank" rel="noopener noreferrer">GitHub</a>
          <a class="btn btn-secondary" href="https://github.com/MenkeTechnologies/node-js/issues" target="_blank" rel="noopener noreferrer">Issues</a>
        </div>
      </div>
    </header>

    <div class="hub-scheme-strip">
      <div class="hub-scheme-strip-inner">
        <span class="hud-scheme-label">// Color scheme</span>
        <div class="scheme-grid" id="hudSchemeGrid"></div>
      </div>
    </div>

    <main class="tutorial-main">
      <h2 class="tutorial-title"><span class="step-hash">&gt;_</span>NODE-JS REFERENCE</h2>
      <p class="tutorial-subtitle">A compiled JavaScript runtime written in Rust. Source is lexed and parsed to an AST, lowered to <code>fusevm</code> bytecode, and executed on the same language-agnostic VM + Cranelift JIT that hosts <code>zshrs</code>, <code>stryke</code>, <code>awkrs</code>, <code>pythonrs</code>, and <code>rubylang</code>, over a <code>JsHost</code> object heap. The binary is <code>node</code>. <strong>In active development.</strong></p>

      <section class="tutorial-section">
        <h2>What it is</h2>
        <p><code>node-js</code> runs JavaScript programs as ordinary compiled bytecode: it lexes and parses the source, lowers it to <code>fusevm</code> instructions, and lets the shared engine execute and JIT-compile them. There is no bespoke VM or tree-walker — arithmetic and comparisons lower to native fusevm ops so the Cranelift JIT can trace hot loops, while JS-specific behaviour (truthiness, <code>==</code> coercion, <code>+</code> overloading, <code>ToInt32</code> bitwise wrap, number formatting, the builtin objects) is served by the <code>JsHost</code> object heap.</p>
        <p>It is another language hosted on <a href="https://github.com/MenkeTechnologies/fusevm">fusevm</a>, the shared bytecode VM and Cranelift JIT behind <code>zshrs</code>, <code>stryke</code>, <code>awkrs</code>, <code>pythonrs</code>, and <code>rubylang</code>. node-js carries no VM or JIT of its own.</p>
      </section>

      <section class="tutorial-section">
        <h2>Architecture</h2>
        <p>The pipeline mirrors how the sibling frontends host their languages:</p>
        <pre>JS source  →  lexer  →  parser (AST)  →  lower to fusevm bytecode  →  fusevm VM + Cranelift JIT
                                                │
                                  JsHost object heap (objects/arrays/strings, builtins, numeric hook)</pre>
        <div class="cat-grid">
          <div class="cat-card"><h4>fusevm-hosted</h4><p>No local <code>vm.rs</code> / <code>jit.rs</code>. JS is lowered to fusevm bytecode and executed on the shared Cranelift JIT; <code>jit-disk-cache</code> persists native code across runs.</p></div>
          <div class="cat-card"><h4>Native arithmetic + numeric hook</h4><p>Operators lower to native fusevm ops; a strict numeric hook supplies JS coercion (<code>+</code> string concat, the <code>==</code> matrix, <code>ToInt32</code> for bitwise ops) only for the non-numeric operand cases.</p></div>
          <div class="cat-card"><h4>Arrow-function lookahead</h4><p>Arrow functions are detected at assignment level by looking ahead for <code>=&gt;</code> after a parameter list; template-literal <code>${...}</code> fields are re-parsed from the raw source (<code>src/parser.rs</code>).</p></div>
          <div class="cat-card"><h4>Ordered objects</h4><p>Objects, strings, and arrays live on the <code>JsHost</code> heap behind <code>Value::Obj(u32)</code> handles; property insertion order is preserved (an <code>IndexMap</code>), observable in iteration and JSON round-trips.</p></div>
        </div>
      </section>

      <section class="tutorial-section">
        <h2>Example</h2>
<pre>const fib = n =&gt; (n &lt; 2 ? n : fib(n - 1) + fib(n - 2));

console.log([...Array(11).keys()].map(fib).join(", "));
// =&gt; 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55

let total = 0;
for (const x of [1, 2, 3, 4]) total += x;
console.log(total);                       // =&gt; 10

const o = { b: 2, a: 1 };
console.log(JSON.stringify(Object.keys(o)));   // =&gt; ["b","a"]

const name = "world";
console.log(`hello, ${name}! ${6 * 7}`);  // =&gt; hello, world! 42</pre>
      </section>

      <section class="tutorial-section">
        <h2>Usage</h2>
<pre>node script.js                     # run a file
node -e 'console.log(1 + 1)'       # evaluate a one-liner
echo 'console.log(6 * 7)' | node   # read a script from stdin</pre>
        <p>Errors go to stderr in terse <code>node: &lt;reason&gt;</code> form; nothing else is printed. Runnable <code>examples/*.js</code> ship with the crate.</p>
      </section>

      <section class="tutorial-section">
        <h2>Status &amp; roadmap</h2>
        <p>A working core, grown outward from the sibling frontends. The table reflects the current state of the tree.</p>
        <table class="reflection-table">
          <thead><tr><th>Component</th><th>State</th><th>Notes</th></tr></thead>
          <tbody>
            <tr><td>Lexer / parser → AST</td><td><span class="status-pill status-implemented">Implemented</span></td><td>Tokenizer with newline tracking; arrow-function <code>=&gt;</code> lookahead; template-literal <code>${...}</code> re-lex (<code>src/lexer.rs</code>, <code>src/parser.rs</code>).</td></tr>
            <tr><td>AST → fusevm bytecode lowering</td><td><span class="status-pill status-implemented">Implemented</span></td><td>Native arithmetic + <code>CallBuiltin</code> dispatch; func/arrow/try sub-chunks; no local VM (<code>src/compiler.rs</code>).</td></tr>
            <tr><td>Bindings &amp; operators</td><td><span class="status-pill status-implemented">Implemented</span></td><td><code>var</code>/<code>let</code>/<code>const</code>; full arithmetic/comparison/logical/bitwise/nullish surface, <code>typeof</code>/<code>void</code>/<code>delete</code>/<code>instanceof</code>/<code>in</code>, <code>?:</code>, <code>++</code>/<code>--</code>, compound assign.</td></tr>
            <tr><td>Control flow</td><td><span class="status-pill status-implemented">Implemented</span></td><td><code>if</code>/<code>else</code>, <code>while</code>, <code>do…while</code>, <code>for</code>, <code>for…in</code>, <code>for…of</code>, <code>switch</code>, <code>break</code>/<code>continue</code>/<code>return</code>, <code>throw</code>, <code>try</code>/<code>catch</code>/<code>finally</code>.</td></tr>
            <tr><td>Functions, arrows, closures</td><td><span class="status-pill status-implemented">Implemented</span></td><td>Declarations and expressions, arrow functions, closures, recursion, <code>new</code> (<code>src/host.rs</code>).</td></tr>
            <tr><td>Literals, spread, templates</td><td><span class="status-pill status-implemented">Implemented</span></td><td>Array/object literals, member/index access, spread <code>...</code>, template literals.</td></tr>
            <tr><td>Builtin objects &amp; methods</td><td><span class="status-pill status-implemented">Implemented</span></td><td><code>console</code>, <code>Math</code>, <code>JSON</code>, <code>Object</code>, <code>Array</code>, <code>Number</code>, <code>String</code>, <code>Boolean</code>, <code>parseInt</code>/<code>parseFloat</code>/<code>isNaN</code>/<code>isFinite</code>, and a broad array/string method set (<code>src/builtins.rs</code>).</td></tr>
            <tr><td>Differential parity (harness + fuzzer)</td><td><span class="status-pill status-implemented">Implemented</span></td><td>Frozen corpus replayed with no <code>node</code> installed (<code>tests/parity.rs</code>); generative fuzzer diffs <code>node -e</code> vs reference (<code>src/bin/parity.rs</code>, <code>src/bin/parity_fuzz.rs</code>). Dev tools, never in CI.</td></tr>
            <tr><td>AOT native-exe &amp; bytecode cache</td><td><span class="status-pill status-progress">Scaffolded</span></td><td>Crate is a <code>staticlib</code> with fusevm's <code>aot</code> + <code>jit-disk-cache</code> features enabled (mirrors pythonrs), but not yet exposed on the CLI.</td></tr>
            <tr><td>Classes / async / modules / stdlib</td><td><span class="status-pill status-planned">Planned</span></td><td><code>class</code>, <code>async</code>/<code>await</code>, generators, ES modules, destructuring, default/rest params, <code>RegExp</code>, <code>Map</code>/<code>Set</code>/<code>Promise</code>, and the Node.js standard library.</td></tr>
          </tbody>
        </table>
      </section>

      <section class="tutorial-section">
        <h2>Building from source</h2>
        <p>node-js builds as a standalone Rust crate (an explicit empty <code>[workspace]</code> keeps it independent of the meta repo):</p>
<pre># clone
git clone https://github.com/MenkeTechnologies/node-js
cd node-js

# build (produces target/debug/node + parity + parity-fuzz)
cargo build

# run a file or a one-liner
./target/debug/node script.js
./target/debug/node -e 'console.log([1,2,3].reduce((a,b)=&gt;a+b, 0))'

# run tests (parity corpus replays with no node installed)
cargo test</pre>
        <p><code>fusevm</code> is pulled from crates.io with the <code>jit</code>, <code>jit-disk-cache</code>, and <code>aot</code> features.</p>
      </section>

      <section class="tutorial-section">
        <h2>License</h2>
        <p>node-js is <strong>MIT licensed</strong> — free and open source. See <a href="https://github.com/MenkeTechnologies/node-js/blob/main/LICENSE">LICENSE</a>.</p>
      </section>

      <section class="tutorial-section">
        <h2>Repository &amp; links</h2>
        <ul>
          <li><strong>Engineering report</strong> — <a href="report.html">report.html</a> (architecture, fusevm hosting, parity, roadmap, dependency posture)</li>
          <li><strong>Source</strong> — <a href="https://github.com/MenkeTechnologies/node-js">github.com/MenkeTechnologies/node-js</a></li>
          <li><strong>Issues</strong> — <a href="https://github.com/MenkeTechnologies/node-js/issues">github.com/MenkeTechnologies/node-js/issues</a></li>
          <li><strong>The shared VM</strong> — <a href="https://github.com/MenkeTechnologies/fusevm">fusevm</a> (also behind <code>zshrs</code>, <code>stryke</code>, <code>awkrs</code>, <code>pythonrs</code>, <code>rubylang</code>)</li>
        </ul>
      </section>
    </main>
  </div>

  <script src="hud-theme.js"></script>
</body>
</html>