json-as 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -0,0 +1,400 @@
+# Changelog
+
+## Unreleased
+
+## 2026-04-13 - 1.3.2
+
+- fix: remove the fast double parser dependency and return float deserialization to the local legacy parser path
+- fix: restrict string field destination reuse/renewal to heap-backed strings only and avoid writing into static literal storage
+- perf: reduce branching in string field write paths while preserving heap-backed reuse (`simple`, `swar`, `simd`, and shared `bs.toField`)
+- tests: add string-field regression coverage for literal defaults and heap-backed output pointers
+- tooling: fix d8 bench runner lint issues (`print` global and unused buffer id vars)
+- tooling: align `bench` script to use `charts:build`
+- docs: streamline README benchmark/docs sections and update benchmark chart command references
+
+## 2026-03-19 - 1.3.0
+
+- chore: exclude generated `.as-test` build artifacts from ESLint, tighten generic deserializer offset math, and remove the obsolete `run-tests.sh` helper
+- fix: add built-in typed array and `ArrayBuffer` serialization and deserialization support, including transform-generated field handling inside `@json` classes
+- fix: finish subtype-aware `StaticArray` deserialization for nested arrays, maps, JSON value types, transform-backed structs, and related regressions
+- fix: tighten default-path runtime correctness for signed `JSON.Value`, `@omitif("...")`, escaped nested strings, raw-array string handling, and `JSON.Obj.from(...)`
+- perf: add a SIMD string-field deserializer for fast-path object deserialization and align transform codegen with mode-specific field helpers
+- perf: add direct SWAR and SIMD integer-array deserializers with reusable-storage fast paths and dedicated throughput benches
+- refactor: add `assembly/serialize/index/*` and `assembly/deserialize/index/*` dispatchers and route the public API through them
+- perf: speed up float deserialization with handwritten parser paths, bitwise power-of-ten handling, and batched fractional parsing
+- fix: avoid pulling SIMD code into non-SIMD bench builds and make benchmark temp-file cleanup tolerant of missing `asc --converge` outputs
+- compat: add compatability between json-as and try-as by ignoring methods prefixed by __try
+- feat: gate generated fast struct deserialization behind `JSON_USE_FAST_PATH=1`
+- refactor: make generated struct `__DESERIALIZE` methods return the advanced source pointer
+- perf: tune SWAR and SIMD string deserialization to return plain strings directly and only allocate scratch space after the first escape
+- perf: streamline split SWAR string field deserialization and string-buffer reuse on the fast path
+- perf: simplify generated fast integer field parsing to reuse `srcStart` and offset-based stores
+- perf: parse generated numeric fields in a single pass with typed integer, unsigned, and float field helpers
+- perf: hand-tune `small.bench.ts` and refresh benchmark runner turbofan flag configuration
+- bench: add a string deserialization head-to-head benchmark and simplify throughput/chart comparisons back to the final JS/NAIVE/SWAR/SIMD view
+- fix: keep the fast generated path opt-in by default and restore the `large` benchmark slow-path behavior
+- refactor: split numeric deserializers into dedicated `assembly/deserialize/{integer,unsigned,float}` modules
+- tooling: expand benchmark chart metadata parsing for custom string benchmark series
+- tests: add escaped-quote SWAR deserialization regressions around block boundaries
+
+## 2026-02-18 - 1.2.6
+
+- fix: support arbitrary nested arrays and objects [#176](https://github.com/JairusSW/json-as/pull/176)
+- chore: add contributor from [#176](https://github.com/JairusSW/json-as/pull/176)
+- tests: significantly expand coverage across every file in `assembly/__tests__`
+- tests: add additional primitive, array, nested payload, and escaped string regression cases to all specs
+- tests: add more file-specific deserialize/serialize scenarios for custom, struct, map, resolving, and related schema behaviors
+
+## 2026-02-17 - 1.2.5
+
+- fix: stabilize ESLint for this repo by excluding AssemblyScript sources from standard TypeScript lint parsing
+- fix: allow underscore-prefixed intentionally-unused TypeScript variables in transformer sources
+- fix: add d8 globals for benchmark runner linting and make `bench/lib/bench.js` parseable by ESLint
+
+## 2026-01-23 - 1.2.4
+
+- fix: `Set<T>` and `StaticArray<T>` members in classes were not deserializing correctly
+- fix: Fully reset state of transformer between builds
+
+## 2026-01-03 - 1.2.3
+
+- feat: handle surrogates and code units during string serialization and deserialization
+- perf: add SWAR and SIMD string deserialization implementations
+
+## 2025-12-23 - 1.2.2
+
+- chore: reduce package size to sub 70kb
+
+## 2025-12-23 - 1.2.1
+
+- chore: fix chart link in readme
+
+## 2025-12-23 - 1.2.0
+
+- feat: Implement SWAR based algorithms, SIMD improvements, and better documentation.
+
+## 2025-12-21 - 1.1.26
+
+- chore: remove log
+
+## 2025-12-21 - 1.1.25
+
+- feat: Implement SWAR-based string serialization
+
+## 2025-11-28 - 1.1.24
+
+- feat: Implement a moving average window to determine buffer size (essentially, allow the buffer size to shrink) [#163](https://github.com/JairusSW/json-as/pull/163)
+
+## 2025-11-06 - 1.1.23
+
+- fix: Map keys should follow proper typing and quote rules [#161](https://github.com/JairusSW/json-as/issues/161)
+
+## 2025-09-01 - 1.1.22
+
+- fix: Type aliases should work across files [#154](https://github.com/JairusSW/json-as/issues/154)
+
+## 2025-08-14 - 1.1.21
+
+- fix: JSON.parse on classes with enums [#155](https://github.com/JairusSW/json-as/issues/155)
+- fix: Resolve memory OOB issue within `serializeFloat` function [#153](https://github.com/JairusSW/json-as/issues/153)
+
+## 2025-07-14 - 1.1.20
+
+- feat: enable SIMD string serialization
+
+## 2025-06-30 - 1.1.19
+
+- fix: wrong path used in `readFileSync` when importing from a library
+
+## 2025-06-30 - 1.1.18
+
+- fix: [#150](https://github.com/JairusSW/json-as/issues/150)
+
+## 2025-06-17 - 1.1.17
+
+- fix: add support for classes within namespaces [#147](https://github.com/JairusSW/json-as/pull/147)
+
+## 2025-06-12 - 1.1.16
+
+- tests: properly support nulls (in testing lib)
+- fix: initialize generic properties correctly
+- fix: make generated imports compatible with windows
+- feat: add support for fields marked with `readonly`
+
+## 2025-06-09 - 1.1.15
+
+- feat: add `.as<T>()` method to `JSON.Value`
+- chore: remove all references to `__SERIALIZE_CUSTOM`
+- feat: add support for `StaticArray` serialization
+- feat: support `JSON.Raw` in array types
+- tests: add tests for `JSON.Raw[]`
+
+## 2025-05-29 - 1.1.14
+
+- fix: hotfix schema resolver
+
+## 2025-05-29 - 1.1.13
+
+- fix: small issues with schema linking
+- tests: add tests for schema linking and discovery
+
+## 2025-05-29 - 1.1.12
+
+- fix: add helpful warning on unknown or unaccessible types in fields
+- feat: support deserialization of class generics
+- fix: add support for numerical generics
+- tests: add proper testing for generics
+- feat: support type aliases with a custom type resolver/linker
+- chore: add other linkers to tsconfig and clean up
+- feat: add type alias resolving
+
+## 2025-05-28 - 1.1.11
+
+- fix: class resolving should only search top level statements for class declarations
+- fix: add helpful error if class is missing an @json decorator
+- fix: properly calculate relative path when json-as is a library
+- fix: add proper null check when resolving imported classes
+
+## 2025-05-28 - 1.1.10
+
+- feat: add more debug levels (1 = print transform code, 2 = print keys/values at runtime)
+- feat: add write out feature (`JSON_WRITE=path-to-file.ts`) which writes out generated code
+- fix: complete full parity between port and original version for correct deserialization of all types
+- feat: add proper schema resolution and dependency resolution
+- feat: add proper type resolution to schema fields
+- fix: properly calculate the relative path between imports to modules
+
+## 2025-05-27 - 1.1.9
+
+- change: strict mode is disabled by default. Enable it with JSON_STRICT=true
+- fix: should ignore properties of same length and type if no matching key exists
+- fix: should ignore properties of different type if no matching key exists
+- fix: should ignore complex properties if no matching key exists
+
+## 2025-05-27 - 1.1.8
+
+- feat: add support for calling `JSON.stringify/JSON.parse` methods inside of custom serializers, but not yet deserializers
+
+## 2025-05-27 - 1.1.7
+
+- fix: bad boolean logic to decide whether to add 2nd break statement
+
+## 2025-05-23 - 1.1.6
+
+- fix: null and boolean fields would miscalculate offsets when deserializing
+
+## 2025-05-23 - 1.1.5
+
+- fix: index.js didn't point to correct file, thus creating a compiler crash
+
+## 2025-05-23 - 1.1.4
+
+- revert: grouping properties in favor of memory.compare
+
+## 2025-05-23 - 1.1.3
+
+- feat: group properties of structs before code generation
+- fix: break out of switch case after completion
+- ci: make compatible with act for local testing
+
+## 2025-05-22 - 1.1.2
+
+- fix: correct small typos in string value deserialization port
+
+## 2025-05-22 - 1.1.1
+
+- fix: remove random logs
+
+## 2025-05-22 - 1.1.0
+
+- fix: change _DESERIALIZE<T> to _JSON_T to avoid populating local scope
+
+## 2025-05-22 - 1.0.9
+
+- fix: [#132](https://github.com/JairusSW/json-as/issues/132)
+- feat: allow base classes to use their child classes if the signatures match
+- perf: rewrite struct deserialization to be significantly faster
+- fix: [#131](https://github.com/JairusSW/json-as/issues/131) Generic classes with custom deserializer crashing
+- fix: [#66](https://github.com/JairusSW/json-as/issues/66) Throw error when additional keys are in JSON
+
+## 2025-05-21 - 1.0.8
+
+- fix: inline warnings on layer-2 serialize and deserialize functions
+- feat: fully support `JSON.Obj` and `JSON.Box` everywhere
+- fix: temp disable SIMD
+- feat: write fair benchmarks with `v8` using `jsvu`
+
+## 2025-05-14 - 1.0.7
+
+- merge: pull request [#128](https://github.com/JairusSW/json-as/pull/128) from [loredanacirstea/nested-custom-serializer-fix](https://github.com/loredanacirstea/nested-custom-serializer-fix)
+
+## 2025-05-12 - 1.0.6
+
+- fix: support zero-param serialization and make sure types are consistent
+- fix: [#124](https://github.com/JairusSW/json-as/issues/124)
+
+## 2025-05-11 - 1.0.5
+
+- feat: add sanity checks for badly formatted strings
+- fix: [#120](https://github.com/JairusSW/json-as/issues/120) handle empty `JSON.Obj` serialization
+- feat: add SIMD optimization if SIMD is enabled by user
+- fix: handle structs with nullable array as property [#123](https://github.com/JairusSW/json-as/pull/123)
+- fix: struct serialization from writing to incorrect parts of memory when parsing nested structs [#125](https://github.com/JairusSW/json-as/pull/125)
+- chore: add two new contributors
+
+## 2025-04-07 - 1.0.4
+
+- fix: paths must be resolved as POSIX in order to be valid TypeScript imports [#116](https://github.com/JairusSW/json-as/issues/116)
+
+## 2025-03-24 - 1.0.3
+
+- fix: make transform windows-compatible [#119](https://github.com/JairusSW/json-as/issues/119?reload=1)
+
+## 2025-03-19 - 1.0.2
+
+- fix: include check for nullable types for properties when deserialization is called internally [#118](https://github.com/JairusSW/json-as/pull/118)
+
+## 2025-03-10 - 1.0.1
+
+- docs: add comprehensive performance metrics
+
+## 2025-03-09 - 1.0.0
+
+- fix: relative paths pointing through node_modules would create a second Source
+- feat: move behavior of `--lib` into transform itself
+- fix: object with an object as a value containing a rhs bracket or brace would exit early [3b33e94](https://github.com/JairusSW/json-as/commit/3b33e9414dc04779d22d65272863372fcd7af4a6)
+
+## 2025-03-04 - 1.0.0-beta.17
+
+- fix: forgot to build transform
+
+## 2025-03-04 - 1.0.0-beta.16
+
+- fix: isPrimitive should only trigger on actual primitives
+
+## 2025-03-04 - 1.0.0-beta.15
+
+- fix: deserialize custom should take in string
+
+## 2025-03-04 - 1.0.0-beta.14
+
+- fix: reference to nonexistent variable during custom deserialization layer 2
+
+## 2025-03-04 - 1.0.0-beta.13
+
+- fix: forgot to actually build the transform
+
+## 2025-03-04 - 1.0.0-beta.12
+
+- fix: build transform
+
+## 2025-03-04 - 1.0.0-beta.11
+
+- fix: wrongly assumed pointer types within arbitrary deserialization
+- fix: wrong pointer type being passed during map deserialization
+
+## 2025-03-04 - 1.0.0-beta.10
+
+- fix: transform not generating the right load operations for keys
+- fix: whitespace not working in objects or struct deserialization
+- fix: JSON.Raw not working when deserializing as Map<string, JSON.Raw>
+
+## 2025-03-03 - 1.0.0-beta.9
+
+- rename: change libs folder to lib
+
+## 2025-03-03 - 1.0.0-beta.8
+
+- docs: add instructions for using `--lib` in README
+
+## 2025-03-03 - 1.0.0-beta.7
+
+- fix: add as-bs to `--lib` section
+- chore: clean up transform
+- refactor: transform should import `~lib/as-bs.ts` instead of relative path
+
+## 2025-03-01 - 1.0.0-beta.6
+
+- fix: import from base directory index.ts
+
+## 2025-03-01 - 1.0.0-beta.5
+
+- fix: revert pull request [#112](https://github.com/JairusSW/json-as/pull/112)
+
+## 2025-02-25 - 1.0.0-beta.4
+
+- fix: warn on presence of invalid types contained in a schema [#112](https://github.com/JairusSW/json-as/pull/112)
+
+## 2025-02-25 - 1.0.0-beta.3
+
+- feat: change `JSON.Raw` to actual class to facilitate proper support without transformations
+- fix: remove old `JSON.Raw` logic from transform code
+
+## 2025-02-25 - 1.0.0-beta.2
+
+- feat: add support for custom serializers and deserializers [#110](https://github.com/JairusSW/json-as/pull/110)
+
+## 2025-02-22 - 1.0.0-beta.1
+
+- perf: add benchmarks for both AssemblyScript and JavaScript
+- docs: publish preliminary benchmark results
+- tests: ensure nested serialization works and add to tests
+- feat: finish arbitrary type implementation
+- feat: introduce `JSON.Obj` to handle objects effectively
+- feat: reimplement arbitrary array deserialization
+- fix: remove brace check on array deserialization
+- feat: introduce native support for `JSON.Obj` transformations
+- feat: implement arbitrary object serialization
+- fix: deserialization of booleans panics on `false`
+- fix: `bs.resize` should be type-safe
+- impl: add `JSON.Obj` type as prototype to handle arbitrary object structures
+- chore: rename static objects (schemas) to structs and name arbitrary objects as `obj`
+- tests: add proper tests for arbitrary types
+- fix: empty method generation using outdated function signature
+- docs: update readme to be more concise
+
+## 2025-02-13 - 1.0.0-alpha.4
+
+- feat: reintroduce support for `Box<T>`-wrapped primitive types
+- tests: add extensive tests to all supported types
+- fix: 6-byte keys being recognized on deserialize
+- perf: take advantage of aligned memory to use a single 64-bit load on 6-byte keys
+- fix: `bs.proposeSize()` should increment `stackSize` by `size` instead of setting it
+- fix: allow runtime to manage `bs.buffer`
+- fix: memory leaks in `bs` module
+- fix: add (possibly temporary) `JSON.Memory.shrink()` to shrink memory in `bs`
+- perf: prefer growing memory by `nextPowerOf2(size + 64)` for less reallocations
+- tests: add boolean tests to `Box<T>`
+- fix: serialization of non-growable data types should grow `bs.stackSize`
+
+## 2025-01-31 - 1.0.0-alpha.3
+
+- fix: write to proper offset when deserializing string with \u0000-type escapes
+- fix: simplify and fix memory offset issues with bs module
+- fix: properly predict minimum size of to-be-serialized schemas
+- fix: replace as-test with temporary framework to mitigate json-as versioning issues
+- fix: fix multiple memory leaks during serialization
+- feat: align memory allocations for better performance
+- feat: achieve a space complexity of O(n) for serialization operations, unless dealing with \u0000-type escapes
+
+## 2025-01-20 - 1.0.0-alpha.2
+
+- fix: disable SIMD in generated transform code by default
+- fix: re-add as-bs dependency so that it will not break in non-local environments
+- fix: remove AS201 'conversion from type usize to i32' warning
+- fix: add as-bs to peer dependencies so only one version is installed
+- fix: point as-bs imports to submodule
+- fix: remove submodule in favor of static module
+- fix: bs.ensureSize would not grow and thus cause memory faults
+- fix: bs.ensureSize triggering unintentionally
+
+## 2025-01-20 - 1.0.0-alpha.1
+
+- feat: finish implementation of arbitrary data serialization and deserialization using JSON.Value
+- feat: reinstate usage of `JSON.Box<T>()` to support nullable primitive types
+- feat: eliminate the need to import the `JSON` namespace when defining a schema
+- feat: reduce memory usage so that it is viable for low-memory environments
+- feat: write to a central buffer and reduce memory overhead
+- feat: rewrite the transform to properly resolve schemas and link them together
+- feat: pre-allocate and compute the minimum size of a schema to avoid memory out of range errors
+>>>>>>> cf237fa (chore: release 1.3.0)

package/README.md

@@ -6,6 +6,7 @@
 <summary>Table of Contents</summary>
 
 - [Installation](#installation)
+- [Docs](#docs)
 - [Usage](#usage)
 - [Examples](#examples)
   - [Omitting Fields](#omitting-fields)
@@ -14,9 +15,12 @@
   - [Using Raw JSON Strings](#using-raw-json-strings)
   - [Working with Enums](#working-with-enums)
   - [Using Custom Serializers or Deserializers](#using-custom-serializers-or-deserializers)
+  - [Overriding built-in Container Types](#overriding-built-in-container-types)
 - [Performance](#performance)
   - [Comparison to JavaScript](#comparison-to-javascript)
   - [Performance Tuning](#performance-tuning)
+  - [Fast-Path Compatibility Matrix](#fast-path-compatibility-matrix)
+  - [Container Compatibility Matrix](#container-compatibility-matrix)
   - [Running Benchmarks Locally](#running-benchmarks-locally)
 - [Debugging](#debugging)
 - [Architecture](#architecture)
@@ -57,6 +61,12 @@ Alternatively, add it to your `asconfig.json`
 
 If you'd like to see the code that the transform generates, run the build step with `DEBUG=true`
 
+## Docs
+
+Full documentation lives at:
+
+<https://docs.jairus.dev/json-as>
+
 ## Usage
 
 ```typescript
@@ -334,11 +344,11 @@ const serialized = JSON.stringify<Foo>(Foo.bar);
 
 This library supports custom serialization and deserialization methods, which can be defined using the `@serializer` and `@deserializer` decorators.
 
-Here's an example of creating a custom data type called `Point` which serializes to `(x,y)`
+Custom serializers and deserializers must always speak valid JSON. You can optionally provide the JSON value shape they operate on using one of: `"any"`, `"string"`, `"number"`, `"object"`, `"array"`, `"boolean"`, or `"null"`. If omitted, the shape defaults to `"any"`.
 
-```typescript
-import { bytes } from "json-as/assembly/util";
+Here's an example of creating a custom data type called `Point` which serializes to a JSON string:
 
+```typescript
 @json
 class Point {
   x: f64 = 0.0;
@@ -348,21 +358,21 @@ class Point {
     this.y = y;
   }
 
-  @serializer
+  @serializer("string")
   serializer(self: Point): string {
-    return `(${self.x},${self.y})`;
+    return JSON.stringify(`${self.x},${self.y}`);
   }
 
-  @deserializer
+  @deserializer("string")
   deserializer(data: string): Point {
-    const dataSize = bytes(data);
-    if (dataSize <= 2) throw new Error("Could not deserialize provided data as type Point");
+    const raw = JSON.parse<string>(data);
+    if (!raw.length) throw new Error("Could not deserialize provided data as type Point");
 
-    const c = data.indexOf(",");
-    const x = data.slice(1, c);
-    const y = data.slice(c + 1, data.length - 1);
+    const c = raw.indexOf(",");
+    const x = raw.slice(0, c);
+    const y = raw.slice(c + 1);
 
-    return new Point(f64.parse(x), f64.parse(y));
+    return new Point(f64.parse(x), f64.parse(y)); // NEVER use this in deserializers. Always return a new instance
   }
 }
 
@@ -375,9 +385,11 @@ console.log("Serialized    " + serialized);
 console.log("Deserialized  " + JSON.stringify(deserialized));
 ```
 
-The serializer function converts a `Point` instance into a string format `(x,y)`.
+The serializer function converts a `Point` instance into a valid JSON string value.
+
+The deserializer function parses that JSON string back into a `Point` instance.
 
-The deserializer function parses the string `(x,y)` back into a `Point` instance.
+Custom deserializers should always instantiate and return a new object. They should not assume an existing destination instance will be passed in or reused.
 
 These functions are then wrapped before being consumed by the json-as library:
 
@@ -396,6 +408,85 @@ These functions are then wrapped before being consumed by the json-as library:
 
 This allows custom serialization while maintaining a generic interface for the library to access.
 
+### Overriding built-in container types
+
+Undecorated subclasses of built-in container types keep the built-in JSON behavior.
+
+This rule applies consistently across:
+
+- `JSON.stringify(...)`
+- `JSON.parse<T>(...)`
+- `JSON.Value.from(...)`
+- `JSON.internal.stringify(...)`
+- `JSON.internal.parse(...)`
+
+For example:
+
+- `class MyBytes extends Uint8Array {}` still serializes like a normal `Uint8Array`
+- `class MyMap extends Map<string, i32> {}` still serializes like a normal `Map<string, i32>`
+- the same applies to subclassable built-ins such as `Array`, `Set`, and typed arrays
+
+If you decorate that subclass with `@json`, it is treated as a normal generated class instead of inheriting the built-in container behavior. That means generated `__SERIALIZE` / `__DESERIALIZE` logic and custom serializer/deserializer hooks can take over.
+
+If you want a different wire format, decorate the subclass with `@json` and provide custom `@serializer(...)` / `@deserializer(...)` methods:
+
+```typescript
+function hexDigit(value: u8): string {
+  return String.fromCharCode(value < 10 ? 48 + value : 87 + value);
+}
+
+function parseHexNibble(code: u16): u8 {
+  if (code >= 48 && code <= 57) return <u8>(code - 48);
+  if (code >= 97 && code <= 102) return <u8>(code - 87);
+  return <u8>(code - 55);
+}
+
+@json
+class HexBytes extends Uint8Array {
+  constructor(length: i32 = 0) {
+    super(length);
+  }
+
+  @serializer("string")
+  serializer(self: HexBytes): string {
+    let out = "";
+    for (let i = 0; i < self.length; i++) {
+      const value = unchecked(self[i]);
+      out += hexDigit(value >> 4);
+      out += hexDigit(value & 0x0f);
+    }
+    return JSON.stringify(out);
+  }
+
+  @deserializer("string")
+  deserializer(data: string): HexBytes {
+    const raw = JSON.parse<string>(data);
+    const out = new HexBytes(raw.length >> 1);
+
+    for (let i = 0, j = 0; i < raw.length; i += 2, j++) {
+      const hi = parseHexNibble(<u16>raw.charCodeAt(i));
+      const lo = parseHexNibble(<u16>raw.charCodeAt(i + 1));
+      unchecked((out[j] = <u8>((hi << 4) | lo)));
+    }
+
+    return out;
+  }
+}
+
+const bytes = new HexBytes(4);
+bytes[0] = 10;
+bytes[1] = 20;
+bytes[2] = 30;
+bytes[3] = 40;
+
+JSON.stringify(bytes);      // "\"0a141e28\""
+JSON.parse<HexBytes>("\"0a141e28\"");
+```
+
+This same pattern works for subclassable built-ins like `Array`, `Map`, `Set`, and typed arrays.
+
+`ArrayBuffer` and `String` are `@final` in AssemblyScript, so they cannot be subclassed there.
+
 ## Performance
 
 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.
@@ -414,14 +505,38 @@ 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/chart02.svg" alt="Performance Chart 2">
 
+<details>
+<summary>String serialize charts (click to expand)</summary>
+
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart03.png" alt="Performance Chart 3">
 
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart07.png" alt="Performance Chart 7">
+</details>
+
+<details>
+<summary>String deserialize charts (click to expand)</summary>
+
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart04.png" alt="Performance Chart 4">
 
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart08.png" alt="Performance Chart 8">
+</details>
+
+<details>
+<summary>Object serialize charts (click to expand)</summary>
+
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart05.png" alt="Performance Chart 5">
 
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart09.png" alt="Performance Chart 9">
+</details>
+
+<details>
+<summary>Object deserialize charts (click to expand)</summary>
+
 <img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart06.png" alt="Performance Chart 6">
 
+<img src="https://raw.githubusercontent.com/JairusSW/json-as/refs/heads/docs/charts/chart10.png" alt="Performance Chart 10">
+</details>
+
 ### Performance Tuning
 
 Instead of using flags for setting options, `json-as` is configured by environmental variables.
@@ -433,7 +548,7 @@ 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_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. See [FAST_PATH_DESERIALIZE.md](./FAST_PATH_DESERIALIZE.md) for the current support matrix, known gaps, and dedicated test command.
 
 **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`
 
@@ -464,32 +579,20 @@ npm install
 4. Run either benchmark suite directly:
 
 ```bash
-./run-bench.as.sh
-./run-bench.js.sh
+npm run bench:as
+npm run bench:js
 ```
 
 5. Build charts from the latest local logs:
 
 ```bash
-./build-charts.sh
-```
-
-6. Publish benchmark charts to the `docs` branch:
-
-```bash
-./publish-benchmarks.sh
+npm run charts:build
 ```
 
-If you already have fresh logs and only want to rebuild charts and push them:
+Or run the full local benchmark flow in one step:
 
 ```bash
-./publish-benchmarks.sh --no-run
-```
-
-Or run the full local publish flow in one step:
-
-```bash
-npm run bench:publish
+npm run bench
 ```
 
 ## Debugging
@@ -502,6 +605,8 @@ npm run bench:publish
 
 For a deep dive into how json-as works internally, including the transform system, optimization modes (NAIVE, SWAR, SIMD), and buffer management, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 
+For a code-oriented repository walkthrough that maps the runtime, transform, tests, and benchmark files to their concrete responsibilities, see [PROJECT_WALKTHROUGH.md](./PROJECT_WALKTHROUGH.md).
+
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on:

package/assembly/deserialize/index/arbitrary.ts

@@ -1,7 +1,7 @@
 import { JSON } from "../..";
 import { deserializeArray } from "./array";
 import { deserializeBoolean } from "./bool";
-import { deserializeFloat } from "./float";
+import { deserializeFloat } from "../simple/float";
 import { deserializeObject } from "./object";
 import { deserializeString } from "./string";
 import { BRACE_LEFT, BRACKET_LEFT, CHAR_N, QUOTE } from "../../custom/chars";