jz 0.2.1 → 0.3.1

package/README.md

@@ -68,7 +68,7 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 | `imports: { mod: host }` | Wire host namespaces/functions used by `import { fn } from "mod"`; functions may be plain JS functions or `{ fn, returns }` specs. |
 | `memory` | Pass `memory: N` to create owned memory with `N` initial pages, or pass `memory: jz.memory()` / `WebAssembly.Memory` to share memory across modules. |
 | `host: 'js' \| 'wasi'` | Select runtime-service lowering. Default `js` uses small `env.*` imports auto-wired by `jz()`; `wasi` emits WASI Preview 1 imports for wasmtime/wasmer/deno. |
-| `optimize` | `false`/`0` disables optimization, `1` keeps cheap size passes, `true`/`2` is the default, `3` enables aggressive experimental passes, object form overrides individual passes. |
+| `optimize` | `false`/`0` disables optimization, `1` keeps cheap size passes, `true`/`2` is the default, `3` enables aggressive experimental passes. String aliases `'size'` (unroll/vectorize off, tight scalar caps — smallest wasm), `'balanced'` (= default), `'speed'` (full unroll + SIMD). Object form overrides individual passes/knobs (and accepts `level:` as a number or alias base). |
 | `strict: true` | Reject dynamic fallbacks such as unknown receiver method calls, `obj[k]`, and `for-in` instead of emitting JS-host dynamic dispatch. |
 | `alloc: false` | Omit raw allocator exports like `_alloc`/`_clear` when compiling standalone WASM that never marshals heap values across the host boundary. |
 | `wat: true` | `compile()` returns WAT text instead of a WASM binary. |
@@ -82,7 +82,16 @@ Options are passed as `jz(source, opts)` or `compile(source, opts)`. Common ones
 
 ```sh
 # Compile
-jz program.js # → program.wasm
+jz program.js              # → program.wasm
+jz program.js --wat        # → program.wat
+jz program.js -o out.wasm  # custom output (- for stdout)
+
+# Optimization level: -O0 off, -O1 size-only, -O2 default, -O3 aggressive
+# aliases: -Os/--optimize size, -Ob/balanced, -Of/speed
+jz program.js -O3
+
+# Runtime-service lowering: js (default) or wasi
+jz program.js --host wasi
 
 # Evaluate
 jz -e "1 + 2" # 3
@@ -91,33 +100,12 @@ jz -e "1 + 2" # 3
 jz --help
 ```
 
+Other flags: `--strict` (no auto-`jzify`, reject dynamic fallbacks), `--jzify` (transform JS → jz, no compile), `--no-alloc` (omit `_alloc`/`_clear`), `--names` (emit wasm `name` section), `--resolve` (Node.js bare-specifier resolution), `--imports <file.json>` (host import specs).
+
 ## Language
 
 JZ is a strict functional JS subset. Built-in `jzify` transform extends support to legacy patterns.
 
-<!--
-```mermaid
-%%{init: {'flowchart': {'titleTopMargin': 0, 'padding': 0, 'margin': 0}}}%%
-flowchart TB
-    classDef plain fill:none,stroke:none,font-size:14px,font-weight:bold,padding:0px,margin:0px
-
-    subgraph JS[JS — not supported]
-        subgraph JZify[JZ + jzify]
-            subgraph JZ[JZ strict]
-                j1["let/const, arrows, default/rest params, flow, break/continue, try/catch/finally, a[]/a()/a.b, operators, strings, booleans, numbers, std, memory, host"]:::plain
-            end
-            z1["var, function, arguments, switch, new Foo(), ==, !=, instanceof"]:::plain
-        end
-        n1["async/await, Promise, generators, this, class, eval, Function, with, Proxy, Reflect, WeakMap, WeakSet, dynamic import, DOM, fetch, Intl, Node APIs"]:::plain
-    end
-
-    style JZ fill:#ffe0b2,stroke-width:0
-    style JZify fill:#fff9c4,stroke-width:0
-    style JS fill:#ffffff,stroke:#ccc,stroke-width:1px
-    style n1 min-width:720px
-```
--->
-
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
 │ JZify                                                                  │
