BSON - TypeScript 数据管理工具

原BSON js版本不再维护，https://github.com/woodhans/BSON 一个功能强大的 TypeScript 数据管理工具，支持增删改查、数据类型验证、主键管理、排序和深度搜索等功能。

功能特性

• 完整的 CRUD 操作：支持添加、更新、删除和查询数据(v1.0.0)
• 丰富的数据类型：支持 string、number、boolean、object、array 和 bson 类型(v1.0.0)
• 强大的错误处理：提供清晰的错误提示和验证(v1.0.0)
• 主键管理：支持自增主键、自定义主键类型和唯一性检查(v1.0.0)
• 默认条件处理：简化条件查询语法(v1.0.0)
• 排序功能：支持按字段排序和链式操作(v1.0.0)
• 深度搜索：支持树形结构的递归搜索(v1.0.0)
• 嵌套 BSON：支持字段为另一个 BSON 数据集(v1.0.0)
• 分页功能：支持 limit 和 offset 进行分页(v1.0.1)
• 正则表达式匹配：支持 like 操作符进行正则表达式匹配(v1.0.1)
• 数据统计：支持 total 方法返回数据集总数(v1.0.1)
• 深度搜索bug修复：修复深度搜索时返回的数据，由原来扁平化的数据改为原树形数据(v1.0.2)
• toArray方法优化：把BSON逻辑字段类似，key，fields, keyType等等都不要输出到toArray结果里面(v1.0.2)
• 新增get(index)方法：获取当前BSON数据的下标index的单条记录(v1.0.2)

安装

npm install bson

基本用法

创建 BSON 实例

const { BSON } = require('bson');

// 创建带有字段定义的 BSON 实例
const bson = new BSON({
  fields: {
    name: { type: 'string', required: true },
    age: { type: 'number', default: 0 },
    active: { type: 'boolean', default: true }
  },
  key: 'id' // 主键字段
});

添加数据

// 添加单条数据
bson.add({ name: 'Alice', age: 25 });

// 添加多条数据
bson.add([
  { name: 'Bob', age: 30 },
  { name: 'Charlie', age: 35 }
]);

查询数据

// 查询所有数据
const allData = bson.all.toArray();

// 条件查询
const activeUsers = bson.find({ field: 'active', operator: 'eq', value: true }).toArray();

// 深度搜索（搜索所有层级）
const usersWithZhang = bson.find(
  { field: 'name', operator: 'include', value: '张' },
  { deep: true }
).toArray();

更新数据

// 条件更新
const updatedCount = bson.update(
  { age: 26 },
  { field: 'name', operator: 'eq', value: 'Alice' }
);

// 使用默认条件（基于主键）
bson.update({ age: 31 }, { value: 2 }); // 更新 id=2 的记录

删除数据

// 条件删除
const deletedCount = bson.delete({ field: 'age', operator: 'lt', value: 30 });

// 使用默认条件（基于主键）
bson.delete({ value: 1 }); // 删除 id=1 的记录

高级功能

主键配置

// 自定义字符串主键
const bsonWithStringKey = new BSON({
  fields: {
    name: { type: 'string', required: true }
  },
  key: 'userId',
  keyType: 'string'
});

// 自定义主键生成器
let customId = 1000;
const bsonWithCustomKey = new BSON({
  fields: {
    name: { type: 'string', required: true }
  },
  key: 'customId',
  keyType: 'custom',
  keyGenerator: () => `C${customId++}`
});

嵌套 BSON

const parentBSON = new BSON({
  fields: {
    name: { type: 'string', required: true },
    address: {
      type: 'bson',
      bsonOptions: {
        fields: {
          street: { type: 'string', required: true },
          city: { type: 'string', required: true }
        }
      }
    }
  }
});

parentBSON.add({
  name: 'Alice',
  address: { street: '123 Main St', city: 'New York' }
});

// 访问和操作嵌套 BSON
const alice = parentBSON.findOne({ field: 'name', operator: 'eq', value: 'Alice' });
alice.address.add({ street: '456 Oak Ave', city: 'Los Angeles' });

排序

// 默认按主键排序
const sortedByKey = bson.all.sort().toArray();

// 按指定字段排序
const sortedByAge = bson.all.sort({ field: 'age', order: 'asc' }).toArray();

// 链式操作：查询后排序
const filteredAndSorted = bson.find({ field: 'age', operator: 'lte', value: 30 })
  .sort({ field: 'score', order: 'desc' })
  .toArray();

深度搜索

// 深度搜索所有包含特定内容的节点
const result = bson.find(
  { field: 'name', operator: 'include', value: '张' },
  { deep: true }
).toArray();

// 深度搜索并排序
const sortedResult = bson.find(
  { field: 'name', operator: 'include', value: '张' },
  { deep: true }
).sort({ field: 'name' }).toArray();

API 参考

BSON 构造函数

new BSON(options: BSONOptions);

interface BSONOptions {
  fields: Record<string, FieldType>;
  key?: string;            // 主键字段名
  keyType?: 'number' | 'string' | 'custom';  // 主键类型
  keyGenerator?: () => any;  // 自定义主键生成器
}

interface FieldType {
  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'bson';
  required?: boolean;      // 是否必填
  default?: any;           // 默认值
  bsonOptions?: BSONOptions;  // 当 type 为 'bson' 时的配置
}

方法

add(param: BSONData | BSONData[]): void

添加一条或多条数据

update(options: BSONData, conditions: any): number

更新符合条件的数据，返回更新的数量

delete(conditions: any): number

删除符合条件的数据，返回删除的数量

find(conditions?: any, options?: { deep?: boolean }): QueryResult

