1384 lines
50 KiB
TypeScript
1384 lines
50 KiB
TypeScript
/**
|
||
* metona-sqlark Constants — 类型定义 / 默认配置 / 枚举
|
||
* @module constants
|
||
*/
|
||
/** 存储模式 */
|
||
type StorageMode = 'memory' | 'disk' | 'hybrid' | 'aria';
|
||
/** 磁盘引擎类型 */
|
||
type DiskEngine = 'indexeddb' | 'opfs';
|
||
/** 字段数据类型 */
|
||
type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'json';
|
||
/** 列定义 */
|
||
interface ColumnDef {
|
||
/** 字段类型 */
|
||
type: FieldType;
|
||
/** 是否主键 */
|
||
primaryKey?: boolean;
|
||
/** 是否必填 */
|
||
required?: boolean;
|
||
/** 是否唯一 */
|
||
unique?: boolean;
|
||
/** 默认值 */
|
||
default?: unknown;
|
||
/** 是否创建索引 */
|
||
index?: boolean;
|
||
/** 外键引用: 'table.column' */
|
||
references?: string;
|
||
/** 删除级联: 'CASCADE' | 'SET NULL' | 'RESTRICT' */
|
||
onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
|
||
/** 更新级联: 'CASCADE' | 'SET NULL' | 'RESTRICT' */
|
||
onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
|
||
/** 字符串最大长度 */
|
||
maxLength?: number;
|
||
/** 数字最小值 */
|
||
min?: number;
|
||
/** 数字最大值 */
|
||
max?: number;
|
||
}
|
||
/** 表结构定义 */
|
||
interface TableSchema {
|
||
/** 表名 */
|
||
name: string;
|
||
/** 列定义映射 */
|
||
columns: Record<string, ColumnDef>;
|
||
}
|
||
/** 数据库配置 */
|
||
interface DatabaseConfig {
|
||
/** 数据库名称 */
|
||
name: string;
|
||
/** 存储模式 */
|
||
mode?: StorageMode;
|
||
/** 磁盘引擎（仅 mode='disk'|'hybrid' 时生效） */
|
||
diskEngine?: DiskEngine;
|
||
/** 版本号 */
|
||
version?: number;
|
||
/** 插件列表 */
|
||
plugins?: MetonaPlugin[];
|
||
/** 数据库就绪回调 */
|
||
onReady?: (db: unknown) => void;
|
||
/** 错误回调 */
|
||
onError?: (error: Error) => void;
|
||
/** 查询结果行数上限（默认 0，0 表示不限制） */
|
||
maxRowsPerQuery?: number;
|
||
/** 调试模式（启用后输出详细操作日志） */
|
||
debug?: boolean;
|
||
/** 多标签页同步（v0.3.2）：BroadcastChannel 广播表变更，其他标签页自动刷新 */
|
||
multiTabSync?: boolean;
|
||
}
|
||
/** Where 条件操作符 */
|
||
type WhereOperator = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$like' | '$and' | '$or' | '$not';
|
||
/** 简单条件值：直接相等 */
|
||
type SimpleCondition = unknown;
|
||
/** 操作符条件 */
|
||
type OperatorCondition = Partial<Record<WhereOperator, unknown>>;
|
||
/** 字段条件：简单值 | 操作符对象 */
|
||
type FieldCondition = SimpleCondition | OperatorCondition;
|
||
/** Where 条件对象 */
|
||
type WhereCondition = Record<string, FieldCondition>;
|
||
/** 排序方向 */
|
||
type SortDirection = 'asc' | 'desc';
|
||
/** 排序定义 */
|
||
interface OrderBy {
|
||
/** 列名 */
|
||
column: string;
|
||
/** 排序方向 */
|
||
direction: SortDirection;
|
||
/** v0.4.0: NULL 值排序位置（first 排最前 / last 排最后，默认同引擎行为） */
|
||
nulls?: 'first' | 'last';
|
||
}
|
||
/** 查询计划 — 由 Executor 编译 AST 后生成 */
|
||
interface QueryPlan {
|
||
/** 表名 */
|
||
table: string;
|
||
/** 要返回的列（undefined = 全部，['*'] = 全部） */
|
||
columns?: string[];
|
||
/** 过滤条件 */
|
||
where?: WhereCondition;
|
||
/** 排序 */
|
||
orderBy?: OrderBy[];
|
||
/** 限制条数 */
|
||
limit?: number;
|
||
/** 偏移量 */
|
||
offset?: number;
|
||
}
|
||
/** 钩子名称 */
|
||
type HookName = 'beforeCreateTable' | 'afterCreateTable' | 'beforeDropTable' | 'afterDropTable' | 'beforeInsert' | 'afterInsert' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete' | 'beforeQuery' | 'afterQuery' | 'beforeTransaction' | 'afterTransaction';
|
||
/** 插件定义 */
|
||
interface MetonaPlugin {
|
||
/** 插件名称 */
|
||
name: string;
|
||
/** 插件版本 */
|
||
version: string;
|
||
/** 描述 */
|
||
description?: string;
|
||
/** 优先级，越大越先执行 */
|
||
priority?: number;
|
||
/** 安装 */
|
||
install(db: unknown): void;
|
||
/** 销毁 */
|
||
destroy(): void;
|
||
}
|
||
declare const VERSION = "0.4.4";
|
||
|
||
/**
|
||
* metona-sqlark Plugin — 插件系统
|
||
* @module plugin
|
||
*
|
||
* 管理插件的注册、生命周期和钩子调度。
|
||
*/
|
||
|
||
type HookCallback = (...args: unknown[]) => void | Promise<void>;
|
||
declare class PluginManager {
|
||
private plugins;
|
||
private hooks;
|
||
/** 注册插件 */
|
||
register(plugin: MetonaPlugin, db?: unknown): void;
|
||
/** 卸载插件 */
|
||
unregister(pluginName: string): void;
|
||
/** 获取所有已注册插件 */
|
||
getPlugins(): MetonaPlugin[];
|
||
/** 添加钩子回调 */
|
||
on(hook: HookName, callback: HookCallback): void;
|
||
/** 移除钩子回调 */
|
||
off(hook: HookName, callback: HookCallback): void;
|
||
/** 触发钩子 */
|
||
trigger(hook: HookName, ...args: unknown[]): Promise<void>;
|
||
/** 销毁所有插件 */
|
||
destroy(): void;
|
||
}
|
||
|
||
interface IStorageEngine {
|
||
/** 引擎名称 */
|
||
readonly name: string;
|
||
/** 打开数据库 */
|
||
open(dbName: string, version: number): Promise<void>;
|
||
/** 关闭数据库 */
|
||
close(): Promise<void>;
|
||
/** 检查数据库是否已打开 */
|
||
isOpen(): boolean;
|
||
/** 创建表 */
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
/** 删除表 */
|
||
dropTable(tableName: string): Promise<void>;
|
||
/** 检查表是否存在 */
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
/** 获取所有表名 */
|
||
getTableNames(): Promise<string[]>;
|
||
/** 获取表结构 */
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
/** 插入行，返回主键值列表 */
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
/** 查询行 */
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
/** v0.4.0: 流式查询 — 逐行回调扫描（有 where/limit/projection，无 orderBy 语义；有 orderBy 时实现可回退物化） */
|
||
findStream?(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
/** 更新行，返回影响行数 */
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
/** 删除行，返回影响行数 */
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
/** 计数 */
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
/** 清空表数据（保留结构） */
|
||
clear(tableName: string): Promise<void>;
|
||
/** v0.4.1: ALTER TABLE（可选）— 引擎级结构变更（Aria 需重写存储行，其余引擎走 Executor 通用路径） */
|
||
alterTable?(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
/** 创建二级索引（CREATE INDEX） */
|
||
createIndex?(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
/** 删除二级索引（DROP INDEX） */
|
||
dropIndex?(tableName: string, column: string, indexName?: string): Promise<void>;
|
||
/** 开始事务 */
|
||
beginTransaction(): Promise<void>;
|
||
/** 提交事务 */
|
||
commitTransaction(): Promise<void>;
|
||
/** 回滚事务 */
|
||
rollbackTransaction(): Promise<void>;
|
||
/** 创建 Savepoint */
|
||
savepoint?(name: string): Promise<void>;
|
||
/** 回滚到 Savepoint */
|
||
rollbackToSavepoint?(name: string): Promise<void>;
|
||
/** 释放 Savepoint */
|
||
releaseSavepoint?(name: string): Promise<void>;
|
||
/** 在线备份：导出全库一致性快照 */
|
||
backup?(): Promise<Record<string, Record<string, unknown>[]>>;
|
||
/** 崩溃恢复自愈：校验并清理损坏数据、恢复一致性（检测到异常后调用，无需删库重建） */
|
||
repair?(): Promise<void>;
|
||
/** 清空全部数据与表结构（保留库本身，供演示页刷新/重建用） */
|
||
clearAll?(): Promise<void>;
|
||
/** 读取库内元数据（迁移版本持久化用） */
|
||
getMeta?(key: string): Promise<string | null>;
|
||
/** 写入库内元数据（迁移版本持久化用） */
|
||
setMeta?(key: string, value: string): Promise<void>;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark Query AST — 查询抽象语法树类型定义
|
||
* @module query/ast
|
||
*
|
||
* QueryBuilder 和 SQL Parser 统一输出此 AST，
|
||
* Executor 只认 AST，保证两种查询接口行为一致。
|
||
*/
|
||
|
||
/** 列引用，'*' 表示所有列；支持 'table.column' 格式 */
|
||
type ColumnRef = string;
|
||
/** JOIN 类型 */
|
||
type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'CROSS';
|
||
/** JOIN 子句 */
|
||
interface JoinClause {
|
||
type: JoinType;
|
||
table: string;
|
||
alias?: string;
|
||
on: WhereCondition;
|
||
}
|
||
interface ASTColumnDef {
|
||
name: string;
|
||
type: string;
|
||
primaryKey?: boolean;
|
||
unique?: boolean;
|
||
required?: boolean;
|
||
default?: unknown;
|
||
index?: boolean;
|
||
maxLength?: number;
|
||
min?: number;
|
||
max?: number;
|
||
/** 外键引用 */
|
||
references?: string;
|
||
/** 级联删除 */
|
||
onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
|
||
/** 级联更新 */
|
||
onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
|
||
}
|
||
interface CreateTableStatement {
|
||
type: 'CREATE_TABLE';
|
||
name: string;
|
||
columns: ASTColumnDef[];
|
||
/** IF NOT EXISTS — 表已存在时不报错 */
|
||
ifNotExists?: boolean;
|
||
}
|
||
interface DropTableStatement {
|
||
type: 'DROP_TABLE';
|
||
name: string;
|
||
/** IF EXISTS — 表不存在时不报错 */
|
||
ifExists?: boolean;
|
||
}
|
||
/** EXPLAIN 查询计划 */
|
||
interface ExplainStatement {
|
||
type: 'EXPLAIN';
|
||
query: Statement;
|
||
}
|
||
interface InsertStatement {
|
||
type: 'INSERT';
|
||
into: string;
|
||
columns?: string[];
|
||
/** VALUES 字面量 */
|
||
values?: unknown[][];
|
||
/** INSERT INTO ... SELECT ...（v0.3.0） */
|
||
select?: SelectStatement | SelectUnionStatement;
|
||
}
|
||
interface UpdateStatement {
|
||
type: 'UPDATE';
|
||
table: string;
|
||
sets: Record<string, unknown>;
|
||
where: WhereCondition;
|
||
}
|
||
interface DeleteStatement {
|
||
type: 'DELETE';
|
||
from: string;
|
||
where: WhereCondition;
|
||
}
|
||
interface SelectStatement {
|
||
type: 'SELECT';
|
||
columns: ColumnRef[];
|
||
distinct?: boolean;
|
||
from: string;
|
||
/** v0.4.0: FROM (SELECT ...) 派生表（存在时 from 为占位，行源取此子查询结果） */
|
||
fromSubquery?: SelectStatement | SelectUnionStatement;
|
||
/** 主表别名 */
|
||
alias?: string;
|
||
/** JOIN 子句列表 */
|
||
joins?: JoinClause[];
|
||
where: WhereCondition;
|
||
/** GROUP BY */
|
||
groupBy?: string[];
|
||
/** HAVING */
|
||
having?: WhereCondition;
|
||
orderBy?: OrderBy[];
|
||
limit?: number;
|
||
offset?: number;
|
||
}
|
||
interface SelectUnionStatement {
|
||
type: 'SELECT_UNION';
|
||
/** 左操作数（可以是 SELECT 或嵌套 UNION） */
|
||
left: SelectStatement | SelectUnionStatement;
|
||
/** 右操作数 */
|
||
right: SelectStatement | SelectUnionStatement;
|
||
/** UNION ALL 不去重 */
|
||
all?: boolean;
|
||
}
|
||
interface AlterTableStatement {
|
||
type: 'ALTER_TABLE';
|
||
name: string;
|
||
action: 'ADD' | 'DROP';
|
||
column: ASTColumnDef;
|
||
}
|
||
interface TruncateTableStatement {
|
||
type: 'TRUNCATE_TABLE';
|
||
name: string;
|
||
}
|
||
interface CreateIndexStatement {
|
||
type: 'CREATE_INDEX';
|
||
/** 索引名（语法占位） */
|
||
name: string;
|
||
table: string;
|
||
column: string;
|
||
/** UNIQUE 索引 */
|
||
unique?: boolean;
|
||
}
|
||
interface DropIndexStatement {
|
||
type: 'DROP_INDEX';
|
||
name: string;
|
||
table: string;
|
||
column: string;
|
||
}
|
||
interface BeginTransactionStatement {
|
||
type: 'BEGIN';
|
||
}
|
||
interface CommitTransactionStatement {
|
||
type: 'COMMIT';
|
||
}
|
||
interface RollbackTransactionStatement {
|
||
type: 'ROLLBACK';
|
||
}
|
||
type Statement = SelectStatement | SelectUnionStatement | ExplainStatement | InsertStatement | UpdateStatement | DeleteStatement | CreateTableStatement | DropTableStatement | AlterTableStatement | TruncateTableStatement | CreateIndexStatement | DropIndexStatement | BeginTransactionStatement | CommitTransactionStatement | RollbackTransactionStatement;
|
||
|
||
/**
|
||
* metona-sqlark Query Executor — AST 执行器
|
||
* @module query/executor
|
||
*
|
||
* JOIN / GROUP BY / DISTINCT 逻辑在此层处理。
|
||
*/
|
||
|
||
declare class QueryExecutor {
|
||
private engine;
|
||
private maxRowsPerQuery;
|
||
constructor(engine: IStorageEngine, maxRowsPerQuery?: number);
|
||
/** 设置查询结果行数上限 */
|
||
setMaxRowsPerQuery(max: number): void;
|
||
execute(stmt: Statement): Promise<unknown>;
|
||
/** 递归执行 UNION / UNION ALL，返回合并结果 */
|
||
private executeSelectUnion;
|
||
private executeSelectPart;
|
||
/** 将 UNION 右侧行投影为左侧列结构（按位置取值） */
|
||
private projectUnionRow;
|
||
/** EXPLAIN: 输出查询计划 */
|
||
private executeExplain;
|
||
private executeSelect;
|
||
private executeJoinSelect;
|
||
private prefixRow;
|
||
/**
|
||
* v0.4.1: 提取可下推的 WHERE 条件 — 主表别名前缀的普通条件（如 o.user_id = '1'）。
|
||
* 下推到引擎可走二级索引；$col/$subquery/$and/$or/$not 等复杂条件保守不下推。
|
||
*/
|
||
private extractPushableWhere;
|
||
/**
|
||
* 哈希连接（v0.3.2 单等值 / v0.4.0 多列等值）：
|
||
* ON 为等值条件（单列或多列）且右表任一列为索引/主键时，
|
||
* 收集左表连接值 → 一次 $in 查询右表 → 哈希映射匹配。
|
||
* 替代嵌套循环，大表 INNER/LEFT JOIN 复杂度 O(N + M)。
|
||
* 不适用时返回 null（回退嵌套循环）。
|
||
*/
|
||
private tryHashJoin;
|
||
/** 嵌套循环连接（优化：避免 ON 时对象扩散） */
|
||
private joinRows;
|
||
private executeGroupBy;
|
||
private computeAggregate;
|
||
private executeDistinct;
|
||
private executeInsert;
|
||
private executeUpdate;
|
||
private executeDelete;
|
||
private executeCreateTable;
|
||
private executeDropTable;
|
||
private executeAlterTable;
|
||
private executeTruncateTable;
|
||
private executeCreateIndex;
|
||
private executeDropIndex;
|
||
private executeBegin;
|
||
private executeCommit;
|
||
private executeRollback;
|
||
/** 列列表是否包含 CASE WHEN 表达式 */
|
||
private hasCaseColumn;
|
||
/**
|
||
* v0.3.3: ORDER BY 是否引用 SELECT 别名（如 `SELECT name AS n ... ORDER BY n`）。
|
||
* 别名列在引擎层投影前不存在，需投影后重新排序。
|
||
*/
|
||
private orderByUsesSelectAlias;
|
||
/** WHERE 是否包含 CASE WHEN 表达式键 */
|
||
private whereHasCase;
|
||
getEngine(): IStorageEngine;
|
||
/**
|
||
* 列投影（v0.3.1）：普通列走 projectColumns，CASE WHEN 表达式逐行求值；
|
||
* v0.3.3: 支持 `col AS alias` 列别名
|
||
*/
|
||
private projectRow;
|
||
/** 检查 SELECT 列列表中是否包含聚合函数 */
|
||
private _hasAggregateColumn;
|
||
/** 计算单行聚合结果（无 GROUP BY） */
|
||
private computeSingleAggregate;
|
||
/** 剥离主表别名前缀：'u.id' → 'id'（键与 $col 值均处理，支持多层别名） */
|
||
private normalizeWhereColumns;
|
||
private normalizeExistsValue;
|
||
private normalizeFieldValue;
|
||
private stripAlias;
|
||
/** WHERE 是否含关联引用（$col 或关联 EXISTS）或 CASE WHEN 表达式键 */
|
||
private hasCorrelatedRefs;
|
||
private fieldHasColRef;
|
||
/** 移除关联 EXISTS 标记（引擎层先执行无 EXISTS 条件的查询） */
|
||
private stripCorrelatedExists;
|
||
/** 逐行绑定外层行上下文，求值关联 EXISTS、$col 引用与 CASE WHEN 键 */
|
||
private filterCorrelated;
|
||
/** 将 WHERE 中的 CASE WHEN 表达式键求值为布尔条件（$caseResult） */
|
||
private resolveCaseKeys;
|
||
/** CASE 求值结果与操作符条件比较 */
|
||
private caseConditionMatches;
|
||
/** 将 where 中的 $col 引用替换为上下文行值 */
|
||
private bindColumnRefs;
|
||
private bindWhereRefs;
|
||
/**
|
||
* 递归扫描 WHERE 条件，找到 $subquery 标记并执行子查询，
|
||
* 将结果替换为具体值。
|
||
* @param contextRow 关联子查询的外层行上下文（用于绑定 $col 引用）
|
||
*/
|
||
private resolveSubqueries;
|
||
/**
|
||
* 解析操作符值中嵌套的子查询
|
||
*/
|
||
private resolveOperatorSubqueries;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark Query Builder — 链式查询构建器
|
||
* @module query/builder
|
||
*
|
||
* 链式调用 → 构建 AST → 执行引擎操作。
|
||
* 支持 JOIN（需要 Executor）。
|
||
*/
|
||
|
||
declare class SelectQueryBuilder {
|
||
private engine;
|
||
private tableName;
|
||
private _columns;
|
||
private _where;
|
||
private _orderBy;
|
||
private _limit?;
|
||
private _offset?;
|
||
private _joins;
|
||
private _alias?;
|
||
private _executor?;
|
||
constructor(engine: IStorageEngine, tableName: string, _columns?: string[], executor?: QueryExecutor);
|
||
/** 主表别名 */
|
||
as(alias: string): this;
|
||
/** INNER JOIN */
|
||
innerJoin(table: string, on: WhereCondition, alias?: string): this;
|
||
/** LEFT JOIN */
|
||
leftJoin(table: string, on: WhereCondition, alias?: string): this;
|
||
/** RIGHT JOIN */
|
||
rightJoin(table: string, on: WhereCondition, alias?: string): this;
|
||
/** CROSS JOIN */
|
||
crossJoin(table: string, alias?: string): this;
|
||
/** 通用 JOIN */
|
||
join(table: string, on: WhereCondition, alias?: string): this;
|
||
private _addJoin;
|
||
/** 添加过滤条件 */
|
||
where(condition: WhereCondition): this;
|
||
/** 排序 */
|
||
orderBy(column: string, direction?: SortDirection): this;
|
||
/** 限制返回条数 */
|
||
limit(n: number): this;
|
||
/** 偏移量 */
|
||
offset(n: number): this;
|
||
/** 执行查询 */
|
||
execute(): Promise<Record<string, unknown>[]>;
|
||
/** 获取 AST */
|
||
toAST(): SelectStatement;
|
||
}
|
||
declare class UpdateQueryBuilder {
|
||
private engine;
|
||
private tableName;
|
||
private _updates;
|
||
private _where;
|
||
private onWrite?;
|
||
constructor(engine: IStorageEngine, tableName: string, _updates: Record<string, unknown>, onWrite?: (table: string) => void);
|
||
where(condition: WhereCondition): this;
|
||
execute(): Promise<number>;
|
||
toAST(): UpdateStatement;
|
||
}
|
||
declare class DeleteQueryBuilder {
|
||
private engine;
|
||
private tableName;
|
||
private _where;
|
||
private onWrite?;
|
||
constructor(engine: IStorageEngine, tableName: string, onWrite?: (table: string) => void);
|
||
where(condition: WhereCondition): this;
|
||
execute(): Promise<number>;
|
||
toAST(): DeleteStatement;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark Table — 表操作 API
|
||
* @module table/table
|
||
*/
|
||
|
||
declare class Table<T = Record<string, unknown>> {
|
||
readonly name: string;
|
||
private engine;
|
||
private schema;
|
||
private executor;
|
||
/** 写入回调（多标签页广播，v0.3.2） */
|
||
private onWrite?;
|
||
constructor(engine: IStorageEngine, tableName: string, executor?: QueryExecutor, onWrite?: (table: string) => void);
|
||
getSchema(): Promise<TableSchema>;
|
||
insert(row: T & Record<string, unknown>): Promise<string>;
|
||
insertMany(rows: (T & Record<string, unknown>)[]): Promise<string[]>;
|
||
select(columns?: string[]): SelectQueryBuilder;
|
||
/** v0.4.0: 流式查询 — 逐行回调，不物化全部结果 */
|
||
stream(onRow: (row: T & Record<string, unknown>) => void, query?: {
|
||
where?: Record<string, unknown>;
|
||
limit?: number;
|
||
offset?: number;
|
||
columns?: string[];
|
||
}): Promise<number>;
|
||
update(updates: Partial<T> & Record<string, unknown>): UpdateQueryBuilder;
|
||
delete(): DeleteQueryBuilder;
|
||
count(where?: Record<string, unknown>): Promise<number>;
|
||
clear(): Promise<void>;
|
||
drop(): Promise<void>;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark Transaction — 事务管理
|
||
* @module transaction
|
||
*
|
||
* v0.1.13: 支持真正的回滚 — 利用引擎层 begin/commit/rollback 实现原子性。
|
||
*/
|
||
|
||
declare class Transaction {
|
||
private engine;
|
||
private tables;
|
||
private completed;
|
||
constructor(engine: IStorageEngine);
|
||
/** 获取表操作对象 */
|
||
table(tableName: string): Table;
|
||
/** 标记事务完成（由 TransactionManager 调用） */
|
||
_markCompleted(): void;
|
||
/** 是否已完成 */
|
||
isCompleted(): boolean;
|
||
}
|
||
|
||
declare class MetonaSqlark {
|
||
/** 数据库名称 */
|
||
readonly name: string;
|
||
/** 存储模式 */
|
||
readonly mode: string;
|
||
/** 版本号 */
|
||
private _version;
|
||
/** 获取版本号 */
|
||
get version(): number;
|
||
private engine;
|
||
private executor;
|
||
private transactionManager;
|
||
private pluginManager;
|
||
private config;
|
||
private ready;
|
||
private tableCache;
|
||
/** 查询结果行数上限 */
|
||
get maxRowsPerQuery(): number;
|
||
/** 调试模式 */
|
||
get debug(): boolean;
|
||
/** 多标签页同步通道（v0.3.2） */
|
||
private channel;
|
||
constructor(config: DatabaseConfig);
|
||
/** 初始化数据库（创建引擎、打开连接） */
|
||
init(): Promise<void>;
|
||
/** 检查是否就绪 */
|
||
isReady(): boolean;
|
||
/** 创建表 */
|
||
defineTable(name: string, columns: Record<string, ColumnDef>): Promise<void>;
|
||
/** 获取表操作对象 */
|
||
table(name: string): Table;
|
||
/** 删除表 */
|
||
dropTable(name: string): Promise<void>;
|
||
/** 获取所有表名 */
|
||
getTableNames(): Promise<string[]>;
|
||
/** 执行 SQL 字符串查询 */
|
||
query(sql: string): Promise<unknown>;
|
||
/**
|
||
* 流式查询：逐行回调，不一次性物化全部结果（大表友好）。
|
||
* 支持简单 SELECT（WHERE/LIMIT/OFFSET/列投影）；
|
||
* JOIN/GROUP BY/UNION/聚合/ORDER BY 自动回退为物化查询后逐行回调。
|
||
*
|
||
* @example
|
||
* ```ts
|
||
* let total = 0;
|
||
* await db.queryStream('SELECT * FROM logs WHERE level = \'error\'', (row) => {
|
||
* total++;
|
||
* processRow(row);
|
||
* });
|
||
* ```
|
||
*/
|
||
queryStream<T extends Record<string, unknown> = Record<string, unknown>>(sql: string, onRow: (row: T) => void): Promise<number>;
|
||
/** 流式查询用：剥离主表别名前缀（复用 query 路径的规范化逻辑） */
|
||
private normalizeWhereForStream;
|
||
/** 执行事务 */
|
||
transaction<T>(fn: (trx: Transaction) => Promise<T>): Promise<T>;
|
||
/** 导出表数据为 JSON */
|
||
exportTable(tableName: string): Promise<Record<string, unknown>[]>;
|
||
/** 导入 JSON 数据到表 */
|
||
importTable(tableName: string, data: Record<string, unknown>[]): Promise<string[]>;
|
||
/** 导出整个数据库为 JSON */
|
||
exportAll(): Promise<Record<string, Record<string, unknown>[]>>;
|
||
private listeners;
|
||
/** 订阅表变更 */
|
||
subscribe(tableName: string, callback: (event: {
|
||
type: string;
|
||
row?: unknown;
|
||
table?: string;
|
||
}) => void): () => void;
|
||
/** 触发变更事件 */
|
||
emit(tableName: string, event: {
|
||
type: string;
|
||
row?: unknown;
|
||
table?: string;
|
||
}): void;
|
||
/** 广播表变更到其他标签页（多标签页同步） */
|
||
broadcastChange(tableName: string): void;
|
||
/** 写语句对应的表名（多标签页广播用） */
|
||
private writeStatementTable;
|
||
private migrations;
|
||
/** 注册迁移 */
|
||
addMigration(version: number, up: (db: MetonaSqlark) => Promise<void>): void;
|
||
/** 执行迁移到指定版本 */
|
||
migrateTo(targetVersion: number): Promise<void>;
|
||
/**
|
||
* 崩溃恢复自愈 — 校验并清理损坏数据、恢复一致性。
|
||
* 检测到异常后调用，无需删库重建。
|
||
*/
|
||
repair(): Promise<void>;
|
||
/**
|
||
* 清空全部数据与表结构（保留库本身）。
|
||
* 支持后续继续使用本实例重建表。
|
||
*/
|
||
clearAll(): Promise<void>;
|
||
/** 获取插件管理器 */
|
||
getPluginManager(): PluginManager;
|
||
/** 注册钩子 */
|
||
on(hook: HookName, callback: HookCallback): void;
|
||
/** 关闭数据库 */
|
||
close(): Promise<void>;
|
||
/** 获取底层引擎 */
|
||
getEngine(): IStorageEngine;
|
||
private createEngine;
|
||
private ensureReady;
|
||
/** 错误回调分发 */
|
||
private _onError;
|
||
/** 调试日志 */
|
||
private _debug;
|
||
}
|
||
|
||
declare class MemoryEngine implements IStorageEngine {
|
||
readonly name = "memory";
|
||
private tables;
|
||
private schemas;
|
||
private indexes;
|
||
private opened;
|
||
/** v0.4.2-fix: 库内元数据（迁移版本持久化用） */
|
||
private metaStore;
|
||
private snapshot;
|
||
open(_dbName: string, _version: number): Promise<void>;
|
||
close(): Promise<void>;
|
||
isOpen(): boolean;
|
||
/** 内存引擎无需修复（无持久化损坏概念） */
|
||
repair(): Promise<void>;
|
||
/** 清空全部数据与表结构 */
|
||
clearAll(): Promise<void>;
|
||
getMeta(key: string): Promise<string | null>;
|
||
setMeta(key: string, value: string): Promise<void>;
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
dropTable(tableName: string): Promise<void>;
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
getTableNames(): Promise<string[]>;
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
/**
|
||
* v0.4.2-fix: 引擎级 ALTER TABLE — 直接修改内存 schema 引用并清理行数据。
|
||
* （此前走 executor 通用路径，行为相同；统一到引擎层保证 Hybrid/IndexedDB 委托一致性）
|
||
*/
|
||
alterTable(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
/** v0.4.0: 流式查询 — 逐行回调（单次迭代，不物化结果数组） */
|
||
findStream(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
/**
|
||
* v0.4.2-fix: ON UPDATE 外键级联 — 被引用表主键变更时处理引用表：
|
||
* RESTRICT 抛错 / CASCADE 更新 FK 值 / SET NULL 置空。
|
||
* 分两阶段：先全量 RESTRICT 检查（任何修改前），再执行级联（防部分修改）。
|
||
*/
|
||
private applyUpdateCascade;
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
clear(tableName: string): Promise<void>;
|
||
createIndex(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
dropIndex(tableName: string, column: string, _indexName?: string): Promise<void>;
|
||
beginTransaction(): Promise<void>;
|
||
commitTransaction(): Promise<void>;
|
||
rollbackTransaction(): Promise<void>;
|
||
private deepCloneMapMap;
|
||
private deepCloneIndexes;
|
||
private ensureTable;
|
||
private getPrimaryKey;
|
||
private validateRow;
|
||
private checkType;
|
||
/** O(1) 唯一性检查：利用哈希索引 */
|
||
private checkUniqueness;
|
||
/** 索引查找 */
|
||
private tryIndexLookup;
|
||
/** 更新索引 */
|
||
private updateIndexes;
|
||
/** v0.3.3: 从所有索引中移除一行的条目（update/delete 前调用，修复索引过期/残留） */
|
||
private removeIndexEntries;
|
||
/**
|
||
* 级联删除：查找引用 tableName.pkValue 的所有表的行并删除。
|
||
* @returns 级联删除的行数
|
||
*/
|
||
private cascadeDelete;
|
||
}
|
||
|
||
declare class IndexedDBEngine implements IStorageEngine {
|
||
readonly name = "indexeddb";
|
||
private db;
|
||
private dbName;
|
||
private version;
|
||
private memoryCache;
|
||
private txActive;
|
||
open(dbName: string, version: number): Promise<void>;
|
||
/** v0.4.2-fix: 多标签页冲突处理 — 其他标签页升级版本时自动关闭当前连接 */
|
||
private setupVersionChangeHandler;
|
||
/**
|
||
* v0.4.2-fix: 打开 IndexedDB 连接。
|
||
* - P0-2: 请求版本低于库实际版本（VersionError）时，先无版本参数探测库当前版本，
|
||
* 再以实际版本重开（建表每张表版本号 +1，config.version 会过期）
|
||
* - P2-8: onblocked 为瞬时状态（另一连接短暂持有），等待后重试多次，超时才抛 IDB_BLOCKED
|
||
*/
|
||
private openDatabaseWithRetry;
|
||
/**
|
||
* 发起一次 indexedDB.open 请求（success/error/blocked 三态收敛）。
|
||
* onblocked 不立即失败：阻塞解除后 success 仍会触发，仅超时兜底判失败，
|
||
* 避免"拒绝后连接迟到成功"泄漏未关闭的数据库连接。
|
||
*/
|
||
private openRequest;
|
||
/** 无版本参数打开库，解析其当前实际版本号（随后立即关闭） */
|
||
private resolveCurrentVersion;
|
||
/**
|
||
* v0.4.2-fix (P2-7): 确保 __metona_schema store 存在。
|
||
* 新库（或版本升级前创建的旧库）没有该 store 时，通过一次版本升级创建，
|
||
* 使 getMeta/setMeta（迁移版本持久化）始终可用。
|
||
*/
|
||
private ensureSchemaStore;
|
||
/**
|
||
* 从 IDB 恢复内存 schema：
|
||
* 1. 优先读取持久化的 schema 记录（'__metona_schema' store，v0.3.2）
|
||
* 2. 旧数据回退：从 objectStore 主键 / 索引 / 样例数据推断
|
||
*/
|
||
private rebuildSchemaFromIDB;
|
||
close(): Promise<void>;
|
||
/**
|
||
* v0.4.2-fix: 自愈 — 从磁盘重建内存 schema 与数据（schema 丢失/内存不一致时调用）。
|
||
* 无删库需求即可恢复可用的库。
|
||
*/
|
||
repair(): Promise<void>;
|
||
/**
|
||
* v0.4.2-fix: 清空全部数据与表结构（含持久化 schema 记录），保留库本身。
|
||
* 单个版本升级事务内原子完成。
|
||
*/
|
||
clearAll(): Promise<void>;
|
||
getMeta(key: string): Promise<string | null>;
|
||
setMeta(key: string, value: string): Promise<void>;
|
||
isOpen(): boolean;
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
dropTable(tableName: string): Promise<void>;
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
getTableNames(): Promise<string[]>;
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
/**
|
||
* v0.4.2-fix: 引擎级 ALTER TABLE — schema 持久化到 __metona_schema store，
|
||
* 重启后 ALTER 不丢失（此前通用路径只改内存引用，重启回退；DROP 的行数据也没真正删）。
|
||
*/
|
||
alterTable(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
/** v0.4.0: 流式查询 — IDB 批量读入后逐行回调（保持接口一致性） */
|
||
findStream(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
clear(tableName: string): Promise<void>;
|
||
createIndex(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
dropIndex(tableName: string, column: string, _indexName?: string): Promise<void>;
|
||
beginTransaction(): Promise<void>;
|
||
commitTransaction(): Promise<void>;
|
||
rollbackTransaction(): Promise<void>;
|
||
private idbCreateTable;
|
||
private idbDropTable;
|
||
private idbInsert;
|
||
private idbFind;
|
||
/** 尝试使用 IDB 索引进行等值查询，成功返回结果，不适用返回 null */
|
||
private tryIDBIndexLookup;
|
||
private idbUpdate;
|
||
private idbDelete;
|
||
private idbClear;
|
||
/** 持久化单个表 schema 到 __metona_schema store（v0.4.2-fix: ALTER TABLE 用） */
|
||
private persistSchema;
|
||
/** 将内存缓存中的所有表数据原子性刷新到 IndexedDB */
|
||
private flushToIDB;
|
||
private ensureDB;
|
||
}
|
||
|
||
declare class OPFSEngine implements IStorageEngine {
|
||
readonly name = "opfs";
|
||
private root;
|
||
private tablesDir;
|
||
private dbName;
|
||
private memoryCache;
|
||
/**
|
||
* v0.4.3-fix: 写操作串行队列 — 内存写 + 快照 + 文件持久化整体排队执行，
|
||
* close() 等待队列排空后再释放目录句柄（避免 close 后挂起写泄漏/读旧数据）。
|
||
* 前一个操作失败不阻塞后续（错误仍返回给调用方）。
|
||
*/
|
||
private opQueue;
|
||
/** 将写操作加入串行队列（快照在队列内取，始终最新） */
|
||
private enqueueOp;
|
||
open(dbName: string, version: number): Promise<void>;
|
||
close(): Promise<void>;
|
||
isOpen(): boolean;
|
||
/** 自愈：重置内存缓存后从 OPFS 重新加载（单文件损坏不影响其他表） */
|
||
repair(): Promise<void>;
|
||
/** 清空全部数据与表结构（删除目录内全部文件） */
|
||
clearAll(): Promise<void>;
|
||
getMeta(key: string): Promise<string | null>;
|
||
setMeta(key: string, value: string): Promise<void>;
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
dropTable(tableName: string): Promise<void>;
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
getTableNames(): Promise<string[]>;
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
/** v0.4.2-fix: 引擎级 ALTER TABLE — 内存 + schema 持久化 + 整表文件重写 */
|
||
alterTable(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
/** v0.4.0: 流式查询（委托内存缓存） */
|
||
findStream(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
clear(tableName: string): Promise<void>;
|
||
createIndex(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
dropIndex(tableName: string, column: string, indexName?: string): Promise<void>;
|
||
beginTransaction(): Promise<void>;
|
||
commitTransaction(): Promise<void>;
|
||
rollbackTransaction(): Promise<void>;
|
||
private ensureDir;
|
||
private writeTableData;
|
||
private readTableData;
|
||
/**
|
||
* 从 OPFS 加载已有表到内存缓存。
|
||
* v0.4.2-fix: 优先从持久化 schema（__metona_schema_*.meta）恢复 —
|
||
* 空表不再消失、索引标记/主键/约束完整；无 schema 记录的旧库从数据推断（兼容）。
|
||
*/
|
||
private loadExistingTables;
|
||
/** 从 OPFS 加载表数据到内存缓存 */
|
||
loadTableIntoMemory(tableName: string, schema: TableSchema): Promise<void>;
|
||
}
|
||
|
||
interface AriaEngineConfig {
|
||
/** 页面大小（默认 4096） */
|
||
pageSize?: number;
|
||
/** Buffer Pool 页面数量（默认 256） */
|
||
bufferPoolPages?: number;
|
||
/** MemTable 刷盘阈值（默认 4MB） */
|
||
memtableSizeThreshold?: number;
|
||
/** LSM 层级之间的容量倍数（默认 10） */
|
||
levelSizeMultiplier?: number;
|
||
/** Bloom Filter 每 key 位数（默认 10） */
|
||
bloomFilterBitsPerKey?: number;
|
||
/** 是否启用 WAL（默认 true） */
|
||
walEnabled?: boolean;
|
||
/** WAL 同步模式 */
|
||
walSyncMode?: 'full' | 'batch' | 'none';
|
||
/** Checkpoint 间隔（操作数，默认 1000） */
|
||
checkpointInterval?: number;
|
||
/** 是否启用页面压缩（默认 false） */
|
||
compression?: boolean;
|
||
/** 存储后端 */
|
||
storageBackend?: 'indexeddb' | 'opfs' | 'memory';
|
||
/** WAL 大小阈值（字节，超过则强制 checkpoint，默认 16MB） */
|
||
walSizeThreshold?: number;
|
||
/** 最大内存预算（MB，默认 64） */
|
||
maxMemoryMB?: number;
|
||
}
|
||
|
||
declare class AriaEngine implements IStorageEngine {
|
||
readonly name = "aria";
|
||
private config;
|
||
private lsm;
|
||
private wal;
|
||
private checkpointManager;
|
||
private backend;
|
||
private opened;
|
||
private dbName;
|
||
private schemas;
|
||
private tablePKs;
|
||
private opCounter;
|
||
private secondaryIndexes;
|
||
private mvcc;
|
||
private currentTxnId;
|
||
private txnSnapshot;
|
||
private gcCounter;
|
||
private bufferPool;
|
||
constructor(config?: AriaEngineConfig);
|
||
open(dbName: string, _version: number): Promise<void>;
|
||
/** open 内部实现（错误包装在 open 外层） */
|
||
private openInternal;
|
||
close(): Promise<void>;
|
||
/**
|
||
* v0.4.2-fix: 崩溃恢复/自愈 — 校验并移除损坏 SSTable、截断 WAL、重建二级索引。
|
||
* 应用层检测到异常后调用，无需删库重建。
|
||
*/
|
||
repair(): Promise<void>;
|
||
/**
|
||
* v0.4.1: 重置数据库 — 清空全部数据与表结构（演示页刷新/重新初始化用）。
|
||
* 清空存储后端、LSM、WAL、MVCC 与二级索引，后续可继续使用本实例。
|
||
*/
|
||
clearAll(): Promise<void>;
|
||
isOpen(): boolean;
|
||
getMeta(key: string): Promise<string | null>;
|
||
setMeta(key: string, value: string): Promise<void>;
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
dropTable(tableName: string): Promise<void>;
|
||
/**
|
||
* v0.4.2-fix: 清理指定表的全部二级索引 LSM（内存 + 存储文件 + meta）。
|
||
* dropTable / DROP_TABLE 恢复 / alterTable DROP 索引列 共用。
|
||
*/
|
||
private cleanupTableIndexes;
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
getTableNames(): Promise<string[]>;
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
/**
|
||
* v0.4.2-fix: ON UPDATE 外键级联 — 主键 oldPk → newPk 时处理引用表。
|
||
* RESTRICT 抛错 / CASCADE 更新 FK / SET NULL 置空（含索引与 WAL 记录）。
|
||
* 两阶段：先全量 RESTRICT 检查，再执行级联。
|
||
*/
|
||
private applyForeignKeyUpdateRules;
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
/**
|
||
* v0.4.1: 外键级联规则 — 对齐 MemoryEngine.cascadeDelete 行为。
|
||
* 删除 tableName 主键为 pkValue 的行前，检查引用它的所有表：
|
||
* - RESTRICT: 存在引用行 → 抛 FOREIGN_KEY_VIOLATION
|
||
* - CASCADE: 递归删除引用行（含索引/WAL）
|
||
* - SET NULL: 引用行外键列置 null（含索引/WAL）
|
||
* @returns 级联影响的行数（CASCADE 删除行数 + SET NULL 更新行数）
|
||
*/
|
||
private applyForeignKeyRules;
|
||
/**
|
||
* v0.4.0: 流式查询 — 逐行回调，不物化结果数组。
|
||
* 全表路径走 LSM rangeScanLazy 惰性扫描；索引等值/范围路径复用 tryIndexLookup。
|
||
* 事务中回退物化（快照合并需要全量行集）。
|
||
*/
|
||
findStream(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
clear(tableName: string): Promise<void>;
|
||
/**
|
||
* v0.4.1: ALTER TABLE — 结构变更真正生效于存储：
|
||
* - ADD: 持久化 schema（persistSchemas），行无需修改
|
||
* - DROP: 持久化 schema + 遍历主 LSM 重写所有行（移除该列键）+ WAL UPDATE 记录
|
||
* （通用路径 getTableSchema 返回副本，Executor 的引用修改对 Aria 无效）
|
||
*/
|
||
alterTable(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
createIndex(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
dropIndex(tableName: string, column: string, _indexName?: string): Promise<void>;
|
||
beginTransaction(): Promise<void>;
|
||
commitTransaction(): Promise<void>;
|
||
rollbackTransaction(): Promise<void>;
|
||
private savepoints;
|
||
savepoint(name: string): Promise<void>;
|
||
rollbackToSavepoint(name: string): Promise<void>;
|
||
releaseSavepoint(name: string): Promise<void>;
|
||
backup(): Promise<Record<string, Record<string, unknown>[]>>;
|
||
private getAllRows;
|
||
/**
|
||
* v0.3.3: 将事务未提交快照的变更合并到行列表（新增/更新/删除标记）。
|
||
* 幂等操作：行已是最新时不重复修改。
|
||
*/
|
||
private mergeTxnSnapshot;
|
||
private getPK;
|
||
private validateRow;
|
||
private checkType;
|
||
private persistSchemas;
|
||
private loadSchemas;
|
||
/**
|
||
* 创建命名空间隔离的 SSTableStore。
|
||
*
|
||
* 主 LSM 与每个二级索引 LSM 各持有独立实例：
|
||
* - 文件 key 前缀隔离（sst_ / sst_idx_${table}_${col}_）
|
||
* - 元数据 key 隔离（__aria_lsm_meta / __aria_lsm_meta_${ns}）
|
||
* - id 序列独立（避免 v0.2.4 共享 id 空间导致的文件互相覆盖）
|
||
*/
|
||
private createSSTableStore;
|
||
private applyWALRecord;
|
||
/**
|
||
* v0.3.3: DROP_TABLE 恢复 — 删除 schema 并清除主 LSM 中该表的所有残留数据。
|
||
*
|
||
* 此前 DROP_TABLE 在恢复时被忽略，而 CREATE_TABLE 回放会重建 schema，
|
||
* 导致崩溃后"已删除的表和数据复活"（实证 P0 bug）。
|
||
*/
|
||
private applyDropTableRecovery;
|
||
/** 更新行的二级索引条目 */
|
||
private updateSecondaryIndexes;
|
||
/** 通过二级索引快速查找 */
|
||
private tryIndexLookup;
|
||
/** 从索引扫描结果恢复完整行 */
|
||
private indexScanToRows;
|
||
/** 每 10 次 gc 计数器触发一次 MVCC 垃圾回收 */
|
||
private tryGC;
|
||
/** 回收主 LSM 与所有二级索引 LSM 的临时缓存超限 */
|
||
private trimAllCaches;
|
||
/** 检查内存预算，超出时强制 flush + GC */
|
||
private checkMemoryBudget;
|
||
/** 估算 WAL 大小（字节） */
|
||
getWALEstimatedSize(): number;
|
||
/**
|
||
* ANALYZE: 收集表统计信息
|
||
* 返回行数、平均行大小、索引深度等
|
||
*/
|
||
analyzeTable(tableName: string): Promise<Record<string, unknown>>;
|
||
/**
|
||
* REINDEX: 重建指定表的所有二级索引
|
||
*/
|
||
reindexTable(tableName: string): Promise<number>;
|
||
/** v0.4.2-fix: 重建索引内部实现（不校验 opened，供 open 恢复流程调用） */
|
||
private reindexTableInternal;
|
||
/**
|
||
* VACUUM: 压缩 LSM + 清理碎片
|
||
*/
|
||
vacuum(): Promise<{
|
||
compactedLevels: number;
|
||
gcVersions: number;
|
||
}>;
|
||
/**
|
||
* 查询优化器：估算各索引成本，选择最优方案
|
||
*/
|
||
estimateQueryCost(tableName: string, query: QueryPlan): {
|
||
strategy: string;
|
||
estimatedRows: number;
|
||
};
|
||
private ensureOpen;
|
||
/** v0.4.2-fix: Aria 事务中 DDL 显式拒绝（结构变更无法通过行快照回滚） */
|
||
private ensureNoDDLInTransaction;
|
||
private ensureTable;
|
||
/** Get the number of WAL records stored */
|
||
private getWALCount;
|
||
/** Set the number of WAL records stored */
|
||
private setWALCount;
|
||
}
|
||
|
||
declare class HybridEngine implements IStorageEngine {
|
||
readonly name = "hybrid";
|
||
private memoryEngine;
|
||
private diskEngine;
|
||
private diskEngineType;
|
||
private dbName;
|
||
private version;
|
||
constructor(diskEngine?: DiskEngine);
|
||
open(dbName: string, version: number): Promise<void>;
|
||
/**
|
||
* 从磁盘重载内存缓存（v0.3.2：多标签页同步）。
|
||
* 其他标签页写入磁盘后调用，使本标签页读到最新数据。
|
||
*/
|
||
reloadMemoryFromDisk(): Promise<void>;
|
||
close(): Promise<void>;
|
||
isOpen(): boolean;
|
||
/** 自愈：修复磁盘引擎后重载内存缓存 */
|
||
repair(): Promise<void>;
|
||
/** 清空全部数据与表结构 */
|
||
clearAll(): Promise<void>;
|
||
getMeta(key: string): Promise<string | null>;
|
||
setMeta(key: string, value: string): Promise<void>;
|
||
createTable(schema: TableSchema): Promise<void>;
|
||
dropTable(tableName: string): Promise<void>;
|
||
hasTable(tableName: string): Promise<boolean>;
|
||
getTableNames(): Promise<string[]>;
|
||
getTableSchema(tableName: string): Promise<TableSchema | null>;
|
||
/** v0.4.2-fix: 引擎级 ALTER TABLE — 双引擎同步（磁盘持久化 + 内存引用） */
|
||
alterTable(tableName: string, action: 'ADD' | 'DROP', column: ColumnDef & {
|
||
name: string;
|
||
}): Promise<void>;
|
||
insert(tableName: string, rows: Record<string, unknown>[]): Promise<string[]>;
|
||
find(tableName: string, query: QueryPlan): Promise<Record<string, unknown>[]>;
|
||
/** v0.4.0: 流式查询（内存引擎逐行回调） */
|
||
findStream(tableName: string, query: QueryPlan, onRow: (row: Record<string, unknown>) => void): Promise<number>;
|
||
update(tableName: string, query: QueryPlan, updates: Record<string, unknown>): Promise<number>;
|
||
delete(tableName: string, query: QueryPlan): Promise<number>;
|
||
count(tableName: string, query?: QueryPlan): Promise<number>;
|
||
clear(tableName: string): Promise<void>;
|
||
createIndex(tableName: string, column: string, unique?: boolean): Promise<void>;
|
||
dropIndex(tableName: string, column: string, indexName?: string): Promise<void>;
|
||
beginTransaction(): Promise<void>;
|
||
commitTransaction(): Promise<void>;
|
||
rollbackTransaction(): Promise<void>;
|
||
/** 获取磁盘引擎类型 */
|
||
getDiskEngineType(): DiskEngine;
|
||
/** 获取内存引擎（供内部使用） */
|
||
getMemoryEngine(): MemoryEngine;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark SQL Parser — 递归下降语法分析器
|
||
* @module sql/parser
|
||
*
|
||
* Token 流 → AST Statement。
|
||
* 支持的语法是标准 SQL 的子集。
|
||
*/
|
||
|
||
/** 解析 SQL 字符串为 AST Statement */
|
||
declare function parse(sql: string): Statement;
|
||
/** 解析 SQL 字符串为 AST Statement 数组（分号分隔的多语句支持，v0.3.0） */
|
||
declare function parseAll(sql: string): Statement[];
|
||
|
||
/**
|
||
* metona-sqlark SQL Token Types — 词法单元定义
|
||
* @module sql/tokens
|
||
*/
|
||
declare enum TokenType {
|
||
SELECT = "SELECT",
|
||
FROM = "FROM",
|
||
WHERE = "WHERE",
|
||
INSERT = "INSERT",
|
||
INTO = "INTO",
|
||
VALUES = "VALUES",
|
||
UPDATE = "UPDATE",
|
||
SET = "SET",
|
||
DELETE = "DELETE",
|
||
CREATE = "CREATE",
|
||
TABLE = "TABLE",
|
||
DROP = "DROP",
|
||
ORDER = "ORDER",
|
||
BY = "BY",
|
||
ASC = "ASC",
|
||
DESC = "DESC",
|
||
LIMIT = "LIMIT",
|
||
OFFSET = "OFFSET",
|
||
AND = "AND",
|
||
OR = "OR",
|
||
NOT = "NOT",
|
||
LIKE = "LIKE",
|
||
IN = "IN",
|
||
PRIMARY = "PRIMARY",
|
||
KEY = "KEY",
|
||
UNIQUE = "UNIQUE",
|
||
DEFAULT = "DEFAULT",
|
||
NULL = "NULL",
|
||
TRUE = "TRUE",
|
||
REFERENCES = "REFERENCES",
|
||
CASCADE = "CASCADE",
|
||
BETWEEN = "BETWEEN",
|
||
IF = "IF",
|
||
EXISTS = "EXISTS",
|
||
FALSE = "FALSE",
|
||
ALTER = "ALTER",
|
||
ADD = "ADD",
|
||
TRUNCATE = "TRUNCATE",
|
||
INNER = "INNER",
|
||
LEFT = "LEFT",
|
||
RIGHT = "RIGHT",
|
||
CROSS = "CROSS",
|
||
JOIN = "JOIN",
|
||
ON = "ON",
|
||
AS = "AS",
|
||
OUTER = "OUTER",
|
||
GROUP = "GROUP",
|
||
HAVING = "HAVING",
|
||
COUNT = "COUNT",
|
||
SUM = "SUM",
|
||
AVG = "AVG",
|
||
MIN = "MIN",
|
||
MAX = "MAX",
|
||
DISTINCT = "DISTINCT",
|
||
BEGIN = "BEGIN",
|
||
COMMIT = "COMMIT",
|
||
ROLLBACK = "ROLLBACK",
|
||
UNION = "UNION",
|
||
ALL = "ALL",
|
||
INDEX = "INDEX",
|
||
CASE = "CASE",
|
||
WHEN = "WHEN",
|
||
THEN = "THEN",
|
||
ELSE = "ELSE",
|
||
END = "END",
|
||
IDENTIFIER = "IDENTIFIER",
|
||
STRING = "STRING",
|
||
NUMBER = "NUMBER",
|
||
COMMA = "COMMA",
|
||
LPAREN = "LPAREN",
|
||
RPAREN = "RPAREN",
|
||
SEMICOLON = "SEMICOLON",
|
||
EQ = "EQ",
|
||
NEQ = "NEQ",
|
||
GT = "GT",
|
||
GTE = "GTE",
|
||
LT = "LT",
|
||
LTE = "LTE",
|
||
STAR = "STAR",
|
||
DOT = "DOT",
|
||
EOF = "EOF",
|
||
ILLEGAL = "ILLEGAL"
|
||
}
|
||
interface Token {
|
||
type: TokenType;
|
||
value: string;
|
||
position: number;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark SQL Lexer — 词法分析器
|
||
* @module sql/lexer
|
||
*
|
||
* 将 SQL 字符串切分为 Token 流。
|
||
*/
|
||
|
||
/** 将 SQL 字符串解析为 Token 列表 */
|
||
declare function tokenize(sql: string): Token[];
|
||
|
||
/**
|
||
* AriaEngine Storage Backend — 存储后端抽象层
|
||
* @module engine/aria/store/backend
|
||
*
|
||
* 封装底层浏览器存储 API（IndexedDB / OPFS / Memory 回退），
|
||
* 供 Buffer Pool 的 PageIO 和 WAL 的 WALStore 使用。
|
||
*/
|
||
interface IStorageBackend {
|
||
/** 打开存储 */
|
||
open(name: string): Promise<void>;
|
||
/** 关闭存储 */
|
||
close(): Promise<void>;
|
||
/** 是否已打开 */
|
||
isOpen(): boolean;
|
||
/** 读取数据块 */
|
||
read(key: string): Promise<ArrayBuffer | null>;
|
||
/** 写入数据块 */
|
||
write(key: string, data: ArrayBuffer): Promise<void>;
|
||
/**
|
||
* 批量原子写入（v0.4.2-fix）：多个 key 在单个底层事务中提交，
|
||
* 中断时整体回滚，不留半写状态。WAL count 与记录同事务保证一致性。
|
||
*/
|
||
writeMany(entries: Record<string, ArrayBuffer>): Promise<void>;
|
||
/** 删除数据块 */
|
||
delete(key: string): Promise<void>;
|
||
/**
|
||
* 批量原子删除（v0.4.2-fix）：多个 key 在单个底层事务中提交。
|
||
*/
|
||
deleteMany(keys: string[]): Promise<void>;
|
||
/** 列出所有 key */
|
||
listKeys(): Promise<string[]>;
|
||
/** 检查 key 是否存在 */
|
||
exists(key: string): Promise<boolean>;
|
||
/** 清空所有数据 */
|
||
clear(): Promise<void>;
|
||
}
|
||
|
||
/**
|
||
* AriaEngine OPFS Backend — 基于 Origin Private File System 的自研存储后端
|
||
* @module engine/aria/store/opfs_backend
|
||
*
|
||
* 零外部依赖，纯浏览器文件系统 API。
|
||
* 每个 key 对应 OPFS 目录下的一个二进制文件。
|
||
*
|
||
* 浏览器要求：Chrome 102+ / Edge 102+
|
||
*/
|
||
|
||
declare class OPFSBackend implements IStorageBackend {
|
||
private root;
|
||
private dbDir;
|
||
private dbName;
|
||
private writeQueue;
|
||
open(name: string): Promise<void>;
|
||
close(): Promise<void>;
|
||
isOpen(): boolean;
|
||
read(key: string): Promise<ArrayBuffer | null>;
|
||
write(key: string, data: ArrayBuffer): Promise<void>;
|
||
/** v0.4.2-fix: 批量写入 — 串行队列内逐个落盘（OPFS 无跨文件事务，顺序保证一致） */
|
||
writeMany(entries: Record<string, ArrayBuffer>): Promise<void>;
|
||
delete(key: string): Promise<void>;
|
||
/** v0.4.2-fix: 批量删除 — 串行队列内逐个删除 */
|
||
deleteMany(keys: string[]): Promise<void>;
|
||
listKeys(): Promise<string[]>;
|
||
exists(key: string): Promise<boolean>;
|
||
clear(): Promise<void>;
|
||
}
|
||
|
||
/**
|
||
* metona-sqlark — 入口文件
|
||
* @module metona-sqlark
|
||
* @version 0.4.1
|
||
*
|
||
* 前端关系型数据库，内存与磁盘双模式。
|
||
* 支持 Query Builder 链式 API 和 SQL 字符串查询。
|
||
*/
|
||
|
||
/**
|
||
* 创建数据库实例并初始化
|
||
*
|
||
* @example
|
||
* ```ts
|
||
* const db = await MetonaSqlark.create({
|
||
* name: 'my-app',
|
||
* mode: 'hybrid',
|
||
* });
|
||
*
|
||
* await db.defineTable('users', {
|
||
* id: { type: 'string', primaryKey: true },
|
||
* name: { type: 'string', required: true },
|
||
* });
|
||
*
|
||
* await db.table('users').insert({ id: '1', name: 'Alice' });
|
||
* const results = await db.query('SELECT * FROM users');
|
||
* ```
|
||
*/
|
||
declare function create(config: DatabaseConfig): Promise<MetonaSqlark>;
|
||
declare const api: {
|
||
VERSION: string;
|
||
version: string;
|
||
create: typeof create;
|
||
MetonaSqlark: typeof MetonaSqlark;
|
||
MeSqlark: typeof MetonaSqlark;
|
||
};
|
||
declare global {
|
||
interface Window {
|
||
MetonaSqlark: typeof api;
|
||
MeSqlark: typeof api;
|
||
}
|
||
}
|
||
|
||
declare const MeSqlark: typeof MetonaSqlark;
|
||
|
||
export { AriaEngine, AriaEngineConfig, ColumnDef, DatabaseConfig, DeleteStatement, DiskEngine, FieldType, HybridEngine, IStorageEngine, IndexedDBEngine, InsertStatement, MeSqlark, MemoryEngine, MetonaSqlark, OPFSBackend, OPFSEngine, SelectStatement, Statement, StorageMode, Table, TableSchema, UpdateStatement, VERSION, api, create, api as default, parse, parseAll, tokenize };
|