# jsondb

**Repository Path**: yanxxit/jsondb

## Basic Information

- **Project Name**: jsondb
- **Description**: 一个简单的 json数据库
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-04-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @yanit/jsondb - 基于 Node.js 的轻量级 JSON 数据库

## 项目概述

**@yanit/jsondb** 是一个基于 Node.js 实现的轻量级文档型数据库，使用 JSON 文件作为存储介质，提供类似 MongoDB 的查询语法和操作接口。适合小型项目、原型开发、测试环境和本地应用。

### 核心特点

- 📦 **零依赖部署** - 无需安装数据库服务器，开箱即用
- 📝 **JSON 存储** - 数据以 JSON 格式持久化到本地文件
- 🔧 **MongoDB 风格语法** - 熟悉的查询和操作方式，学习成本低
- 🚀 **轻量快速** - 适合小型项目和本地开发
- 🔍 **丰富查询** - 支持条件查询、排序、分页、聚合等
- 📊 **索引支持** - 可选的索引机制提升查询性能
- ⚡ **内存模式** - 支持纯内存存储，适合测试和原型验证
- 🐛 **Debug 模式** - 支持命令执行日志和性能监控，方便调试和优化

---

## 快速开始

### 安装

```bash
npm install
```

### 基本使用

```javascript
import { Database } from '@yanit/jsondb';

async function main() {
  // 连接数据库（普通模式）
  const db = new Database('./temp/mydb');
  await db.open();

  // 连接数据库（JSONB 模式 - 更节省空间）
  const jsonbDb = new Database('./temp/mydb-jsonb', { jsonb: true });
  await jsonbDb.open();

  // 连接数据库（内存模式 - 快速测试和原型验证）
  const memDb = new Database('my-memory-db', { memory: true });
  await memDb.open();

  // 获取集合
  const users = db.collection('users');

  // 插入文档
  const user = await users.insertOne({
    name: 'Alice',
    age: 25,
    email: 'alice@example.com'
  });

  // 查询
  const allUsers = await users.find().toArray();
  const youngUsers = await users.find({ age: { $lt: 30 } }).toArray();

  // 更新
  await users.updateOne(
    { name: 'Alice' },
    { $set: { age: 26 } }
  );

  // 删除
  await users.deleteOne({ name: 'Alice' });

  // 使用 for await...of 遍历
  for await (const user of users.find().limit(5)) {
    console.log(user.name);
  }

  // 关闭连接
  await db.close();
}

main().catch(console.error);
```

### SQL 查询支持

JSONDB 支持标准 SQL 语法子集，可以直接使用 SQL 进行增删改查操作：

```javascript
import { Database } from '@yanit/jsondb';

const db = new Database('./temp/mydb');
await db.open();

const users = db.collection('users');

// INSERT - 插入数据
await users.sql("INSERT INTO users (name, age, email) VALUES ('Alice', 25, 'alice@example.com')");

// 批量插入
await users.sql(`
  INSERT INTO users (name, age, email) VALUES 
  ('Bob', 30, 'bob@example.com'),
  ('Charlie', 28, 'charlie@example.com')
`);

// SELECT - 查询数据
const result = await users.sql('SELECT * FROM users WHERE age > 25');
console.log(result.data); // 查询结果

// 多条件查询
const complex = await users.sql(`
  SELECT name, age, department 
  FROM users 
  WHERE department IN ('Engineering', 'Sales') 
    AND age BETWEEN 25 AND 30
  ORDER BY age DESC
  LIMIT 10
`);

// UPDATE - 更新数据
await users.sql("UPDATE users SET age = 26 WHERE name = 'Alice'");

// DELETE - 删除数据
await users.sql("DELETE FROM users WHERE age < 25");

await db.close();
```

**支持的 SQL 语法：**

| 类型 | 语法 | 示例 |
|------|------|------|
| SELECT | 查询数据 | `SELECT * FROM users WHERE age > 25` |
| INSERT | 插入数据 | `INSERT INTO users (name, age) VALUES ('Alice', 25)` |
| UPDATE | 更新数据 | `UPDATE users SET age = 26 WHERE name = 'Alice'` |
| DELETE | 删除数据 | `DELETE FROM users WHERE age < 25` |
| WHERE | 条件过滤 | `WHERE age > 25 AND department = 'Engineering'` |
| ORDER BY | 排序 | `ORDER BY age DESC` |
| LIMIT | 限制数量 | `LIMIT 10` |
| OFFSET | 跳过数量 | `OFFSET 5` |
| DISTINCT | 去重 | `SELECT DISTINCT department FROM users` |
| LIKE | 模糊匹配 | `WHERE email LIKE '%@example.com'` |
| IN | 范围匹配 | `WHERE department IN ('A', 'B')` |
| BETWEEN | 范围匹配 | `WHERE age BETWEEN 25 AND 30` |

