watr 4.7.1 → 5.0.0

package/src/compile.js

@@ -37,17 +37,10 @@ const cleanup = (node, result) => {
 }
 
 
-/**
- * Converts a WebAssembly Text Format (WAT) tree to a WebAssembly binary format (WASM).
- *
- * @param {string|Array} nodes - The WAT tree or string to be compiled to WASM binary.
- * @returns {Uint8Array} The compiled WASM binary. When the WAT carries
- *   `@metadata.code.<type>` annotations, the result also exposes a `.metadata`
- *   property — `{ [type]: [[absoluteByteOffset, data], ...] }`, each offset the
- *   instruction's position in the final binary. That's the hook a source-map
- *   emitter needs to correlate generated wasm back to its source.
- */
-export default function compile(nodes) {
+// Internal: assemble the module. sizeOnly=false → wasm bytes (Uint8Array); sizeOnly=true →
+// just the byte LENGTH, skipping materialization of the multi-MB binary — that's size()'s
+// reason to exist (the optimizer's size-revert guard can't afford to build bytes it discards).
+function assemble(nodes, sizeOnly) {
   // normalize to (module ...) form
   if (typeof nodes === 'string') err.src = nodes, nodes = parse(nodes) || []
   else err.src = '' // clear source if AST passed directly
@@ -63,10 +56,10 @@ export default function compile(nodes) {
   else if (typeof nodes[0] === 'string') nodes = [nodes]
 
   // binary abbr "\00" "\0x61" ...
-  if (nodes[idx] === 'binary') return Uint8Array.from(nodes.slice(++idx).flat())
+  if (nodes[idx] === 'binary') { const b = Uint8Array.from(nodes.slice(++idx).flat()); return sizeOnly ? b.length : b }
 
   // quote "a" "b"
-  if (nodes[idx] === 'quote') return compile(nodes.slice(++idx).map(v => v.valueOf().slice(1, -1)).flat().join(''))
+  if (nodes[idx] === 'quote') return assemble(nodes.slice(++idx).map(v => v.valueOf().slice(1, -1)).flat().join(''), sizeOnly)
 
   // expand grouped imports: (import "mod" (item "name" type)*) -> individual imports
   // compact import section (Phase 3)
@@ -241,6 +234,26 @@ export default function compile(nodes) {
   // pre-compute sections that may collect string constants (for strings section ordering)
   const globalSection = bin(SECTION.global)
   const elemSection = bin(SECTION.elem)
+  // measure: byte LENGTH only — skip building + materializing the multi-MB code byte array
+  // (the optimizer's size-revert guard only needs the count). Sizes the code section via
+  // codeItemSize; other sections are small, built normally + summed. Same string-collection
+  // ORDER as the emit path (global, elem, code, meta, data → strings).
+  if (sizeOnly) {
+    const codeSizes = ctx.code.filter(Boolean).map(item => codeItemSize(item, ctx))
+    const innerLen = codeSizes.length ? ulebSize(codeSizes.length) + codeSizes.reduce((a, b) => a + b, 0) : 0
+    const codeSecLen = codeSizes.length ? 1 + ulebSize(innerLen) + innerLen : 0  // SECTION.code + vec(vec(items))
+    const metaSection = binMeta()
+    const dataSection = bin(SECTION.data)
+    const stringsSection = ctx.strings.length ? [SECTION.strings, ...vec([0x00, ...vec(ctx.strings.map(s => vec(s)))])] : []
+    const others = [
+      bin(SECTION.custom), bin(SECTION.type), bin(SECTION.import), bin(SECTION.func),
+      bin(SECTION.table), bin(SECTION.memory), bin(SECTION.tag), stringsSection,
+      globalSection, bin(SECTION.export), bin(SECTION.start, false), elemSection,
+      bin(SECTION.datacount, false), metaSection, dataSection
+    ]
+    return 8 + codeSecLen + others.reduce((s, sec) => s + sec.length, 0)   // 8 = magic + version
+  }
+
   // inline bin(code) so the per-function item bytes survive — with ctx.codeSizePrefix
   // they let us lift code-metadata positions to absolute binary offsets below
   const codeItems = ctx.code.filter(Boolean).map(item => build[SECTION.code](item, ctx)).filter(Boolean)
@@ -317,6 +330,19 @@ export default function compile(nodes) {
   }
 }
 
+/**
+ * Convert a WAT tree (or source string) to a wasm binary (Uint8Array). When the WAT carries
+ * `@metadata.code.<type>` annotations the result also exposes `.metadata` —
+ * `{ [type]: [[absByteOffset, data], ...] }`, the hook a source-map emitter needs.
+ */
+export default function compile(nodes) { return assemble(nodes) }
+
+/**
+ * Byte size of `compile(nodes)` without materializing the binary — a peer transform for
+ * tooling (the optimizer's size-revert guard, size budgeting). Exactly `compile(nodes).length`,
+ * summed from section sizes instead of building them (invariant-tested).
+ */
+export function size(nodes) { return assemble(nodes, true) }
 
 /** Check if node is a valid index reference ($name or number) */
 const isIdx = n => n?.[0] === '$' || !isNaN(n)
@@ -1062,6 +1088,59 @@ const instr = (nodes, ctx) => {
   return out.push(0x0b), out
 }
 
+// LEB128 byte-width of an unsigned integer (exact, reuses uleb so it can never drift).
+const ulebSize = (n) => uleb(n).length
+
+// Size-only twin of instr(): the byte LENGTH of the encoded instruction stream,
+// WITHOUT building the (multi-MB) byte array. Reuses every HANDLER for exact
+// immediate widths + index resolution — only `out.push(...bytes)` accumulation is
+// replaced by integer summation (the dominant cost on large modules). The
+// opcode-value tweaks in instr() (typed-select / nullable-reftype) change a byte
+// VALUE, not the length, so they're irrelevant here. MUST equal instr(...).length
+// (asserted by the byteSize↔compile invariant test).
+const instrSize = (nodes, ctx) => {
+  let size = 0, meta = []
+  while (nodes?.length) {
+    let op = nodes.shift()
+    if (op?.[0] === '@metadata') { meta.push(op.slice(1)); continue }
+    if (Array.isArray(op)) { op.loc != null && (err.loc = op.loc); err(`Unknown instruction ${op[0]}`) }
+    const opc = INSTR[op] || err(`Unknown instruction ${op}`)
+    let n = opc.length
+    if (HANDLER[op]) n += HANDLER[op](nodes, ctx, op).length
+    if (meta.length) { for (const [type, data] of meta) ((ctx.meta[type] ??= []).push([size, data])); meta = [] }
+    size += n
+  }
+  return size + 1   // trailing 0x0b (end)
+}
+
+// Size-only twin of build[SECTION.code]: byte LENGTH of one function's code item.
+// Mirrors the builder exactly (local setup, squash, metadata bookkeeping, vec
+// framing) but uses instrSize for the body — so locals/strings/metadata side
+// effects on ctx stay identical, only the body byte array is never materialized.
+const codeItemSize = (body, ctx) => {
+  let [typeidx, param] = body.shift()
+  if (!param) [, [param]] = ctx.type[id(typeidx, ctx.type)]
+  ctx.local = Object.create(param); ctx.block = []
+  ctx.local.name = 'local'; ctx.block.name = 'block'
+  if (ctx._codeIdx === undefined) ctx._codeIdx = 0
+  let codeIdx = ctx._codeIdx++
+  while (body[0]?.[0] === 'local') {
+    let [, ...types] = body.shift()
+    if (isId(types[0])) { let nm = types.shift(); if (nm in ctx.local) err(`Duplicate local ${nm}`); else ctx.local[nm] = ctx.local.length }
+    ctx.local.push(...types)
+  }
+  ctx.meta = {}
+  const bytesLen = instrSize(body, ctx)
+  let loctypes = ctx.local.slice(param.length).reduce((a, type) => (type == a[a.length - 1]?.[1] ? a[a.length - 1][0]++ : a.push([1, type]), a), [])
+  const locals = vec(loctypes.map(([n, t]) => [...uleb(n), ...reftype(t, ctx)]))
+  const funcIdx = ctx.import.filter(imp => imp[2][0] === 'func').length + codeIdx
+  for (const type in ctx.meta) { for (const inst of ctx.meta[type]) inst[0] += locals.length; ((ctx.metadata ??= {})[type] ??= []).push([funcIdx, ctx.meta[type]]) }
+  ctx.local = ctx.block = ctx.meta = null
+  const bodyLen = locals.length + bytesLen
+  ;(ctx.codeSizePrefix ??= [])[codeIdx] = ulebSize(bodyLen)   // = vec prefix width
+  return ulebSize(bodyLen) + bodyLen                          // vec([...locals, ...bytes]).length
+}
+
 // instantiation time value initializer (consuming) - normalize then encode + add end byte
 const expr = (node, ctx) => instr(normalize([node], ctx), ctx)
 

package/src/optimize.js

@@ -7,7 +7,7 @@
  * @module wat/optimize
  */
 
-import compile from './compile.js'
+import compile, { size } from './compile.js'
 import parse from './parse.js'
 
 // Fixpoint round caps — empirical convergence bounds, not correctness limits.
@@ -68,7 +68,10 @@ const count = (node) => {
  * @returns {number}
  */
 const binarySize = (ast) => {
-  try { return compile(ast).length } catch { return Infinity }
+  // `size` = byte length without materializing the binary — the size-revert guard only needs
+  // the count, and re-encoding the whole module each round is the optimizer's dominant cost on
+  // large modules. Exactly compile(ast).length (invariant-tested).
+  try { return size(ast) } catch { return Infinity }
 }
 
 /**

package/src/template.js

@@ -19,6 +19,24 @@ import { resultType } from './const.js'
 /** Private Use Area character as placeholder for interpolation */
 const PUA = '\uE000'
 
+/**
+ * Apply a backend transform (`polyfill`/`optimize`), or throw an actionable
+ * pointer when this entry doesn't bundle it. The default `watr` build wires a
+ * lean backend (parse + compile) and leaves the heavy transforms to their own
+ * entries, so `compile(src, { optimize })` here directs you to compose instead.
+ *
+ * @param {Function|undefined} fn - transform from the backend
+ * @param {string} name - 'polyfill' | 'optimize'
+ * @param {Array} ast
+ * @param {any} opt - the option value
+ * @returns {Array} transformed AST
+ */
+function applyTransform(fn, name, ast, opt) {
+  if (typeof fn !== 'function')
+    throw Error(`watr: '${name}' is not bundled in this entry \u2014 import it from 'watr/${name}' and compose: compile(${name}(src))`)
+  return fn(ast, opt)
+}
+
 /**
  * Infer type of an expression AST node.
  * Used for auto-import parameter type inference.
@@ -209,9 +227,9 @@ export function compile(backend, source, values) {
       }
     }
 
-    // Apply transforms
-    if (opts.polyfill) ast = polyfill(ast, opts.polyfill)
-    if (opts.optimize) ast = optimize(ast, opts.optimize)
+    // Apply transforms (heavy passes live in separate entries — see applyTransform)
+    if (opts.polyfill) ast = applyTransform(polyfill, 'polyfill', ast, opts.polyfill)
+    if (opts.optimize) ast = applyTransform(optimize, 'optimize', ast, opts.optimize)
 
     const binary = emit(ast)
     // Attach imports for watr() to use
@@ -222,8 +240,8 @@ export function compile(backend, source, values) {
   // String/AST source with options
   if (opts.polyfill || opts.optimize) {
     let ast = typeof source === 'string' ? parse(source) : source
-    if (opts.polyfill) ast = polyfill(ast, opts.polyfill)
-    if (opts.optimize) ast = optimize(ast, opts.optimize)
+    if (opts.polyfill) ast = applyTransform(polyfill, 'polyfill', ast, opts.polyfill)
+    if (opts.optimize) ast = applyTransform(optimize, 'optimize', ast, opts.optimize)
     return emit(ast)
   }
   return emit(source)

package/types/src/compile.d.ts

@@ -1,12 +1,13 @@
 /**
- * Converts a WebAssembly Text Format (WAT) tree to a WebAssembly binary format (WASM).
- *
- * @param {string|Array} nodes - The WAT tree or string to be compiled to WASM binary.
- * @returns {Uint8Array} The compiled WASM binary. When the WAT carries
- *   `@metadata.code.<type>` annotations, the result also exposes a `.metadata`
- *   property — `{ [type]: [[absoluteByteOffset, data], ...] }`, each offset the
- *   instruction's position in the final binary. That's the hook a source-map
- *   emitter needs to correlate generated wasm back to its source.
+ * Convert a WAT tree (or source string) to a wasm binary (Uint8Array). When the WAT carries
+ * `@metadata.code.<type>` annotations the result also exposes `.metadata` —
+ * `{ [type]: [[absByteOffset, data], ...] }`, the hook a source-map emitter needs.
  */
-export default function compile(nodes: string | any[]): Uint8Array;
+export default function compile(nodes: any): any;
+/**
+ * Byte size of `compile(nodes)` without materializing the binary — a peer transform for
+ * tooling (the optimizer's size-revert guard, size budgeting). Exactly `compile(nodes).length`,
+ * summed from section sizes instead of building them (invariant-tested).
+ */
+export function size(nodes: any): any;
 //# sourceMappingURL=compile.d.ts.map

package/types/src/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.js"],"names":[],"mappings":"AAuCA;;;;;;;;;GASG;AACH,uCAPW,MAAM,QAAM,GACV,UAAU,CAkRtB"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.js"],"names":[],"mappings":"AA4UA;;;;GAIG;AACH,iDAAiE;AAEjE;;;;GAIG;AACH,sCAA4D"}

package/types/src/optimize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimize.d.ts","sourceRoot":"","sources":["../../src/optimize.js"],"names":[],"mappings":"AAmxHA,gEA6FC;AA5zHD;;;;GAIG;AACH,4BAHW,GAAG,GACD,MAAM,CAOlB;AAED;;;;GAIG;AACH,wCAFa,MAAM,CAIlB;AA8CD;;;;;GAKG;AACH,6CAgJC;AAwUD;;;;GAIG;AACH,wCAkDC;AA0YD;;;;GAIG;AACH,4CAqBC;AA+CD;;;;;GAKG;AACH,8CAmDC;AAndD;;;;GAIG;AACH,4CASC;AAID;;;;GAIG;AACH,4CAwDC;AAID;;;;GAIG;AACH,0CA6CC;AAuyBD,yCAqCC;AAmND;;;QAqEC;AAuQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;UA+IC;AA/aD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAwOC;AA0gDD;;;;;;;;GAQG;AACH,gCAHW,OAAO,GAAC,MAAM,MAAO,OAc/B;AAvBD,qEAAqE;AACrE,uBAA8D;AArlC9D;;;;;GAKG;AACH,0CA8DC;AA+ED;;;;GAIG;AACH,4CAQC;AAiCD;;;;;;;;;;;GAWG;AACH,2CAyDC;AAID,2EAA2E;AAC3E,sCAgEC;AAID;;;;GAIG;AACH,4CAyCC;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAiDC;AAID;;;;;GAKG;AACH,4CAqBC;AAID;;;;;;GAMG;AACH,wCAmBC;AAID;;;;;GAKG;AACH,4CAiDC;AAoCD;;;;;GAKG;AACH,0CA8DC;AAwWD,uCAyBC;AA7XD;;;;;GAKG;AACH,8CAyEC;AA2ID;;;;GAIG;AACH,4CAyDC;AAqBD;;;;;GAKG;AACH,iDAgBC;AA/sCD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+CAiFC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,kDAyFC"}
+{"version":3,"file":"optimize.d.ts","sourceRoot":"","sources":["../../src/optimize.js"],"names":[],"mappings":"AAsxHA,gEA6FC;AA/zHD;;;;GAIG;AACH,4BAHW,GAAG,GACD,MAAM,CAOlB;AAED;;;;GAIG;AACH,wCAFa,MAAM,CAOlB;AA8CD;;;;;GAKG;AACH,6CAgJC;AAwUD;;;;GAIG;AACH,wCAkDC;AA0YD;;;;GAIG;AACH,4CAqBC;AA+CD;;;;;GAKG;AACH,8CAmDC;AAndD;;;;GAIG;AACH,4CASC;AAID;;;;GAIG;AACH,4CAwDC;AAID;;;;GAIG;AACH,0CA6CC;AAuyBD,yCAqCC;AAmND;;;QAqEC;AAuQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;UA+IC;AA/aD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAwOC;AA0gDD;;;;;;;;GAQG;AACH,gCAHW,OAAO,GAAC,MAAM,MAAO,OAc/B;AAvBD,qEAAqE;AACrE,uBAA8D;AArlC9D;;;;;GAKG;AACH,0CA8DC;AA+ED;;;;GAIG;AACH,4CAQC;AAiCD;;;;;;;;;;;GAWG;AACH,2CAyDC;AAID,2EAA2E;AAC3E,sCAgEC;AAID;;;;GAIG;AACH,4CAyCC;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAiDC;AAID;;;;;GAKG;AACH,4CAqBC;AAID;;;;;;GAMG;AACH,wCAmBC;AAID;;;;;GAKG;AACH,4CAiDC;AAoCD;;;;;GAKG;AACH,0CA8DC;AAwWD,uCAyBC;AA7XD;;;;;GAKG;AACH,8CAyEC;AA2ID;;;;GAIG;AACH,4CAyDC;AAqBD;;;;;GAKG;AACH,iDAgBC;AA/sCD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+CAiFC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,kDAyFC"}

package/types/src/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/template.js"],"names":[],"mappings":"AA4HA;;;;;;;;;;GAUG;AACH,8CAPW,MAAM,WAAO,oBAAoB,UACjC,GAAG,EAAE,GAIH,UAAU,CAgGtB;AAED;;;;;;;GAOG;AACH,2CAJW,MAAM,WAAO,oBAAoB,UACjC,GAAG,EAAE,GACH,WAAW,CAAC,OAAO,CAO/B"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/template.js"],"names":[],"mappings":"AA8IA;;;;;;;;;;GAUG;AACH,8CAPW,MAAM,WAAO,oBAAoB,UACjC,GAAG,EAAE,GAIH,UAAU,CAgGtB;AAED;;;;;;;GAOG;AACH,2CAJW,MAAM,WAAO,oBAAoB,UACjC,GAAG,EAAE,GACH,WAAW,CAAC,OAAO,CAO/B"}

