json-as 1.2.2 → 1.2.4

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__acp__Bash",
+      "mcp__acp__Edit",
+      "mcp__acp__Write"
+    ]
+  }
+}

package/ARCHITECTURE.md

@@ -0,0 +1,320 @@
+# Architecture
+
+This document describes the architecture of json-as, a high-performance JSON serialization library for AssemblyScript.
+
+## Overview
+
+json-as uses a two-tier architecture:
+
+1. **Compile-time Transform**: A TypeScript-based AST transformer that generates optimized serialization/deserialization code
+2. **Runtime Library**: AssemblyScript implementations for JSON processing with multiple optimization levels
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Compile Time                             │
+│   ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐   │
+│   │ Source Code │ -> │  Transform   │ -> │ Generated Code   │   │
+│   │ with @json  │    │ (TypeScript) │    │ __SERIALIZE etc  │   │
+│   └─────────────┘    └──────────────┘    └──────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              V
+┌─────────────────────────────────────────────────────────────────┐
+│                      Runtime                                    │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                    JSON Namespace                        │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
+│  │  │  stringify  │  │    parse    │  │  Dynamic Types  │   │   │
+│  │  └──────┬──────┘  └──────┬──────┘  │  Value, Obj,    │   │   │
+│  │         │                │         │  Box, Raw       │   │   │
+│  │         V                V         └─────────────────┘   │   │
+│  │  ┌───────────────────────────────────────────────────┐   │   │
+│  │  │               Optimization Modes                  │   │   │
+│  │  │         ┌───────┐  ┌────────┐  ┌────────┐         │   │   │
+│  │  │         │ NAIVE │  │  SWAR  │  │  SIMD  │         │   │   │
+│  │  │         └───────┘  └────────┘  └────────┘         │   │   │
+│  │  └───────────────────────────────────────────────────┘   │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                              │                                  │
+│                              V                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │              Memory Allocator (bs namespace)             │   │
+│  │  - Dynamic buffer management                             │   │
+│  │  - EMA-based adaptive sizing                             │   │
+│  │  - Optional string caching (sc namespace)                │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Transform System
+
+The transform (`transform/src/`) is an AssemblyScript compiler plugin that runs during compilation.
+
+### How It Works
+
+1. **Discovery**: Scans source files for classes decorated with `@json` or `@serializable`
+2. **Schema Building**: Creates a schema for each decorated class including:
+   - Field names and types
+   - Decorator metadata (@alias, @omit, @omitnull, @omitif)
+   - Inheritance relationships
+   - Type dependencies
+3. **Code Generation**: Generates two methods for each class:
+   - `__SERIALIZE(ptr: usize): void` - Writes JSON to the buffer
+   - `__DESERIALIZE<T>(srcStart, srcEnd, out): T` - Parses JSON into object
+
+### Key Files
+
+- `transform/src/index.ts` - Main transform entry point (JSONTransform class)
+- `transform/src/visitor.ts` - AST visitor for traversing source code
+- `transform/src/builder.ts` - AST builder for code generation
+- `transform/src/types.ts` - Type definitions (Property, Schema, Src)
+
+### Generated Code Example
+
+For this class:
+```typescript
+@json
+class Player {
+  name: string = "";
+  score: i32 = 0;
+}
+```
+
+The transform generates:
+```typescript
+__SERIALIZE(ptr: usize): void {
+  store<u16>(bs.offset, 123); // {
+  bs.offset += 2;
+  // ... "name": serialize string ...
+  // ... "score": serialize integer ...
+  store<u16>(bs.offset, 125); // }
+  bs.offset += 2;
+}
+
+__DESERIALIZE<T>(srcStart: usize, srcEnd: usize, out: T): T {
+  // Key matching and value parsing logic
+  // Uses switch statements on key length for efficiency
+}
+```
+
+## Optimization Modes
+
+json-as provides three optimization levels, selected via the `JSON_MODE` environment variable:
+
+### NAIVE Mode
+
+The baseline implementation with character-by-character processing.
+
+- **Best for**: Debugging, compatibility testing
+- **Performance**: Slowest but most readable
+- **String escaping**: Checks each character individually
+
+### SWAR Mode (Default)
+
+Single Instruction, Multiple Data processing at the word level.
+
+- **Best for**: General use, good balance of speed and compatibility
+- **Performance**: Processes 4 characters at once
+- **String escaping**: Uses bit manipulation to detect escape characters in parallel:
+  ```
+  // Check if any byte in a 64-bit word needs escaping
+  const hasEscape = (word ^ 0x2222...) - 0x0101... & 0x8080...
+  ```
+
+### SIMD Mode
+
+Uses WebAssembly SIMD instructions for 128-bit parallel processing.
+
+- **Best for**: Maximum performance when SIMD is available
+- **Performance**: Processes 8 characters at once
+- **Requirement**: `--enable simd` flag during compilation
+- **String escaping**: Uses `v128` operations for parallel character checking
+
+## Buffer System
+
+Located in `lib/as-bs.ts`, the buffer system (`bs` namespace) manages memory for serialization output.
+
+### Key Features
+
+1. **Dynamic Growth**: Buffer grows as needed during serialization
+2. **Adaptive Sizing**: Uses exponential moving average (EMA) to track typical output sizes
+3. **Automatic Shrinking**: Periodically shrinks if buffer is oversized for typical usage
+
+### Memory Layout
+
+```
+┌───────────────────────────────────────────┐
+│              ArrayBuffer                  │
+│  ┌───────────────────┬─────────────────┐  │
+│  │   Written Data    │   Free Space    │  │
+│  └───────────────────┴─────────────────┘  │
+│  ^ buffer            ^ offset             │
+└───────────────────────────────────────────┘
+```
+
+### Key Functions
+
+- `proposeSize(size)` - Ensure buffer can hold additional bytes
+- `ensureSize(size)` - Grow buffer if necessary
+- `out<T>()` - Copy buffer contents to new string, reset for next use
+- `resize(size)` - Explicitly resize buffer
+
+### String Caching (`sc` namespace)
+
+Optional feature enabled via `JSON_CACHE=1` for repeated string serialization.
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                    Cache Structure                            │
+│  ┌─────────────────────────────────────────────────────────┐  │
+│  │  Entry Table (4096 slots)                               │  │
+│  │  ┌────────┬────────┬────────┬────────┐                  │  │
+│  │  │ Entry 0│ Entry 1│  ...   │Entry N │                  │  │
+│  │  │key,ptr,│key,ptr,│        │key,ptr,│                  │  │
+│  │  │  len   │  len   │        │  len   │                  │  │
+│  │  └────────┴────────┴────────┴────────┘                  │  │
+│  └─────────────────────────────────────────────────────────┘  │
+│  ┌─────────────────────────────────────────────────────────┐  │
+│  │  Arena (1MB circular buffer)                            │  │
+│  │  ┌──────────────────────────────────────────────────┐   │  │
+│  │  │  Cached serialized string data...                │   │  │
+│  │  └──────────────────────────────────────────────────┘   │  │
+│  │                                          ^              │  │
+│  │                                       arenaPtr          │  │
+│  └─────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Type System
+
+### Static Types
+
+Regular AssemblyScript types handled directly:
+- Primitives: `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`, `f32`, `f64`, `bool`
+- Strings: `string`
+- Collections: `Array<T>`, `StaticArray<T>`, `Map<K, V>`
+- Classes decorated with `@json`
+
+### Dynamic Types
+
+For runtime type flexibility:
+
+- **`JSON.Value`**: Can hold any JSON type
+  ```typescript
+  const v = JSON.Value.from<i32>(42);
+  v.set<string>("hello");  // Can change type
+  ```
+
+- **`JSON.Obj`**: Dynamic object with string keys
+  ```typescript
+  const obj = new JSON.Obj();
+  obj.set("key", 123);
+  ```
+
+- **`JSON.Box<T>`**: Nullable wrapper for primitives
+  ```typescript
+  let maybeInt: JSON.Box<i32> | null = null;
+  ```
+
+- **`JSON.Raw`**: Pre-formatted JSON string (no re-serialization)
+  ```typescript
+  map.set("data", new JSON.Raw('{"already":"json"}'));
+  ```
+
+## Serialization Flow
+
+```
+JSON.stringify<T>(data)
+        │
+        V
+┌───────────────────┐
+│  Type Dispatch    │
+│  (compile-time)   │
+└─────────┬─────────┘
+          │
+    ┌─────┴─────┬─────────────┬──────────────┐
+    V           V             V              V
+┌───────┐  ┌────────┐   ┌──────────┐   ┌──────────┐
+│Boolean│  │Integer │   │  String  │   │  Struct  │
+│ Float │  │        │   │          │   │ (@json)  │
+└───┬───┘  └────┬───┘   └────┬─────┘   └────┬─────┘
+    │           │            │              │
+    │           │            │              │
+    └───────────┴─────┬──────┴──────────────┘
+                      V
+              ┌───────────────┐
+              │ Buffer System │
+              └───────┬───────┘
+                      V
+              ┌───────────────┐
+              │     Heap      │
+              └───────┬───────┘
+                      V
+                   String
+```
+
+## Deserialization Flow
+
+```
+JSON.parse<T>(jsonString)
+        │
+        V
+┌───────────────────┐
+│  Type Dispatch    │
+│  (compile-time)   │
+└─────────┬─────────┘
+          │
+    ┌─────┴─────┬─────────────┬──────────────┐
+    V           V             V              V
+┌───────┐  ┌────────┐   ┌──────────┐   ┌──────────┐
+│Boolean│  │Integer │   │  String  │   │  Struct  │
+└───┬───┘  └────┬───┘   └────┬─────┘   └────┬─────┘
+    │           │            │              │
+    └───────────┴─────┬──────┴──────────────┘
+                      │
+                      V
+                      T
+```
+
+### Struct Deserialization
+
+For `@json` decorated classes, the generated `__DESERIALIZE` method:
+
+1. Scans for opening `{`
+2. Iterates through key-value pairs
+3. Uses switch on key length for fast dispatch
+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
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JSON_MODE` | SWAR | Optimization mode: NAIVE, SWAR, SIMD |
+| `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) |
+| `JSON_STRICT` | false | Enable strict JSON validation |
+
+## Performance Considerations
+
+### Serialization
+
+- Pre-computes static key bytes at compile time
+- Uses direct memory stores for known strings
+- SIMD/SWAR for escape character detection
+- Optional caching for repeated strings
+
+### Deserialization
+
+- Groups fields by key length for switch optimization
+- Uses direct memory loads for key comparison
+- Avoids string allocation during key matching
+- Tracks depth for nested structures
+
+### Memory
+
+- Single reusable buffer reduces allocations
+- EMA-based sizing prevents memory waste
+- Circular arena for cache prevents unbounded growth