**比较操作符：** `=`, `!=`, `<>`, `<`, `<=`, `>`, `>=`

**逻辑操作符：** `AND`, `OR`

**运行 SQL 示例：**
```bash
node dist/examples/sql-example.js
```

### 内存模式

内存模式将数据完全存储在内存中，无需磁盘 I/O，适合快速测试、原型验证和临时数据存储：

```javascript
import { Database } from '@yanit/jsondb';

// 创建内存数据库
const db = new Database('my-memory-db', { memory: true });
await db.open();

// 检查是否为内存模式
console.log(db.isMemoryMode()); // true

// 使用方式与持久化模式完全相同
const users = db.collection('users');
await users.insertOne({ name: 'Alice', age: 25 });

// 查看统计信息
const stats = await db.stats();
console.log(stats.memory); // true
console.log(stats.path);   // 'memory'
```

**内存模式特点：**
- ✅ 无需磁盘 I/O，性能极快
- ✅ 适合单元测试和快速原型
- ✅ 不需要指定实际路径
- ✅ 使用方式与持久化模式完全相同
- ⚠️ 程序重启后数据会丢失
- ⚠️ 不适合持久化存储

**使用场景：**
- 单元测试和集成测试
- 原型开发和功能验证
- 临时数据处理
- 性能敏感的场景

**运行内存模式示例：**
```bash
npm run example:memory
```

### JSONB 模式

JSONB（JSON Binary）模式使用二进制格式存储数据，适合对存储空间和 I/O 性能敏感的场景：

```javascript
// 启用 JSONB 模式
const db = new Database('./temp/mydb', { jsonb: true });

// 查看统计信息
const stats = await db.stats();
console.log(stats.jsonb); // true
```

**JSONB 二进制格式：**
```
[4 字节长度 (uint32 BE)][UTF-8 JSON 数据...]
```

**JSONB 模式特点：**
- ✅ 二进制存储，无格式化和空格
- ✅ 4 字节长度前缀，快速验证完整性
- ✅ 向后兼容普通 JSON 格式
- ✅ 适合大规模数据存储
- ✅ 更小的文件体积（约节省 30-40%）
- ⚠️ 人类不可直接阅读（需要解码）

**使用场景：**
- 生产环境数据存储
- 大规模数据集
- 对存储空间敏感的应用
- 需要快速加载的场景

### 运行示例

```bash
# 运行所有示例（推荐）
npm run example        # 使用 Node.js 运行所有示例
bun run example:bun    # 使用 Bun 运行所有示例

# 运行单个示例
npm run example:basic        # 基础示例
npm run example:advanced     # 高级查询示例
npm run example:jsonb        # JSONB 模式示例
npm run example:memory       # 内存模式示例
npm run example:debug        # Debug 模式示例
npm run example:repl         # REPL 功能演示
npm run example:sql          # SQL 查询示例
npm run example:transaction  # 事务和批量操作示例
npm run example:index        # 索引功能示例
npm run example:schema       # Schema 验证示例
npm run example:cache        # 查询缓存示例

# 使用 Bun 运行单个示例
bun run test/examples/basic.ts
bun run test/examples/advanced.ts
bun run test/examples/sql-example.ts
```

### Debug 模式

Debug 模式提供命令执行日志和性能监控功能，方便调试和性能优化：

```javascript
import { Database, enableDebug } from '@yanit/jsondb';

// 方法 1: 全局启用 debug 模式
enableDebug({
  enabled: true,
  showParams: true,      // 显示参数
  showResult: false,     // 不显示结果（避免输出太多）
  showDuration: true,    // 显示执行时间
  slowQueryThreshold: 50 // 慢查询阈值（毫秒）
});

// 方法 2: 在构造函数中启用
const db = new Database('./temp/mydb', { debug: true });
await db.open();

// 方法 3: 动态开关
db.setDebug(true);   // 启用
db.setDebug(false);  // 禁用

// 查看性能统计
db.printDebugStats();
```

