Add JZ WebAssembly kernel example

Author: dy

examples/jz-kernel/README.md

@@ -0,0 +1,29 @@
+# JZ kernel example
+
+This example uses [`jz`](https://www.npmjs.com/package/jz) to compile a small JavaScript-subset numeric kernel to WebAssembly and run it inside EdgeJS.
+
+The primary path is a pure scalar module: `compile()` returns WebAssembly bytes, `WebAssembly.Module.imports()` is empty, and EdgeJS runs the module through the standard WebAssembly API. `index.mjs` also includes a small explicit host-import sample that passes a `console`-like object through `imports`; this is useful for diagnostics without requiring implicit runtime imports.
+
+JZ is useful for hot numeric, DSP, parser, and typed-array kernels. It is not a general JavaScript runtime or a Node.js compatibility layer; EdgeJS remains the runtime.
+
+Install the example dependency:
+
+```bash
+npm install
+```
+
+Run the smoke example:
+
+```bash
+edge index.mjs
+```
+
+Run the checksum benchmark. The benchmark uses a small `Float64Array` 4x4 matrix kernel and calls one compiled export that owns the hot loop, so it measures generated WebAssembly work rather than repeated JS-to-WASM call overhead.
+
+```bash
+edge bench.mjs
+```
+
+The benchmark prints matching checksums, WebAssembly import count, generated byte size, and median timings. Tune the workload with `ITERATIONS`, `WARMUP`, and `RUNS`.
+
+When working from a local EdgeJS checkout, replace `edge` with `../../build-edge/edge` after running `make build`.

examples/jz-kernel/bench.mjs

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import { compile } from 'jz';
+
+const kernelSource = `
+const init = (a, b) => {
+  for (let i = 0; i < 16; i++) {
+    a[i] = (i + 1) * 0.125
+    b[i] = (16 - i) * 0.0625
+  }
+}
+
+const multiplyMany = (a, b, out, iters) => {
+  for (let n = 0; n < iters; n++) {
+    for (let r = 0; r < 4; r++) {
+      for (let c = 0; c < 4; c++) {
+        let s = 0
+        for (let k = 0; k < 4; k++) s += a[r * 4 + k] * b[k * 4 + c]
+        out[r * 4 + c] = s + n * 0.0000001
+      }
+    }
+    const t = a[0]
+    a[0] = out[15]
+    a[5] = t + out[10] * 0.000001
+  }
+}
+
+export let run = (iters) => {
+  const a = new Float64Array(16)
+  const b = new Float64Array(16)
+  const out = new Float64Array(16)
+  init(a, b)
+  multiplyMany(a, b, out, iters)
+  let checksum = 0
+  for (let i = 0; i < 16; i++) checksum = (checksum + out[i] * 1000000) | 0
+  return checksum
+}
+`;
+
+function init(a, b) {
+  for (let i = 0; i < 16; i += 1) {
+    a[i] = (i + 1) * 0.125;
+    b[i] = (16 - i) * 0.0625;
+  }
+}
+
+function multiplyMany(a, b, out, iters) {
+  for (let n = 0; n < iters; n += 1) {
+    for (let r = 0; r < 4; r += 1) {
+      for (let c = 0; c < 4; c += 1) {
+        let s = 0;
+        for (let k = 0; k < 4; k += 1) s += a[r * 4 + k] * b[k * 4 + c];
+        out[r * 4 + c] = s + n * 0.0000001;
+      }
+    }
+    const t = a[0];
+    a[0] = out[15];
+    a[5] = t + out[10] * 0.000001;
+  }
+}
+
+function runJs(iters) {
+  const a = new Float64Array(16);
+  const b = new Float64Array(16);
+  const out = new Float64Array(16);
+  init(a, b);
+  multiplyMany(a, b, out, iters);
+  let checksum = 0;
+  for (let i = 0; i < 16; i += 1) checksum = (checksum + out[i] * 1000000) | 0;
+  return checksum;
+}
+
+const wasm = compile(kernelSource);
+const mod = new WebAssembly.Module(wasm);
+const imports = WebAssembly.Module.imports(mod);
+const { exports } = new WebAssembly.Instance(mod);
+
+assert.deepEqual(imports, []);
+assert.equal(exports.run(128), runJs(128));
+
+const iterations = Number(process.env.ITERATIONS || 200000);
+const warmup = Number(process.env.WARMUP || 5);
+const runs = Number(process.env.RUNS || 9);
+const now = globalThis.performance && typeof globalThis.performance.now === 'function'
+  ? () => globalThis.performance.now()
+  : () => Date.now();
+
+function median(values) {
+  const sorted = values.slice().sort((a, b) => a - b);
+  return sorted[sorted.length >> 1];
+}
+
+function measure(fn) {
+  for (let i = 0; i < warmup; i += 1) fn(iterations);
+  const samples = [];
+  const start = now();
+  let checksum = 0;
+  for (let i = 0; i < runs; i += 1) {
+    const sampleStart = now();
+    checksum = fn(iterations);
+    samples.push(now() - sampleStart);
+  }
+  const totalMs = now() - start;
+  return {
+    checksum,
+    medianMs: Number(median(samples).toFixed(3)),
+    totalMs: Number(totalMs.toFixed(3)),
+  };
+}
+
+const js = measure(runJs);
+const jzWasm = measure(exports.run);
+
+assert.equal(jzWasm.checksum, js.checksum);
+
+console.log(JSON.stringify({
+  iterations,
+  warmup,
+  runs,
+  imports: imports.length,
+  wasmBytes: wasm.length,
+  js,
+  jzWasm,
+}, null, 2));

examples/jz-kernel/index.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import jz, { compile } from 'jz';
+
+const kernelSource = `
+export let mac = (a, b, c) => {
+  let x = c
+  for (let i = 0; i < 8; i++) x = x + (a + i) * (b - i)
+  return x
+}
+
+export let mix = (x, y) => mac(x, y, 3) - mac(y, x, 1)
+`;
+
+function macJs(a, b, c) {
+  let x = c;
+  for (let i = 0; i < 8; i += 1) x += (a + i) * (b - i);
+  return x;
+}
+
+function mixJs(x, y) {
+  return macJs(x, y, 3) - macJs(y, x, 1);
+}
+
+const wasm = compile(kernelSource);
+const mod = new WebAssembly.Module(wasm);
+const imports = WebAssembly.Module.imports(mod);
+
+assert.deepEqual(imports, []);
+
+const { exports } = new WebAssembly.Instance(mod);
+const vectors = [
+  [2, 9, 1],
+  [7, 4, 3],
+  [11, -2, 5],
+];
+
+let checksum = 0;
+for (const [a, b, c] of vectors) {
+  const actual = exports.mac(a, b, c);
+  const expected = macJs(a, b, c);
+  assert.equal(actual, expected);
+  checksum += actual;
+}
+
+const mix = exports.mix(4, 7);
+assert.equal(mix, mixJs(4, 7));
+
+const captured = [];
+const hostConsole = Object.assign(Object.create(console), {
+  log(value) {
+    captured.push(value);
+  },
+});
+
+const hostModule = jz(`
+import { log } from "console"
+export let report = (value) => {
+  log(value)
+  return value + 1
+}
+`, {
+  imports: { console: hostConsole },
+});
+
+assert.equal(hostModule.exports.report(41), 42);
+assert.deepEqual(captured, [41]);
+
+console.log(JSON.stringify({
+  kernel: {
+    imports: imports.length,
+    checksum,
+    mix,
+  },
+  explicitHostImport: {
+    module: 'console',
+    captured,
+    result: 42,
+  },
+}, null, 2));

examples/jz-kernel/package-lock.json

@@ -0,0 +1,12 @@
+{
+  "name": "edgejs-jz-kernel-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "edge index.mjs",
+    "bench": "edge bench.mjs"
+  },
+  "dependencies": {
+    "jz": "^0.1.1"
+  }
+}