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,202 @@
+/**
+ * metona-sqlark Constants — 类型定义 / 默认配置 / 枚举
+ * @module constants
+ */
+
+// ---------------------------------------------------------------------------
+//  存储模式
+// ---------------------------------------------------------------------------
+
+/** 存储模式 */
+export type StorageMode = 'memory' | 'disk' | 'hybrid';
+
+/** 磁盘引擎类型 */
+export type DiskEngine = 'indexeddb' | 'opfs';
+
+/** 所有存储模式 */
+export const STORAGE_MODES: StorageMode[] = ['memory', 'disk', 'hybrid'];
+
+/** 所有磁盘引擎 */
+export const DISK_ENGINES: DiskEngine[] = ['indexeddb', 'opfs'];
+
+// ---------------------------------------------------------------------------
+//  字段类型
+// ---------------------------------------------------------------------------
+
+/** 字段数据类型 */
+export type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'json';
+
+/** 所有字段类型 */
+export const FIELD_TYPES: FieldType[] = ['string', 'number', 'boolean', 'date', 'json'];
+
+// ---------------------------------------------------------------------------
+//  列定义 & 表结构
+// ---------------------------------------------------------------------------
+
+/** 列定义 */
+export interface ColumnDef {
+  /** 字段类型 */
+  type: FieldType;
+  /** 是否主键 */
+  primaryKey?: boolean;
+  /** 是否必填 */
+  required?: boolean;
+  /** 是否唯一 */
+  unique?: boolean;
+  /** 默认值 */
+  default?: unknown;
+  /** 是否创建索引 */
+  index?: boolean;
+  /** 外键引用: 'table.column' */
+  references?: string;
+  /** 字符串最大长度 */
+  maxLength?: number;
+  /** 数字最小值 */
+  min?: number;
+  /** 数字最大值 */
+  max?: number;
+}
+
+/** 表结构定义 */
+export interface TableSchema {
+  /** 表名 */
+  name: string;
+  /** 列定义映射 */
+  columns: Record<string, ColumnDef>;
+}
+
+// ---------------------------------------------------------------------------
+//  数据库配置
+// ---------------------------------------------------------------------------
+
+/** 数据库配置 */
+export interface DatabaseConfig {
+  /** 数据库名称 */
+  name: string;
+  /** 存储模式 */
+  mode?: StorageMode;
+  /** 磁盘引擎（仅 mode='disk'|'hybrid' 时生效） */
+  diskEngine?: DiskEngine;
+  /** 版本号 */
+  version?: number;
+  /** 插件列表 */
+  plugins?: MetonaPlugin[];
+  /** 数据库就绪回调 */
+  onReady?: (db: unknown) => void;
+  /** 错误回调 */
+  onError?: (error: Error) => void;
+}
+
+/** 数据库默认配置 */
+export const DB_DEFAULTS: Readonly<Required<Omit<DatabaseConfig, 'plugins' | 'onReady' | 'onError'>>> = Object.freeze({
+  name: 'metona-sqlark',
+  mode: 'hybrid' as const,
+  diskEngine: 'indexeddb' as const,
+  version: 1,
+});
+
+// ---------------------------------------------------------------------------
+//  Where 操作符
+// ---------------------------------------------------------------------------
+
+/** Where 条件操作符 */
+export type WhereOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$like' | '$and' | '$or' | '$not';
+
+/** 简单条件值：直接相等 */
+export type SimpleCondition = unknown;
+
+/** 操作符条件 */
+export type OperatorCondition = Partial<Record<WhereOperator, unknown>>;
+
+/** 字段条件：简单值 | 操作符对象 */
+export type FieldCondition = SimpleCondition | OperatorCondition;
+
+/** Where 条件对象 */
+export type WhereCondition = Record<string, FieldCondition>;
+
+// ---------------------------------------------------------------------------
+//  排序
+// ---------------------------------------------------------------------------
+
+/** 排序方向 */
+export type SortDirection = 'asc' | 'desc';
+
+/** 排序定义 */
+export interface OrderBy {
+  /** 列名 */
+  column: string;
+  /** 排序方向 */
+  direction: SortDirection;
+}
+
+// ---------------------------------------------------------------------------
+//  查询计划（引擎层使用）
+// ---------------------------------------------------------------------------
+
+/** 查询计划 — 由 Executor 编译 AST 后生成 */
+export interface QueryPlan {
+  /** 表名 */
+  table: string;
+  /** 要返回的列（undefined = 全部，['*'] = 全部） */
+  columns?: string[];
+  /** 过滤条件 */
+  where?: WhereCondition;
+  /** 排序 */
+  orderBy?: OrderBy[];
+  /** 限制条数 */
+  limit?: number;
+  /** 偏移量 */
+  offset?: number;
+}
+
+// ---------------------------------------------------------------------------
+//  插件接口
+// ---------------------------------------------------------------------------
+
+/** 钩子名称 */
+export type HookName =
+  | 'beforeCreateTable' | 'afterCreateTable'
+  | 'beforeDropTable' | 'afterDropTable'
+  | 'beforeInsert' | 'afterInsert'
+  | 'beforeUpdate' | 'afterUpdate'
+  | 'beforeDelete' | 'afterDelete'
+  | 'beforeQuery' | 'afterQuery'
+  | 'beforeTransaction' | 'afterTransaction';
+
+/** 插件定义 */
+export interface MetonaPlugin {
+  /** 插件名称 */
+  name: string;
+  /** 插件版本 */
+  version: string;
+  /** 描述 */
+  description?: string;
+  /** 优先级，越大越先执行 */
+  priority?: number;
+  /** 安装 */
+  install(db: unknown): void;
+  /** 销毁 */
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+//  错误类型
+// ---------------------------------------------------------------------------
+
+/** 数据库错误 */
+export class DatabaseError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = 'DatabaseError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  版本
+// ---------------------------------------------------------------------------
+
+export const VERSION = '0.1.12';