@@ -151,6 +139,10 @@ Not supported
 
 Numbers pass directly as f64, arrays of ≤ 8 elements return as plain JS arrays (multi-value). Strings, arrays, objects, and typed arrays are heap values — `inst.memory` provides read/write across the boundary:
 
+> [!WARNING] jz objects are fixed-layout schemas (like C structs), not dynamic key bags.
+> `memory.Object({ x: 3, y: 4 })` expects the same key order as the jz source `{ x, y }`.
+> `{ y: 4, x: 3 }` with reversed keys will produce wrong values.
+
 ```js
 const { exports, memory } = jz`
   export let greet = (s) => s.length
@@ -494,7 +486,7 @@ cc program.c -o program
 | [bitwise](bench/bitwise/bitwise.js) | 0.98ms<br>1.3kB | 3.76ms<br>1005 B | fails | 8.79ms<br>1.5kB | 4.86ms<br>355 B | 1.30ms | 5.20ms | 4.15ms | 1.30ms | 14.72ms |
 | [poly](bench/poly/poly.js) | 0.27ms<br>1.4kB | 1.62ms<br>1014 B | fails | 0.73ms<br>1.3kB | 0.81ms<br>359 B | 0.57ms | 0.79ms | 0.89ms | 0.63ms | 0.60ms |
 | [callback](bench/callback/callback.js) | 0.03ms<br>1.6kB | 0.69ms<br>828 B | fails | 1.04ms<br>1.9kB | 0.24ms<br>267 B | 0.08ms | 0.23ms | 0.01ms | 0.12ms | 1.78ms |
-| [json](bench/json/json.js) | 0.24ms<br>11.0kB | 0.37ms<br>1.2kB | fails | — | — | 0.03ms | 1.05ms | <0.01ms | 0.03ms | 1.21ms |
+| [json](bench/json/json.js) | 0.25ms<br>10.9kB | 0.36ms<br>1.2kB | fails | — | — | 0.25ms | 1.16ms | 0.64ms | 0.65ms | 1.20ms |
 | [watr](bench/watr/watr.js) | 1.04ms<br>169.8kB | 1.05ms<br>2.6kB | fails | — | — | — | — | — | — | — |
 
 _Numbers from `node bench/bench.mjs` on Apple Silicon. Porffor cells were refreshed with `porf` 0.61.13; `fails` means the latest Porffor compiler/runtime did not complete that benchmark._

package/cli.js

@@ -11,10 +11,14 @@ import { execFileSync } from 'child_process'
 import { parse } from 'subscript/feature/jessie'
 import jz, { compile } from './index.js'
 import jzifyFn, { codegen } from './src/jzify.js'
+import { createRequire } from 'module'
+
+const jzRequire = createRequire(import.meta.url)
+const PKG = jzRequire('./package.json')
 
 function showHelp() {
   console.log(`
-jz - min JS → WASM compiler
+jz v${PKG.version} - min JS → WASM compiler
 
 Usage:
   jz <file.js>              Compile JS to WASM (auto-jzify)
@@ -28,23 +32,38 @@ Examples:
   jz program.js --wat              # → program.wat
   jz program.js -o out.wasm        # custom output name
   jz program.js -o -               # write to stdout
+  jz program.js -O3                # aggressive optimization
+  jz program.js -Os                # optimize for size
+  jz program.js --host wasi        # emit WASI Preview 1 imports
   jz --strict program.js           # strict mode
   jz --jzify lib.js                # → lib.jz
   jz -e "1 + 2"
 
 Options:
   --output, -o <file>       Output file (.wat, .wasm, or - for stdout)
-  --strict                  Strict jz mode (no auto-transform)
+  -O<n>, --optimize <n>     Optimization level: 0 off, 1 size-only, 2 default,
+                            3 aggressive. Aliases: -Os/size, -Ob/balanced, -Of/speed.
+  --host <js|wasi>          Runtime-service lowering (default js)
+  --no-alloc                Omit _alloc/_clear allocator exports (standalone wasm)
+  --names                   Emit wasm name section for profilers/debuggers
+  --strict                  Strict jz mode (no auto-transform), reject dynamic fallbacks
   --jzify                   Transform JS to jz (no compilation)
   --eval, -e                Evaluate expression or file
   --wat                     Output WAT text instead of binary
   --resolve                 Resolve bare specifiers via Node.js module resolution
+  --imports <file>          JSON file with host import specs (e.g. {"env":{"fn":{"params":2}}})
+  --version, -v             Show version number
   `)
 }
 
 async function main() {
   const args = process.argv.slice(2)
 
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(PKG.version)
+    return
+  }
+
   if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
     showHelp()
     return