查询符合条件的数据，返回 QueryResult 对象

findOne(conditions: any): BSONData | undefined

查询符合条件的第一条数据

count(conditions?: any): number

返回符合条件的数据数量

clear(): void

清空所有数据

get all(): QueryResult

获取所有数据

QueryResult 方法

sort(options?: { field?: string; order?: 'asc' | 'desc' }): QueryResult

排序结果

limit(limit: number, offset: number = 0): QueryResult

分页结果，参数为每页数量和偏移量

total(): number

返回结果集总数

toArray(): BSONData[]

将结果转换为数组

forEach(callback: (item: BSONData, index: number) => void): void

遍历结果

map(callback: (item: BSONData, index: number) => T): T[]

获取index下标的结果

get(index: number): BSONData | undefined

映射结果

get length(): number

获取结果长度

条件操作符

| 操作符 | 描述 | 适用类型 | | ------- | ---- | ------ | | eq | 等于 | 所有类型 | | ne | 不等于 | 所有类型 | | gt | 大于 | 数字 | | gte | 大于等于 | 数字 | | lt | 小于 | 数字 | | lte | 小于等于 | 数字 | | include | 包含 | 数组、字符串 | | exclude | 不包含 | 数组、字符串 | | like | 正则匹配 | 字符串 |

复杂条件

// AND 条件
const result = bson.find({
  and: [
    { field: 'age', operator: 'gte', value: 18 },
    { field: 'active', operator: 'eq', value: true }
  ]
});

// OR 条件
const result = bson.find({
  or: [
    { field: 'name', operator: 'eq', value: 'Alice' },
    { field: 'age', operator: 'lt', value: 25 }
  ]
});

错误处理

BSON 会在以下情况抛出错误：

• 未知字段（拼写错误）
• 必填字段缺失
• 主键重复
• 更新主键为已存在的值
• 条件匹配不到数据
• 无效的操作符
• 无效的条件格式

示例

完整示例

const { BSON } = require('bson');

// 创建 BSON 实例
const userBSON = new BSON({
  fields: {
    name: { type: 'string', required: true },
    age: { type: 'number', default: 0 },
    email: { type: 'string', required: true },
    hobbies: {
      type: 'bson',
      bsonOptions: {
        fields: {
          name: { type: 'string', required: true },
          level: { type: 'string', default: 'beginner' }
        }
      }
    }
  },
  key: 'id'
});

// 添加数据
for (let i = 1; i <= 10; i++) {
  userBSON.add({
    name: `User${i}`,
    age: 20 + i,
    email: `user${i}@example.com`,
    hobbies: [
      { name: 'reading', level: 'advanced' },
      { name: 'swimming', level: 'intermediate' }
    ]
  });
}

// 1. 分页功能
console.log('=== 分页功能 ===');
const page1 = userBSON.all.limit(3, 0).toArray();
console.log('第一页数据:', page1.map(item => item.name));
console.log('第一页数据量:', page1.length);

// 2. 正则表达式匹配
console.log('\n=== 正则表达式匹配 ===');
const usersWithEvenId = userBSON.find({ field: 'id', operator: 'like', value: '^[24680]$' }).toArray();
console.log('ID为偶数的用户:', usersWithEvenId.map(item => item.name));

const usersWithEmail = userBSON.find({ field: 'email', operator: 'like', value: /user[12]@/ }).toArray();
console.log('邮箱包含user1或user2的用户:', usersWithEmail.map(item => item.email));

// 3. 数据统计
console.log('\n=== 数据统计 ===');
console.log('总用户数:', userBSON.count());
console.log('年龄>=25的用户数:', userBSON.count({ field: 'age', operator: 'gte', value: 25 }));

// 4. 链式操作
console.log('\n=== 链式操作 ===');
const result = userBSON.find({ field: 'age', operator: 'gte', value: 23 })
  .sort({ field: 'age', order: 'desc' })
  .limit(2, 0)
  .toArray();
console.log('年龄>=23且按年龄降序排序的前2个用户:', result.map(item => `${item.name} (${item.age}岁)`));

// 5. 深度搜索结合正则表达式
console.log('\n=== 深度搜索结合正则表达式 ===');
const usersWithHobby = userBSON.find(
  { field: 'name', operator: 'like', value: /reading/ },
  { deep: true }
).toArray();
console.log('包含reading爱好的节点:', usersWithHobby.map(item => item.name));

// 6. 完整的分页查询
console.log('\n=== 完整的分页查询 ===');
const pageSize = 3;
const pageNumber = 2;
const offset = (pageNumber - 1) * pageSize;

const pagedResult = userBSON.find({ field: 'age', operator: 'gte', value: 20 })
  .sort({ field: 'name' })
  .limit(pageSize, offset);

console.log(`第${pageNumber}页数据:`, pagedResult.toArray().map(item => item.name));
console.log(`当前页数据量:`, pagedResult.total());
console.log(`总符合条件的数据量:`, userBSON.count({ field: 'age', operator: 'gte', value: 20 }));

主要使用场景

之前在做一些复杂的Form List表单时候，需要前端大量交互操作，不可能每一个操作调用接口去更新后端数据，所以需要大量前端增删改查，所以在5年前做了一版bson js版本的。现在想想之前的很多设计不是很好，又用typescript改版了一版。所以主要使用场景就是较复杂的表单操作，前端操作完了以后将数据提交给后端，像crontab定时任务，监控规则等等。另外就是大量的数据操作，比如指标库，后端将大量数据吐出给前端，由前端去排序筛选分页等等。很适合用这个库来进行数据处理。

许可证

MIT