json-as 1.2.6 → 1.3.0

package/.as-test/logs/test.types.spec.ts.log.json

@@ -0,0 +1,273 @@
+[
+  {
+    "file": "assembly/__tests__/types.spec.ts",
+    "suites": [
+      {
+        "file": "types.spec.ts",
+        "order": 1,
+        "time": {
+          "start": 24563168.395059,
+          "end": 24563168.738608
+        },
+        "description": "Should serialize with type aliases",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "{\"foo\":\"bar\"}",
+            "right": "{\"foo\":\"bar\"}",
+            "instr": "toBe",
+            "message": "",
+            "location": "22:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      },
+      {
+        "file": "types.spec.ts",
+        "order": 1,
+        "time": {
+          "start": 24563168.79409,
+          "end": 24563168.974308
+        },
+        "description": "Should deserialize with type aliases",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "{\"foo\":\"bar\"}",
+            "right": "{\"foo\":\"bar\"}",
+            "instr": "toBe",
+            "message": "",
+            "location": "26:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      },
+      {
+        "file": "types.spec.ts",
+        "order": 6,
+        "time": {
+          "start": 24563169.012157,
+          "end": 24563169.688812
+        },
+        "description": "Additional regression coverage - primitives and arrays",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "\"regression\"",
+            "right": "\"regression\"",
+            "instr": "toBe",
+            "message": "",
+            "location": "30:3"
+          },
+          {
+            "order": 1,
+            "type": "",
+            "verdict": "ok",
+            "left": "-42",
+            "right": "-42",
+            "instr": "toBe",
+            "message": "",
+            "location": "31:3"
+          },
+          {
+            "order": 2,
+            "type": "",
+            "verdict": "ok",
+            "left": "false",
+            "right": "false",
+            "instr": "toBe",
+            "message": "",
+            "location": "32:3"
+          },
+          {
+            "order": 3,
+            "type": "",
+            "verdict": "ok",
+            "left": "3.5",
+            "right": "3.5",
+            "instr": "toBe",
+            "message": "",
+            "location": "33:3"
+          },
+          {
+            "order": 4,
+            "type": "",
+            "verdict": "ok",
+            "left": "[1,2,3,4]",
+            "right": "[1,2,3,4]",
+            "instr": "toBe",
+            "message": "",
+            "location": "34:3"
+          },
+          {
+            "order": 5,
+            "type": "",
+            "verdict": "ok",
+            "left": "[\"a\",\"b\",\"c\"]",
+            "right": "[\"a\",\"b\",\"c\"]",
+            "instr": "toBe",
+            "message": "",
+            "location": "35:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      },
+      {
+        "file": "types.spec.ts",
+        "order": 2,
+        "time": {
+          "start": 24563169.72887,
+          "end": 24563169.834605
+        },
+        "description": "Should handle additional alias instances",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "{\"foo\":\"\"}",
+            "right": "{\"foo\":\"\"}",
+            "instr": "toBe",
+            "message": "",
+            "location": "39:3"
+          },
+          {
+            "order": 1,
+            "type": "",
+            "verdict": "ok",
+            "left": "{\"foo\":\"symbols-!@#\"}",
+            "right": "{\"foo\":\"symbols-!@#\"}",
+            "instr": "toBe",
+            "message": "",
+            "location": "40:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      },
+      {
+        "file": "types.spec.ts",
+        "order": 2,
+        "time": {
+          "start": 24563169.865938,
+          "end": 24563169.990183
+        },
+        "description": "Should deserialize additional alias payloads",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "",
+            "right": "",
+            "instr": "toBe",
+            "message": "",
+            "location": "44:3"
+          },
+          {
+            "order": 1,
+            "type": "",
+            "verdict": "ok",
+            "left": "multi word value",
+            "right": "multi word value",
+            "instr": "toBe",
+            "message": "",
+            "location": "45:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      },
+      {
+        "file": "types.spec.ts",
+        "order": 5,
+        "time": {
+          "start": 24563170.034756,
+          "end": 24563170.386557
+        },
+        "description": "Extended regression coverage - nested and escaped payloads",
+        "depth": 0,
+        "suites": [],
+        "tests": [
+          {
+            "order": 0,
+            "type": "",
+            "verdict": "ok",
+            "left": "0",
+            "right": "0",
+            "instr": "toBe",
+            "message": "",
+            "location": "49:3"
+          },
+          {
+            "order": 1,
+            "type": "",
+            "verdict": "ok",
+            "left": "true",
+            "right": "true",
+            "instr": "toBe",
+            "message": "",
+            "location": "50:3"
+          },
+          {
+            "order": 2,
+            "type": "",
+            "verdict": "ok",
+            "left": "-0.125",
+            "right": "-0.125",
+            "instr": "toBe",
+            "message": "",
+            "location": "51:3"
+          },
+          {
+            "order": 3,
+            "type": "",
+            "verdict": "ok",
+            "left": "[[1],[2,3],[]]",
+            "right": "[[1],[2,3],[]]",
+            "instr": "toBe",
+            "message": "",
+            "location": "52:3"
+          },
+          {
+            "order": 4,
+            "type": "",
+            "verdict": "ok",
+            "left": "\"line\\nbreak\"",
+            "right": "\"line\\nbreak\"",
+            "instr": "toBe",
+            "message": "",
+            "location": "53:3"
+          }
+        ],
+        "logs": [],
+        "kind": "describe",
+        "verdict": "ok"
+      }
+    ]
+  }
+]

package/.as-test/runners/default.bindings.js

@@ -0,0 +1,68 @@
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+let patched = false;
+
+function readExact(length) {
+  const out = Buffer.alloc(length);
+  let offset = 0;
+  while (offset < length) {
+    let read = 0;
+    try {
+      read = fs.readSync(0, out, offset, length - offset, null);
+    } catch (error) {
+      if (error && error.code === "EAGAIN") {
+        continue;
+      }
+      throw error;
+    }
+    if (!read) break;
+    offset += read;
+  }
+  const view = out.subarray(0, offset);
+  return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+}
+
+function writeRaw(data) {
+  const view = Buffer.from(data);
+  fs.writeSync(1, view);
+}
+
+function withNodeIo(imports = {}) {
+  if (!patched) {
+    patched = true;
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk, ...args) => {
+      if (chunk instanceof ArrayBuffer) {
+        writeRaw(chunk);
+        return true;
+      }
+      return originalWrite(chunk, ...args);
+    };
+    process.stdin.read = (size) => readExact(Number(size ?? 0));
+  }
+  return imports;
+}
+
+const wasmPathArg = process.argv[2];
+if (!wasmPathArg) {
+  process.stderr.write("usage: node ./.as-test/runners/default.bindings.js <file.wasm>\n");
+  process.exit(1);
+}
+
+const wasmPath = path.resolve(process.cwd(), wasmPathArg);
+const jsPath = wasmPath.replace(/\.wasm$/, ".js");
+
+try {
+  const binary = fs.readFileSync(wasmPath);
+  const module = new WebAssembly.Module(binary);
+  const mod = await import(pathToFileURL(jsPath).href);
+  if (typeof mod.instantiate !== "function") {
+    throw new Error("bindings helper missing instantiate export");
+  }
+  mod.instantiate(module, withNodeIo({}));
+} catch (error) {
+  process.stderr.write("failed to run bindings module: " + String(error) + "\n");
+  process.exit(1);
+}

package/.as-test/runners/default.wasi.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "fs";
+import { WASI } from "wasi";
+
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = (warning, ...args) => {
+  const type = typeof args[0] == "string" ? args[0] : "";
+  const name = typeof warning?.name == "string" ? warning.name : type;
+  const message = typeof warning == "string" ? warning : String(warning?.message ?? "");
+  if (name == "ExperimentalWarning" && message.includes("WASI is an experimental feature")) {
+    return;
+  }
+  return originalEmitWarning(warning, ...args);
+};
+
+const wasmPath = process.argv[2];
+if (!wasmPath) {
+  process.stderr.write("usage: node ./.as-test/runners/default.wasi.js <file.wasm>\n");
+  process.exit(1);
+}
+
+try {
+  const wasi = new WASI({
+    version: "preview1",
+    args: [wasmPath],
+    env: process.env,
+    preopens: {},
+  });
+
+  const binary = readFileSync(wasmPath);
+  const module = new WebAssembly.Module(binary);
+  const instance = new WebAssembly.Instance(module, {
+    wasi_snapshot_preview1: wasi.wasiImport,
+  });
+  wasi.start(instance);
+} catch (error) {
+  process.stderr.write("failed to run WASI module: " + String(error) + "\n");
+  process.exit(1);
+}

package/ARCHITECTURE.md

@@ -58,9 +58,9 @@ The transform (`transform/src/`) is an AssemblyScript compiler plugin that runs
    - Decorator metadata (@alias, @omit, @omitnull, @omitif)
    - Inheritance relationships
    - Type dependencies
-3. **Code Generation**: Generates two methods for each class:
+3. **Code Generation**: Generates methods for each class:
    - `__SERIALIZE(ptr: usize): void` - Writes JSON to the buffer
-   - `__DESERIALIZE<T>(srcStart, srcEnd, out): T` - Parses JSON into object
+   - `__DESERIALIZE<T>(srcStart, srcEnd, out): usize` - Parses JSON into `out` and returns the advanced source pointer
 
 ### Key Files
 
@@ -91,9 +91,10 @@ __SERIALIZE(ptr: usize): void {
   bs.offset += 2;
 }
 
-__DESERIALIZE<T>(srcStart: usize, srcEnd: usize, out: T): T {
+__DESERIALIZE<T>(srcStart: usize, srcEnd: usize, out: T): usize {
   // Key matching and value parsing logic
   // Uses switch statements on key length for efficiency
+  return srcStart;
 }
 ```
 
@@ -286,12 +287,14 @@ For `@json` decorated classes, the generated `__DESERIALIZE` method:
 4. Compares key bytes directly (often as `u32` or `u64` for short keys)
 5. Deserializes value to appropriate type
 6. Stores in output object at correct offset
+7. Returns the updated source pointer after the parsed value
 
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `JSON_MODE` | SWAR | Optimization mode: NAIVE, SWAR, SIMD |
+| `JSON_USE_FAST_PATH` | 0 | When set to `1`, emit the fast struct `__DESERIALIZE` body and helper; otherwise emit only the slow path |
 | `JSON_DEBUG` | 0 | Debug level 0-3 (prints generated code) |
 | `JSON_WRITE` | "" | Comma-separated files to output after transform |
 | `JSON_CACHE` | 0 | Enable string caching (set to 1) |

package/CONTRIBUTING.md

@@ -60,7 +60,7 @@ npm test
 Run a specific test file:
 
 ```bash
-./run-tests.sh string  # Runs string.spec.ts
+npm test string # Runs string.spec.ts
 ```
 
 ### Running Benchmarks
@@ -79,17 +79,23 @@ npm run bench:js
 
 ```
 json-as/
-├── assembly/           # AssemblyScript runtime implementation
+├── .as-test/          # As-test configuration and runners
+├── assembly/          # AssemblyScript runtime implementation
 │   ├── index.ts       # Main entry point (JSON namespace)
 │   ├── serialize/     # Serialization implementations
+│   │   ├── index/     # Indexer of all methods
 │   │   ├── simple/    # Naive implementation
 │   │   ├── swar/      # SWAR-optimized
 │   │   └── simd/      # SIMD-optimized
 │   ├── deserialize/   # Deserialization implementations
+│   │   ├── index/     # Indexer of all methods
+│   │   ├── simple/    # Naive implementation
+│   │   ├── swar/      # SWAR-optimized
+│   │   └── simd/      # SIMD-optimized
 │   ├── util/          # Utility functions
 │   ├── custom/        # Constants and character codes
 │   └── __tests__/     # Test files
-├── transform/          # TypeScript compiler transform
+├── transform/         # TypeScript compiler transform
 │   └── src/           # Transform source code
 ├── lib/               # Shared utilities (buffer system)
 ├── bench/             # Benchmark suite

package/README.md

@@ -36,7 +36,7 @@ npm install json-as
 Add the `--transform` to your `asc` command (e.g. in package.json)
 
 ```bash
---transform json-as/transform
+--transform json-as
 ```
 
 Optionally, for additional performance, also add:
@@ -50,7 +50,7 @@ Alternatively, add it to your `asconfig.json`
 ```typescript
 {
   "options": {
-    "transform": ["json-as/transform"]
+    "transform": ["json-as"]
   }
 }
 ```
@@ -400,15 +400,15 @@ This allows custom serialization while maintaining a generic interface for the l
 
 The `json-as` library is engineered for **multi-GB/s processing speeds**, leveraging SIMD and SWAR optimizations along with highly efficient transformations. The charts below highlight key performance metrics such as build time, operations-per-second, and throughput.
 
-You can **re-run the benchmarks** at any time by clicking the button below. After the workflow completes, refresh this page to view updated results.  
-
-[![Run Benchmarks](https://img.shields.io/badge/Run_Benchmark-blue)](https://github.com/JairusSW/json-as/actions/workflows/benchmark.yml)
-
 ### Comparison to JavaScript
 
-The following charts compare JSON-AS (both SWAR and SIMD variants) against JavaScript's native `JSON` implementation. Benchmarks were conducted in a GitHub Actions environment. On modern hardware, you may see even higher throughput.
+The following charts compare JSON-AS (both SWAR and SIMD variants) against JavaScript's native `JSON` implementation. The published charts are generated locally and pushed to the `docs` branch.
 
 > Note: Benchmarks reflect the **latest version**. Older versions may show different performance.
+>
+> Current local benchmark machine: AMD Ryzen 7 7800X3D (8 cores, 8 threads), 96 MB L3 cache, 32 GB RAM.
+>
+> Benchmark results include normal end-to-end work such as allocating the destination object or array before deserializing into it. Raw parser throughput is higher than the published figures because these numbers intentionally include that allocation/setup cost.
 
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart01.svg" alt="Performance Chart 1">
 
@@ -418,9 +418,9 @@ The following charts compare JSON-AS (both SWAR and SIMD variants) against JavaS
 
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart04.png" alt="Performance Chart 4">
 
-> Note: I have focused on extensively optimizing serialization. I used to have deserialization be highly unsafe and extremely fast, but I've since doubled down on safety for deserialization which has negatively affected performance. I will be optimizing soon.
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart05.png" alt="Performance Chart 5">
 
-> Note on Token: I am currently working on optimizing the token deserialization process. This reflects the *future* performance of this library.
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart06.png" alt="Performance Chart 6">
 
 ### Performance Tuning
 
@@ -433,46 +433,63 @@ Here's a short list:
 
 **JSON_MODE** (default: SWAR) - Selects which mode should be used. Can be `NAIVE,SWAR,SIMD`. Note that `--enable simd` may be required.
 
+**JSON_USE_FAST_PATH** (default: 0) - When set to `1`, the transform emits the fast `__DESERIALIZE` implementation for generated structs. When unset or `0`, it emits only the slow path.
+
 **JSON_WRITE** (default: "") - Select a series of files to output after transform and optimization passes have completed for easy inspection. Usage: `JSON_WRITE=.path-to-file-a.ts,./path-to-file-b.ts`
 
-### Running benchmarks locally
+### Running Benchmarks Locally
 
-Benchmarks are run directly on top of v8 for more tailored control
+Benchmarks are run directly on top of `v8` for tighter control over the engine configuration.
 
-1. Download JSVU off of npm
+1. Install the local benchmark prerequisites:
 
 ```bash
-npm install jsvu -g
+npm install -g jsvu
+jsvu --engines=v8
 ```
 
-2. Modify your dotfiles to add `~/.jsvu/bin` to `PATH`
+2. Add `~/.jsvu/bin` to your `PATH` and make sure `wasm-opt` is installed:
 
 ```bash
 export PATH="${HOME}/.jsvu/bin:${PATH}"
+sudo apt-get install -y binaryen
 ```
 
-3. Clone the repository
+3. Install project dependencies:
 
 ```bash
-git clone https://github.com/JairusSW/json-as
+npm install
 ```
 
-4. Install dependencies
+4. Run either benchmark suite directly:
 
 ```bash
-npm i
+./run-bench.as.sh
+./run-bench.js.sh
 ```
 
-5. Run benchmarks for either AssemblyScript or JavaScript
+5. Build charts from the latest local logs:
 
 ```bash
-./run-bench.as.sh
+./build-charts.sh
 ```
 
-or
+6. Publish benchmark charts to the `docs` branch:
 
 ```bash
-./run-bench.js.sh
+./publish-benchmarks.sh
+```
+
+If you already have fresh logs and only want to rebuild charts and push them:
+
+```bash
+./publish-benchmarks.sh --no-run
+```
+
+Or run the full local publish flow in one step:
+
+```bash
+npm run bench:publish
 ```
 
 ## Debugging

package/as-test.config.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "./node_modules/as-test/as-test.config.schema.json",
+  "input": ["./assembly/__tests__/*.spec.ts"],
+  "outDir": "./.as-test/build",
+  "logs": "./.as-test/logs",
+  "coverageDir": "./.as-test/coverage",
+  "snapshotDir": "./.as-test/snapshots",
+  "config": "none",
+  "coverage": true,
+  "buildOptions": {
+    "args": ["--transform ./transform", "--debug"],
+    "target": "wasi"
+  },
+  "runOptions": {
+    "runtime": {
+      "cmd": "wasmtime <file>"
+    },
+    "reporter": "default"
+  },
+  "modes": {
+    "naive": {
+      "env": {
+        "JSON_MODE": "NAIVE"
+      }
+    },
+    "swar": {
+      "env": {
+        "JSON_MODE": "SWAR"
+      }
+    },
+    "simd": {
+      "env": {
+        "JSON_MODE": "SIMD"
+      },
+      "buildOptions": {
+        "args": ["--enable simd"]
+      }
+    }
+  }
+}