**Debug 日志输出示例：**
```
[09:23:14.116] DEBUG Collection.insertOne - 执行完成 (1.00ms)
  参数：{ collection: "users", docKeys: [ "name", ... 等 4 项 ] }
  结果：{ _id: "019d485a-a844-7099-b90b-7e8c937c9ea6" }

[09:23:14.117] DEBUG Cursor.toArray - 执行完成 (0.00ms)
  参数：{ collection: "users" }
  结果：{ count: 4 }
```

**数组和对象显示：**
```
[09:23:14.117] DEBUG Collection.insertMany - 执行完成 (1.00ms)
  参数：{ collection: "users", count: 3 }
  结果：{ 
    acknowledged: true, 
    insertedCount: 3, 
    insertedIds: { 0: "019d...", 1: "019d...", 2: "019d..." } 
  }
```

**慢查询警告：**
```
⚠️ 慢查询警告 Collection.find 耗时 150.00ms
  参数：{ "collection": "users", "query": { ... } }
```

**性能统计报告：**
```
============================================================
性能统计报告
============================================================
操作                            次数     平均 (ms)    最小 (ms)    最大 (ms)    
--------------------------------------------------------------------
Collection.insertMany           1        2.00         2.00         2.00         
Cursor._execute                 5        0.40         0.00         1.00         
Collection.insertOne            3        1.33         1.00         2.00         
============================================================
```

**使用场景：**
- 开发调试阶段
- 性能问题排查
- 慢查询优化
- 命令执行跟踪

---

## Web 管理工具

JSONDB 提供了一个功能完整的 Web 管理工具，可以通过浏览器管理数据库。

### 启动 Web 管理工具

```bash
npm start
```

然后在浏览器中访问：http://127.0.0.1:3000

### 功能特性

- 📁 **打开数据库** - 选择包含 JSON/JSONB 文件的文件夹
- 📊 **集合列表** - 显示所有集合及文档数量
- 🔍 **查询执行** - 支持 MongoDB 风格查询语法
- 📥 **数据导出** - 支持导出为 CSV 和 XLSX 格式
- ➕ **插入文档** - 可视化插入新文档
- 🔄 **实时刷新** - 刷新集合数据
- 📄 **格式切换** - 支持 JSON 和 JSONB 格式
- ⬆️ **上传文件** - 支持上传 JSON/JSONB 文件创建集合
- 💾 **保存更改** - 下载修改的集合
- ⬇️ **批量下载** - 下载所有集合（JSON/JSONB 格式）

### 查询语法

```javascript
// 精确匹配
{ "status": "active" }

// 比较操作符
{ "age": { "$gt": 25 } }
{ "salary": { "$gte": 5000, "$lte": 10000 } }

// 逻辑操作符
{ "$and": [{ "age": { "$gt": 18 } }, { "status": "active" }] }
{ "$or": [{ "role": "admin" }, { "role": "moderator" }] }

// 数组操作符
{ "tags": { "$in": ["javascript", "nodejs"] } }

// 正则表达式
{ "name": { "$regex": "^A" } }

// 查询所有
{}
```

### 使用截图

1. 打开数据库文件夹
2. 选择集合
3. 执行查询
4. 导出数据

---

## 命令行工具

### 导出工具

```bash
# 导出单个文件（支持 JSON/JSONB）
node bin/cli-export.js export <输入文件> <输出文件> [选项]

# 从数据库导出集合
node bin/cli-export.js db <数据库目录> <集合名> <输出文件> [选项]

# 列出数据库中的所有集合
node bin/cli-export.js list <数据库目录>
```

### 导入工具

```bash
# 从 CSV/XLSX/JSON 导入数据
node bin/cli-import.js import <输入文件> <数据库目录> <集合名> [选项]

# 转换文件格式（JSON ↔ JSONB）
node bin/cli-import.js convert <输入文件> <输出文件> [选项]
```

