jz 0.4.0 → 0.5.0

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "jz",
-  "version": "0.4.0",
-  "description": "Modern functional JS compiling to WASM",
+  "version": "0.5.0",
+  "description": "Functional JS subset compiling to WASM",
   "main": "index.js",
   "type": "module",
   "exports": {
     ".": "./index.js",
-    "./wasi": "./wasi.js"
+    "./wasi": "./wasi.js",
+    "./interop": "./interop.js"
   },
   "files": [
     "index.js",
     "cli.js",
     "wasi.js",
+    "interop.js",
     "src",
     "module",
     "README.md"
@@ -26,8 +28,9 @@
     "bench": "node bench/bench.mjs",
     "bench:size": "node scripts/bench-size.mjs",
     "bench:compile": "node scripts/bench-compile.mjs",
-    "test:bench-pin": "node test/bench-pin.js",
-    "test:all": "npm test && npm run test:bench-pin",
+    "build:examples": "for dir in examples/*; do node \"$dir/build.mjs\"; done",
+    "test:bench": "node test/bench.js",
+    "test:all": "npm test && npm run test:bench",
     "prepublishOnly": "npm run test:all"
   },
   "repository": {
@@ -41,8 +44,8 @@
   "author": "Dmitry Iv",
   "license": "MIT",
   "dependencies": {
-    "subscript": "^10.4.8",
-    "watr": "^4.6.5"
+    "subscript": "^10.4.15",
+    "watr": "^4.6.9"
   },
   "keywords": [
     "javascript",

package/src/abi/array.js

@@ -0,0 +1,89 @@
+/**
+ * src/abi/array — ARRAY backing-store carriers.
+ *
+ * An ARRAY value is an `__alloc_hdr` block — `[-8:len(i32)][-4:cap(i32)]` then
+ * N element cells. The carrier owns where element `i` lives and how wide each
+ * cell is. Every array-element access routed through `ctx.abi.array.ops` reads
+ * layout from one place: the `[…]` literal store, the elem-schema fast-path
+ * read, the `ir.js` element helpers (`slotAddr`/`elemLoad`/`elemStore`, and so
+ * `arrayLoop`), the boxed-handle inner-array load.
+ *
+ * Ops are cycle-safe (no `src/*` imports) and return raw wasm IR arrays;
+ * callers wrap in `typed()`. `base` is an i32 IR node holding the array's data
+ * offset (post-header — a `['local.get', …]`, a `['local.tee', …]`, or a
+ * `['call', '$__ptr_offset', …]` that follows the grow-forwarding chain). `idx`
+ * is either a JS integer (constant slot — folds the multiply) or an i32 IR node
+ * (runtime index).
+ *
+ *   taggedLinear — today's layout: every element one 8-byte f64 cell. An
+ *                  element holds a raw f64 (Array<NUMBER>) or a NaN-boxed
+ *                  pointer (Array<OBJECT|STRING>); both are 8 bytes wide, so
+ *                  one carrier serves every plain `[]`.
+ *
+ *   structInline — SRoA layout for an `Array<{uniform K-field schema}>` whose
+ *                  element pointers never escape as object identities: the K
+ *                  f64 schema fields are inlined into the data region (stride
+ *                  K), so `rows[i].x` is one direct `f64.load` with no per-row
+ *                  object allocation and no pointer indirection. `len`/`cap`
+ *                  still count *physical* f64 cells, so every stride-8 helper
+ *                  (`__alloc_hdr`, `__arr_grow`, `__len`, `__set_len`) is
+ *                  reused untouched — `.push` of a struct writes K cells and
+ *                  adds K to `len`; `.length` divides the physical len by K.
+ *                  Picked per-schema by `analyzeStructInline` (src/analyze.js),
+ *                  whole-program, default-disqualify.
+ *
+ * Typed arrays (`Float64Array`/`Int32Array`/…) are a distinct value type
+ * (`VAL.TYPED`, ctor-determined stride) handled by `module/typedarray.js`, not
+ * a carrier here — they are not `VAL.ARRAY`.
+ *
+ * @module src/abi/array
+ */
+
+// Byte address of element `idx` off an i32 base. A JS-integer idx folds the
+// `*8` (and idx=0 returns base untouched — matches `slotAddr`); an IR-node idx
+// emits the runtime `i32.shl … 3`.
+const addr = (base, idx) =>
+  typeof idx === 'number'
+    ? (idx === 0 ? base : ['i32.add', base, ['i32.const', idx * 8]])
+    : ['i32.add', base, ['i32.shl', idx, ['i32.const', 3]]]
+
+export const taggedLinear = {
+  // Element operations the compiler routes array access through.
+  ops: {
+    // Byte address of element `idx` — for callers that need the address
+    // itself (`slotAddr`) rather than a load/store.
+    addr,
+
+    // Element `idx` read as the canonical f64 value.
+    load: (base, idx) => ['f64.load', addr(base, idx)],
+
+    // Element `idx` read as raw i64 bits — moves a slot without reinterpreting
+    // through f64.
+    loadBits: (base, idx) => ['i64.load', addr(base, idx)],
+
+    // Element `idx` write of an f64-typed value IR node.
+    store: (base, idx, val) => ['f64.store', addr(base, idx), val],
+  },
+}
+
+// structInline(K) — SRoA carrier factory. Logical element `idx` occupies K
+// consecutive 8-byte cells; the carrier hands back the byte address of the
+// element's first cell, and field `f` is then a plain `+f*8` composed by the
+// schema slot machinery (`ctx.abi.object.ops`). Built on demand per schema
+// (`K = ctx.schema.list[sid].length`) — not a `ctx.abi` default.
+export const structInline = (K) => ({
+  K,
+  ops: {
+    // Byte address of logical element `idx`'s first cell off i32 `base`.
+    // A JS-integer idx folds to a constant; an IR-node idx emits `idx*K`
+    // then the `<<3` (via `addr`).
+    elemAddr: (base, idx) =>
+      typeof idx === 'number'
+        ? addr(base, idx * K)
+        : addr(base, K === 1 ? idx : ['i32.mul', idx, ['i32.const', K]]),
+  },
+})
+
+// Default carrier — picked when the narrower has no stronger evidence.
+// Reached via `ctx.abi.array`.
+export default taggedLinear

package/src/abi/index.js

@@ -0,0 +1,35 @@
+/**
+ * src/abi — internal codegen carriers.
+ *
+ * The `abi/` directory hosts compiler-internal codegen modules — one file per
+ * value type, each exporting every carrier (slot strategy) the compiler may
+ * pick for that type. **No user surface.** `opts.host` is the only knob users
+ * see; internal representation is analysis-driven and per-site.
+ *
+ * Today the narrower has not yet been wired to pick carriers per site, so
+ * each type module's `default` export is used as the carrier for every site
+ * of that type. `ctx.abi.<type>` resolves to that default; codegen reads
+ * `ctx.abi.string.ops.byteLen(...)` etc. Per-site dispatch arrives by
+ * exposing all carriers (`ctx.abi.string.sso`, `.jsstring`) and letting
+ * `narrow.js` tag each binding with a carrier choice.
+ *
+ * No presets, no preset-name discriminant, no public ABI knob — carrier
+ * choice is analysis-driven, not user-pickable. See `.work/todo.md`
+ * "Boundary protocol and internal representation" for the policy.
+ *
+ * @module src/abi
+ */
+
+import nanboxF64 from './number.js'
+import sso, { jsstring } from './string.js'
+import tagged from './object.js'
+import taggedLinear, { structInline } from './array.js'
+
+/** The default carrier bundle — what `ctx.abi` resolves to. Identity-stable
+ *  reference so codegen can compare without string keys. */
+export const DEFAULTS = Object.freeze({ number: nanboxF64, string: sso, object: tagged, array: taggedLinear })
+
+// Carrier re-exports — for tests and tools that want to reach a specific
+// carrier directly. Per-site narrowing will use these via `ctx.abi.<type>`
+// once the narrower exposes the full carrier dictionary.
+export { nanboxF64, sso, jsstring, tagged, taggedLinear, structInline }

package/src/abi/number.js

@@ -0,0 +1,137 @@
+/**
+ * src/abi/number — number carriers.
+ *
+ * One file holds every strategy the compiler may pick for a number-typed
+ * binding. Today `nanboxF64` is the only carrier; flat-i32 / flat-f64
+ * specialization is achieved through direct type narrowing in `narrow.js`
+ * (Phase E i32 results, Phase E3 pointer results, locals/params lifted by
+ * the fixpoint) rather than via a carrier-bundle dispatch. The single-carrier
+ * `ctx.abi` infrastructure is scaffold for the architectural cleanup that
+ * would migrate those narrowed cases into named carriers here. See
+ * `.work/todo.md` "Boundary protocol and internal representation".
+ *
+ * Carriers:
+ *   - `nanboxF64`  default. f64 carrier with NaN-boxed pointers. Owns the
+ *                  NaN-box-layout peephole folds — pure-WASM equivalences
+ *                  (`wrap(extend x)→x`, `trunc(convert x)→x`, …) stay in
+ *                  `src/optimize.js`; the folds here assume the low 32 bits
+ *                  of a NaN-boxed f64 are the pointer offset.
+ *
+ * No `name`/`type` discriminant field — carriers are referenced by object
+ * identity from the default-bundle in `src/abi/index.js`.
+ *
+ * @module src/abi/number
+ */
+
+// ── nanboxF64 ─────────────────────────────────────────────────────────────
+
+export const nanboxF64 = {
+  slotTypes: ['f64'],
+
+  /**
+   * Carrier-specific peephole rules — folds that depend on the NaN-box layout.
+   * Called by the optimizer's fused-rewrite walk after generic folds; returns
+   * a replacement node or `null` to leave the node unchanged.
+   *
+   * The folds:
+   *   1. `i64.reinterpret_f64 (f64.reinterpret_i64 x)` → `x` — rebox-undo.
+   *      Re-introduced by watr's inliner at boundaries (caller's `boxPtrIR(g)`
+   *      meets callee's `i32.wrap_i64 (i64.reinterpret_f64 __env)`), so the
+   *      post-watr reopt pass needs this to keep nanbox call boundaries clean.
+   *   2. `f64.reinterpret_i64 (i64.reinterpret_f64 x)` → `x` — unbox-undo.
+   *   3. `i32.wrap_i64 (i64.reinterpret_f64 (f64.load A ?off))` → `i32.load A ?off`.
+   *      Wasm is little-endian; the low 32 bits of a NaN-boxed f64 at A are
+   *      exactly i32.load(A). Saves two ops on every pointer extraction from
+   *      an array slot or struct field.
+   *   4. `i32.wrap_i64 (i64.reinterpret_f64 (call $__mkptr* … offset))` → offset.
+   *      A NaN-boxed pointer keeps type/aux in the high bits and the i32
+   *      offset in the low 32, so the f64 round-trip is pure overhead when the
+   *      consumer only wants the offset. Covers generic `$__mkptr` and
+   *      specialized `$__mkptr_T_A_d` trampolines (offset is the last arg).
+   *   5. As (4) but reaching through `(block (result f64) … (call $__mkptr …))`
+   *      — `new TypedArray(n)` lowers to this shape — by retyping the block
+   *      to i32 and dropping the box on its tail.
+   *   6. `i32.wrap_i64 (i64.or HIGH_ONLY (i64.extend_i32_* X))` → X.
+   *      The NaN-tag-or-extend pattern: high bits hold the NaN prefix + tag,
+   *      low 32 bits carry the i32 offset unchanged.
+   */
+  peephole(node) {
+    const op = node[0]
+
+    if (op === 'i64.reinterpret_f64' && node.length === 2) {
+      const a = node[1]
+      if (Array.isArray(a) && a[0] === 'f64.reinterpret_i64' && a.length === 2) return a[1]
+      return null
+    }
+
+    if (op === 'f64.reinterpret_i64' && node.length === 2) {
+      const a = node[1]
+      if (Array.isArray(a) && a[0] === 'i64.reinterpret_f64' && a.length === 2) return a[1]
+      return null
+    }
+
+    if (op === 'i32.wrap_i64' && node.length === 2) {
+      const a = node[1]
+
+      if (Array.isArray(a) && a[0] === 'i64.reinterpret_f64' && a.length === 2) {
+        const inner = a[1]
+        // (3) wrap(reinterpret(f64.load ADDR ?offset)) → (i32.load ADDR ?offset)
+        if (Array.isArray(inner) && inner[0] === 'f64.load') {
+          const out = ['i32.load']
+          for (let i = 1; i < inner.length; i++) out.push(inner[i])
+          return out
+        }
+        // (4) wrap(reinterpret(call $__mkptr* … offset)) → offset
+        if (isMkptr(inner)) return inner[inner.length - 1]
+        // (5) reach through (block (result f64) … (call $__mkptr*))
+        if (Array.isArray(inner) && inner[0] === 'block' && isMkptr(inner[inner.length - 1])) {
+          let ri = -1
+          for (let i = 1; i <= 2 && i < inner.length; i++) {
+            if (Array.isArray(inner[i]) && inner[i][0] === 'result') { ri = i; break }
+          }
+          if (ri >= 0 && inner[ri][1] === 'f64') {
+            const tail = inner[inner.length - 1]
+            const nb = inner.slice()
+            nb[ri] = ['result', 'i32']
+            nb[nb.length - 1] = tail[tail.length - 1]
+            return nb
+          }
+        }
+        return null
+      }
+
+      // (6) wrap(or HIGH_ONLY (extend X)) → X
+      if (Array.isArray(a) && a[0] === 'i64.or' && a.length === 3) {
+        const l = a[1], r = a[2]
+        if (isHighOnly(l) && isExtend(r)) return r[1]
+        if (isHighOnly(r) && isExtend(l)) return l[1]
+      }
+    }
+
+    return null
+  },
+}
+
+// ── helpers (carrier-local; cycle-safe — no src/* import) ─────────────────
+
+const isMkptr = (n) => Array.isArray(n) && n[0] === 'call' && typeof n[1] === 'string'
+  && (n[1] === '$__mkptr' || n[1].startsWith('$__mkptr_'))
+
+const isExtend = (n) => Array.isArray(n) &&
+  (n[0] === 'i64.extend_i32_u' || n[0] === 'i64.extend_i32_s') && n.length === 2
+
+const isHighOnly = (n) => {
+  if (!Array.isArray(n) || n[0] !== 'i64.const') return false
+  const v = n[1]
+  let bi
+  if (typeof v === 'number') bi = BigInt(v)
+  else if (typeof v === 'string') {
+    try { bi = v.startsWith('-') ? -BigInt(v.slice(1)) : BigInt(v) } catch { return false }
+  } else return false
+  return (bi & 0xFFFFFFFFn) === 0n
+}
+
+// Default carrier — picked when narrower has no stronger evidence. Reached
+// via `ctx.abi.number` (which the default-bundle in `src/abi/index.js` binds
+// to this export).
+export default nanboxF64

package/src/abi/object.js

@@ -0,0 +1,57 @@
+/**
+ * src/abi/object — OBJECT layout carriers.
+ *
+ * An OBJECT value is `__alloc_hdr` + N field cells; the carrier owns where
+ * field `i` lives and how wide each cell is. Every object-field access in the
+ * compiler — literal stores, `.prop` / `obj['k']` reads & writes, the bulk
+ * copies in `Object.values`/`entries`/`assign`/`create` and object spread,
+ * JSON-const objects, boxed-handle slot 0, `toPrimitive` method slots —
+ * routes through `ctx.abi.object.ops` so layout lives in one place.
+ *
+ * Ops are cycle-safe (no `src/*` imports) and return raw wasm IR arrays;
+ * callers wrap in `typed()`. `base` is an i32 IR node holding the object's
+ * data offset (a `['local.get', …]` or a `ptrOffsetIR(…)` expression).
+ *
+ *   tagged  — today's layout: schema-tagged, every field one 8-byte f64 cell.
+ *
+ * A future `packed` carrier (narrowing per-field width from
+ * `ctx.schema.slotIntCertain` / `slotTypes`) slots in here without touching a
+ * single call site — that is the seam this file exists to provide.
+ *
+ * `flat` (SRoA) is the third object strategy but lives outside this seam: a
+ * non-escaping `let/const o = {staticLiteral}` binding has no heap presence at
+ * all — its fields are dissolved into plain WASM locals (`o#0`, `o#1`, …) and
+ * `o.prop` compiles to `local.get`. It carries no memory base, so it cannot be
+ * expressed as `ops.load(base, i)`; it is a binding-dissolution transform
+ * driven by `scanFlatObjects` (src/analyze.js) and the codegen flat hooks
+ * (emitDecl, the `.`/`[]` read & write emitters), not a layout carrier here.
+ *
+ * @module src/abi/object
+ */
+
+// Byte address of field `i` off an i32 base. idx=0 returns the base node
+// untouched — matches `slotAddr` so routed sites stay byte-identical.
+const addr = (base, i) => i === 0 ? base : ['i32.add', base, ['i32.const', i * 8]]
+
+export const tagged = {
+  // Field operations the compiler routes object access through.
+  ops: {
+    // Heap cells `__alloc_hdr` must reserve for an N-field object. Floored at
+    // 1 so a zero-field object still owns a header-addressable cell.
+    allocSlots: (n) => Math.max(1, n),
+
+    // Field `i` read as the canonical f64 value.
+    load: (base, i) => ['f64.load', addr(base, i)],
+
+    // Field `i` read as raw i64 bits — dyn-shadow writes and cross-schema
+    // copies move slots without reinterpreting through f64.
+    loadBits: (base, i) => ['i64.load', addr(base, i)],
+
+    // Field `i` write of an f64-typed value IR node.
+    store: (base, i, val) => ['f64.store', addr(base, i), val],
+  },
+}
+
+// Default carrier — picked when the narrower has no stronger evidence.
+// Reached via `ctx.abi.object`.
+export default tagged