# @happyvertical/json 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/json/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:02:01.734Z
中文译文更新时间：2026-11-17T09:30:32.200Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/json
原文对照：https://npmcn.com/package/%40happyvertical/json/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/json#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：75.6 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-23T08:14:16.586Z
- 最新版本发布：2026-11-17T00:02:01.549Z
- 近 30 天下载量：39714（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

高性能 JSON 与 Rust SIMD 同步并自动回落解析和序列化

## 安装

```sh
npm install @happyvertical/json
```

也可以使用：`pnpm add @happyvertical/json`、`yarn add @happyvertical/json`、`bun add @happyvertical/json`

## README

# @ 喜悦的垂直/ json

高性能的JSON与Rust SIMD加速度和自动倒置一起解析并串行.

## 特征

-   **空投替换** 页:1 `JSON.parse()` 财务报告和审定财务报表 `JSON.stringify()`
-   **2 -3x 速度快一点** 在支持的平台上分析 SIMD 加速
-   **自动倒置** 无法使用 Rust 绑定时切入本地 JavaScript
-   **深克隆** 函数已优化 `JSON.parse(JSON.stringify())` 模式
-   **安全变种** 不要犯错
-   **先输入脚本** 带有完整类型定义

## 安装

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

## 快速启动

```typescript
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 密码

### 空投替换

```typescript
// 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;
```

### 安全替代品(不投掷)

```typescript
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);
```

### 验证

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

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

### 适配器控制

```typescript
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);
```

## 业绩

在680KB 显示文件(典型的 SMRT 显示文件):

| 运行 | 本地 JSON | @ 喜悦的垂直/ json | 加速 |
| --- | --- | --- | --- |
| 解析 | ~50 ms 时 | ~18ms 时 | **2.8x 单曲** |
| 字符串 | ~45ms (英语) | ~16,000米) | **2.8x 单曲** |
| 克隆 | ~95ms (单位:千米) | ~34ms 时 | **2.8x 单曲** |

在Apple M2 Pro上测量的结果,性能因平台和数据结构而异.

## 平台支持

SIMD-加速解析可在:

-   & macOS ARM64 (苹果硅)
-   \* macOS x64(英特尔)
-   XQ Linux x64 (GNU) (英语)
-   Linux ARM64 (GNU) (英语)
-   QQ Linux x64( 穆尔)
-   Linux ARM64( 穆斯尔)
-   视窗x64

当本地二进制不可用时, 软件包会自动倒回 JavaScript 的内置 `JSON` 对象为零.

## 如何运作

此软件包使用 [音响](https://github.com/cloudwego/sonic-rs) - Rust JSON图书馆,使用SIMD指令(AVX2、SSE4.2、NEON)进行矢量分解和序列化.

适配器模式允许:

1.  自动选择可用最快的执行程序
2.  原始束缚无法装入时, 优雅地回落
3.  一致的API,无论基本执行

## 类型脚本支持

完整类型脚本定义包括:

```typescript
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
}
```

## 退缩和替换

标准复活器和替换器功能按预期工作:

```typescript
// 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);
```

## 环境变量

-   `HAPPYVERTICAL_JSON_ADAPTER`: 强制适配器选择 ("音速" QQ"内置")

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/json 是什么？

高性能 JSON 与 Rust SIMD 同步并自动回落解析和序列化

### 如何安装 @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 和提交记录判断。