### 选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-f, --format <format>` | 输入/输出格式 (json, csv, xlsx) | auto |
| `-p, --pretty` | 格式化 JSON 输出 | false |
| `-d, --delimiter <char>` | CSV 分隔符 | , |
| `--no-header` | 不包含 CSV 表头 | false |
| `--no-flatten` | 不扁平化嵌套对象 | false |
| `--jsonb` | 使用 JSONB 二进制格式存储 | false |
| `--to-jsonb` | 转换为 JSONB 格式 | false |
| `--to-json` | 转换为 JSON 格式 | false |

### 使用示例

```bash
# ============ 导出 ============

# 导出 JSONB 文件为 JSON
node bin/cli-export.js export data/users.json output/users.json --pretty

# 导出为 CSV
node bin/cli-export.js export data/users.json output/users.csv --format csv

# 导出为 XLSX
node bin/cli-export.js export data/users.json output/users.xlsx --format xlsx

# 从数据库导出集合
node bin/cli-export.js db ./data/mydb users output/users.json --pretty

# ============ 导入 ============

# 从 CSV 导入（自动检测格式）
node bin/cli-import.js import users.csv ./data/mydb users

# 从 CSV 导入到 JSONB 格式
node bin/cli-import.js import users.csv ./data/mydb users --jsonb

# 从 XLSX 导入
node bin/cli-import.js import users.xlsx ./data/mydb users --format xlsx

# 转换 JSONB 为 JSON
node bin/cli-import.js convert data/users.json output/users.json --to-json --pretty

# 转换 JSON 为 JSONB
node bin/cli-import.js convert data/users.json output/users.jsonb --to-jsonb
```

## 功能需求清单

### ✅ 已完成功能

#### 1. 核心数据库功能

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 数据库管理 | ✅ 完成 | 100% | 创建/打开/关闭/删除数据库 |
| 集合管理 | ✅ 完成 | 100% | 创建/删除/列出集合 |
| 文档 CRUD | ✅ 完成 | 100% | 插入/查询/更新/删除 |
| 索引管理 | ✅ 完成 | 90% | 创建/删除/列出索引 |

#### 2. 查询功能

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 比较操作符 | ✅ 完成 | 100% | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
| 逻辑操作符 | ✅ 完成 | 100% | `$and`, `$or`, `$not`, `$nor` |
| 数组操作符 | ✅ 完成 | 100% | `$in`, `$nin`, `$all`, `$elemMatch`, `$size` |
| 正则表达式 | ✅ 完成 | 100% | `$regex`, `$options` |
| 元素操作符 | ✅ 完成 | 100% | `$exists`, `$type` |
| 查询选项 | ✅ 完成 | 100% | `sort()`, `skip()`, `limit()`, `project()` |

#### 3. 更新功能

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 字段操作符 | ✅ 完成 | 100% | `$set`, `$unset`, `$rename` |
| 数值操作符 | ✅ 完成 | 100% | `$inc`, `$mul`, `$min`, `$max` |
| 数组操作符 | ✅ 完成 | 100% | `$push`, `$pull`, `$pop`, `$addToSet` |

#### 4. 聚合管道

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 基础阶段 | ✅ 完成 | 95% | `$match`, `$group`, `$project`, `$sort`, `$limit`, `$skip`, `$count` |
| 聚合函数 | ✅ 完成 | 95% | `$sum`, `$avg`, `$min`, `$max` |
| 数组聚合 | ✅ 完成 | 90% | `$push`, `$addToSet` |

#### 5. SQL 查询支持

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| SELECT 查询 | ✅ 完成 | 100% | 支持 WHERE, ORDER BY, LIMIT, OFFSET |
| INSERT 语句 | ✅ 完成 | 100% | 支持单条和批量插入 |
| UPDATE 语句 | ✅ 完成 | 100% | 支持 WHERE 条件更新 |
| DELETE 语句 | ✅ 完成 | 100% | 支持 WHERE 条件删除 |
| GROUP BY | ✅ 完成 | 100% | 支持 COUNT, AVG, SUM, MIN, MAX |
| 聚合函数 | ✅ 完成 | 100% | 支持别名、多字段分组 |
| 操作符 | ✅ 完成 | 100% | `=`, `!=`, `<>`, `<`, `<=`, `>`, `>=`, `LIKE`, `ILIKE`, `IN`, `BETWEEN` |
| 正则表达式 | ✅ 完成 | 100% | `~`, `~*`, `!~`, `!~*` |

