@yanit/jsondb 0.1.1

package/src/Collection.ts

@@ -0,0 +1,896 @@
+/**
+ * 集合类 - 管理文档集合
+ * 支持 async/await 异步操作
+ * 支持 JSONB 二进制存储模式
+ * 支持 Schema 验证
+ * 支持内存缓存优化
+ */
+
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { generateId, deepClone, getNestedValue } from './Utils.js';
+import { Cursor } from './Cursor.js';
+import { matchQuery, applyUpdate } from './Operators.js';
+import { CollectionNotFoundError, DocumentNotFoundError, ValidationError } from './errors.js';
+import type { Database } from './Database.js';
+import type { Schema } from './Schema.js';
+import type { SQLExecutionResult } from './SQLExecutor.js';
+import { executeSQL } from './SQLExecutor.js';
+
+/**
+ * 集合统计信息接口
+ */
+interface CollectionStats {
+  ns: string;
+  count: number;
+  size: number;
+  avgObjSize: number;
+  indexes: number;
+  jsonb: boolean;
+}
+
+/**
+ * 索引信息接口
+ */
+export interface IndexInfo {
+  key: Record<string, number>;
+  name: string;
+  unique: boolean;
+}
+
+/**
+ * 集合数据接口
+ */
+interface CollectionData {
+  _meta: {
+    name: string;
+    count: number;
+    indexes: IndexInfo[];
+  };
+  _documents: Array<Record<string, unknown>>;
+  _indexes: Record<string, Record<string, string[]>>;
+}
+
+/**
+ * Collection 类
+ * 表示一个文档集合，提供 CRUD 操作
+ */
+export class Collection {
+  db: Database;
+  name: string;
+  private _filePath: string;
+  _data: CollectionData | null;
+  private _lock: boolean | null;
+  jsonb: boolean;
+  private _schema: Schema | null;
+  _validateOnInsert: boolean;
+  _validateOnUpdate: boolean;
+
+  // 内存缓存优化
+  _cache: CollectionData | null;
+  _cacheTime: number;
+  private _cacheTTL: number;
+  private _dirty: boolean;
+
+  /**
+   * @param db - 数据库实例
+   * @param name - 集合名称
+   */
+  constructor(db: Database, name: string) {
+    this.db = db;
+    this.name = name;
+    this._filePath = join(db.dbPath, `${name}.json`);
+    this._data = null;
+    this._lock = null;
+    this.jsonb = db.options.jsonb;
+    this._schema = null;
+    this._validateOnInsert = true;
+    this._validateOnUpdate = false;
+
+    // 内存缓存优化
+    this._cache = null;
+    this._cacheTime = 0;
+    this._cacheTTL = db.options.cacheTTL || 5000;
+    this._dirty = false;
+  }
+
+  /**
+   * 设置 Schema
+   */
+  setSchema(schema: Schema, options: { validateOnInsert?: boolean; validateOnUpdate?: boolean } = {}): Collection {
+    this._schema = schema;
+    this._validateOnInsert = options.validateOnInsert !== false;
+    this._validateOnUpdate = options.validateOnUpdate || false;
+    return this;
+  }
+
+  /**
+   * 获取 Schema
+   */
+  getSchema(): Schema | null {
+    return this._schema;
+  }
+
+  /**
+   * 验证文档
+   */
+  _validate(doc: Record<string, unknown>): void {
+    if (!this._schema) {
+      return;
+    }
+
+    const result = this._schema.validate(doc);
+    if (!result.valid) {
+      throw new ValidationError(`验证失败：${result.errors!.map(e => `${e.field}: ${e.message}`).join(', ')}`);
+    }
+  }
+
+  /**
+   * 加载集合数据（带缓存）
+   */
+  async _load(): Promise<void> {
+    if (this._data !== null) {
+      return;
+    }
+
+    // 检查内存缓存
+    const now = Date.now();
+    if (this._cache && (now - this._cacheTime) < this._cacheTTL) {
+      this._data = this._cache;
+      return;
+    }
+
+    // 等待锁
+    await this._acquireLock();
+
+    try {
+      if (!existsSync(this._filePath)) {
+        // 如果集合文件不存在，自动创建
+        this._data = {
+          _meta: { name: this.name, count: 0, indexes: [] },
+          _documents: [],
+          _indexes: {}
+        };
+        await this._save();
+        return;
+      }
+
+      // JSONB 模式：读取二进制文件
+      if (this.jsonb) {
+        const buffer = await readFile(this._filePath);
+        this._data = this._decodeJsonb(buffer);
+      } else {
+        // 普通模式：读取文本文件
+        const content = await readFile(this._filePath, 'utf-8');
+        this._data = JSON.parse(content) as CollectionData;
+      }
+
+      // 确保数据结构完整
+      if (!this._data._meta) {
+        this._data._meta = { name: this.name, count: 0, indexes: [] };
+      }
+      if (!this._data._documents) {
+        this._data._documents = [];
+      }
+      if (!this._data._indexes) {
+        this._data._indexes = {};
+      }
+
+      // 更新缓存
+      this._cache = this._data;
+      this._cacheTime = now;
+    } finally {
+      this._releaseLock();
+    }
+  }
+
+  /**
+   * 保存集合数据（带缓存失效）
+   */
+  async _save(): Promise<void> {
+    if (this._data === null) {
+      return;
+    }
+
+    // 标记为脏数据
+    this._dirty = true;
+
+    // 更新元数据
+    this._data._meta.count = this._data._documents.length;
+
+    // 失效缓存
+    this._cache = null;
+    this._cacheTime = 0;
+
+    // JSONB 模式：写入二进制文件
+    if (this.jsonb) {
+      const buffer = this._encodeJsonb();
+      await writeFile(this._filePath, buffer);
+    } else {
+      // 普通模式：写入格式化的 JSON 文本
+      const content = JSON.stringify(this._data, null, 2);
+      await writeFile(this._filePath, content, 'utf-8');
+    }
+  }
+
+  /**
+   * JSONB 编码 - 将数据编码为二进制 Buffer
+   */
+  _encodeJsonb(): Buffer {
+    const json = JSON.stringify(this._data);
+    const jsonBuffer = Buffer.from(json, 'utf-8');
+
+    // 创建包含长度前缀的 Buffer
+    // 4 字节 (uint32) 长度 + JSON 数据
+    const lengthBuffer = Buffer.alloc(4);
+    lengthBuffer.writeUInt32BE(jsonBuffer.length, 0);
+
+    return Buffer.concat([lengthBuffer, jsonBuffer]);
+  }
+
+  /**
+   * JSONB 解码 - 将二进制 Buffer 解码为数据
+   */
+  _decodeJsonb(buffer: Buffer): CollectionData {
+    try {
+      // 读取长度前缀
+      const length = buffer.readUInt32BE(0);
+
+      // 验证长度
+      if (length !== buffer.length - 4) {
+        throw new Error('JSONB 长度不匹配');
+      }
+
+      // 读取 JSON 数据
+      const jsonBuffer = buffer.subarray(4);
+      const json = jsonBuffer.toString('utf-8');
+      return JSON.parse(json) as CollectionData;
+    } catch (e) {
+      // 如果不是有效的 JSONB 格式，尝试直接 JSON 解析（向后兼容）
+      try {
+        const json = buffer.toString('utf-8');
+        return JSON.parse(json) as CollectionData;
+      } catch (e2) {
+        throw new Error(`无法解析数据：${(e as Error).message}`);
+      }
+    }
+  }
+
+  /**
+   * 获取锁
+   */
+  async _acquireLock(): Promise<void> {
+    while (this._lock) {
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+    this._lock = true;
+  }
+
+  /**
+   * 释放锁
+   */
+  _releaseLock(): void {
+    this._lock = null;
+  }
+
+  /**
+   * 获取所有文档
+   */
+  async _getDocuments(): Promise<Array<Record<string, unknown>>> {
+    await this._load();
+    return this._data!._documents;
+  }
+
+  /**
+   * 插入单个文档
+   */
+  async insertOne(doc: Record<string, unknown>): Promise<Record<string, unknown>> {
+    await this._load();
+
+    // Schema 验证
+    if (this._validateOnInsert) {
+      this._validate(doc);
+    }
+
+    // 创建文档副本并添加 _id
+    const newDoc: Record<string, unknown> = {
+      ...deepClone(doc),
+      _id: (doc as Record<string, unknown>)._id || generateId(),
+      createdAt: new Date().toISOString()
+    };
+
+    this._data!._documents.push(newDoc);
+    await this._save();
+
+    return deepClone(newDoc);
+  }
+
+  /**
+   * 插入多个文档（优化版 - 单次写入）
+   */
+  async insertMany(
+    docs: Array<Record<string, unknown>>,
+    options: Record<string, unknown> = {}
+  ): Promise<{
+    acknowledged: boolean;
+    insertedCount: number;
+    insertedIds: Record<number, string>;
+  }> {
+    if (!Array.isArray(docs)) {
+      throw new Error('insertMany 需要数组参数');
+    }
+
+    await this._load();
+
+    // 批量验证
+    if (this._validateOnInsert) {
+      for (const doc of docs) {
+        this._validate(doc);
+      }
+    }
+
+    // 批量创建文档（带 _id 和 createdAt）
+    const now = new Date().toISOString();
+    const insertedDocs = docs.map(doc => ({
+      ...deepClone(doc),
+      _id: doc._id || generateId(),
+      createdAt: doc.createdAt || now
+    }));
+
+    // 单次批量添加
+    this._data!._documents.push(...insertedDocs);
+
+    // 更新索引（如果有）
+    if (this._data!._meta.indexes?.length > 0) {
+      await this._updateIndexes(insertedDocs, 'insert');
+    }
+
+    // 单次保存
+    await this._save();
+
+    // 失效缓存
+    this._cache = null;
+    this._cacheTime = 0;
+
+    return {
+      acknowledged: true,
+      insertedCount: insertedDocs.length,
+      insertedIds: insertedDocs.reduce((acc: Record<number, string>, doc, i) => {
+        acc[i] = doc._id as string;
+        return acc;
+      }, {})
+    };
+  }
+
+  /**
+   * 更新索引
+   */
+  private async _updateIndexes(
+    docs: Array<Record<string, unknown>>,
+    operation: 'insert' | 'update' | 'delete'
+  ): Promise<void> {
+    // 简化版本：重建所有索引
+    for (const index of this._data!._meta.indexes) {
+      await this._buildIndex(index);
+    }
+  }
+
+  /**
+   * 查询文档
+   */
+  find(query: Record<string, unknown> = {}, options: Record<string, unknown> = {}): Cursor {
+    return new Cursor(this, query, options);
+  }
+
+  /**
+   * 查询单个文档
+   */
+  async findOne(query: Record<string, unknown> = {}, options: Record<string, unknown> = {}): Promise<Record<string, unknown> | null> {
+    return await new Cursor(this, query, options).first();
+  }
+
+  /**
+   * 更新单个文档
+   */
+  async updateOne(
+    query: Record<string, unknown>,
+    update: Record<string, unknown>,
+    options: { upsert?: boolean } = {}
+  ): Promise<{
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId?: string;
+  }> {
+    await this._load();
+
+    const docIndex = this._data!._documents.findIndex(doc => matchQuery(doc, query));
+
+    if (docIndex === -1) {
+      if (options.upsert) {
+        // 插入新文档
+        const newDoc: Record<string, unknown> = {
+          _id: generateId(),
+          ...deepClone(query),
+          ...deepClone(update)
+        };
+        this._data!._documents.push(newDoc);
+        await this._save();
+
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: newDoc._id as string
+        };
+      }
+
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0
+      };
+    }
+
+    // 应用更新
+    const updatedDoc = applyUpdate(this._data!._documents[docIndex], update) as Record<string, unknown>;
+    updatedDoc.updatedAt = new Date().toISOString();
+    this._data!._documents[docIndex] = updatedDoc;
+
+    await this._save();
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1
+    };
+  }
+
+  /**
+   * 更新多个文档
+   */
+  async updateMany(
+    query: Record<string, unknown>,
+    update: Record<string, unknown>,
+    options: { upsert?: boolean } = {}
+  ): Promise<{
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId?: string;
+  }> {
+    await this._load();
+
+    let matchedCount = 0;
+    let modifiedCount = 0;
+
+    for (let i = 0; i < this._data!._documents.length; i++) {
+      const doc = this._data!._documents[i];
+
+      if (matchQuery(doc, query)) {
+        matchedCount++;
+        const updatedDoc = applyUpdate(doc, update) as Record<string, unknown>;
+        updatedDoc.updatedAt = new Date().toISOString();
+
+        if (JSON.stringify(doc) !== JSON.stringify(updatedDoc)) {
+          modifiedCount++;
+          this._data!._documents[i] = updatedDoc;
+        }
+      }
+    }
+
+    if (matchedCount === 0 && options.upsert) {
+      // 插入新文档
+      const newDoc: Record<string, unknown> = {
+        _id: generateId(),
+        ...deepClone(query),
+        ...deepClone(update)
+      };
+      this._data!._documents.push(newDoc);
+      await this._save();
+
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0,
+        upsertedId: newDoc._id as string
+      };
+    }
+
+    await this._save();
+
+    return {
+      acknowledged: true,
+      matchedCount,
+      modifiedCount
+    };
+  }
+
+  /**
+   * 替换单个文档
+   */
+  async replaceOne(
+    query: Record<string, unknown>,
+    doc: Record<string, unknown>,
+    options: { upsert?: boolean } = {}
+  ): Promise<{
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId?: string;
+  }> {
+    await this._load();
+
+    const docIndex = this._data!._documents.findIndex(d => matchQuery(d, query));
+
+    if (docIndex === -1) {
+      if (options.upsert) {
+        const newDoc: Record<string, unknown> = {
+          ...deepClone(doc),
+          _id: generateId(),
+          createdAt: new Date().toISOString()
+        };
+        this._data!._documents.push(newDoc);
+        await this._save();
+
+        return {
+          acknowledged: true,
+          matchedCount: 0,
+          modifiedCount: 0,
+          upsertedId: newDoc._id as string
+        };
+      }
+
+      return {
+        acknowledged: true,
+        matchedCount: 0,
+        modifiedCount: 0
+      };
+    }
+
+    // 保留 _id，替换其他字段
+    const oldId = this._data!._documents[docIndex]._id;
+    const newDoc: Record<string, unknown> = {
+      ...deepClone(doc),
+      _id: oldId,
+      updatedAt: new Date().toISOString()
+    };
+
+    this._data!._documents[docIndex] = newDoc;
+    await this._save();
+
+    return {
+      acknowledged: true,
+      matchedCount: 1,
+      modifiedCount: 1
+    };
+  }
+
+  /**
+   * 删除单个文档
+   */
+  async deleteOne(query: Record<string, unknown>): Promise<{ acknowledged: boolean; deletedCount: number }> {
+    await this._load();
+
+    const docIndex = this._data!._documents.findIndex(doc => matchQuery(doc, query));
+
+    if (docIndex === -1) {
+      return {
+        acknowledged: true,
+        deletedCount: 0
+      };
+    }
+
+    this._data!._documents.splice(docIndex, 1);
+    await this._save();
+
+    return {
+      acknowledged: true,
+      deletedCount: 1
+    };
+  }
+
+  /**
+   * 删除多个文档
+   */
+  async deleteMany(query: Record<string, unknown>): Promise<{ acknowledged: boolean; deletedCount: number }> {
+    await this._load();
+
+    const initialCount = this._data!._documents.length;
+    this._data!._documents = this._data!._documents.filter(doc => !matchQuery(doc, query));
+    const deletedCount = initialCount - this._data!._documents.length;
+
+    await this._save();
+
+    return {
+      acknowledged: true,
+      deletedCount
+    };
+  }
+
+  /**
+   * 计数文档
+   */
+  async countDocuments(query: Record<string, unknown> = {}): Promise<number> {
+    return await this.find(query).count();
+  }
+
+  /**
+   * 获取不同值
+   */
+  async distinct(key: string, query: Record<string, unknown> = {}): Promise<unknown[]> {
+    const docs = await this.find(query).toArray();
+    const values = new Set<unknown>();
+
+    for (const doc of docs) {
+      const value = getNestedValue(doc, key);
+      if (value !== undefined) {
+        values.add(value);
+      }
+    }
+
+    return Array.from(values);
+  }
+
+  /**
+   * 聚合查询
+   */
+  async aggregate(pipeline: Array<Record<string, unknown>>): Promise<Array<Record<string, unknown>>> {
+    await this._load();
+
+    let results = this._data!._documents.map(doc => deepClone(doc));
+
+    for (const stage of pipeline) {
+      const stageName = Object.keys(stage)[0];
+      const stageValue = stage[stageName];
+
+      results = this._applyAggregationStage(results, stageName, stageValue);
+    }
+
+    return results;
+  }
+
+  /**
+   * 应用聚合阶段
+   */
+  private _applyAggregationStage(
+    docs: Array<Record<string, unknown>>,
+    stageName: string,
+    stageValue: unknown
+  ): Array<Record<string, unknown>> {
+    switch (stageName) {
+      case '$match':
+        return docs.filter(doc => matchQuery(doc, stageValue as Record<string, unknown>));
+
+      case '$project':
+        return docs.map(doc => {
+          const result: Record<string, unknown> = {};
+          for (const [key, value] of Object.entries(stageValue as Record<string, unknown>)) {
+            if (typeof value === 'string' && value.startsWith('$')) {
+              result[key] = getNestedValue(doc, value.substring(1));
+            } else if (value === 0 || value === false) {
+              // 排除字段
+            } else {
+              result[key] = getNestedValue(doc, key);
+            }
+          }
+          if ((stageValue as Record<string, unknown>)._id !== undefined) {
+            result._id = (stageValue as Record<string, unknown>)._id === 0 ? undefined : doc._id;
+          } else {
+            result._id = doc._id;
+          }
+          return result;
+        });
+
+      case '$group':
+        return this._applyGroup(docs, stageValue as Record<string, unknown>);
+
+      case '$sort':
+        return docs.sort((a, b) => {
+          for (const [key, direction] of Object.entries(stageValue as Record<string, number>)) {
+            const aVal = getNestedValue(a, key);
+            const bVal = getNestedValue(b, key);
+            if (aVal < bVal) return -1 * direction;
+            if (aVal > bVal) return 1 * direction;
+          }
+          return 0;
+        });
+
+      case '$limit':
+        return docs.slice(0, stageValue as number);
+
+      case '$skip':
+        return docs.slice(stageValue as number);
+
+      case '$count':
+        return [{ [stageValue as string]: docs.length }];
+
+      default:
+        console.warn(`未实现的聚合阶段：${stageName}`);
+        return docs;
+    }
+  }
+
+  /**
+   * 应用分组
+   */
+  private _applyGroup(
+    docs: Array<Record<string, unknown>>,
+    stageValue: Record<string, unknown>
+  ): Array<Record<string, unknown>> {
+    const groups = new Map<unknown, Array<Record<string, unknown>>>();
+
+    for (const doc of docs) {
+      let key: unknown;
+      if (stageValue._id === null) {
+        key = null;
+      } else if (typeof stageValue._id === 'string') {
+        key = getNestedValue(doc, stageValue._id.substring(1));
+      } else {
+        key = JSON.stringify(stageValue._id);
+      }
+
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key)!.push(doc);
+    }
+
+    return Array.from(groups.entries()).map(([key, groupDocs]) => {
+      const result: Record<string, unknown> = { _id: key };
+
+      for (const [aggKey, aggExpr] of Object.entries(stageValue)) {
+        if (aggKey === '_id') continue;
+
+        if (typeof aggExpr === 'object' && aggExpr !== null) {
+          const aggOp = Object.keys(aggExpr)[0];
+          const aggField = aggExpr[aggOp] as string;
+
+          if (aggOp === '$sum') {
+            result[aggKey] = groupDocs.reduce((sum, d) => {
+              const val = getNestedValue(d, aggField.substring(1)) as number || 0;
+              return sum + val;
+            }, 0);
+          } else if (aggOp === '$avg') {
+            result[aggKey] = groupDocs.reduce((sum, d) => {
+              const val = getNestedValue(d, aggField.substring(1)) as number || 0;
+              return sum + val;
+            }, 0) / groupDocs.length;
+          } else if (aggOp === '$count') {
+            result[aggKey] = groupDocs.length;
+          } else if (aggOp === '$min') {
+            result[aggKey] = Math.min(...groupDocs.map(d => getNestedValue(d, aggField.substring(1)) as number || 0));
+          } else if (aggOp === '$max') {
+            result[aggKey] = Math.max(...groupDocs.map(d => getNestedValue(d, aggField.substring(1)) as number || 0));
+          }
+        }
+      }
+
+      return result;
+    });
+  }
+
+  /**
+   * 创建索引
+   */
+  async createIndex(keys: Record<string, number>, options: { unique?: boolean } = {}): Promise<IndexInfo> {
+    await this._load();
+
+    const indexName = Object.entries(keys)
+      .map(([k, v]) => `${k}_${v}`)
+      .join('_');
+
+    // 检查索引是否已存在
+    const existingIndex = this._data!._meta.indexes?.find(i => i.name === indexName);
+    if (existingIndex) {
+      return existingIndex;
+    }
+
+    // 创建索引
+    const index: IndexInfo = {
+      key: keys,
+      name: indexName,
+      unique: options.unique || false
+    };
+
+    if (!this._data!._meta.indexes) {
+      this._data!._meta.indexes = [];
+    }
+    this._data!._meta.indexes.push(index);
+
+    // 构建索引数据
+    await this._buildIndex(index);
+
+    await this._save();
+
+    return index;
+  }
+
+  /**
+   * 构建索引数据
+   */
+  private async _buildIndex(index: IndexInfo): Promise<void> {
+    const indexKeys = Object.keys(index.key);
+    const indexData: Record<string, string[]> = {};
+
+    for (const doc of this._data!._documents) {
+      for (const key of indexKeys) {
+        const value = getNestedValue(doc, key);
+        if (value !== undefined) {
+          const keyStr = String(value);
+          if (!indexData[keyStr]) {
+            indexData[keyStr] = [];
+          }
+          indexData[keyStr].push(doc._id as string);
+        }
+      }
+    }
+
+    if (!this._data!._indexes) {
+      this._data!._indexes = {};
+    }
+    this._data!._indexes[index.name] = indexData;
+  }
+
+  /**
+   * 删除索引
+   */
+  async dropIndex(name: string): Promise<{ acknowledged: boolean }> {
+    await this._load();
+
+    if (!this._data!._meta.indexes) {
+      return { acknowledged: false };
+    }
+
+    const initialLength = this._data!._meta.indexes.length;
+    this._data!._meta.indexes = this._data!._meta.indexes.filter(i => i.name !== name);
+
+    if (this._data!._meta.indexes.length === initialLength) {
+      return { acknowledged: false };
+    }
+
+    await this._save();
+
+    return { acknowledged: true };
+  }
+
+  /**
+   * 列出所有索引
+   */
+  async listIndexes(): Promise<IndexInfo[]> {
+    await this._load();
+    return this._data!._meta.indexes || [];
+  }
+
+  /**
+   * 获取集合统计信息
+   */
+  async stats(): Promise<CollectionStats> {
+    await this._load();
+
+    const size = this.jsonb
+      ? this._encodeJsonb().length
+      : JSON.stringify(this._data).length;
+
+    return {
+      ns: this.name,
+      count: this._data!._documents.length,
+      size,
+      avgObjSize: this._data!._documents.length > 0
+        ? size / this._data!._documents.length
+        : 0,
+      indexes: this._data!._meta.indexes?.length || 0,
+      jsonb: this.jsonb
+    };
+  }
+
+  /**
+   * 执行 SQL 语句
+   * @param sql - SQL 语句
+   * @returns SQL 执行结果
+   */
+  async sql(sqlStr: string): Promise<SQLExecutionResult> {
+    return await executeSQL(this, sqlStr);
+  }
+}