██ ███████  ██████  ███    ██        █████  ███████
     ██ ██      ██    ██ ████   ██       ██   ██ ██
     ██ ███████ ██    ██ ██ ██  ██ █████ ███████ ███████
██   ██      ██ ██    ██ ██  ██ ██       ██   ██      ██
 █████  ███████  ██████  ██   ████       ██   ██ ███████
 
    AssemblyScript - v1.0.3
  

📝 About

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
• Usage
• Examples
  • Omitting Fields
  • Nullable Primitives
  • Unknown or Dynamic Data
  • Using Raw JSON Strings
  • Custom Serializers
• Performance
• License
• Contact

💾 Installation

npm install json-as

Add the --transform to your asc command (e.g. in package.json)

--transform json-as/transform

Alternatively, add it to your asconfig.json

{
  "options": {
    "transform": ["json-as/transform"]
  }
}

If you’d like to see the code that the transform generates, run with JSON_DEBUG=true

🪄 Usage

import { JSON } from "json-as";
@json
class Vec3 {
  x: f32 = 0.0;
  y: f32 = 0.0;
  z: f32 = 0.0;
}
@json
class Player {
  @alias("first name")
  firstName!: string;
  lastName!: string;
  lastActive!: i32[];
  // Drop in a code block, function, or expression that evaluates to a boolean
  @omitif((self: Player) => self.age < 18)
  age!: i32;
  @omitnull()
  pos!: Vec3 | null;
  isVerified!: boolean;
}
const player: Player = {
  firstName: "Jairus",
  lastName: "Tanaka",
  lastActive: [3, 9, 2025],
  age: 18,
  pos: {
    x: 3.4,
    y: 1.2,
    z: 8.3,
  },
  isVerified: true,
}
const serialized = JSON.stringify<Player>(player);
const deserialized = JSON.parse<Player>(serialized);
console.log("Serialized    " + serialized);
console.log("Deserialized  " + JSON.stringify(deserialized));

🔍 Examples

🏷️ Omitting Fields

This library allows selective omission of fields during serialization using the following decorators:

@omit

This decorator excludes a field from serialization entirely.

@json
class Example {
  name!: string;
  @omit
  SSN!: string;
}
const obj = new Example();
obj.name = "Jairus";
obj.SSN = "123-45-6789";
console.log(JSON.stringify(obj)); // { "name": "Jairus" }

@omitnull

This decorator omits a field only if its value is null.

@json
class Example {
  name!: string;
  @omitnull()
  optionalField!: string | null;
}
const obj = new Example();
obj.name = "Jairus";
obj.optionalField = null;
console.log(JSON.stringify(obj)); // { "name": "Jairus" }

@omitif((self: this) => condition)

This decorator omits a field based on a custom predicate function.

@json
class Example {
  name!: string;
  @omitif((self: Example) => self.age <= 18)
  age!: number;
}
const obj = new Example();
obj.name = "Jairus";
obj.age = 18;
console.log(JSON.stringify(obj)); // { "name": "Jairus" }
obj.age = 99;
console.log(JSON.stringify(obj)); // { "name": "Jairus", "age": 99 }

If age were higher than 18, it would be included in the serialization.

🗳️ Using nullable primitives

AssemblyScript doesn’t support using nullable primitive types, so instead, json-as offers the JSON.Box class to remedy it.

For example, this schema won’t compile in AssemblyScript:

@json
class Person {
  name!: string;
  age: i32 | null = null;
}

Instead, use JSON.Box to allow nullable primitives:

@json
class Person {
  name: string;
  age: JSON.Box<i32> | null = null;
  constructor(name: string) {
    this.name = name;
  }
}
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":"Jairus","age":18}

📤 Working with unknown or dynamic data

Sometimes it’s necessary to work with unknown data or data with dynamic types.

Because AssemblyScript is a statically-typed language, that typically isn’t allowed, so json-as provides the JSON.Value and JSON.Obj types.

Here’s a few examples:

Working with multi-type arrays

When dealing with arrays that have multiple types within them, eg. ["string",true,["array"]], use JSON.Value[]

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])); // ["array"]

Working with unknown objects

When dealing with an object with an unknown structure, use the JSON.Obj type

const obj = JSON.parse<JSON.Obj>('{"a":3.14,"b":true,"c":[1,2,3],"d":{"x":1,"y":2,"z":3}}');
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 = obj.get("d")!.get<JSON.Obj>().get("y")!;
console.log('o1["d"]["y"] = ' + y.toString()); // o1["d"]["y"] = 2

Working with dynamic types within a schema

More often, objects will be completely statically typed except for one or two values.

In such cases, JSON.Value can be used to handle fields that may hold different types at runtime.

@json
class DynamicObj {
  id: i32 = 0;
  name: string = "";
  data!: JSON.Value; // Can hold any type of value
}
const obj = new DynamicObj();
obj.id = 1;
obj.name = "Example";
obj.data = JSON.parse<JSON.Value>('{"key":"value"}'); // Assigning an object
console.log(JSON.stringify(obj)); // {"id":1,"name":"Example","data":{"key":"value"}}
obj.data = JSON.Value.from<i32>(42); // Changing to an integer
console.log(JSON.stringify(obj)); // {"id":1,"name":"Example","data":42}
obj.data = JSON.Value.from("a string"); // Changing to a string
console.log(JSON.stringify(obj)); // {"id":1,"name":"Example","data":"a string"}

🏗️ Using Raw JSON strings

Sometimes its necessary to simply copy a string instead of serializing it.

For example, the following data would typically be serialized as:

const map = new Map<string, string>();
map.set("pos", '{"x":1.0,"y":2.0,"z":3.0}');
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:

const map = new Map<string, JSON.Raw>();
map.set("pos", new JSON.Raw('{"x":1.0,"y":2.0,"z":3.0}'));
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!

⚒️ Using custom serializers or deserializers

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)

import { bytes } from "json-as/assembly/util";
@json
class Point {
  x: f64 = 0.0;
  y: f64 = 0.0;
  constructor(x: f64, y: f64) {
    this.x = x;
    this.y = y;
  }
  @serializer
  serializer(self: Point): string {
    return `(${self.x},${self.y})`;
  }
  @deserializer
  deserializer(data: string): Point {
    const dataSize = bytes(data);
    if (dataSize <= 2) 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);
    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).

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:

@inline __SERIALIZE_CUSTOM(ptr: usize): void {
  const data = this.serializer(changetype<Point>(ptr));
  const dataSize = data.length << 1;
  memory.copy(bs.offset, changetype<usize>(data), dataSize);
  bs.offset += dataSize;
}
@inline __DESERIALIZE_CUSTOM(data: string): Point {
  return this.deserializer(data);
}

This allows custom serialization while maintaining a generic interface for the library to access.

⚡ 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 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)

Table 2 - JavaScript (V8)

📌 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.

📈 Comparison to v0.9.x version

Table 1 - v1.0.0

Table 2 - v0.9.29

📌 Insights:

• 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.

🔭 What’s Next

• Theorize plans to keep key-order in generated schemas
• Generate optimized deserialization methods
• Inline specific hot code paths
• Implement error handling implementation

📃 License

This project is distributed under an open source license. You can view the full license using the following link: License

📫 Contact

Please send all issues to GitHub Issues and to converse, please send me an email at me@jairus.dev

• Email: Send me inquiries, questions, or requests at me@jairus.dev
• GitHub: Visit the official GitHub repository Here
• Website: Visit my official website at jairus.dev
• Discord: Contact me at My Discord or on the AssemblyScript Discord Server