#### 6. 缓存与优化

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 查询缓存 | ✅ 完成 | 90% | 自动缓存查询结果 |
| 缓存配置 | ✅ 完成 | 90% | 可配置 TTL、最大条目数 |
| 缓存失效 | ✅ 完成 | 90% | 写入时自动失效 |
| 缓存预热 | ✅ 完成 | 90% | 支持手动预热 |
| 慢查询日志 | ✅ 完成 | 90% | 记录慢查询 |
| 索引推荐 | ✅ 完成 | 90% | 基于慢查询推荐索引 |
| EXPLAIN | ✅ 完成 | 90% | 查询执行计划分析 |

#### 7. 数据验证

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| Schema 验证 | ✅ 完成 | 100% | 支持字段类型、长度、范围验证 |
| 必填字段 | ✅ 完成 | 100% | 支持 required 验证 |
| 枚举验证 | ✅ 完成 | 100% | 支持 enum 验证 |
| 自定义验证 | ✅ 完成 | 100% | 支持自定义验证函数 |

#### 8. 事务支持

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| 事务操作 | ✅ 完成 | 95% | 支持多集合事务 |
| 事务提交 | ✅ 完成 | 95% | 支持 commit |
| 事务回滚 | ✅ 完成 | 95% | 支持 rollback |

#### 9. 存储模式

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| JSON 模式 | ✅ 完成 | 100% | 标准 JSON 格式存储 |
| JSONB 模式 | ✅ 完成 | 100% | 二进制格式存储（节省 30-40% 空间） |
| 内存模式 | ✅ 完成 | 100% | 纯内存存储，适合测试和原型验证 |

#### 10. Debug 与监控

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| Debug 日志 | ✅ 完成 | 100% | 命令执行日志和参数记录 |
| 性能统计 | ✅ 完成 | 100% | 操作次数和响应时间统计 |
| 慢查询检测 | ✅ 完成 | 100% | 慢查询自动告警 |
| 动态开关 | ✅ 完成 | 100% | 运行时启用/禁用 debug |

#### 11. 工具链

| 功能模块 | 状态 | 测试覆盖 | 说明 |
|---------|------|---------|------|
| Web 管理工具 | ✅ 完成 | - | 浏览器管理界面 |
| CLI 导出工具 | ✅ 完成 | - | 支持 JSON/CSV/XLSX 导出 |
| CLI 导入工具 | ✅ 完成 | - | 支持 CSV/XLSX/JSON 导入 |
| 格式转换 | ✅ 完成 | - | JSON ↔ JSONB 转换 |

---

## 开发计划

### ✅ 已完成阶段

| 阶段 | 状态 | 完成时间 | 主要内容 |
|------|------|---------|---------|
| Phase 1: 基础框架 | ✅ 完成 | Week 1 | Database/Collection 类、CRUD 操作、TypeScript 迁移 |
| Phase 2: 查询引擎 | ✅ 完成 | Week 2 | 查询解析器、操作符、Cursor 类 |
| Phase 3: 更新与索引 | ✅ 完成 | Week 3 | 更新操作符、索引机制 |
| Phase 4: 聚合管道 | ✅ 完成 | Week 4 | 聚合框架、表达式系统 |
| Phase 5: 优化与完善 | ✅ 完成 | Week 5 | 缓存、事务、Schema 验证、JSONB |
| Phase 6: 工具与生态 | ✅ 完成 | Week 6 | Web 管理工具、CLI 工具、SQL 支持 |

### 🚀 进行中阶段

| 阶段 | 状态 | 预计完成 | 主要内容 |
|------|------|---------|---------|
| Phase 7: 高级功能 | 🟡 进行中 | Week 8-10 | 全文搜索、地理空间查询、视图 |

### 📋 计划中阶段

| 阶段 | 状态 | 预计开始 | 主要内容 |
|------|------|---------|---------|
| Phase 8: 安全与性能 | ⚪ 计划中 | Week 11-13 | ACL、数据加密、审计日志 |
| Phase 9: 扩展性 | ⚪ 计划中 | Week 14-16 | 插件系统、分布式存储 |

---

## 当前状态

### 📊 测试结果

```
✓ Test Files  9 passed (9)
✓ Tests       128 passed (128)
Duration      ~1.5s
```

### 📈 性能指标