package/types/watr.d.ts

@@ -17,18 +17,17 @@ export function watr(source: string | TemplateStringsArray, ...values: any[]): W
  *
  * @param {string|TemplateStringsArray} source - WAT source or template strings
  * @param {...any} values - Interpolation values (for template literal).
- *   Last value can be an options object: { polyfill, optimize }.
  * @returns {Uint8Array} WebAssembly binary
  *
  * @example
  * compile('(func (export "f") (result i32) (i32.const 42))')
  * compile`(func (export "f") (result f64) (f64.const ${Math.PI}))`
- * compile(src, { polyfill: true, optimize: true })
+ * // transforms ship as separate entries — compose them:
+ * // import optimize from 'watr/optimize'
+ * // compile(optimize(src))
  */
 export function compile(source: string | TemplateStringsArray, ...values: any[]): Uint8Array;
 import parse from './src/parse.js';
 import print from './src/print.js';
-import _polyfill from './src/polyfill.js';
-import _optimize from './src/optimize.js';
-export { parse, print, _polyfill as polyfill, _optimize as optimize };
+export { parse, print };
 //# sourceMappingURL=watr.d.ts.map

package/types/watr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watr.d.ts","sourceRoot":"","sources":["../watr.js"],"names":[],"mappings":";AAiCA;;;;;;;;;;;GAWG;AACH,6BATW,MAAM,GAAC,oBAAoB,aACxB,GAAG,EAAA,GACJ,WAAW,CAAC,OAAO,CAS/B;AA/BD;;;;;;;;;;;;GAYG;AACH,gCAVW,MAAM,GAAC,oBAAoB,aACxB,GAAG,EAAA,GAEJ,UAAU,CAStB;kBAxBiB,gBAAgB;kBAChB,gBAAgB;sBACZ,mBAAmB;sBACnB,mBAAmB"}
+{"version":3,"file":"watr.d.ts","sourceRoot":"","sources":["../watr.js"],"names":[],"mappings":";AAoCA;;;;;;;;;;;GAWG;AACH,6BATW,MAAM,GAAC,oBAAoB,aACxB,GAAG,EAAA,GACJ,WAAW,CAAC,OAAO,CAS/B;AAhCD;;;;;;;;;;;;;GAaG;AACH,gCAXW,MAAM,GAAC,oBAAoB,aACxB,GAAG,EAAA,GACJ,UAAU,CAWtB;kBA3BiB,gBAAgB;kBAChB,gBAAgB"}

