json-as 1.0.0-beta.9 → 1.0.1

package/.github/workflows/{nodejs.yml → tests.yml}

@@ -20,4 +20,4 @@ jobs:
         run: bun install
 
       - name: Run Tests
-        run: bun run test
+        run: bash ./run-tests.sh

package/{CHANGELOG → CHANGELOG.md}

@@ -1,5 +1,50 @@
 # Change Log
 
+## 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

package/README.md

@@ -6,7 +6,7 @@
 ██   ██      ██ ██    ██ ██  ██ ██       ██   ██      ██
  █████  ███████  ██████  ██   ████       ██   ██ ███████
  </span>
-    AssemblyScript - v1.0.0-beta.9
+    AssemblyScript - v1.0.1
   </pre>
 </h5>
 
@@ -14,6 +14,18 @@
 
 JSON is the de-facto serialization format of modern web applications, but its serialization and deserialization remain a significant performance bottleneck, especially at scale. Traditional parsing approaches are computationally expensive, adding unnecessary overhead to both clients and servers. This library is designed to mitigate this by leveraging SIMD acceleration and highly optimized transformations.
 
+## 🔭 What's new
+
+🔹Major performance improvements and addition of SIMD
+
+🔹Near zero-growth allocation design and low overhead
+
+🔹Support for custom serializer and deserializers
+
+🔹Fixes to many, many, bugs and edge cases
+
+🔹Support for dynamic objects, arrays, arbitrary values, and raw types
+
 ## 📚 Contents
 
 - [Installation](#-installation)
@@ -31,22 +43,21 @@ JSON is the de-facto serialization format of modern web applications, but its se
 ## 💾 Installation
 
 ```bash
-npm install json-as@1.0.0-beta.9
+npm install json-as
 ```
 
 Add the `--transform` to your `asc` command (e.g. in package.json)
 
 ```bash
---transform json-as/transform --lib json-as/lib
+--transform json-as/transform
 ```
 
 Alternatively, add it to your `asconfig.json`
 
-```json
+```typescript
 {
   "options": {
-    "transform": ["json-as/transform"],
-    "lib": ["json-as/lib"]
+    "transform": ["json-as/transform"]
   }
 }
 ```
@@ -55,7 +66,7 @@ If you'd like to see the code that the transform generates, run with `JSON_DEBUG
 
 ## 🪄 Usage
 
-```js
+```typescript
 import { JSON } from "json-as";
 
 @json
@@ -82,15 +93,15 @@ class Player {
 const player: Player = {
   firstName: "Jairus",
   lastName: "Tanaka",
-  lastActive: [2, 13, 2025],
+  lastActive: [3, 9, 2025],
   age: 18,
   pos: {
     x: 3.4,
     y: 1.2,
-    z: 8.3
+    z: 8.3,
   },
-  isVerified: true
-};
+  isVerified: true,
+}
 
 const serialized = JSON.stringify<Player>(player);
 const deserialized = JSON.parse<Player>(serialized);
@@ -109,26 +120,26 @@ This library allows selective omission of fields during serialization using the
 
 This decorator excludes a field from serialization entirely.
 
-```js
+```typescript
 @json
 class Example {
   name!: string;
   @omit
-  secret!: string;
+  SSN!: string;
 }
 
 const obj = new Example();
-obj.name = "Visible";
-obj.secret = "Hidden";
+obj.name = "Jairus";
+obj.SSN = "123-45-6789";
 
-console.log(JSON.stringify(obj)); // { "name": "Visible" }
+console.log(JSON.stringify(obj)); // { "name": "Jairus" }
 ```
 
 **@omitnull**
 
 This decorator omits a field only if its value is null.
 
-```js
+```typescript
 @json
 class Example {
   name!: string;
@@ -137,30 +148,36 @@ class Example {
 }
 
 const obj = new Example();
-obj.name = "Present";
+obj.name = "Jairus";
 obj.optionalField = null;
 
-console.log(JSON.stringify(obj)); // { "name": "Present" }
+console.log(JSON.stringify(obj)); // { "name": "Jairus" }
+```
 
-@omitif((self: this) => condition)
+**@omitif((self: this) => condition)**
 
 This decorator omits a field based on a custom predicate function.
 
+```typescript
 @json
 class Example {
   name!: string;
-  @omitif((self: Example) => self.age < 18)
+  @omitif((self: Example) => self.age <= 18)
   age!: number;
 }
 
 const obj = new Example();
-obj.name = "John";
-obj.age = 16;
+obj.name = "Jairus";
+obj.age = 18;
+
+console.log(JSON.stringify(obj)); // { "name": "Jairus" }
+
+obj.age = 99;
 
-console.log(JSON.stringify(obj)); // { "name": "John" }
+console.log(JSON.stringify(obj)); // { "name": "Jairus", "age": 99 }
 ```
 
-If age were 18 or higher, it would be included in the serialization.
+If age were higher than 18, it would be included in the serialization.
 
 ### 🗳️ Using nullable primitives
 
@@ -168,7 +185,7 @@ AssemblyScript doesn't support using nullable primitive types, so instead, json-
 
 For example, this schema won't compile in AssemblyScript:
 
-```js
+```typescript
 @json
 class Person {
   name!: string;
@@ -178,7 +195,7 @@ class Person {
 
 Instead, use `JSON.Box` to allow nullable primitives:
 
-```js
+```typescript
 @json
 class Person {
   name: string;
@@ -188,11 +205,11 @@ class Person {
   }
 }
 
-const person = new Person("Bob");
-console.log(JSON.stringify(person)); // {"name":"Bob","age":null}
+const person = new Person("Jairus");
+console.log(JSON.stringify(person)); // {"name":"Jairus","age":null}
 
 person.age = new JSON.Box<i32>(18); // Set age to 18
-console.log(JSON.stringify(person)); // {"name":"Bob","age":18}
+console.log(JSON.stringify(person)); // {"name":"Jairus","age":18}
 ```
 
 ### 📤 Working with unknown or dynamic data
@@ -205,31 +222,31 @@ Here's a few examples:
 
 **Working with multi-type arrays**
 
-When dealing with arrays that have multiple types within them, eg. `["string",true,null,["array"]]`, use `JSON.Value[]`
+When dealing with arrays that have multiple types within them, eg. `["string",true,["array"]]`, use `JSON.Value[]`
 
-```js
-const a1 = JSON.parse<JSON.Value[]>('["string",true,null,["array"]]');
+```typescript
+const a = JSON.parse<JSON.Value[]>('["string",true,["array"]]');
 console.log(JSON.stringify(a[0])); // "string"
 console.log(JSON.stringify(a[1])); // true
-console.log(JSON.stringify(a[2])); // null
-console.log(JSON.stringify(a[3])); // ["array"]
+console.log(JSON.stringify(a[2])); // ["array"]
 ```
 
 **Working with unknown objects**
 
 When dealing with an object with an unknown structure, use the `JSON.Obj` type
 
-```js
-const o1 = JSON.parse<JSON.Obj>('{"a":3.14,"b":true,"c":[1,2,3],"d":{"x":1,"y":2,"z":3}}');
+```typescript
+const obj = JSON.parse<JSON.Obj>('{"a":3.14,"b":true,"c":[1,2,3],"d":{"x":1,"y":2,"z":3}}');
 
-console.log(o1.keys().join(" ")); // a b c d
-console.log(
-  o1.values()
-  .map<string>((v) => JSON.stringify(v))
-  .join(" ")
+console.log("Keys: " + obj.keys().join(" ")); // a b c d
+console.log("Values: " +
+  obj
+    .values()
+    .map<string>((v) => JSON.stringify(v))
+    .join(" "),
 ); // 3.14 true [1,2,3] {"x":1,"y":2,"z":3}
 
-const y = o1.get("d").get<JSON.Obj>().get<i32>();
+const y = obj.get("d")!.get<JSON.Obj>().get("y")!;
 console.log('o1["d"]["y"] = ' + y.toString()); // o1["d"]["y"] = 2
 ```
 
@@ -239,7 +256,7 @@ More often, objects will be completely statically typed except for one or two va
 
 In such cases, `JSON.Value` can be used to handle fields that may hold different types at runtime.
 
-```js
+```typescript
 @json
 class DynamicObj {
   id: i32 = 0;
@@ -267,24 +284,22 @@ Sometimes its necessary to simply copy a string instead of serializing it.
 
 For example, the following data would typically be serialized as:
 
-```js
-const m1 = new Map<string, string>();
-m1.set('pos', '{"x":1.0,"y":2.0,"z":3.0}');
+```typescript
+const map = new Map<string, string>();
+map.set("pos", '{"x":1.0,"y":2.0,"z":3.0}');
 
-const a1 = JSON.stringify(m1);
-console.log("a1: " + a1);
+console.log(JSON.stringify(map));
 // {"pos":"{\"x\":1.0,\"y\":2.0,\"z\":3.0}"}
 // pos's value (Vec3) is contained within a string... ideally, it should be left alone
 ```
 
 If, instead, one wanted to insert Raw JSON into an existing schema/data structure, they could make use of the JSON.Raw type to do so:
 
-```js
-const m1 = new Map<string, JSON.Raw>();
-m1.set('pos', new JSON.Raw('{"x":1.0,"y":2.0,"z":3.0}'));
+```typescript
+const map = new Map<string, JSON.Raw>();
+map.set("pos", new JSON.Raw('{"x":1.0,"y":2.0,"z":3.0}'));
 
-const a1 = JSON.stringify(m1);
-console.log("a1: " + a1);
+console.log(JSON.stringify(map));
 // {"pos":{"x":1.0,"y":2.0,"z":3.0}}
 // Now its properly formatted JSON where pos's value is of type Vec3 not string!
 ```
@@ -295,7 +310,9 @@ This library supports custom serialization and deserialization methods, which ca
 
 Here's an example of creating a custom data type called `Point` which serializes to `(x,y)`
 
-```js
+```typescript
+import { bytes } from "json-as/assembly/util";
+
 @json
 class Point {
   x: f64 = 0.0;
@@ -319,12 +336,17 @@ class Point {
     const x = data.slice(1, c);
     const y = data.slice(c + 1, data.length - 1);
 
-    return new Point(
-      f64.parse(x),
-      f64.parse(y)
-    );
+    return new Point(f64.parse(x), f64.parse(y));
   }
 }
+
+const obj = new Point(3.5, -9.2);
+
+const serialized = JSON.stringify<Point>(obj);
+const deserialized = JSON.parse<Point>(serialized);
+
+console.log("Serialized    " + serialized);
+console.log("Deserialized  " + JSON.stringify(deserialized));
 ```
 
 The serializer function converts a `Point` instance into a string format `(x,y)`.
@@ -333,7 +355,7 @@ The deserializer function parses the string `(x,y)` back into a `Point` instance
 
 These functions are then wrapped before being consumed by the json-as library:
 
-```js
+```typescript
 @inline __SERIALIZE_CUSTOM(ptr: usize): void {
   const data = this.serializer(changetype<Point>(ptr));
   const dataSize = data.length << 1;
@@ -350,47 +372,79 @@ This allows custom serialization while maintaining a generic interface for the l
 
 ## ⚡ Performance
 
-The `json-as` library has been optimized to achieve near-gigabyte-per-second JSON processing speeds through SIMD acceleration and highly efficient transformations. Below are some key performance benchmarks to give you an idea of how it performs.
+The `json-as` library has been optimized to achieve near-gigabyte-per-second JSON processing speeds through SIMD acceleration and highly efficient transformations. Below are detailed statistics comparing performance metrics such as build time, operations-per-second, and throughput.
+
+### 🔍 Comparison to JavaScript
+
+These benchmarks compare this library to JavaScript's native `JSON.stringify` and `JSON.parse` functions.
+
+**Table 1** - _AssemblyScript (LLVM)_
+
+| Test Case       | Size       | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
+| --------------- | ---------- | --------------------- | ----------------------- | -------------------- | ---------------------- |
+| Vector3 Object  | 38 bytes   | 35,714,285 ops/s      | 35,435,552 ops/s        | 1,357 MB/s           | 1,348 MB/s             |
+| Alphabet String | 104 bytes  | 13,617,021 ops/s      | 18,390,804 ops/s        | 1,416 MB/s           | 1,986 MB/s             |
+| Small Object    | 88 bytes   | 24,242,424 ops/s      | 12,307,692 ops/s        | 2,133 MB/s           | 1,083 MB/s             |
+| Medium Object   | 494 bytes  | 4,060,913 ops/s       | 1,396,160 ops/s         | 2,006 MB/s           | 689.7 MB/s             |
+| Large Object    | 3374 bytes | 614,754 ops/s         | 132,802 ops/s           | 2,074 MB/s           | 448.0 MB/s             |
+
+**Table 2** - _JavaScript (V8)_
+
+| Test Case       | Size       | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
+| --------------- | ---------- | --------------------- | ----------------------- | -------------------- | ---------------------- |
+| Vector3 Object  | 38 bytes   | 8,791,209 ops/s       | 5,369,12 ops/s          | 357.4 MB/s           | 204.3 MB/s             |
+| Alphabet String | 104 bytes  | 13,793,103 ops/s      | 14,746,544 ops/s        | 1,416 MB/s           | 1,592 MB/s             |
+| Small Object    | 88 bytes   | 8,376,963 ops/s       | 4,968,944 ops/s         | 737.1 MB/s           | 437.2 MB/s             |
+| Medium Object   | 494 bytes  | 2,395,210 ops/s       | 1,381,693 ops/s         | 1,183 MB/s           | 682.5 MB/s             |
+| Large Object    | 3374 bytes | 222,222 ops/s         | 117,233 ops/s           | 749.7 MB/s           | 395.5 MB/s             |
+
+**📌 Insights**
+
+- JSON-AS consistently outperforms JavaScript's native implementation.
+
+- **Serialization Speed:**
+  - JSON-AS achieves speeds up to `2,133 MB/s`, significantly faster than JavaScript's peak of `1,416 MB/s`.
+  - Large objects see the biggest improvement, with JSON-AS at `2,074 MB/s` vs. JavaScript’s `749.7 MB/s`.
+
+- **Deserialization Speed:**
+  - JSON-AS reaches `1,986 MB/s`, while JavaScript caps at `1,592 MB/s`.
+  - Small and medium objects see the most significant performance boost overall.
 
-### Raw Performance
+### 📈 Comparison to v0.9.x version
 
-Simple
+**Table 1** - _v1.0.0_
 
-| Test Case          | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
-| ------------------ | --------------------- | ----------------------- | -------------------- | ---------------------- |
-| Vector3 Object     | 32,642,320 ops/s      | 9,736,272 ops/s         | 1,240 MB/s           | 369 MB/s               |
-| Alphabet String    | 4,928,856 ops/s       | 7,567,360 ops/s         | 975 MB/s             | 1,498 MB/s             |
-| Small JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Medium JSON Object | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Large JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
+| Test Case       | Size       | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
+| --------------- | ---------- | --------------------- | ----------------------- | -------------------- | ---------------------- |
+| Vector3 Object  | 38 bytes   | 35,714,285 ops/s      | 35,435,552 ops/s        | 1,357 MB/s           | 1,348 MB/s             |
+| Alphabet String | 104 bytes  | 13,617,021 ops/s      | 18,390,804 ops/s        | 1,416 MB/s           | 1,986 MB/s             |
+| Small Object    | 88 bytes   | 24,242,424 ops/s      | 12,307,692 ops/s        | 2,133 MB/s           | 1,083 MB/s             |
+| Medium Object   | 494 bytes  | 4,060,913 ops/s       | 1,396,160 ops/s         | 2,006 MB/s           | 689.7 MB/s             |
+| Large Object    | 3374 bytes | 614,754 ops/s         | 132,802 ops/s           | 2,074 MB/s           | 448.0 MB/s             |
 
-SIMD
+**Table 2** - _v0.9.29_
 
-| Test Case          | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
-| ------------------ | --------------------- | ----------------------- | -------------------- | ---------------------- |
-| Vector3 Object     | 32,642,320 ops/s      | 9,736,272 ops/s         | 1,240 MB/s           | 369 MB/s               |
-| Alphabet String    | 20,368,584 ops/s      | 28,467,424 ops/s        | 3,910 MB/s           | 5,636 MB/s             |
-| Small JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Medium JSON Object | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Large JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
+| Test Case       | Size       | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
+| --------------- | ---------- | --------------------- | ----------------------- | -------------------- | ---------------------- |
+| Vector3 Object  | 38 bytes   | 6,896,551 ops/s       | 10,958,904 ops/s        | 262.1 MB/s           | 416.4 MB/s             |
+| Alphabet String | 104 bytes  | 5,128,205 ops/s       | 8,695,652 ops/s         | 533.3 MB/s           | 939.1 MB/s             |
+| Small Object    | 88 bytes   | 4,953,560 ops/s       | 3,678,160 ops/s         | 435.9 MB/s           | 323.7 MB/s             |
+| Medium Object   | 494 bytes  | 522,193 ops/s         | 508,582 ops/s           | 258.0 MB/s           | 251.2 MB/s             |
+| Large Object    | 3374 bytes | 51,229 ops/s          | 65,585 ops/s            | 172.8 MB/s           | 221.3 MB/s             |
 
-JavaScript
+**📌 Insights:**
 
-| Test Case          | Serialization (ops/s) | Deserialization (ops/s) | Serialization (MB/s) | Deserialization (MB/s) |
-| ------------------ | --------------------- | ----------------------- | -------------------- | ---------------------- |
-| Vector3 Object     | 2,548,013 ops/s       | 1,942,440 ops/s         | 97 MB/s              | 73 MB/s                |
-| Alphabet String    | 3,221,556 ops/s       | 2,716,617 ops/s         | 624 MB/s             | 537 MB/s               |
-| Small JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Medium JSON Object | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
-| Large JSON Object  | [Fill Value]          | [Fill Value]            | [Fill Value]         | [Fill Value]           |
+- Massive performance improvements in JSON-AS `v1.0.0`:
+- Serialization is **2-12x faster** (e.g., Large Object: `2,074 MB/s` vs. `172.8 MB/s`).
+- Deserialization is **2-3x faster** (e.g., Large Object: `1,348 MB/s` vs. `221.3 MB/s`).
+- Vector3 Object serialization improved from `416 MB/s` to `1,357 MB/s`--a **3x benefit** through new code generation techniques.
 
-### Real-World Usage
+## 🔭 What's Next
 
-| Scenario         | JSON Size (kb) | Serialization Time (ops/s) | Deserialization Time (ops/s) | Throughput (GB/s) |
-| ---------------- | -------------- | -------------------------- | ---------------------------- | ----------------- |
-| Web API Response | [Fill Value]   | [Fill Value]               | [Fill Value]                 | [Fill Value]      |
-| Database Entry   | [Fill Value]   | [Fill Value]               | [Fill Value]                 | [Fill Value]      |
-| File Parsing     | [Fill Value]   | [Fill Value]               | [Fill Value]                 | [Fill Value]      |
+- Theorize plans to keep key-order in generated schemas
+- Generate optimized deserialization methods
+- Inline specific hot code paths
+- Implement error handling implementation
 
 ## 📃 License
 
@@ -403,4 +457,4 @@ Please send all issues to [GitHub Issues](https://github.com/JairusSW/json-as/is
 - **Email:** Send me inquiries, questions, or requests at [me@jairus.dev](mailto:me@jairus.dev)
 - **GitHub:** Visit the official GitHub repository [Here](https://github.com/JairusSW/json-as)
 - **Website:** Visit my official website at [jairus.dev](https://jairus.dev/)
-- **Discord:** Contact me at [My Discord](https://discord.com/users/600700584038760448) or on the [AssemblyScript Discord Server](https://discord.gg/assemblyscript/)
+- **Discord:** Contact me at [My Discord](https://discord.com/users/600700584038760448) or on the [AssemblyScript Discord Server](https://discord.gg/assemblyscript/)

package/assembly/__benches__/abc.bench.ts

@@ -0,0 +1,21 @@
+import { JSON } from "..";
+import { bench } from "../custom/bench";
+
+const v1 = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const v2 = '"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"';
+
+bench(
+  "Serialize Alphabet",
+  () => {
+    JSON.stringify(v1);
+  },
+  1_000_00,
+);
+
+bench(
+  "Deserialize Alphabet",
+  () => {
+    JSON.parse<string>(v2);
+  },
+  1_000_00,
+);