| 场景 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 批量插入 vs 单条插入 | 64ms | 2ms | **32x** |
| 索引查询 vs 全表扫描 | 4ms | 2ms | **2x** |
| JSONB vs JSON 存储 | 209 bytes | 150 bytes | **28% 节省** |
| 缓存命中查询 | 50ms | 1ms | **50x** |

### 🎯 测试覆盖率

| 功能模块 | 测试文件 | 测试数 | 通过率 |
|---------|---------|--------|--------|
| 基础 CRUD | basic.test.ts | 31 | 100% |
| 索引性能 | index.test.ts | 9 | 100% |
| JSONB 模式 | jsonb.test.ts | 13 | 100% |
| Schema 验证 | schema.test.ts | 14 | 100% |
| 查询优化器 | optimization.test.ts | 15 | 100% |
| SQL 查询 | sql.test.ts | 2 | 100% |
| 缓存增强 | cache-enhancement.vitest.test.ts | 8 | 100% |
| GROUP BY | groupby.vitest.test.ts | 13 | 100% |
| 日常场景 | daily-scenarios.vitest.test.ts | 27 | 100% |
| **总计** | **9 个文件** | **128** | **100%** |

---

## API 参考

### Database 类

```javascript
const db = new Database('./data/mydb');

await db.open();              // 打开数据库
await db.close();             // 关闭数据库
await db.drop();              // 删除数据库

db.collection(name);          // 获取集合（同步）
await db.createCollection(name);  // 创建集合
await db.dropCollection(name);    // 删除集合
await db.listCollections();       // 列出所有集合
await db.stats();                 // 获取统计信息
```

### Collection 类

```javascript
const collection = db.collection('users');

// 插入
await collection.insertOne(doc);
await collection.insertMany([docs]);

// 查询
const cursor = collection.find(query);  // 返回 Cursor
const doc = await collection.findOne(query);

// 更新
await collection.updateOne(query, update);
await collection.updateMany(query, update);
await collection.replaceOne(query, doc);

// 删除
await collection.deleteOne(query);
await collection.deleteMany(query);

// 统计
await collection.countDocuments(query);
await collection.distinct(key, query);
await collection.aggregate(pipeline);

// 索引
await collection.createIndex(keys);
await collection.dropIndex(name);
await collection.listIndexes();
await collection.stats();
```

### Cursor 类

```javascript
const cursor = collection.find(query)
  .sort({ age: -1 })
  .skip(10)
  .limit(20)
  .project({ name: 1, email: 1 });

const results = await cursor.toArray();   // 获取所有结果
const first = await cursor.first();       // 获取第一个
const next = await cursor.next();         // 获取下一个
const count = await cursor.count();       // 获取数量

// 遍历
await cursor.forEach(doc => {
  console.log(doc);
});

// for await...of
for await (const doc of cursor) {
  console.log(doc.name);
}
```

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `$eq` | 等于 | `{ age: { $eq: 25 } }` |
| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
| `$gt` | 大于 | `{ price: { $gt: 100 } }` |
| `$gte` | 大于等于 | `{ score: { $gte: 60 } }` |
| `$lt` | 小于 | `{ age: { $lt: 18 } }` |
| `$lte` | 小于等于 | `{ level: { $lte: 5 } }` |
| `$in` | 在...中 | `{ status: { $in: ['A', 'B'] } }` |
| `$nin` | 不在...中 | `{ type: { $nin: ['test'] } }` |
| `$and` | 与 | `{ $and: [{ a: 1 }, { b: 2 }] }` |
| `$or` | 或 | `{ $or: [{ a: 1 }, { b: 2 }] }` |
| `$not` | 非 | `{ price: { $not: { $gte: 100 } } }` |
| `$exists` | 字段存在 | `{ phone: { $exists: true } }` |
| `$regex` | 正则 | `{ name: { $regex: /^A/ } }` |
| `$all` | 数组包含所有 | `{ tags: { $all: ['a', 'b'] } }` |
| `$size` | 数组大小 | `{ comments: { $size: 5 } }` |
| `$elemMatch` | 数组元素匹配 | `{ scores: { $elemMatch: { $gte: 80 } } }` |

