@happyvertical/json

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module零依赖近 30 天下载 4万

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

原始使用文档
文档目录15 节
  1. Features
  2. Installation
  3. Quick Start
  4. API
  5. Drop-in Replacements
  6. Safe Variants (Non-throwing)
  7. Validation
  8. Adapter Control
  9. Performance
  10. Platform Support
  11. How It Works
  12. TypeScript Support
  13. Reviver and Replacer
  14. Environment Variables
  15. License

@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):

OperationNative JSON@happyvertical/jsonSpeedup
Parse~50ms~18ms2.8x
Stringify~45ms~16ms2.8x
Clone~95ms~34ms2.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

版本与发布记录

@happyvertical/json 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/json 的常见问题

@happyvertical/json 是什么?

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

如何安装 @happyvertical/json?

在项目目录运行 npm install @happyvertical/json,或使用 pnpm add / yarn add / bun add。

@happyvertical/json 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/json 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/json 可以商用吗?

@happyvertical/json 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/json 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/json 在 2026/10/17 – 2026/11/15 这 30 天内被下载 39,714 次,日均约 1,324 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/json 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。