tbdb 0.0.0 → 0.0.5

package/README.md

@@ -0,0 +1,72 @@
+<p align="center">
+  <img src="docs-src/logo/tbdb-logo.png" alt="TableDB Logo" height="128" />
+</p>
+
+# TableDB
+
+A very simple NoSQL database abstraction layer that provides MongoDB-like CRUD APIs, supporting multiple backends including SQLite, MongoDB and IndexedDB.
+
+---
+
+> 这个世界上复杂的数据库和 ORM 已经够多了，而我们只想简单地存个东西。
+
+一个非常简单却实用的 NoSQL 数据库抽象层，提供类似 MongoDB 的增删改查 API，支持多种存储后端（SQLite, MongoDB, IndexedDB）。
+
+- **完全兼容 JavaScript 数据类型**\
+   直接存入 `Date`, `Map`, `RegExp`, `ArrayBuffer`,`Unint8Array`, `Blob`, `File` 等 JavaScript 类型，取出后数据类型不变，不用额外考虑数据库类型问题。
+- **类似 MongoDB 的 NoSQL API**\
+   增删改查的接口遵照 MongoDB 设计，例如 `findOne()`, `updateMany()`，易于上手，可以平滑的从 MongoDB 迁移。
+- **切换不同数据库后端**\
+   提供 SQLite, MongoDB 等多种数据库适配器，可以方便的切换不同的数据库存储后端。
+  并且可以在不同数据库间迁移数据，让你可以从 SQLite 开始，当规模变大时迁移到 MongoDB。
+
+- **集成实用方法**\
+  内置 “分页”、“游标分页”、“批量遍历”等实用功能。
+
+- **可选功能**：
+    - `autoMetadata` 自动元数据（创建时间，修改时间）
+    - `markDelete` 标记删除
+    - `tree` 目录树存储
+
+
+
+
+## 安装
+
+```sh [npm]
+$ npm add -D tbdb fzz
+```
+
+> `fzz` 是 TableDB 使用的数据类型定义库 `dto` 的依赖，可选安装，如果你不需要通过定义 Schema 获得更好的 TypeScript 类型提示，可以不安装。
+
+## 快速开始
+
+```ts
+import { defineTable, SQLiteAdapter } from "tbdb"
+
+// 1. 定义 Table，并得到 useTable 函数
+let useMemberTable = defineTable({
+    name: "Member",
+    adapter: SQLiteAdapter({ filename: "./member.sqlite" }),
+})
+
+// 2.使用 useTable 创建 Table 实例
+let memberTable = await useMemberTable()
+
+// 3.使用 Table 实例进行数据操作
+await memberTable.insertMany([
+    {
+        id: "member1",
+        name: "Alice",
+        age: 30,
+    },
+])
+
+let members = await memberTable.findMany({ age: { $gt: 20 } })
+```
+
+## 项目目录结构
+
+- 接口定义：`./core/types.ts`, `./adapter/adapter.ts`
+- 核心实现：`./core/Table.ts`
+- 适配器实现：`./adapter/`

package/dist/adapter/IndexedDB/IndexedDBAdapter.d.ts

