docs(G6): 宣称与实现一致性收口 —— priority 真正生效、MVCC/backup/引擎数/打包 全部对齐
独立核验（12 条宣称逐条对源码验证）发现 5 处**硬伤**与 2 处**数字过期**， 本提交按"能改代码就让宣称成立、改不动就如实描述"的原则全部收口。 让实现符合文档（2 处）： 1. **插件 priority 此前不生效** — `register()` 虽按 priority 插入数组，但 `install()` 在 register 内**立即**执行，因此 install 与钩子顺序 = config 数组 顺序（实测 priority low=1/high=100/mid=50 时钩子按 low→high→mid 触发， 只有 `getPlugins()` 是 high,mid,low）。而 README/CONTRIBUTING/constants 一直宣称"越大越先执行"。 现在 Core 注册前按 priority **稳定降序**排序（同优先级保持数组顺序）， install 与钩子都按优先级执行 → 宣称成立。新增 `tests/v080-plugin-priority.test.ts` 锁定 install 顺序、钩子顺序、稳定性、缺省值。 2. **连接池静态方法不在类型系统里** — `MetonaSqlark.connect/disconnect/ disconnectAll/getActiveConnections` 由 connection-manager 用 `as unknown as Record<string, unknown>` 注入，README 的连接池表格在 TypeScript 下全部 TS2339。现在在类上声明为可选静态成员，注入处去掉断言。 如实描述（3 处）： 3. **MVCC 快照隔离**（README 三处 + 实现对照）— `snapshotLsn` / `prevVersion` 只写不读，事务读走 `txnSnapshot`+LSM，commit 即清理版本链，并发 `beginTransaction` 抛 `TX_ACTIVE`。改为"快照回滚（事务串行，非 MVCC 隔离）"， 并在 README 架构图与维护语句表里同步措辞。 4. **"存储引擎（5 种）"** — 实际是 4 种模式 + 3 种后端，引擎类只有 4 个 （Memory / KVStore / Hybrid / Aria），OPFS 是后端而非引擎。标题与条目已改写， 并写明"`disk`/`hybrid` 恒用 KVStore"。 5. **`diskEngine` 生效范围** — 仅 `mode:'aria'` 生效；`constants.ts` 的注释 此前写成"仅 mode='disk'|'hybrid' 时生效"（正好写反），已改正；README 配置表、 快速开始示例与 Aria 示例同步标注。 数字口径统一（可复现）： - 测试 1872（90 套件）+ 14 e2e，另 4 个重型套件在独立 CI job 串行运行； - 覆盖率 语句 90.43% / 分支 82.21% / 函数 94.27% / 行 93.44%； - README 明确写出**产出这些数字的完整命令**（与 CI 常规 job 一致）， 并要求改动覆盖范围/阈值时同步更新表格（G5）。 - CHANGELOG 0.8.0 条目与 site 首页/文档页同步。 另修 **CONTRIBUTING 的钩子契约**：明确写出"返回值被忽略（不能取消/改写）、 就地改参数在 Table API 生效、抛异常可取消、SQL 路径的 beforeInsert 收到副本" —— 此前只写 "allow intercepting"，容易被理解为返回值可改变行为。 验证：全量 90 套件 / 1872 测试通过（+4 重型套件）；覆盖率四项均高于阈值； typecheck(src+tests)、lint、build 零错误零告警；e2e 14 项通过；dist 已重建。
This commit is contained in:
thzxx
Vendored
+67
-3
@@ -819,6 +819,13 @@ declare class QueryExecutor {
|
||||
* v0.3.3: ORDER BY 是否引用 SELECT 别名（如 `SELECT name AS n ... ORDER BY n`）。
|
||||
* 别名列在引擎层投影前不存在，需投影后重新排序。
|
||||
*/
|
||||
/**
|
||||
* v0.8.0（B-5）：SELECT 列表产出的**别名集合**（`AS x` 与 `CASE ... AS x`）。
|
||||
*
|
||||
* 与 `orderByUsesSelectAlias` 共用同一套识别规则 —— 两处若各写一份，
|
||||
* 会出现"排序认为它是别名、校验认为它是列"的矛盾（本项目反复出现的漂移模式）。
|
||||
*/
|
||||
private selectAliasNames;
|
||||
private orderByUsesSelectAlias;
|
||||
/** WHERE 是否包含 CASE WHEN 表达式键 */
|
||||
private whereHasCase;
|
||||
@@ -1187,6 +1194,16 @@ interface ChangeEvent {
|
||||
declare class MetonaSqlark {
|
||||
/** 数据库名称 */
|
||||
readonly name: string;
|
||||
/**
|
||||
* v0.8.0：释放一个连接引用（引用计数 -1，归零时自动关闭）。
|
||||
*
|
||||
* 由 `MetonaSqlark.connect()` 注入实现 —— 此前该方法是**运行时注入、类型上不存在**：
|
||||
* README 与示例都在用 `await db.disconnect()`，但 `db` 的声明里没有它，
|
||||
* TypeScript 使用者会直接编译失败（只能 `as any` 绕过）。
|
||||
* 普通 `create()` 得到的实例没有这个方法，因此为可选：
|
||||
* 只有经 `connect()` 取得的实例才有，直接调用会抛错（而不是静默无操作）。
|
||||
*/
|
||||
disconnect?: () => Promise<void>;
|
||||
/**
|
||||
* v0.7.1: 静态工厂（与 connect/disconnect 同一入口风格）。
|
||||
* 此前 create 仅存在于 api 对象 / window 挂载 —— README/站点示例的
|
||||
@@ -1292,8 +1309,14 @@ declare class MetonaSqlark {
|
||||
/** 导出整个数据库为 JSON */
|
||||
exportAll(): Promise<Record<string, Record<string, unknown>[]>>;
|
||||
/**
|
||||
* v0.5.1: 在线备份 — 导出全库一致性快照。
|
||||
* Aria 引擎走引擎级 backup()（MVCC 一致性视图）；其余引擎回退 exportAll()。
|
||||
* v0.5.1: 在线备份 — 导出全库数据。
|
||||
*
|
||||
* v0.8.0 修正表述：此前注释与 README 宣称"全库**一致性**快照"，但引擎层
|
||||
* 并没有跨表快照原语 —— 实现是**逐表读取**（Aria 走引擎级 `backup()`，
|
||||
* 其余引擎回退 `exportAll()`）。备份过程中的并发写入会让不同表来自不同
|
||||
* 时间点（单表内部仍是一致的）。需要强一致时先 `close()`，或用
|
||||
* `db.transaction()` 包住调用（事务期间并发写被 `TX_ACTIVE` 拒绝）。
|
||||
* 真正的跨表快照需要 COW 行所有权改造，列入后续版本。
|
||||
*/
|
||||
backup(): Promise<Record<string, Record<string, unknown>[]>>;
|
||||
/** 变更通知引擎（init 后可用）；未初始化时为 null */
|
||||
@@ -2085,6 +2108,47 @@ declare class OPFSBackend implements IStorageBackend {
|
||||
clear(): Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* migrateFromIndexedDB — 旧 IndexedDB 数据迁移到自研 KV 引擎
|
||||
* @module migration/index
|
||||
*
|
||||
* v0.6.0: IndexedDB 从引擎中完全移除后，提供一次性迁移工具把旧库数据
|
||||
* 导入新引擎（KVStoreEngine disk 模式 / AriaEngine）。
|
||||
*
|
||||
* 旧库命名：
|
||||
* - disk 模式（IndexedDBEngine）：库名 = dbName
|
||||
* - aria 模式（IndexedDBBackend）：库名 = `aria-${dbName}`
|
||||
*
|
||||
* 仅此模块保留原生 IndexedDB 读取代码（一次性迁移用途，不参与运行时）。
|
||||
*/
|
||||
|
||||
interface MigrationOptions {
|
||||
/** 旧库名（业务名，不含 aria- 前缀） */
|
||||
dbName: string;
|
||||
/**
|
||||
* 旧引擎类型：仅支持 disk（IndexedDBEngine，每表一个 objectStore，行数据可直接读取）。
|
||||
* aria 旧库（IndexedDBBackend）数据为引擎私有格式（SSTable/WAL），无法按行迁移。
|
||||
*/
|
||||
engine: 'disk';
|
||||
/** 目标数据库实例（已初始化，新引擎） */
|
||||
target: MetonaSqlark;
|
||||
/** 进度回调 */
|
||||
onProgress?: (done: number, total: number, table?: string) => void;
|
||||
}
|
||||
interface MigrationResult {
|
||||
/** 已迁移的表 */
|
||||
migratedTables: string[];
|
||||
/** 迁移的行总数 */
|
||||
rowCount: number;
|
||||
/** 跳过（无 schema 且无数据）的表 */
|
||||
skippedTables: string[];
|
||||
}
|
||||
/**
|
||||
* 将旧 IndexedDB 库迁移到目标引擎。
|
||||
* @returns 迁移结果（表/行数统计）
|
||||
*/
|
||||
declare function migrateFromIndexedDB(opts: MigrationOptions): Promise<MigrationResult>;
|
||||
|
||||
/**
|
||||
* metona-sqlark — 入口文件
|
||||
* @module metona-sqlark
|
||||
@@ -2130,4 +2194,4 @@ declare global {
|
||||
|
||||
declare const MeSqlark: typeof MetonaSqlark;
|
||||
|
||||
export { AriaEngine, AriaEngineConfig, ColumnDef, DatabaseConfig, DatabaseError, DeleteStatement, DiskEngine, FieldType, HookCallback, HookName, HybridEngine, IStorageEngine, InsertStatement, KVStoreEngine, MeSqlark, MemoryEngine, MetonaPlugin, MetonaSqlark, OPFSBackend, OrderBy, PluginManager, QueryPlan, SelectStatement, Statement, StorageMode, Table, TableSchema, Transaction, TransactionManager, UpdateStatement, VERSION, WhereCondition, WhereOperator, api, bindParameters, create, api as default, parse, parseAll, parseWhereCondition, tokenize };
|
||||
export { AriaEngine, AriaEngineConfig, ColumnDef, DatabaseConfig, DatabaseError, DeleteStatement, DiskEngine, FieldType, HookCallback, HookName, HybridEngine, IStorageEngine, InsertStatement, KVStoreEngine, MeSqlark, MemoryEngine, MetonaPlugin, MetonaSqlark, MigrationOptions, MigrationResult, OPFSBackend, OrderBy, PluginManager, QueryPlan, SelectStatement, Statement, StorageMode, Table, TableSchema, Transaction, TransactionManager, UpdateStatement, VERSION, WhereCondition, WhereOperator, api, bindParameters, create, api as default, migrateFromIndexedDB, parse, parseAll, parseWhereCondition, tokenize };
|
||||
|
||||
Reference in New Issue
Block a user