package/watr.js

@@ -7,25 +7,28 @@
 import _compile from './src/compile.js'
 import parse from './src/parse.js'
 import print from './src/print.js'
-import _polyfill from './src/polyfill.js'
-import _optimize from './src/optimize.js'
 import { compile as _tcompile, watr as _twatr } from './src/template.js'
 
-/** JS-source backend primitives for the tagged-template layer. */
-const backend = { parse, compile: _compile, optimize: _optimize, polyfill: _polyfill }
+/** JS-source backend primitives for the tagged-template layer.
+ *  `polyfill` and `optimize` are intentionally NOT wired here — they're heavy
+ *  (the optimizer alone is ~5× the core encoder) and ship as separate entries,
+ *  `watr/polyfill` and `watr/optimize`, that you compose explicitly:
+ *  `compile(optimize(src))`. This keeps the default bundle minimal. */
+const backend = { parse, compile: _compile }
 
 /**
  * Compile WAT to binary. Supports both string and template literal.
  *
  * @param {string|TemplateStringsArray} source - WAT source or template strings
  * @param {...any} values - Interpolation values (for template literal).
- *   Last value can be an options object: { polyfill, optimize }.
  * @returns {Uint8Array} WebAssembly binary
  *
  * @example
  * compile('(func (export "f") (result i32) (i32.const 42))')
  * compile`(func (export "f") (result f64) (f64.const ${Math.PI}))`
- * compile(src, { polyfill: true, optimize: true })
+ * // transforms ship as separate entries — compose them:
+ * // import optimize from 'watr/optimize'
+ * // compile(optimize(src))
  */
 function compile(source, ...values) {
   return _tcompile(backend, source, values)
@@ -48,4 +51,4 @@ function watr(source, ...values) {
 }
 
 export default watr
-export { watr, compile, parse, print, _polyfill as polyfill, _optimize as optimize }
+export { watr, compile, parse, print }