# json-stream-parse

**Repository Path**: zmzmCoder/json-stream-parse

## Basic Information

- **Project Name**: json-stream-parse
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JSON Stream Parser

一个支持流式解析 JSON 的解析器，支持自动修复和增量解析。可以逐字符解析 JSON 字符串，实时获取解析结果。

## 特性

- 🚀 **流式解析**：支持逐字符解析 JSON，无需等待完整 JSON 字符串
- 🔧 **自动修复**：可选的自动修复功能，能够处理常见的 JSON 格式错误
- 📊 **增量解析**：实时输出解析结果，使用 JSONURI 风格的路径标识
- 🎯 **事件驱动**：基于 EventEmitter 的事件系统，方便监听解析过程
- 🐛 **调试模式**：支持调试模式，输出详细的解析日志

## 安装

使用 npm:

```bash
npm install json-stream-parse
```

使用 pnpm:

```bash
pnpm add json-stream-parse
```

使用 yarn:

```bash
yarn add json-stream-parse
```

## 构建

如果需要从源码构建：

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（监听文件变化）
npm run dev
```

构建后的文件会输出到 `dist/` 目录（所有文件都是压缩版本）：
- `dist/index.esm.js` - ES 模块格式（已压缩）
- `dist/index.cjs.js` - CommonJS 格式（已压缩）
- `dist/index.umd.js` - UMD 格式（已压缩）

## 使用方式

### ES 模块

```javascript
import JSONParser from 'json-stream-parse';
```

### CommonJS

```javascript
const JSONParser = require('json-stream-parse');
```

### 浏览器（UMD）

```html
<script src="./dist/index.umd.js"></script>
<script>
  const parser = new JSONParser();
</script>
```

### 直接使用源码

```html
<script type="module">
  import JSONParser from './index.js';
</script>
```

## 使用方法

### 基本用法

**ES 模块 (推荐):**

```javascript
import JSONParser from 'json-stream-parse';
```

**CommonJS:**

```javascript
const JSONParser = require('json-stream-parse');
```

**浏览器 (UMD):**

```html
<script src="https://unpkg.com/json-stream-parse/dist/index.umd.js"></script>
<script>
  const parser = new JSONParser();
</script>
```

**使用源码:**

```javascript
import JSONParser from './index.js';

// 创建解析器实例
const parser = new JSONParser({
  autoFix: false,      // 是否启用自动修复
  parentPath: null,    // 父路径（可选）
  debug: false         // 是否启用调试模式
});

// 监听解析事件
parser.on('data', (data) => {
  console.log('解析数据:', data);
  // data 格式: { uri: 'path/to/key', delta: value }
});

parser.on('string-resolve', (data) => {
  console.log('字符串解析完成:', data);
});

parser.on('object-resolve', (data) => {
  console.log('对象解析完成:', data);
});

parser.on('finish', (data) => {
  console.log('解析完成:', data);
});

// 开始解析
const jsonString = '{"name": "bearbobo", "age": 10}';
for (const char of jsonString) {
  parser.trace(char);
}

// 完成解析
parser.finish();
```

### 流式解析示例

```javascript
import JSONParser from 'json-stream-parse';

const parser = new JSONParser({ autoFix: true });

let result = {};

parser.on('data', (data) => {
  // 使用 JSONURI 路径更新结果对象
  const path = data.uri ? data.uri.split('/').filter(p => p) : [];
  let current = result;
  
  for (let i = 0; i < path.length - 1; i++) {
    if (!current[path[i]]) {
      current[path[i]] = {};
    }
    current = current[path[i]];
  }
  
  const key = path[path.length - 1];
  if (typeof data.delta === 'string') {
    current[key] = (current[key] || '') + data.delta;
  } else {
    current[key] = data.delta;
  }
});

parser.on('finish', (finalData) => {
  console.log('最终结果:', finalData);
  console.log('累积结果:', result);
});

// 模拟流式输入
const jsonChunks = ['{"name":', ' "bearbobo",', ' "age":', ' 10}'];
jsonChunks.forEach(chunk => {
  for (const char of chunk) {
    parser.trace(char);
  }
});

parser.finish();
```

### 自动修复功能

启用自动修复后，解析器可以自动处理以下常见错误：

- 缺少引号（自动补充）
- 中文引号和单引号（自动转换）
- 多余的引号
- 缺少值的处理
- 转义字符的处理

```javascript
import JSONParser from 'json-stream-parse';

const parser = new JSONParser({ autoFix: true });

// 可以解析格式不完美的 JSON
parser.trace('{name: "bearbobo"}'); // 缺少引号会自动修复
```

### 事件说明

#### `data` 事件

当解析到数据时触发，包括字符串的增量字符、数字、布尔值、null 等。

```javascript
parser.on('data', (data) => {
  // data.uri: JSONURI 风格的路径，如 'name' 或 '0/items/1'
  // data.delta: 增量值
  // data.error: 错误信息（如果有）
});
```

#### `string-resolve` 事件

当字符串解析完成时触发。

```javascript
parser.on('string-resolve', (data) => {
  // data.uri: 路径
  // data.delta: 完整的字符串值
});
```

#### `object-resolve` 事件

当对象或数组解析完成时触发。

```javascript
parser.on('object-resolve', (data) => {
  // data.uri: 路径
  // data.delta: 完整的对象或数组
});
```

#### `finish` 事件

当整个 JSON 解析完成时触发。

```javascript
parser.on('finish', (data) => {
  // data: 完整的解析结果
});
```

## API 参考

### 构造函数

```javascript
new JSONParser(options)
```

**参数：**

- `options.autoFix` (boolean, 默认: false): 是否启用自动修复
- `options.parentPath` (string, 可选): 父路径前缀
- `options.debug` (boolean, 默认: false): 是否启用调试模式

### 方法

#### `trace(input)`

解析输入的字符或字符串。

```javascript
parser.trace('{');
parser.trace('"name"');
parser.trace(': "value"');
```

#### `finish()`

完成解析，验证解析状态。

```javascript
parser.finish();
```

#### `on(event, listener)`

监听事件。

```javascript
parser.on('data', (data) => { /* ... */ });
```

#### `off(event, listener)`

移除事件监听器。

```javascript
parser.off('data', listener);
```

#### `once(event, listener)`

监听事件一次。

```javascript
parser.once('finish', (data) => { /* ... */ });
```

### 属性

- `currentState`: 获取当前解析状态
- `lastState`: 获取上一个解析状态
- `arrayIndex`: 获取当前数组索引

## JSONURI 路径说明

解析器使用 JSONURI 风格的路径来标识数据位置：

- 对象属性：`"name"` → 路径: `"name"`
- 数组元素：`[0, 1, 2]` → 路径: `"0"`, `"1"`, `"2"`
- 嵌套对象：`{"user": {"name": "bob"}}` → 路径: `"user/name"`
- 嵌套数组：`{"items": [{"id": 1}]}` → 路径: `"items/0/id"`

## 示例

查看 `demo.html` 文件获取完整的交互式示例。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 开发

```bash
# 克隆项目
git clone https://github.com/your-username/json-stream-parse.git
cd json-stream-parse

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 发布

发布到 npm：

```bash
# 1. 确保已登录 npm
npm login

# 2. 更新版本号（遵循语义化版本）
npm version patch  # 或 minor, major

# 3. 发布
npm publish
```

## 许可证

MIT License

Copyright (c) 2024 json-stream-parse