package/CONTRIBUTING.md

@@ -0,0 +1,238 @@
+# Contributing to json-as
+
+Thank you for your interest in contributing to json-as! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Issues](#reporting-issues)
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/json-as.git
+   cd json-as
+   ```
+3. Add the upstream remote:
+   ```bash
+   git remote add upstream https://github.com/JairusSW/json-as.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+ or Bun
+- Wasmtime (for running tests)
+
+### Install Dependencies
+
+```bash
+npm install
+# or
+bun install
+```
+
+### Build the Transform
+
+The transform is written in TypeScript and needs to be compiled:
+
+```bash
+npm run build:transform
+```
+
+### Running Tests
+
+Run the full test suite across all modes (NAIVE, SWAR, SIMD):
+
+```bash
+npm test
+```
+
+Run a specific test file:
+
+```bash
+./run-tests.sh string  # Runs string.spec.ts
+```
+
+### Running Benchmarks
+
+AssemblyScript benchmarks:
+```bash
+npm run bench:as
+```
+
+JavaScript comparison benchmarks:
+```bash
+npm run bench:js
+```
+
+## Project Structure
+
+```
+json-as/
+├── assembly/           # AssemblyScript runtime implementation
+│   ├── index.ts       # Main entry point (JSON namespace)
+│   ├── serialize/     # Serialization implementations
+│   │   ├── simple/    # Naive implementation
+│   │   ├── swar/      # SWAR-optimized
+│   │   └── simd/      # SIMD-optimized
+│   ├── deserialize/   # Deserialization implementations
+│   ├── util/          # Utility functions
+│   ├── custom/        # Constants and character codes
+│   └── __tests__/     # Test files
+├── transform/          # TypeScript compiler transform
+│   └── src/           # Transform source code
+├── lib/               # Shared utilities (buffer system)
+├── bench/             # Benchmark suite
+└── .github/           # CI/CD workflows
+```
+
+## Making Changes
+
+### Branching Strategy
+
+1. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes with clear, atomic commits
+
+3. Keep your branch up to date:
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+### Commit Messages
+
+Use clear, descriptive commit messages:
+
+- `feat: add support for BigInt serialization`
+- `fix: handle escaped unicode in strings`
+- `perf: optimize SIMD string escaping`
+- `docs: update README examples`
+- `test: add edge case tests for nested arrays`
+- `chore: update dependencies`
+
+## Testing
+
+### Writing Tests
+
+Tests are located in `assembly/__tests__/`. Each test file follows the pattern `*.spec.ts`.
+
+Example test structure:
+
+```typescript
+import { JSON } from "..";
+
+describe("Feature Name", () => {
+  test("should serialize correctly", () => {
+    const result = JSON.stringify<string>("hello");
+    expect(result).toBe('"hello"');
+  });
+
+  test("should deserialize correctly", () => {
+    const result = JSON.parse<string>('"hello"');
+    expect(result).toBe("hello");
+  });
+});
+```
+
+### Test Coverage
+
+Ensure your changes include tests for:
+- Happy path scenarios
+- Edge cases
+- Error conditions
+- All three modes (NAIVE, SWAR, SIMD) if applicable
+
+## Code Style
+
+### Formatting
+
+The project uses Prettier for formatting:
+
+```bash
+npm run format
+```
+
+### AssemblyScript Guidelines
+
+- Use `@inline` decorator for small, frequently-called functions
+- Prefer `store<T>` and `load<T>` for direct memory operations
+- Use typed arrays and explicit types
+- Add `// @ts-ignore` comments with explanations when necessary
+
+### TypeScript Guidelines (Transform)
+
+- Use strict TypeScript settings
+- Document complex logic with comments
+- Keep functions focused and small
+
+## Pull Request Process
+
+1. **Before submitting:**
+   - Run the full test suite: `npm test`
+   - Run the formatter: `npm run format`
+   - Ensure your branch is up to date with `main`
+
+2. **PR Description:**
+   - Clearly describe the changes
+   - Reference any related issues
+   - Include before/after benchmarks for performance changes
+
+3. **Review Process:**
+   - PRs require at least one approval
+   - Address review feedback promptly
+   - Keep the PR focused on a single concern
+
+4. **After Merge:**
+   - Delete your feature branch
+   - Update any related issues
+
+## Reporting Issues
+
+### Bug Reports
+
+Include:
+- json-as version
+- AssemblyScript version
+- Minimal reproduction case
+- Expected vs actual behavior
+- Error messages (if any)
+
+### Feature Requests
+
+Include:
+- Use case description
+- Proposed API (if applicable)
+- Alternatives considered
+
+## Performance Contributions
+
+If your change affects performance:
+
+1. Run benchmarks before and after
+2. Include benchmark results in the PR
+3. Test across all three modes (NAIVE, SWAR, SIMD)
+4. Consider memory usage implications
+
+## Questions?
+
+- Open a GitHub Discussion for general questions
+- Join the [AssemblyScript Discord](https://discord.gg/assemblyscript)
+- Email the maintainer at [me@jairus.dev](mailto:me@jairus.dev)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Jairus Tanaka <me@jairus.dev>
+Copyright (c) 2026 Jairus Tanaka <me@jairus.dev>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -19,6 +19,9 @@
   - [Performance Tuning](#performance-tuning)
   - [Running Benchmarks Locally](#running-benchmarks-locally)
 - [Debugging](#debugging)
+- [Architecture](#architecture)
+- [Contributing](#contributing)
+- [Who uses it?](#who-uses-it)
 - [License](#license)
 - [Contact](#contact)
 
@@ -413,6 +416,8 @@ 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/chart03.png" alt="Performance Chart 3">
 
+<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.
 
 ### Performance Tuning
@@ -474,9 +479,38 @@ or
 `JSON_DEBUG=2` - The above and prints keys/values as they are deserialized
 `JSON_WRITE=path-to-file.ts` - Writes out generated code to `path-to-file.json.ts` for easy inspection
 
+## Architecture
+
+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).
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on:
+
+- Setting up your development environment
+- Running tests and benchmarks
+- Code style and commit conventions
+- The pull request process
+
+## Who uses it?
+
+A few companies and open-source projects use json-as!
+
+| Company/Project | Description |
+|-----------------|-------------|
+| [Impart Security](https://impart.security) | API security platform |
+| [Hypermode](https://hypermode.ai) | AI infrastructure |
+| [Steer Finance](https://steer.finance) | DeFi protocol |
+| [Secretarium](https://secretarium.com) | Confidential computing |
+| [Klave](https://klave.com) | Privacy-first platform |
+| [Bifrost](https://github.com/maximhq/bifrost) | Open source project by Maxim HQ |
+| [Massa Labs](https://github.com/massalabs) | Massa blockchain tooling |
+
 ## License
 
-This project is distributed under an open source license. You can view the full license using the following link: [License](./LICENSE)
+This project is distributed under an open source license. Work on this project is done by passion, but if you want to support it financially, you can do so by making a donation to the project's [GitHub Sponsors](https://github.com/sponsors/JairusSW) page.
+
+You can view the full license using the following link: [License](./LICENSE)
 
 ## Contact
 

package/TODO

@@ -0,0 +1 @@
+get staticarrays working within classes

package/assembly/custom/chars.ts

@@ -74,3 +74,12 @@
 @inline export const FORM_FEED = 12; // \f
 // @ts-ignore: Decorator is valid here
 @inline export const CARRIAGE_RETURN = 13; // \r
+
+// Pre-encoded u64 constants for common JSON literals
+// These represent the UTF-16 encoded bytes stored as u64 for fast comparison/storage
+// @ts-ignore: Decorator is valid here
+@inline export const NULL_WORD_U64: u64 = 30399761348886638; // "null" as u64 (n=110, u=117, l=108, l=108)
+// @ts-ignore: Decorator is valid here
+@inline export const TRUE_WORD_U64: u64 = 28429475166421108; // "true" as u64 (t=116, r=114, u=117, e=101)
+// @ts-ignore: Decorator is valid here
+@inline export const FALSE_WORD_U64: u64 = 32370086184550502; // "fals" as u64 (f=102, a=97, l=108, s=115) - first 4 chars of "false"