@@ -98,15 +117,31 @@ async function handleJzify(args) {
   }
 }
 
+// -O<n>/-Os/-Ob/-Of and --optimize <val> → value accepted by compile()'s `optimize` opt
+const OPT_ALIAS = { s: 'size', b: 'balanced', f: 'speed' }
+function parseOptimize(v) {
+  if (v == null) return undefined
+  if (/^\d+$/.test(v)) return +v
+  return OPT_ALIAS[v] ?? v
+}
+
 async function handleCompile(args) {
-  let inputFile = null, outputFile = null, wat = false, strict = false, resolveNode = false
+  let inputFile = null, outputFile = null, wat = false, strict = false, resolveNode = false, importsFile = null
+  let optimize, host, alloc = true, names = false
 
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--output' || args[i] === '-o') outputFile = args[++i]
-    else if (args[i] === '--wat') wat = true
-    else if (args[i] === '--strict') strict = true
-    else if (args[i] === '--resolve') resolveNode = true
-    else if (!inputFile) inputFile = args[i]
+    const a = args[i]
+    if (a === '--output' || a === '-o') outputFile = args[++i]
+    else if (a === '--wat') wat = true
+    else if (a === '--strict') strict = true
+    else if (a === '--resolve') resolveNode = true
+    else if (a === '--imports') importsFile = args[++i]
+    else if (a === '--optimize' || a === '-O') optimize = parseOptimize(args[++i])
+    else if (/^-O.+/.test(a)) optimize = parseOptimize(a.slice(2))
+    else if (a === '--host') host = args[++i]
+    else if (a === '--no-alloc') alloc = false
+    else if (a === '--names') names = true
+    else if (!inputFile) inputFile = a
   }
 
   if (!inputFile) throw new Error('No input file specified')