@@ -0,0 +1,29 @@
+import { ITableDBAdapter } from "../adapter";
+/**
+ * IndexedDBAdapter 机制说明
+ * ===============================================
+ *
+ * 核心设计目标：
+ * 在浏览器环境下提供高性能的 MongoDB 风格文档数据库体验。
+ *
+ * 关键机制:
+ * 1. 动态 Schema 管理:
+ *    IndexedDB 只能在 onupgradeneeded 事件中修改 ObjectStore 和 Index。
+ *    当调用 defineIndexes 时，如果发现需要创建新索引，会关闭当前数据库连接，
+ *    增加版本号并重新打开。
+ *
+ * 2. 多表与并发升级支持:
+ *    - 适配器在获取 Store 前会自动检查表是否存在，如果不存在则触发数据库升级。
+ *    - 通过监听 onversionchange 事件，当其他实例请求升级时主动关闭连接，防止死锁和超时。
+ *
+ * 3. 混合查询策略:
+ *    - 尽可能利用 IndexedDB 索引进行范围查询 (IDBKeyRange)。(待进一步优化)
+ *    - 对于复杂查询，使用游标 (Cursor) 遍历并在内存中进行 matches 匹配。
+ *
+ * 4. 兼容性:
+ *    - _id: 为每个文档维护一个虚拟的 _id，以兼容核心层对 _id 的依赖（如游标分页）。
+ *    - undefined 规范化: 将 undefined 转换为 null，保持与其他适配器行为一致。
+ */
+export declare function IndexedDBAdapter(config: {
+    dbName: string;
+}): ITableDBAdapter;

package/dist/adapter/IndexedDB/index.d.ts

@@ -0,0 +1 @@
+export * from "./IndexedDBAdapter";

package/dist/adapter/IndexedDB/test/indexeddb.test.d.ts

@@ -0,0 +1 @@
+import "fake-indexeddb/auto";

package/dist/adapter/SQLite/SQLiteAdapter.d.ts

@@ -1,31 +1,120 @@
-import Database from "better-sqlite3";
-import { ITableDBAdapterInstance, ITableDBAdapter, ITableDefineIndexesOptions, ITableDeletedResult, ITableDeleteOptions, ITableDoc, ITableFindOptions, ITableIndexConfig, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableUpdateOptions, ITableUpdateResult } from "../adapter";
+import { ITableDBAdapterInstance, ITableDBAdapter, ITableDefineIndexesOptions, ITableDeletedResult, ITableDeleteOptions, ITableDoc, ITableFindOptions, ITableIndexConfig, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableUpdateOptions, ITableUpdateResult, ITableDebugResult } from "../adapter";
 import { ITableFilter, ITableUpdateOp } from "../../core/types";
