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

项目概述

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

核心特点

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

快速开始

安装

npm install

基本使用

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: '[email protected]'
  });

  // 查询
  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 进行增删改查操作：

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, '[email protected]')");

// 批量插入
await users.sql(`
  INSERT INTO users (name, age, email) VALUES 
  ('Bob', 30, '[email protected]'),
  ('Charlie', 28, '[email protected]')
`);

// 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 示例：

node dist/examples/sql-example.js

内存模式

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

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，性能极快
• ✅ 适合单元测试和快速原型
• ✅ 不需要指定实际路径
• ✅ 使用方式与持久化模式完全相同
• ⚠️ 程序重启后数据会丢失
• ⚠️ 不适合持久化存储

使用场景：

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

运行内存模式示例：

npm run example:memory

JSONB 模式

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

// 启用 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%）
• ⚠️ 人类不可直接阅读（需要解码）

使用场景：

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

运行示例

# 运行所有示例（推荐）
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 模式提供命令执行日志和性能监控功能，方便调试和性能优化：

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 管理工具

npm start

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

功能特性

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

查询语法

// 精确匹配
{ "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. 导出数据

命令行工具

导出工具

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

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

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

导入工具

# 从 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 |

使用示例

# ============ 导出 ============

# 导出 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 类

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 类

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 类

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 快速开始

# 使用 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 查询文档
• Node.js 官方文档