@happyvertical/json

High-performance JSON parsing and serialization with Rust SIMD acceleration and automatic fallback.

Features

• Drop-in replacements for JSON.parse() and JSON.stringify()
• 2-3x faster parsing with SIMD acceleration on supported platforms
• Automatic fallback to native JavaScript when Rust bindings unavailable
• Deep clone function optimized for the JSON.parse(JSON.stringify()) pattern
• Safe variants that don't throw on errors
• TypeScript first with full type definitions

Installation

npm install @happyvertical/json
# or
pnpm add @happyvertical/json

Quick Start

import { parse, stringify, clone } from '@happyvertical/json';

// Drop-in replacements for JSON.parse/stringify
const data = parse<User>('{"name": "Alice", "age": 30}');
const json = stringify(data);

// Deep clone (optimized)
const copy = clone(data);
copy.age = 31; // Original unchanged

API

Drop-in Replacements

// Parse JSON string to value
function parse<T = unknown>(text: string, reviver?: Reviver): T;

// Stringify value to JSON
function stringify(value: unknown, replacer?: Replacer, space?: number | string): string;

// Deep clone via JSON round-trip (optimized)
function clone<T>(value: T): T;

Safe Variants (Non-throwing)

import { safeParse, safeStringify } from '@happyvertical/json';

// Returns { success: true, value: T } or { success: false, error: ParseError }
const result = safeParse<User>(maybeInvalidJson);
if (result.success) {
  console.log(result.value.name);
} else {
  console.error(`Line ${result.error.line}: ${result.error.message}`);
}

// Returns { success: true, value: string } or { success: false, error: StringifyError }
const stringifyResult = safeStringify(data);

Validation

import { isValid } from '@happyvertical/json';

if (isValid(userInput)) {
  const data = parse(userInput);
}

Adapter Control

import { JSONFactory, getAdapterInfo, isSIMDAvailable } from '@happyvertical/json';

// Check if SIMD acceleration is available
console.log(isSIMDAvailable()); // true on supported platforms

// Get detailed adapter info
const info = getAdapterInfo();
console.log(info.name);        // 'sonic' or 'native'
console.log(info.simdEnabled); // true if using SIMD

// Create adapter with specific options
const json = JSONFactory.create({
  adapter: 'sonic',    // 'sonic' | 'native' | 'auto'
  fallback: true,      // Fall back to native if sonic unavailable
});

// Use adapter directly
const data = json.parse('{"key": "value"}');
const text = json.stringify(data);

Performance

On a 680KB manifest file (typical SMRT manifest):

| Operation | Native JSON | @happyvertical/json | Speedup | |-----------|-------------|---------------------|---------| | Parse | ~50ms | ~18ms | 2.8x | | Stringify | ~45ms | ~16ms | 2.8x | | Clone | ~95ms | ~34ms | 2.8x |

Results measured on Apple M2 Pro. Performance varies by platform and data structure.

Platform Support

SIMD-accelerated parsing is available on:

• ✅ macOS ARM64 (Apple Silicon)
• ✅ macOS x64 (Intel)
• ✅ Linux x64 (GNU)
• ✅ Linux ARM64 (GNU)
• ✅ Linux x64 (musl)
• ✅ Linux ARM64 (musl)
• ✅ Windows x64

When the native binary isn't available, the package automatically falls back to JavaScript's built-in JSON object with zero overhead.

How It Works

This package uses sonic-rs - a Rust JSON library that uses SIMD instructions (AVX2, SSE4.2, NEON) for vectorized parsing and serialization.

The adapter pattern allows:

1. Automatic selection of the fastest available implementation
2. Graceful fallback when native bindings can't be loaded
3. Consistent API regardless of the underlying implementation

TypeScript Support

Full TypeScript definitions included:

interface User {
  name: string;
  age: number;
}

// Type-safe parsing
const user = parse<User>('{"name": "Alice", "age": 30}');
user.name; // string
user.age;  // number

// Safe variant preserves types
const result = safeParse<User>(json);
if (result.success) {
  result.value.name; // string
}

Reviver and Replacer

Standard reviver and replacer functions work as expected:

// Reviver for custom transformations
const data = parse<{ date: Date }>(
  '{"date": "2024-01-15"}',
  (key, value) => (key === 'date' ? new Date(value) : value)
);
console.log(data.date instanceof Date); // true

// Replacer for filtering
const json = stringify(data, ['name', 'email']); // Only include these keys

// Pretty printing
const pretty = stringify(data, null, 2);

Environment Variables

• HAPPYVERTICAL_JSON_ADAPTER: Force adapter selection ('sonic' | 'native')

License

MIT