@@ -166,10 +201,20 @@ async function handleCompile(args) {
   const opts = {
     wat,
     jzify: !strict && !inputFile.endsWith('.jz'),
+    strict,
     importMetaUrl: pathToFileURL(resolve(inputFile)).href,
+    ...(optimize !== undefined && { optimize }),
+    ...(host && { host }),
+    ...(alloc === false && { alloc: false }),
+    ...(names && { profileNames: true }),
     ...(Object.keys(modules).length && { modules }),
   }
 
+  if (importsFile) {
+    const importsPath = resolve(importsFile)
+    opts.imports = JSON.parse(readFileSync(importsPath, 'utf8'))
+  }
+
   const result = compile(code, opts)
 
   if (outputFile === '-') {

package/index.js

@@ -45,6 +45,7 @@ import prepare, { GLOBALS } from './src/prepare.js'
 import compile from './src/compile.js'
 import { emitter } from './src/emit.js'
 import { optimizeFunc, resolveOptimize } from './src/optimize.js'
+import { detectOptimizeConfig } from './src/auto-config.js'
 import jzify from './src/jzify.js'
 import {
   memory as enhanceMemory, instantiate as instantiateRuntime,
@@ -224,6 +225,16 @@ jz.compile = (code, opts = {}) => {
   let parsed = time('parse', () => parse(code))
   if (opts.jzify) parsed = time('jzify', () => jzify(parsed))
   const ast = time('prepare', () => prepare(parsed))
+
+  // Auto-detect optimization tuning from source characteristics when the user
+  // hasn't provided any optimize option.
+  if (opts.optimize == null) {
+    const autoCfg = detectOptimizeConfig(ast, code)
+    if (Object.keys(autoCfg).length) {
+      ctx.transform.optimize = resolveOptimize(autoCfg)
+    }
+  }
+
   const module = time('compile', () => compile(ast, profiler))
 
   // host: 'wasi' — error if the wasm would import any env.__ext_* helper. Those exist
@@ -249,8 +260,10 @@ jz.compile = (code, opts = {}) => {
   // Only valuable to re-run when watr ran (watr is what re-introduces the boundaries).
   if (cfg.watr) {
     const postCfg = { ...cfg, __phase: 'post' }
+    // Build global name→type map from ctx.scope.globalTypes for promoteGlobals
+    const globalTypesMap = ctx.scope.globalTypes ? new Map([...ctx.scope.globalTypes].map(([k, v]) => [`$${k}`, v])) : null
     time('watrReopt', () => {
-      for (const node of optimized) if (Array.isArray(node) && node[0] === 'func') optimizeFunc(node, postCfg)
+      for (const node of optimized) if (Array.isArray(node) && node[0] === 'func') optimizeFunc(node, postCfg, globalTypesMap)
     })
   }
   if (opts.wat) return time('watrPrint', () => watrPrint(optimized))

package/module/array.js

@@ -225,7 +225,8 @@ export default (ctx) => {
       '__ptr_offset',
       ...(needsArrayDynMove() ? ['__dyn_move', '__hash_new', '__ihash_set_local'] : []),
     ],
-    __arr_set_idx_ptr: ['__arr_grow', '__ptr_offset', '__set_len'],
+    __arr_set_idx_ptr: ['__arr_grow', '__ptr_offset'],
+    __arr_push1: ['__arr_grow_known', '__ptr_offset'],
     __typed_idx: () => ctx.features.typedarray || ctx.features.external
       ? ['__len']
       : ['__len', '__ptr_offset'],
@@ -247,6 +248,16 @@ export default (ctx) => {
       ['i32.eq', ['call', '$__ptr_type', ['i64.reinterpret_f64', ['local.get', `$${t}`]]], ['i32.const', PTR.ARRAY]]], 'i32')
   }
 
+  ctx.core.emit['new.Array'] = (len) => {
+    const n = tempI32('alen')
+    const nIR = ['local.get', `$${n}`]
+    const out = allocPtr({ type: PTR.ARRAY, len: nIR, cap: nIR, tag: 'newarr' })
+    return typed(['block', ['result', 'f64'],
+      ['local.set', `$${n}`, len == null ? ['i32.const', 0] : asI32(emit(len))],
+      out.init,
+      out.ptr], 'f64')
+  }
+
   // ARRAY-only indexed read. Inline forwarding-follow + bounds check + load — avoids
   // the redundant double pass through __len then __ptr_offset that both follow forwarding.
   ctx.core.stdlib['__arr_idx'] = `(func $__arr_idx (param $ptr i64) (param $i i32) (result f64)
@@ -313,8 +324,21 @@ export default (ctx) => {
     return `(func $__typed_idx (param $ptr i64) (param $i i32) (result f64)
     (local $t i32) (local $off i32) (local $et i32) (local $len i32) (local $aux i32)
     (local.set $t (i32.wrap_i64 (i64.and (i64.shr_u (local.get $ptr) (i64.const ${LAYOUT.TAG_SHIFT})) (i64.const ${LAYOUT.TAG_MASK}))))
-    (local.set $aux (i32.wrap_i64 (i64.and (i64.shr_u (local.get $ptr) (i64.const ${LAYOUT.AUX_SHIFT})) (i64.const ${LAYOUT.AUX_MASK}))))
     (local.set $off (i32.wrap_i64 (i64.and (local.get $ptr) (i64.const ${LAYOUT.OFFSET_MASK}))))
+    ;; ARRAY fast path: follow forwarding inline, bounds-check against header len, f64.load — no $__len call.
+    (if (i32.and (i32.eq (local.get $t) (i32.const ${PTR.ARRAY})) (i32.ge_u (local.get $off) (i32.const 8)))
+      (then
+        (block $done
+          (loop $follow
+            (br_if $done (i32.gt_u (local.get $off) (i32.shl (memory.size) (i32.const 16))))
+            (br_if $done (i32.ne (i32.load (i32.sub (local.get $off) (i32.const 4))) (i32.const -1)))
+            (local.set $off (i32.load (i32.sub (local.get $off) (i32.const 8))))
+            (br $follow)))
+        (return (if (result f64)
+          (i32.and (i32.ge_s (local.get $i) (i32.const 0)) (i32.lt_u (local.get $i) (i32.load (i32.sub (local.get $off) (i32.const 8)))))
+          (then (f64.load (i32.add (local.get $off) (i32.shl (local.get $i) (i32.const 3)))))
+          (else (f64.const nan:${UNDEF_NAN}))))))
+    (local.set $aux (i32.wrap_i64 (i64.and (i64.shr_u (local.get $ptr) (i64.const ${LAYOUT.AUX_SHIFT})) (i64.const ${LAYOUT.AUX_MASK}))))
     (if
       (i32.and
         (i32.eq (local.get $t) (i32.const ${PTR.TYPED}))
@@ -461,13 +485,29 @@ export default (ctx) => {
                   (i32.load (i32.sub (local.get $base) (i32.const 8))))
       (then
         (local.set $p (call $__arr_grow (local.get $ptr) (i32.add (local.get $i) (i32.const 1))))
-        (call $__set_len (i64.reinterpret_f64 (local.get $p)) (i32.add (local.get $i) (i32.const 1)))
-        (local.set $base (call $__ptr_offset (i64.reinterpret_f64 (local.get $p))))))
+        (local.set $base (call $__ptr_offset (i64.reinterpret_f64 (local.get $p))))
+        (i32.store (i32.sub (local.get $base) (i32.const 8)) (i32.add (local.get $i) (i32.const 1)))))
     (f64.store
       (i32.add (local.get $base) (i32.shl (local.get $i) (i32.const 3)))
       (local.get $val))
     (local.get $p))`
 
+  // Out-of-line .push(val) for known-ARRAY receivers — keeps each call site to a
+  // single call + var update instead of ~30 inlined instructions. Returns the
+  // (possibly relocated) array pointer; caller derives the new length if needed.
+  ctx.core.stdlib['__arr_push1'] = `(func $__arr_push1 (param $ptr i64) (param $val f64) (result f64)
+    (local $p f64) (local $base i32) (local $len i32)
+    (local.set $p (f64.reinterpret_i64 (local.get $ptr)))
+    (local.set $base (call $__ptr_offset (local.get $ptr)))
+    (local.set $len (i32.load (i32.sub (local.get $base) (i32.const 8))))
+    (if (i32.lt_s (i32.load (i32.sub (local.get $base) (i32.const 4))) (i32.add (local.get $len) (i32.const 1)))
+      (then
+        (local.set $p (call $__arr_grow_known (local.get $ptr) (i32.add (local.get $len) (i32.const 1))))
+        (local.set $base (call $__ptr_offset (i64.reinterpret_f64 (local.get $p))))))
+    (f64.store (i32.add (local.get $base) (i32.shl (local.get $len) (i32.const 3))) (local.get $val))
+    (i32.store (i32.sub (local.get $base) (i32.const 8)) (i32.add (local.get $len) (i32.const 1)))
+    (local.get $p))`
+
   // === Array literal ===
 
   ctx.core.emit['['] = (...elems) => {
@@ -725,6 +765,21 @@ export default (ctx) => {
 
   // .push(val) → append, increment len, return array (possibly reallocated pointer)
   ctx.core.emit['.push'] = (arr, ...vals) => {
+    // Out-of-line fast path: single value, named known-ARRAY receiver. One call +
+    // var update instead of ~30 inlined instructions — the dominant size cost of
+    // push-heavy code (e.g. watr's WASM emitter).
+    if (vals.length === 1 && typeof arr === 'string' && lookupValType(arr) === VAL.ARRAY) {
+      inc('__arr_push1')
+      const box = ctx.func.boxed?.get(arr)
+      const isGlobal = !box && ctx.scope.globals.has(arr) && !ctx.func.locals?.has(arr)
+      const readVar = box ? ['f64.load', ['local.get', `$${box}`]] : isGlobal ? ['global.get', `$${arr}`] : ['local.get', `$${arr}`]
+      const writeVar = v => box ? ['f64.store', ['local.get', `$${box}`], v] : isGlobal ? ['global.set', `$${arr}`, v] : ['local.set', `$${arr}`, v]
+      const vv = asF64(emit(vals[0]))
+      return typed(['block', ['result', 'f64'],
+        writeVar(['call', '$__arr_push1', ['i64.reinterpret_f64', readVar], vv]),
+        ['f64.convert_i32_s', ['i32.load', ['i32.sub',
+          ['call', '$__ptr_offset', ['i64.reinterpret_f64', readVar]], ['i32.const', 8]]]]], 'f64')
+    }
     const va = asF64(emit(arr))
     const t = temp('pp'), len = tempI32('pl')
 
@@ -779,8 +834,10 @@ export default (ctx) => {
       )
     }
 
-    // Update length header, update source variable (pointer may have changed from grow), return new length
-    body.push(['call', '$__set_len', ['i64.reinterpret_f64', ['local.get', `$${t}`]], ['local.get', `$${len}`]])
+    // Update length header (write directly via the offset we already hold —
+    // skips __set_len's tag/forward dispatch), update source variable (pointer
+    // may have changed from grow), return new length
+    body.push(['i32.store', ['i32.sub', ['local.get', `$${pushBase}`], ['i32.const', 8]], ['local.get', `$${len}`]])
     // Update the source variable if it's a named variable (so arr still points to valid memory)
     if (typeof arr === 'string') {
       if (ctx.func.boxed?.has(arr)) {
@@ -898,8 +955,8 @@ export default (ctx) => {
         ['i32.shl',
           ['i32.sub', ['i32.sub', ['local.get', `$${len}`], ['local.get', `$${s}`]], ['local.get', `$${cnt}`]],
           ['i32.const', 3]]],
-      // update length
-      ['call', '$__set_len', ['i64.reinterpret_f64', va], ['i32.sub', ['local.get', `$${len}`], ['local.get', `$${cnt}`]]],
+      // update length (write directly via the offset we already hold)
+      ['i32.store', ['i32.sub', ['local.get', `$${off}`], ['i32.const', 8]], ['i32.sub', ['local.get', `$${len}`], ['local.get', `$${cnt}`]]],
       out.ptr,
     ]
     return typed(['block', ['result', 'f64'], ...body], 'f64')
@@ -919,7 +976,7 @@ export default (ctx) => {
       (local.get $off)
       (i32.shl (local.get $len) (i32.const 3)))
     (f64.store (local.get $off) (local.get $val))
-    (call $__set_len (i64.reinterpret_f64 (local.get $a)) (i32.add (local.get $len) (i32.const 1)))
+    (i32.store (i32.sub (local.get $off) (i32.const 8)) (i32.add (local.get $len) (i32.const 1)))
     (f64.convert_i32_s (i32.add (local.get $len) (i32.const 1))))`
 
   // .some(fn) → return 1 if any element passes, else 0 (early exit)