### 更新操作符

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `$set` | 设置字段 | `{ $set: { status: 'active' } }` |
| `$unset` | 删除字段 | `{ $unset: { temp: '' } }` |
| `$inc` | 自增 | `{ $inc: { views: 1 } }` |
| `$mul` | 自乘 | `{ $mul: { price: 0.8 } }` |
| `$push` | 推入数组 | `{ $push: { tags: 'new' } }` |
| `$pull` | 拉出数组 | `{ $pull: { tags: 'old' } }` |
| `$addToSet` | 添加到集合 | `{ $addToSet: { colors: 'red' } }` |
| `$pop` | 弹出数组 | `{ $pop: { items: 1 } }` |

### 聚合管道

| 阶段 | 说明 |
|------|------|
| `$match` | 过滤文档 |
| `$group` | 分组聚合 |
| `$project` | 重塑文档 |
| `$sort` | 排序 |
| `$limit` | 限制数量 |
| `$skip` | 跳过数量 |
| `$count` | 计数 |
| `$lookup` | 关联查询 |
| `$unwind` | 展开数组 |

---

## 技术栈

- **运行时**: Node.js >= 18 或 Bun >= 1.0
- **语言**: JavaScript (ES Modules)
- **测试**: Vitest / Jest / Bun Test
- **代码质量**: ESLint + Prettier
- **文档**: Markdown
- **包管理**: npm / pnpm / bun

---

## Bun 支持

本项目完全支持使用 Bun 运行时，提供更高的性能和更便捷的开发体验。

### 使用 Bun 快速开始

```bash
# 使用 bun 安装依赖
bun install

# 使用 bun 构建
bun run bun:build

# 运行测试
bun run bun:test

# 启动服务
bun run bun:start
```

### Bun 专用命令

#### 测试命令

| 命令 | 说明 |
|------|------|
| `bun run bun:test` | 使用 bun 内置测试运行器运行 test_bunjs/ 测试 |
| `bun run bun:test:watch` | 使用 bun 监听模式运行测试 |
| `bun run bun:test:coverage` | 使用 bun 运行测试并生成覆盖率报告 |
| `bun run bun:test:vitest` | 使用 bun 运行 vitest 测试（test/ 目录） |
| `bun run bun:test:vitest:watch` | 使用 bun 监听模式运行 vitest 测试 |

> **说明**：项目有两套测试系统：
> - **test_bunjs/**：使用 bun 内置测试运行器（语法：`import { describe, it, expect } from 'bun:test'`）
> - **test/**：使用 vitest 测试框架（语法：`import { describe, it, expect } from 'vitest'`）
> 
> 推荐使用 `bun run bun:test` 运行 bun 原生测试，速度更快。

#### 其他命令

| 命令 | 说明 |
|------|------|
| `bun run bun:install` | 使用 bun 安装依赖 |
| `bun run bun:build` | 使用 bun 构建项目 |
| `bun run bun:start` | 使用 bun 启动服务 |
| `bun run bun:start:dev` | 使用 bun 启动开发服务 |
| `bun run bun:example` | 使用 bun 运行基础示例 |
| `bun run bun:example:advanced` | 使用 bun 运行高级示例 |
| `bun run bun:example:memory` | 使用 bun 运行内存模式示例 |
| `bun run bun:perf` | 使用 bun 运行性能测试 |

### Bun 的优势

- ⚡ **更快的启动速度** - 比 Node.js 快 4x 的启动速度
- 🚀 **更好的性能** - 内置原生代码优化
- 📦 **内置 TypeScript 支持** - 无需额外配置即可运行 TypeScript
- 🔧 **内置测试运行器** - 更快的测试执行速度
- 🎯 **零配置** - 开箱即用，无需额外配置

### Node.js vs Bun 对比

| 特性 | Node.js | Bun |
|------|---------|-----|
| 启动速度 | 标准 | 快 4x |
| TypeScript | 需要编译 | 原生支持 |
| 测试运行 | 需要框架 | 内置支持 |
| 包安装 | npm/pnpm | 内置（快 10x） |
| 兼容性 | 完全兼容 | 高度兼容 |

### 兼容性说明

- ✅ 所有 Node.js 功能在 Bun 中均可使用
- ✅ API 完全兼容，无需修改代码
- ✅ 支持相同的依赖和插件
- ✅ 测试用例在两种运行时下均通过

---

## 许可证

MIT License

---

## 相关链接

- [MongoDB 查询文档](https://docs.mongodb.com/manual/reference/operator/query/)
- [Node.js 官方文档](https://nodejs.org/)