feat: metona-sqlark v0.1.12 — 前端TypeScript关系型数据库

- 4种存储引擎：Memory / IndexedDB / OPFS / Hybrid - 完整SQL支持：SELECT/INSERT/UPDATE/DELETE/JOIN/GROUP BY/HAVING/DISTINCT - Query Builder链式API + TypeScript泛型支持 - 聚合函数：COUNT/SUM/AVG/MIN/MAX - 事务、插件系统(14 hooks)、发布订阅、数据迁移、导入导出 - React/Vue框架集成 - 264个测试用例，93.46%覆盖率 - 零运行时依赖
2026-07-26 15:00:01 +08:00
commit e2a590c5b1
60 changed files with 16359 additions and 0 deletions
@@ -0,0 +1,215 @@
+/**
+ * metona-sqlark Memory Engine — 基于 Map 的内存存储引擎
+ * @module engine/memory
+ */
+
+import type { IStorageEngine } from './interface';
+import type { QueryPlan, TableSchema } from '../constants';
+import { DatabaseError } from '../constants';
+import { matchWhere, applyOrderBy, projectColumns } from '../query/where-matcher';
+
+export class MemoryEngine implements IStorageEngine {
+  readonly name = 'memory';
+
+  private tables: Map<string, Map<string, Record<string, unknown>>> = new Map();
+  private schemas: Map<string, TableSchema> = new Map();
+  private indexes: Map<string, Map<string, Map<unknown, Set<string>>>> = new Map();
+  private opened = false;
+
+  // ---- 生命周期 ----
+  async open(_dbName: string, _version: number): Promise<void> { this.opened = true; }
+  async close(): Promise<void> {
+    this.tables.clear(); this.schemas.clear(); this.indexes.clear(); this.opened = false;
+  }
+  isOpen(): boolean { return this.opened; }
+
+  // ---- 表管理 ----
+  async createTable(schema: TableSchema): Promise<void> {
+    if (this.schemas.has(schema.name)) throw new DatabaseError(`Table "${schema.name}" already exists`, 'TABLE_EXISTS');
+    this.schemas.set(schema.name, schema);
+    this.tables.set(schema.name, new Map());
+    const tableIndexes = new Map<string, Map<unknown, Set<string>>>();
+    for (const [colName, colDef] of Object.entries(schema.columns)) {
+      if (colDef.index || colDef.unique) tableIndexes.set(colName, new Map());
+    }
+    this.indexes.set(schema.name, tableIndexes);
+  }
+
+  async dropTable(tableName: string): Promise<void> {
+    this.ensureTable(tableName);
+    this.schemas.delete(tableName); this.tables.delete(tableName); this.indexes.delete(tableName);
+  }
+
+  async hasTable(tableName: string): Promise<boolean> { return this.schemas.has(tableName); }
+  async getTableNames(): Promise<string[]> { return Array.from(this.schemas.keys()); }
+  async getTableSchema(tableName: string): Promise<TableSchema | null> { return this.schemas.get(tableName) ?? null; }
+
+  // ---- CRUD ----
+  async insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]> {
+    this.ensureTable(tableName);
+    const schema = this.schemas.get(tableName)!;
+    const table = this.tables.get(tableName)!;
+    const pkColumn = this.getPrimaryKey(schema);
+    const pks: string[] = [];
+
+    for (const row of rows) {
+      const validatedRow = this.validateRow(schema, row);
+      const pkValue = String(validatedRow[pkColumn]);
+      if (table.has(pkValue)) throw new DatabaseError(`Duplicate primary key "${pkValue}" in table "${tableName}"`, 'DUPLICATE_KEY');
+      this.checkUniqueness(schema, validatedRow);
+      table.set(pkValue, validatedRow);
+      this.updateIndexes(tableName, validatedRow, pkValue);
+      pks.push(pkValue);
+    }
+    return pks;
+  }
+
+  async find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]> {
+    this.ensureTable(tableName);
+    const table = this.tables.get(tableName)!;
+    let results = this.tryIndexLookup(tableName, table, query);
+
+    if (query.where && Object.keys(query.where).length > 0) {
+      results = results.filter((row) => matchWhere(row, query.where!));
+    }
+    if (query.orderBy && query.orderBy.length > 0) {
+      results = applyOrderBy(results, query.orderBy);
+    }
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? results.length;
+    results = results.slice(offset, offset + limit);
+    if (query.columns && query.columns.length > 0 && query.columns[0] !== '*') {
+      results = results.map((row) => projectColumns(row, query.columns!));
+    }
+    return results;
+  }
+
+  async update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number> {
+    this.ensureTable(tableName);
+    const schema = this.schemas.get(tableName)!;
+    const table = this.tables.get(tableName)!;
+    let count = 0;
+    for (const [pk, row] of table) {
+      if (!query.where || Object.keys(query.where).length === 0 || matchWhere(row, query.where)) {
+        const updated = { ...row, ...updates };
+        this.validateRow(schema, updated);
+        table.set(pk, updated);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  async delete(tableName: string, query: QueryPlan): Promise<number> {
+    this.ensureTable(tableName);
+    const table = this.tables.get(tableName)!;
+    const toDelete: string[] = [];
+    for (const [pk, row] of table) {
+      if (!query.where || Object.keys(query.where).length === 0 || matchWhere(row, query.where)) {
+        toDelete.push(pk);
+      }
+    }
+    for (const pk of toDelete) table.delete(pk);
+    return toDelete.length;
+  }
+
+  async count(tableName: string, query?: QueryPlan): Promise<number> {
+    this.ensureTable(tableName);
+    const table = this.tables.get(tableName)!;
+    if (!query?.where || Object.keys(query.where).length === 0) return table.size;
+    let result = 0;
+    for (const row of table.values()) { if (matchWhere(row, query.where)) result++; }
+    return result;
+  }
+
+  async clear(tableName: string): Promise<void> {
+    this.ensureTable(tableName);
+    this.tables.get(tableName)!.clear();
+    const tableIndexes = this.indexes.get(tableName);
+    if (tableIndexes) for (const colIndex of tableIndexes.values()) colIndex.clear();
+  }
+
+  // ---- 内部辅助 ----
+  private ensureTable(tableName: string): void {
+    if (!this.tables.has(tableName)) throw new DatabaseError(`Table "${tableName}" does not exist`, 'TABLE_NOT_FOUND');
+  }
+
+  private getPrimaryKey(schema: TableSchema): string {
+    for (const [name, col] of Object.entries(schema.columns)) { if (col.primaryKey) return name; }
+    return Object.keys(schema.columns)[0];
+  }
+
+  private validateRow(schema: TableSchema, row: Record<string, unknown>): Record<string, unknown> {
+    const validated: Record<string, unknown> = {};
+    for (const [colName, colDef] of Object.entries(schema.columns)) {
+      let value = row[colName];
+      if (value === undefined && colDef.default !== undefined) value = colDef.default;
+      if (colDef.required && (value === undefined || value === null)) {
+        throw new DatabaseError(`Column "${colName}" is required in table "${schema.name}"`, 'VALIDATION_ERROR');
+      }
+      if (value !== undefined && value !== null) this.checkType(colName, colDef.type, value);
+      if (value !== undefined) validated[colName] = value;
+    }
+    return validated;
+  }
+
+  private checkType(colName: string, type: string, value: unknown): void {
+    const jsType = typeof value;
+    switch (type) {
+      case 'string': if (jsType !== 'string') throw new DatabaseError(`Column "${colName}" expects string, got ${jsType}`, 'TYPE_ERROR'); break;
+      case 'number': if (jsType !== 'number') throw new DatabaseError(`Column "${colName}" expects number, got ${jsType}`, 'TYPE_ERROR'); break;
+      case 'boolean': if (jsType !== 'boolean') throw new DatabaseError(`Column "${colName}" expects boolean, got ${jsType}`, 'TYPE_ERROR'); break;
+      case 'date': if (jsType !== 'string' || isNaN(Date.parse(value as string))) throw new DatabaseError(`Column "${colName}" expects valid date`, 'TYPE_ERROR'); break;
+      case 'json': if (jsType !== 'object') throw new DatabaseError(`Column "${colName}" expects object/array, got ${jsType}`, 'TYPE_ERROR'); break;
+    }
+  }
+
+  /** O(1) 唯一性检查：利用哈希索引 */
+  private checkUniqueness(schema: TableSchema, row: Record<string, unknown>): void {
+    const tableIndexes = this.indexes.get(schema.name);
+    if (!tableIndexes) return;
+    for (const [colName, colDef] of Object.entries(schema.columns)) {
+      if (!colDef.unique || row[colName] === undefined || row[colName] === null) continue;
+      const colIndex = tableIndexes.get(colName);
+      if (colIndex && colIndex.has(row[colName])) {
+        throw new DatabaseError(`Unique constraint violation on column "${colName}" in table "${schema.name}"`, 'UNIQUE_VIOLATION');
+      }
+    }
+  }
+
+  /** 索引查找 */
+  private tryIndexLookup(
+    tableName: string, table: Map<string, Record<string, unknown>>, query: QueryPlan,
+  ): Record<string, unknown>[] {
+    const tableIndexes = this.indexes.get(tableName);
+    if (!tableIndexes || !query.where) return Array.from(table.values());
+    for (const [col, condition] of Object.entries(query.where)) {
+      if (typeof condition !== 'object' || condition === null) {
+        const colIndex = tableIndexes.get(col);
+        if (colIndex) {
+          const pks = colIndex.get(condition);
+          if (pks) {
+            const result: Record<string, unknown>[] = [];
+            for (const pk of pks) { const r = table.get(pk); if (r) result.push(r); }
+            return result;
+          }
+          return [];
+        }
+      }
+    }
+    return Array.from(table.values());
+  }
+
+  /** 更新索引 */
+  private updateIndexes(tableName: string, row: Record<string, unknown>, pk: string): void {
+    const tableIndexes = this.indexes.get(tableName);
+    if (!tableIndexes) return;
+    for (const [colName, colIndex] of tableIndexes) {
+      const value = row[colName];
+      if (value !== undefined && value !== null) {
+        if (!colIndex.has(value)) colIndex.set(value, new Set());
+        colIndex.get(value)!.add(pk);
+      }
+    }
+  }
+}