json-as 1.2.6 → 1.3.1

package/ARCHITECTURE.md

@@ -1,320 +0,0 @@
-# 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

@@ -1,238 +0,0 @@
-# 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/TODO

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

package/assembly/deserialize/simple/float.ts

@@ -1,11 +0,0 @@
-import { ptrToStr } from "../../util/ptrToStr";
-
-// @ts-ignore: inline
-@inline export function deserializeFloat<T>(srcStart: usize, srcEnd: usize): T {
-  // @ts-ignore
-  const type: T = 0;
-  // @ts-ignore
-  if (type instanceof f64) return f64.parse(ptrToStr(srcStart, srcEnd));
-  // @ts-ignore
-  return f32.parse(ptrToStr(srcStart, srcEnd));
-}

package/assembly/deserialize/simple/integer.ts

@@ -1,9 +0,0 @@
-import { atoi } from "../../util/atoi";
-
-// @ts-ignore: inline
-@inline export function deserializeInteger<T>(
-  srcStart: usize,
-  srcEnd: usize,
-): T {
-  return atoi<T>(srcStart, srcEnd);
-}

package/assembly/test.ts

@@ -1,30 +0,0 @@
-class Test {
-  a: string;
-  b: string;
-}
-
-// @ts-expect-error: decorator
-@inline function deserializeTest_NAIVE(
-  srcStart: usize,
-  srcEnd: usize,
-  dst: Test,
-): usize {
-  // fast path
-  do {
-    if (
-      load<u64>(srcStart) != load<u64>(changetype<usize>('{"a"')) ||
-      load<u16>(srcStart, 8) != 0x3a
-    )
-      break;
-    srcStart += 10;
-    srcStart += deserializeString_NAIVE(srcStart, srcEnd); // this needs to somehow return an error (perhaps usize.MAX_VALUE) and also deserialize to the a field in dst.
-    if (
-      load<u64>(srcStart) != load<u64>(changetype<usize>(',"b"')) ||
-      load<u16>(srcStart, 8) != 0x3a
-    )
-      break;
-    srcStart += 10;
-    srcStart += deserializeString_NAIVE(srcStart, srcEnd);
-  } while (false);
-  // have slow path here
-}

package/eslint.config.js

@@ -1,60 +0,0 @@
-// @ts-check
-
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-
-export default tseslint.config(
-  {
-    ignores: [
-      "bin/**",
-      "templates/**",
-      "tests/**/*.js",
-      "transform/lib/**",
-      "build/**",
-      "assembly/**/*.ts",
-      "lib/as-bs.ts",
-    ],
-  },
-  eslint.configs.recommended,
-  ...tseslint.configs.recommended,
-  {
-    files: ["**/*.{js,mjs,cjs,ts}"],
-    languageOptions: {
-      globals: {
-        Buffer: "readonly",
-        WebAssembly: "readonly",
-        console: "readonly",
-        process: "readonly",
-      },
-    },
-  },
-  {
-    files: ["**/*.ts"],
-    rules: {
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-      ],
-    },
-  },
-  {
-    files: ["bench/runners/assemblyscript.js"],
-    languageOptions: {
-      globals: {
-        arguments: "readonly",
-        performance: "readonly",
-        readbuffer: "readonly",
-        writeFile: "readonly",
-      },
-    },
-  },
-  {
-    files: ["bench/lib/bench.js"],
-    languageOptions: {
-      globals: {
-        performance: "readonly",
-        writeFile: "readonly",
-      },
-    },
-  },
-);

package/lib/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "assemblyscript/std/assembly.json",
-  "include": ["./**/*.ts"],
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}