-export declare function SQLiteAdapter(config: {
+import { ISqliteDatabase, SqliteDriverType } from "./driver";
+/**
+ * SQLiteAdapter 机制说明文档
+ * ===============================================
+ *
+ * 核心设计目标：
+ * 在 SQLite 上提供高性能、全功能的 MongoDB 风格文档数据库体验。
+ *
+ * 关键机制 (Key Mechanisms):
+ *
+ * 1. 侧表倒排索引 (Side Table Inverted Index):
+ *    - 问题: 对于数组字段查询 (e.g. { tags: "A" })，SQLite 原生 JSON 函数需要全表扫描。
+ *    - 解决: 为数组字段创建辅助表 `_idx_{tableName}_{field}`，存储 `(val, id)` 对。
+ *    - 实现: 使用 SQLite Triggers 自动维护侧表数据（Insert/Update/Delete 时自动触发）。
+ *    - 效果: 将 Array Containment 查询转化为高效的 SQL `EXISTS` 子查询。
+ *
+ * 2. 脏字段检测与查询优化 ( Dirty Tracking & Query Optimization):
+ *    - 问题: 混合模式 (Hybrid Mode) 虽然万能但较慢，纯 SQL 模式快但可能语义不准确（特别是数组隐式包含）。
+ *    - 解决: 维护 `_schema_dirty_{tableName}` 表，记录哪些字段曾经存储过数组或特殊值 (NaN/Null)。
+ *    - 策略:
+ *      - 如果某字段以前从未存过数组，那么 `{ field: "A" }` 可以安全视为 SQL 相等比较。
+ *      - 如果存过数组，则必须回退到 JsMatch 或使用侧表。
+ *
+ * 3. 混合查询执行 (Hybrid Query Execution):
+ *    - 纯 SQL 模式 (SQL Mode): 当 Filter 可以完全无损映射为 SQL 时使用，性能最高。
+ *    - 混合模式 (Hybrid Mode): `SELECT ... WHERE (SQL_PreFilter) AND JsMatch(data, filter)`
+ *      - 利用 SQL 索引进行粗筛。
+ *      - 利用自定义 SQLite 函数 `JsMatch` 在内存中运行 JS 逻辑进行精确匹配。
+ *      - 保证了 MongoDB 语义的 100% 兼容性 (Regular Expressions, $where, complex logic)。
+ *
+ * 4. 批量操作优化:
+ *    - 批量插入优化: 临时禁用侧表 Trigger -> 批量插入数据 -> 批量 Rebuild 侧表 -> 恢复 Trigger。
+ *    - 批量更新优化 (bulkUpdateSync): 在单个事务中执行所有操作，减少 I/O 和上下文切换。
+ *
+ * 5. 多驱动支持 (Multi-Driver Support):
+ *    - 支持 better-sqlite3 和 node:sqlite (Node.js 22.5+) 两种驱动
+ *    - 通过 Driver 抽象层统一 API 差异
+ *    - 可通过 config.driver 指定驱动类型，或使用 "auto" 自动选择
+ */
+/** SQLiteAdapter 配置选项 */
+export interface SQLiteAdapterConfig {
+    /** 数据库文件路径，":memory:" 表示内存数据库 */
     filename: string;
+    /**
+     * 安全模式配置
+     * - false/undefined: synchronous=OFF，性能最高但系统崩溃可能丢数据
+     * - true: synchronous=NORMAL，平衡性能和安全
+     * - "full": synchronous=FULL，最安全，每次写入都落盘
+     */
     safe?: boolean | "full";
+    /** 是否启用 ZSTD 压缩（打开文件前解压，关闭文件时压缩） */
     zstd?: boolean;
-}): ITableDBAdapter;
+    /**
+     * 多进程访问模式
+     * 使用 WAL 模式和适当的同步设置，SQLite 可以支持多个进程同时访问同一个数据库文件。
+     * 启用 multi 模式后，SQLiteAdapter 将自动配置数据库连接以支持多进程访问：
+     * - PRAGMA journal_mode=WAL
+     * - PRAGMA busy_timeout=15000
+     * 可以与 `safe:true` 一起使用
+     */
+    multi?: boolean;
+    /**
+     * SQLite 驱动类型
+     * - "better-sqlite3": 使用 better-sqlite3（需要安装依赖，兼容性好，支持自定义函数）
+     * - "node:sqlite": 使用 Node.js 内置模块（Node.js 22.5+ 无需安装依赖，支持自定义函数）
+     * - "bun:sqlite": 使用 Bun 内置模块（仅 Bun 运行时，不支持自定义函数，无法使用混合查询模式）
+     * - "auto": 自动选择（Bun 环境用 bun:sqlite，Node 环境优先 better-sqlite3 > node:sqlite）
+     *
+     * 注意：bun:sqlite 不支持自定义函数，因此无法使用 JsMatch/JsPatch 混合查询模式
+     *
+     * @default "auto"
+     */
+    driver?: SqliteDriverType | "auto";
+}
+export declare function SQLiteAdapter(config: SQLiteAdapterConfig): ITableDBAdapter;
 export declare class SQLiteAdapterInstance implements ITableDBAdapterInstance {
     private db;
     private tableName;
     private config;
+    private driverType;
     name: string;
-    constructor(db: Database.Database, tableName: string, config: {
-        filename: string;
-        safe?: boolean | "full";
-        zstd?: boolean;
-    });
+    private statementCache;
+    private indexedFields;
+    private dirtyFieldCache;
+    private supportsCustomFunctions;
+    constructor(db: ISqliteDatabase, tableName: string, config: SQLiteAdapterConfig, driverType?: SqliteDriverType);
+    private loadDirtyFields;
+    /**
+     * 检查查询是否可以使用纯 SQL 模式
+     *
+     * 如果当前驱动不支持自定义函数（如 bun:sqlite），则强制返回 true，
+     * 使用纯 SQL 模式（可能会有语义差异，但至少不会报错）
+     */
+    private isQueryCompatible;
+    private markFieldDirty;
     /**
-     * 将对象中所有 undefined 转换为 null，保持 MongoDB 一致性
-     * 注意：不处理 Map、Set、Date、Buffer 等特殊类型，由 serialize/deserialize 处理
+     * 扫描文档并标记脏字段
+     * 在写入文档前调用，用于更新 Schema 统计信息
+     */
+    private scanAndMarkDirty;
+    private loadExistingIndexes;
+    private getStatement;
+    /**
+     * 数据规范化：处理 undefined 和特殊对象类型
+     * - undefined -> null (JSON 标准)
+     * - 保留 Map, Set, Date, BigInt, Blob 等特殊类型 (Serializer 会处理)
      */
     private normalizeUndefined;
     get(id: any): Promise<ITableDoc | void>;
     set(id: any, value: ITableDoc): Promise<void>;
     delete(id: any): Promise<void>;
     has(id: any): Promise<boolean>;
-    count(filter?: ITableFilter): Promise<number>;
+    count(filter?: ITableFilter, options?: {
+        debug?: ITableDebugResult;
+    }): Promise<number>;
     clear(): Promise<void>;
     clearAll(): Promise<void>;
     drop(): Promise<void>;
@@ -37,13 +126,46 @@ export declare class SQLiteAdapterInstance implements ITableDBAdapterInstance {
         filter: ITableFilter;
         updateOp: ITableUpdateOp<ITableDoc>;
         options?: ITableUpdateOptions;
-    }[]): Promise<ITableUpdateResult>;
+    }[], options?: {
+        debug?: ITableDebugResult;
+    }): Promise<ITableUpdateResult>;
+    bulkUpdateSync(updates: {
+        filter: ITableFilter;
+        updateOp: ITableUpdateOp<ITableDoc>;
+        options?: ITableUpdateOptions;
+    }[], options?: {
+        debug?: ITableDebugResult;
+    }): Promise<ITableUpdateResult>;
     updateOne(filter: ITableFilter, updateOp: ITableUpdateOp<ITableDoc>, options?: ITableUpdateOptions): Promise<ITableUpdateResult>;
