json-as 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,417 @@
+# Changelog
+
+## Unreleased
+
+- feat: allow `JSON.Value` to store and re-serialize built-in typed arrays and `ArrayBuffer`
+- feat: support `JSON.stringify<ArrayBuffer>(...)` directly without a dedicated helper
+- feat: let explicit `__SERIALIZE_CUSTOM` / `__DESERIALIZE_CUSTOM` hooks override built-in typed-array and `ArrayBuffer` handling while keeping generated hooks last
+- feat: support optional JSON shape hints on `@serializer(...)` / `@deserializer(...)` decorators, defaulting to `any` and allowing nullable forms like `string | null`
+- fix: preserve `bs` state across `JSON.internal.stringify(...)` and `JSON.internal.parse(...)`
+- fix: make escaped string deserializers use local `bs` slices so nested parse/custom flows do not clobber active buffer state
+- fix: allow nested `@json` fields that use decorator-based custom deserializers to deserialize correctly from string-valued object properties
+- fix: restore correct object-value end pointers in generated field deserializers so nested maps and custom string-backed fields both deserialize correctly
+- fix: make `JSON.Value` follow built-in subclass rules consistently for typed-array subclasses and custom `@json` subclasses
+- fix: make generated custom serializer wrappers use the provided `ptr` so indirect-call sites like `JSON.Value` serialize correctly
+- fix: resolve stdlib and `--lib` base classes during transform inheritance so `@json` subclasses of built-ins like `Uint8Array` include inherited fields instead of collapsing to empty objects
+- fix: stop preloading transform imports through `parser.parseFile(...)`, so repeated `asc()` calls in the same process no longer poison parser state or trip `lookupForeignFile` assertions
+- fix: rewrite nested `JSON.parse(...)` calls inside custom serializers and deserializers to `JSON.internal.parse(...)`, matching the existing internal stringify rewrite and documented behavior
+- docs: clarify that custom serializers and deserializers must always produce and consume valid JSON
+- docs: document how subclassing built-in container types behaves, including when `@json` custom overrides take effect
+- fix: stop naive string deserialization scratch allocations from growing across repeated large payload parses by using local `ensureSize(...)` scratch capacity instead of serialization-style proposed growth
+- tests: expand custom serializer/deserializer coverage for nullable fields, multiple custom fields, escaped content, whitespace, and repeated round-trips
+- tests: add a repeated large string-heavy struct parse regression that exercises the naive deserialization scratch path
+- tests: add override coverage for plain and custom subclasses of `Array`, `Map`, `Set`, and typed arrays
+- tests: add `JSON.Value` regressions for undecorated and decorated typed-array subclasses
+- tests: add regression coverage for generated `@json` subclasses inheriting stdlib typed-array fields
+- chore: restrict published package contents to the runtime, declarations, built transform output, and top-level metadata files
+- perf: raise the serialization buffer minimum size to 1024 bytes and add adaptive `bs.shrink()`
+- perf: add a packed SWAR `u16_to_hex4_swar` helper for `\uXXXX` emission and use it across simple, SWAR, and SIMD string serializers
+- tests: add dedicated SWAR hex helper coverage, including exhaustive full-range round-trip validation
+- bench: add SWAR hex and SWAR string serializer head-to-head microbenchmarks
+
+## 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

@@ -14,6 +14,7 @@
   - [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)
@@ -334,11 +335,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 +349,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 +376,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 the string `(x,y)` back into a `Point` instance.
+The deserializer function parses that JSON string 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 +399,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.

package/assembly/deserialize/index/typedarray.ts

@@ -1 +1,15 @@
+import { bytes } from "../../util";
 export { deserializeArrayBuffer, deserializeTypedArray } from "../simple/typedarray";
+import { deserializeArrayBuffer, deserializeTypedArray } from "../simple/typedarray";
+
+
+@inline export function parseArrayBuffer(data: string): ArrayBuffer {
+  const dataSize = bytes(data);
+  const dataPtr = changetype<usize>(data);
+  return deserializeArrayBuffer(dataPtr, dataPtr + dataSize, 0);
+}
+
+
+@inline export function __deserializeArrayBuffer(srcStart: usize, srcEnd: usize, dst: usize = 0): ArrayBuffer {
+  return deserializeArrayBuffer(srcStart, srcEnd, dst);
+}

package/assembly/deserialize/simd/string.ts

@@ -99,10 +99,10 @@ import { deserializeStringField_SWAR } from "../swar/string";
   const prefixLen = <u32>(escapeStart - payloadStart);
   let srcStart = escapeStart;
   const srcEnd16 = srcEnd - 16;
+  const outStart = bs.offset - bs.buffer;
   bs.ensureSize(u32(srcEnd - srcStart));
-  bs.offset = bs.buffer;
   if (prefixLen != 0) {
-    memory.copy(bs.buffer, payloadStart, prefixLen);
+    memory.copy(bs.offset, payloadStart, prefixLen);
     bs.offset += prefixLen;
   }
 
@@ -195,7 +195,7 @@ import { deserializeStringField_SWAR } from "../swar/string";
     bs.offset += 2;
   }
 
-  return bs.out<string>();
+  return bs.sliceOut<string>(outStart);
 }
 
 export function deserializeString_SIMD(srcStart: usize, srcEnd: usize): string {