-    insertMany(docs: ITableDoc[]): Promise<ITableInsertResult>;
+    private static BULK_IMPORT_THRESHOLD;
+    insertMany(docs: ITableDoc[], options?: {
+        debug?: ITableDebugResult;
+    }): Promise<ITableInsertResult>;
+    /**
+     * 默认批量插入实现
+     * 使用标准事务通过 INSERT 语句逐条插入
+     */
+    private insertManyDefault;
+    /**
+     * 高性能批量插入实现
+     *
+     * 优化机制：
+     * 1. 禁用 Trigger: 临时禁用侧表维护触发器。
+     * 2. 批量写入: 执行纯数据插入。
+     * 3. 批量重建 (Rebuild): 插入完成后，rebuildSideTableIndexes 一次性回填。
+     */
+    private insertManyOptimized;
     setMany(docs: Partial<ITableDoc>[], options?: ITableSetOptions): Promise<ITableSetResult>;
-    deleteMany(filter: ITableFilter): Promise<ITableDeletedResult>;
+    deleteMany(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
     deleteOne(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
     defineIndexes(indexes: ITableIndexConfig[], options?: ITableDefineIndexesOptions): Promise<void>;
+    private getSideTableName;
+    private createSideTableIndex;
+    private dropSideTableIndex;
+    disableSideTableTriggers(): Promise<void>;
+    enableSideTableTriggers(): Promise<void>;
+    private createSideTableTriggersOnly;
+    rebuildSideTableIndexes(): Promise<void>;
     dropIndexes(): Promise<void>;
     compact(): Promise<void>;
 }

package/dist/adapter/SQLite/benchmark/query_analysis.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/benchmark/sqlite-extended.bench.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SQLite 适配器扩展基准测试
+ * 覆盖以下场景：
+ * 1. 大文档测试（1KB/10KB/100KB payload）
+ * 2. 深层嵌套查询（depth=2/5/10）
+ * 3. 大规模批量导入（10K/50K/100K 文档，对比默认/禁用触发器/分块导入）
+ * 4. 索引数量对写入性能的影响（0/3/5 个索引字段）
+ */
+export {};

package/dist/adapter/SQLite/benchmark/sqlite.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter/SQLite/driver/BetterSqlite3Driver.d.ts

@@ -0,0 +1,27 @@
+/**
+ * BetterSqlite3Driver - better-sqlite3 的 Driver 实现
+ *
+ * 包装 better-sqlite3 以符合 ISqliteDatabase 接口
+ */
+import type Database from "better-sqlite3";
+import type { ISqliteDatabase, ISqliteStatement, ISqliteTransactionFn, ISqliteDriverConfig } from "./types";
+/**
+ * 包装 better-sqlite3 Database
+ */
+export declare class BetterSqlite3Driver implements ISqliteDatabase {
+    private db;
+    private stmtCache;
+    constructor(config: ISqliteDriverConfig);
+    get isOpen(): boolean;
+    prepare(sql: string): ISqliteStatement;
+    exec(sql: string): void;
+    function(name: string, fn: (...args: any[]) => any): void;
+    transaction<T extends (...args: any[]) => any>(fn: T): ISqliteTransactionFn<T>;
+    checkpoint(mode?: "PASSIVE" | "FULL" | "RESTART" | "TRUNCATE"): void;
+    close(): void;
+    /**
+     * 获取原始的 better-sqlite3 Database 实例
+     * 用于需要直接访问底层 API 的场景（如 zstd 压缩）
+     */
+    getRawDatabase(): Database.Database;
+}

package/dist/adapter/SQLite/driver/BunSqliteDriver.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BunSqliteDriver - bun:sqlite 的 Driver 实现
+ *
+ * 包装 Bun 内置的 bun:sqlite 模块以符合 ISqliteDatabase 接口
+ *
+ * 注意事项：
+ * 1. bun:sqlite 仅在 Bun 运行时可用
+ * 2. bun:sqlite 不支持自定义函数 (db.function)，会抛出错误
+ * 3. 因此使用此驱动时，无法使用依赖 JsMatch/JsPatch 的混合查询模式
+ */
+import type { ISqliteDatabase, ISqliteStatement, ISqliteTransactionFn, ISqliteDriverConfig } from "./types";
+interface BunSqliteStatement {
+    all(...params: any[]): any[];
+    get(...params: any[]): any;
+    run(...params: any[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+}
+interface BunSqliteDatabase {
+    query(sql: string): BunSqliteStatement;
+    exec(sql: string): void;
+    close(): void;
+    transaction<T>(fn: () => T): () => T;
+}
+/**
+ * 包装 bun:sqlite Database
+ *
+ * 主要差异处理：
+ * 1. bun:sqlite 使用 query() 而不是 prepare()
+ * 2. bun:sqlite 不支持自定义函数 function()
+ * 3. bun:sqlite 没有 isOpen 属性
+ * 4. bun:sqlite 的 transaction() API 不同于 better-sqlite3
+ */
+export declare class BunSqliteDriver implements ISqliteDatabase {
+    private db;
+    private stmtCache;
+    private _isOpen;
+    constructor(config: ISqliteDriverConfig);
+    get isOpen(): boolean;
+    prepare(sql: string): ISqliteStatement;
+    exec(sql: string): void;
+    /**
+     * bun:sqlite 不支持自定义函数
+     *
+     * 这意味着使用 BunSqliteDriver 时：
+     * - 无法使用 JsMatch 进行混合模式查询
+     * - 无法使用 JsPatch 进行内存更新
+     * - 所有查询必须使用纯 SQL 模式
+     *
+     * @throws Error 始终抛出错误
+     */
+    function(_name: string, _fn: (...args: any[]) => any): void;
+    /**
+     * 包装 bun:sqlite 的 transaction() 方法
+     *
+     * bun:sqlite 的 transaction() 签名: transaction<T>(fn: () => T): () => T
+     * better-sqlite3 的 transaction() 签名: transaction<T>(fn: T): T & { immediate, exclusive, deferred }
+     */
+    transaction<T extends (...args: any[]) => any>(fn: T): ISqliteTransactionFn<T>;
+    checkpoint(mode?: "PASSIVE" | "FULL" | "RESTART" | "TRUNCATE"): void;
+    close(): void;
+    /**
+     * 获取原始的 bun:sqlite Database 实例
+     */
+    getRawDatabase(): BunSqliteDatabase;
+}
+export {};

package/dist/adapter/SQLite/driver/NodeSqliteDriver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * NodeSqliteDriver - node:sqlite 的 Driver 实现
+ *
+ * 包装 Node.js 22+ 内置的 node:sqlite 模块以符合 ISqliteDatabase 接口
+ *
+ * 注意事项：
+ * 1. node:sqlite 从 Node.js 22.5.0 开始可用
+ * 2. node:sqlite 不支持 db.transaction()，需要手动实现
+ * 3. pragma 需要通过 db.exec() 执行
+ */
+import type { ISqliteDatabase, ISqliteStatement, ISqliteTransactionFn, ISqliteDriverConfig } from "./types";
+interface NodeSqliteStatement {
+    all(...params: any[]): any[];
+    get(...params: any[]): any;
+    run(...params: any[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+}
+interface NodeSqliteDatabase {
+    isOpen: boolean;
+    prepare(sql: string): NodeSqliteStatement;
+    exec(sql: string): void;
+    function(name: string, options: {
+        varargs?: boolean;
+    }, fn: (...args: any[]) => any): void;
+    function(name: string, fn: (...args: any[]) => any): void;
+    close(): void;
+}
+/**
+ * 包装 node:sqlite Database
+ *
+ * 主要差异处理：
+ * 1. transaction() 需要手动实现（使用 BEGIN/COMMIT/ROLLBACK）
+ * 2. function() 的签名略有不同
+ * 3. isOpen 属性名称相同
+ */
+export declare class NodeSqliteDriver implements ISqliteDatabase {
+    private db;
+    private stmtCache;
+    constructor(config: ISqliteDriverConfig);
+    get isOpen(): boolean;
+    prepare(sql: string): ISqliteStatement;
+    exec(sql: string): void;
+    function(name: string, fn: (...args: any[]) => any): void;
+    /**
+     * 模拟 better-sqlite3 的 transaction() 行为
+     *
+     * better-sqlite3 的 transaction() 返回一个函数，调用时会自动包装在事务中
+     * node:sqlite 没有这个 API，需要手动实现
+     */
+    transaction<T extends (...args: any[]) => any>(fn: T): ISqliteTransactionFn<T>;
+    checkpoint(mode?: "PASSIVE" | "FULL" | "RESTART" | "TRUNCATE"): void;
+    close(): void;
+    /**
+     * 获取原始的 node:sqlite Database 实例
+     */
+    getRawDatabase(): NodeSqliteDatabase;
+}
+export {};

package/dist/adapter/SQLite/driver/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SQLite Driver 统一导出
+ *
+/**
+ * SQLite Driver 统一导出
+ *
+ * 提供 better-sqlite3 和 node:sqlite 两种驱动的统一接口
+ */
+export * from "./types";
+export { BetterSqlite3Driver } from "./BetterSqlite3Driver";
+export { NodeSqliteDriver } from "./NodeSqliteDriver";
+export { BunSqliteDriver } from "./BunSqliteDriver";
+import type { ISqliteDatabase, ISqliteDriverConfig, SqliteDriverType } from "./types";
+/**
+ * 创建 SQLite Driver 实例
+ *
+ * @param type 驱动类型: "better-sqlite3" 或 "node:sqlite"
+ * @param config 驱动配置
+ * @returns SQLite 数据库实例
+ *
+ * @example
+ * ```ts
+ * // 使用 better-sqlite3（默认，兼容性更好）
+ * const db = createSqliteDriver("better-sqlite3", { filename: "test.db" })
+ *
+ * // 使用 node:sqlite（Node.js 22.5+ 内置，无需安装依赖）
+ * const db = createSqliteDriver("node:sqlite", { filename: "test.db" })
+ * ```
+ */
+export declare function createSqliteDriver(type: SqliteDriverType, config: ISqliteDriverConfig): ISqliteDatabase;
+/**
+ * 自动检测并创建可用的 SQLite Driver
+ *
+ * 选择逻辑：
+ * 1. Bun 环境：直接使用 bun:sqlite
+ * 2. Node 环境：
+ *    - 优先使用环境变量 TABLEDB_SQLITE_DRIVER 指定的驱动
+ *    - 其次使用 better-sqlite3
+ *    - 如果 better-sqlite3 不可用，退回 node:sqlite
+ *
+ * @param config 驱动配置
+ * @returns SQLite 数据库实例和使用的驱动类型
+ */
+export declare function createAutoSqliteDriver(config: ISqliteDriverConfig): {
+    db: ISqliteDatabase;
+    type: SqliteDriverType;
+};
+/**
+ * 检查指定的 SQLite 驱动是否可用
+ */
+export declare function isSqliteDriverAvailable(type: SqliteDriverType): boolean;

package/dist/adapter/SQLite/driver/test/driver.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SQLite Driver 抽象层测试
+ *
+ * 测试 better-sqlite3 和 node:sqlite 两种驱动的统一接口
+ */
+export {};

package/dist/adapter/SQLite/driver/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SQLite Driver 抽象层类型定义
+ *
+ * 提供统一的接口让 better-sqlite3 和 node:sqlite 可以互换使用
+ */
+/**
+ * SQLite Statement 抽象接口
+ * 对应 better-sqlite3 的 Statement 和 node:sqlite 的 StatementSync
+ */
+export interface ISqliteStatement {
+    /**
+     * 执行语句并返回所有结果行
+     */
+    all(...params: any[]): any[];
+    /**
+     * 执行语句并返回第一行结果
+     */
+    get(...params: any[]): any;
+    /**
+     * 执行语句（用于 INSERT/UPDATE/DELETE）
+     * @returns 包含 changes 和 lastInsertRowid 的对象
+     */
+    run(...params: any[]): ISqliteRunResult;
+}
+/**
+ * Statement.run() 的返回值
+ */
+export interface ISqliteRunResult {
+    /** 受影响的行数 */
+    changes: number | bigint;
+    /** 最后插入行的 rowid */
+    lastInsertRowid: number | bigint;
+}
+/**
+ * SQLite 事务函数类型
+ * better-sqlite3 使用 db.transaction() 返回一个可调用函数
+ * node:sqlite 需要手动管理 BEGIN/COMMIT
+ */
+export type ISqliteTransactionFn<T extends (...args: any[]) => any> = T & {
+    /** 立即执行事务 */
+    immediate: T;
+    /** 独占执行事务 */
+    exclusive: T;
+    /** 延迟执行事务 */
+    deferred: T;
+};
+/**
+ * SQLite Database 抽象接口
+ * 统一 better-sqlite3 和 node:sqlite 的 API 差异
+ */
+export interface ISqliteDatabase {
+    /**
+     * 数据库是否已打开
+     */
+    readonly isOpen: boolean;
+    /**
+     * 准备 SQL 语句
+     * @param sql SQL 语句
+     * @returns 预编译的语句对象
+     */
+    prepare(sql: string): ISqliteStatement;
+    /**
+     * 执行 SQL 语句（不返回结果）
+     * @param sql SQL 语句
+     */
+    exec(sql: string): void;
+    /**
+     * 注册自定义函数
+     * @param name 函数名
+     * @param fn 函数实现
+     */
+    function(name: string, fn: (...args: any[]) => any): void;
+    /**
+     * 创建事务
+     * @param fn 事务函数
+     * @returns 可调用的事务函数
+     */
+    transaction<T extends (...args: any[]) => any>(fn: T): ISqliteTransactionFn<T>;
+    /**
+     * 执行 WAL checkpoint
+     * 用于在压缩数据库文件前确保所有 WAL 数据已写入主文件
+     * @param mode checkpoint 模式，默认 "TRUNCATE"
+     */
+    checkpoint(mode?: "PASSIVE" | "FULL" | "RESTART" | "TRUNCATE"): void;
+    /**
+     * 关闭数据库连接
+     */
+    close(): void;
+}
+/**
+ * SQLite Driver 工厂配置
+ */
+export interface ISqliteDriverConfig {
+    /** 数据库文件路径，":memory:" 表示内存数据库 */
+    filename: string;
+    /** 是否启用 WAL 模式 */
+    walMode?: boolean;
+    /** 数据库繁忙时的等待时间，单位毫秒 */
+    busyTimeout?: number;
+    /** 同步模式: "OFF" | "NORMAL" | "FULL" */
+    synchronous?: "OFF" | "NORMAL" | "FULL";
+}
+/**
+ * SQLite Driver 类型枚举
+ */
+export type SqliteDriverType = "better-sqlite3" | "node:sqlite" | "bun:sqlite";

package/dist/adapter/SQLite/index.d.ts

@@ -1 +1,4 @@
 export { SQLiteAdapter } from "./SQLiteAdapter";
+export type { SQLiteAdapterConfig } from "./SQLiteAdapter";
+export { createSqliteDriver, createAutoSqliteDriver, isSqliteDriverAvailable, BetterSqlite3Driver, NodeSqliteDriver, } from "./driver";
+export type { ISqliteDatabase, ISqliteStatement, ISqliteRunResult, ISqliteDriverConfig, SqliteDriverType, } from "./driver";

package/dist/adapter/SQLite/test/dirty-tracking-bugs.test.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 脏字段检测 (Dirty Tracking) 机制测试
+ *
+ * ✅ 已修复的 BUG：
+ *
+ * 1. [已修复] NaN 值查询返回 0 条结果
+ *    - 根因：mongoToSql.ts 对 NaN 生成错误的类型检查
+ *    - 修复：检测 NaN 并生成 `json_type = 'object'` 条件
+ *
+ * 2. [已修复] Infinity 值查询返回 0 条结果
+ *    - 根因：同上
+ *    - 修复：同上
+ *
+ * 测试覆盖：
+ * 1. 字段类型变化追踪
+ * 2. clearAll 后缓存一致性
+ * 3. 嵌套路径追踪
+ * 4. 特殊值 (NaN, Infinity, null) 追踪和查询
+ * 5. 批量操作追踪
+ * 6. 更新操作追踪（包括 upsert）
+ * 7. 查询策略验证
+ * 8. 并发写入追踪
+ */
+export {};

package/dist/adapter/SQLite/test/dirty-tracking-production.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dirty Tracking 生产环境模拟测试
+ *
+ * 模拟真实生产环境中的各种操作组合：
+ * - 频繁的增删改查
+ * - 字段类型动态变化
+ * - 并发操作
+ * - 大量数据操作
+ * - 复杂查询场景
+ */
+export {};