@yunzai-ng/core 0.1.0

package/dist/store/level.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 模块职责：内嵌 LevelDB KV 驱动（默认驱动）
+ * 依赖方向：动态依赖可选原生模块 classic-level；依赖类型包
+ * 生命周期：`open()` 打开数据库目录，`close()` 关闭并 flush
+ * 注意事项：classic-level 是 **optionalDependency**（原生模块，Termux 上可能编不出来），
+ *          所以这里用动态 `import()` 且**不引用它的类型** —— 只声明自己真正用到的
+ *          那几个方法。这样在没装成功的机器上，整个内核依然能编译、能跑，
+ *          由 `openKv()` 自动降级到 json 驱动。
+ *
+ *          刻意不实现 `incr`：LevelDB 没有原子自增原语，硬写成 get+put 会在并发下
+ *          丢计数。留空让上层的按键串行队列接管，语义才是对的。
+ */
+import type { KvBatchOp, KvDriver, StoredEnvelope } from "@yunzai-ng/types";
+/** classic-level 中本驱动实际用到的最小面 */
+interface LevelDb {
+    /** 打开数据库 */
+    open(): Promise<void>;
+    /** 关闭数据库 */
+    close(): Promise<void>;
+    /** 读取，缺失返回 undefined（abstract-level 2.x 语义） */
+    get(key: string): Promise<StoredEnvelope | undefined>;
+    /** 写入 */
+    put(key: string, value: StoredEnvelope): Promise<void>;
+    /** 删除 */
+    del(key: string): Promise<void>;
+    /** 批量写入/删除 */
+    batch(ops: {
+        type: "put" | "del";
+        key: string;
+        value?: StoredEnvelope;
+    }[]): Promise<void>;
+    /** 范围迭代器 */
+    iterator(opts: {
+        gte?: string;
+    }): LevelIterator;
+}
+/** classic-level 的迭代器最小面 */
+interface LevelIterator extends AsyncIterable<[string, StoredEnvelope]> {
+    /** 关闭迭代器，释放底层快照 */
+    close(): Promise<void>;
+}
+/** classic-level 的构造签名 */
+type LevelCtor = new (location: string, opts: {
+    valueEncoding: "json";
+}) => LevelDb;
+/**
+ * 尝试加载 classic-level
+ * @returns 构造函数；模块不可用时 undefined
+ */
+export declare function loadLevel(): Promise<LevelCtor | undefined>;
+/** 内嵌 LevelDB KV 驱动 */
+export declare class LevelKvDriver implements KvDriver {
+    #private;
+    /** 驱动 id */
+    readonly id = "level";
+    /**
+     * @param dir 数据库目录
+     * @param ctor classic-level 构造函数，由 `loadLevel()` 提供
+     */
+    constructor(dir: string, ctor: LevelCtor);
+    /** 数据库目录 */
+    get dir(): string;
+    /**
+     * 打开数据库
+     * @throws 目录被另一个进程锁住时（LevelDB 是单进程独占）
+     */
+    open(): Promise<void>;
+    /** 关闭数据库 */
+    close(): Promise<void>;
+    /**
+     * 读取
+     * @param key 完整键
+     * @returns 值信封；不存在时 undefined
+     */
+    get(key: string): Promise<StoredEnvelope | undefined>;
+    /**
+     * 写入
+     * @param key 完整键
+     * @param value 值信封
+     */
+    set(key: string, value: StoredEnvelope): Promise<void>;
+    /**
+     * 删除
+     * @param key 完整键
+     */
+    del(key: string): Promise<void>;
+    /**
+     * 批量操作（LevelDB 的原子批写）
+     * @param ops 操作列表
+     */
+    batch(ops: KvBatchOp[]): Promise<void>;
+    /**
+     * 按前缀扫描
+     *
+     * 只给出 `gte` 而不给上界，依靠"键按字节序排列 ⇒ 同前缀的键连续"提前结束。
+     * 较自行计算 `lt` 上界更可靠：手工计算上界一旦遇到 emoji 一类四字节字符即会漏键。
+     * @param prefix 键前缀
+     * @returns 键值对迭代器
+     */
+    scan(prefix: string): AsyncIterableIterator<readonly [string, StoredEnvelope]>;
+}
+export {};
+//# sourceMappingURL=level.d.ts.map

package/dist/store/level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.d.ts","sourceRoot":"","sources":["../../src/store/level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAG3E,iCAAiC;AACjC,UAAU,OAAO;IACf,YAAY;IACZ,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,YAAY;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,+CAA+C;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;IACrD,SAAS;IACT,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,SAAS;IACT,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,cAAc;IACd,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,cAAc,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzF,YAAY;IACZ,QAAQ,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,CAAA;CAChD;AAED,4BAA4B;AAC5B,UAAU,aAAc,SAAQ,aAAa,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrE,mBAAmB;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,0BAA0B;AAC1B,KAAK,SAAS,GAAG,KAAK,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAA;AAEnF;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOhE;AAED,uBAAuB;AACvB,qBAAa,aAAc,YAAW,QAAQ;;IAC5C,YAAY;IACZ,QAAQ,CAAC,EAAE,WAAU;IASrB;;;OAGG;gBACS,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS;IAKxC,YAAY;IACZ,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,YAAY;IACN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAI3D;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C;;;;;;;OAOG;IACI,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAsBtF"}

package/dist/store/level.js

@@ -0,0 +1,119 @@
+import { ensureDir } from "../util/fs.js";
+/**
+ * 尝试加载 classic-level
+ * @returns 构造函数；模块不可用时 undefined
+ */
+export async function loadLevel() {
+    try {
+        const mod = (await import("classic-level"));
+        return mod.ClassicLevel;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 内嵌 LevelDB KV 驱动 */
+export class LevelKvDriver {
+    /** 驱动 id */
+    id = "level";
+    /** 数据库目录 */
+    #dir;
+    /** 构造函数 */
+    #ctor;
+    /** 数据库实例 */
+    #db;
+    /**
+     * @param dir 数据库目录
+     * @param ctor classic-level 构造函数，由 `loadLevel()` 提供
+     */
+    constructor(dir, ctor) {
+        this.#dir = dir;
+        this.#ctor = ctor;
+    }
+    /** 数据库目录 */
+    get dir() {
+        return this.#dir;
+    }
+    /**
+     * 打开数据库
+     * @throws 目录被另一个进程锁住时（LevelDB 是单进程独占）
+     */
+    async open() {
+        await ensureDir(this.#dir);
+        const db = new this.#ctor(this.#dir, { valueEncoding: "json" });
+        await db.open();
+        this.#db = db;
+    }
+    /** 关闭数据库 */
+    async close() {
+        const db = this.#db;
+        this.#db = undefined;
+        if (db)
+            await db.close();
+    }
+    /**
+     * 读取
+     * @param key 完整键
+     * @returns 值信封；不存在时 undefined
+     */
+    async get(key) {
+        return this.#require().get(key);
+    }
+    /**
+     * 写入
+     * @param key 完整键
+     * @param value 值信封
+     */
+    async set(key, value) {
+        await this.#require().put(key, value);
+    }
+    /**
+     * 删除
+     * @param key 完整键
+     */
+    async del(key) {
+        await this.#require().del(key);
+    }
+    /**
+     * 批量操作（LevelDB 的原子批写）
+     * @param ops 操作列表
+     */
+    async batch(ops) {
+        if (ops.length === 0)
+            return;
+        await this.#require().batch(ops.map(op => (op.op === "set" ? { type: "put", key: op.key, value: op.value } : { type: "del", key: op.key })));
+    }
+    /**
+     * 按前缀扫描
+     *
+     * 只给出 `gte` 而不给上界，依靠"键按字节序排列 ⇒ 同前缀的键连续"提前结束。
+     * 较自行计算 `lt` 上界更可靠：手工计算上界一旦遇到 emoji 一类四字节字符即会漏键。
+     * @param prefix 键前缀
+     * @returns 键值对迭代器
+     */
+    async *scan(prefix) {
+        const it = this.#require().iterator({ gte: prefix });
+        try {
+            for await (const [key, value] of it) {
+                if (!key.startsWith(prefix))
+                    break;
+                yield [key, value];
+            }
+        }
+        finally {
+            // 迭代器持有底层快照，不关会一直占着 sst 文件不让压缩
+            await it.close().catch(() => undefined);
+        }
+    }
+    /**
+     * 取已打开的数据库
+     * @returns 数据库实例
+     * @throws 未 open 时
+     */
+    #require() {
+        if (!this.#db)
+            throw new Error("LevelDB 尚未打开，请先调用 open()");
+        return this.#db;
+    }
+}
+//# sourceMappingURL=level.js.map

package/dist/store/level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.js","sourceRoot":"","sources":["../../src/store/level.ts"],"names":[],"mappings":"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"}

package/dist/store/memory.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 模块职责：内存 KV 驱动（测试与"仅内存"模式）
+ * 依赖方向：依赖类型包与 util/deep
+ * 生命周期：`close()` 后可再 `open()`
+ * 注意事项：**存取都做深拷贝**。若直接存引用，调用方在 set 之后修改对象会连带改掉
+ *          "已落盘"的值；这样内存驱动下能跑通的代码换到 level/json 驱动就会出错，
+ *          属于最难查的一类问题。宁可多一次拷贝，也要让三种驱动语义完全一致。
+ */
+import type { KvBatchOp, KvDriver, StoredEnvelope } from "@yunzai-ng/types";
+/** 内存 KV 驱动 */
+export declare class MemoryKvDriver implements KvDriver {
+    #private;
+    /** 驱动 id */
+    readonly id = "memory";
+    /** 键数量（含未清理的过期键），仅用于调试与面板展示 */
+    get size(): number;
+    /** 打开（内存驱动无需准备） */
+    open(): Promise<void>;
+    /** 关闭并清空 */
+    close(): Promise<void>;
+    /**
+     * 读取
+     * @param key 完整键
+     * @returns 值信封的副本
+     */
+    get(key: string): Promise<StoredEnvelope | undefined>;
+    /**
+     * 写入
+     * @param key 完整键
+     * @param value 值信封
+     */
+    set(key: string, value: StoredEnvelope): Promise<void>;
+    /**
+     * 删除
+     * @param key 完整键
+     */
+    del(key: string): Promise<void>;
+    /**
+     * 批量操作
+     * @param ops 操作列表
+     */
+    batch(ops: KvBatchOp[]): Promise<void>;
+    /**
+     * 按前缀扫描
+     * @param prefix 键前缀
+     * @returns 键值对迭代器
+     */
+    scan(prefix: string): AsyncIterableIterator<readonly [string, StoredEnvelope]>;
+    /**
+     * 原生原子自增
+     *
+     * 单线程 JS 里同步的读改写天然原子，故内存驱动可以直接提供，
+     * 免掉上层的串行队列开销。
+     * @param key 完整键
+     * @param by 增量
+     * @param expireAt 首次创建时的过期时间点
+     * @returns 自增后的值
+     */
+    incr(key: string, by: number, expireAt?: number): Promise<number>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/store/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/store/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAI3E,eAAe;AACf,qBAAa,cAAe,YAAW,QAAQ;;IAC7C,YAAY;IACZ,QAAQ,CAAC,EAAE,YAAW;IAKtB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mBAAmB;IACb,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,YAAY;IACN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAK3D;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C;;;;OAIG;IACI,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAWrF;;;;;;;;;OASG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CASxE"}

package/dist/store/memory.js

@@ -0,0 +1,94 @@
+import { deepClone } from "../util/deep.js";
+import { isExpired } from "./kv.js";
+/** 内存 KV 驱动 */
+export class MemoryKvDriver {
+    /** 驱动 id */
+    id = "memory";
+    /** 数据表 */
+    #map = new Map();
+    /** 键数量（含未清理的过期键），仅用于调试与面板展示 */
+    get size() {
+        return this.#map.size;
+    }
+    /** 打开（内存驱动无需准备） */
+    async open() {
+        // 无操作
+    }
+    /** 关闭并清空 */
+    async close() {
+        this.#map.clear();
+    }
+    /**
+     * 读取
+     * @param key 完整键
+     * @returns 值信封的副本
+     */
+    async get(key) {
+        const env = this.#map.get(key);
+        return env === undefined ? undefined : deepClone(env);
+    }
+    /**
+     * 写入
+     * @param key 完整键
+     * @param value 值信封
+     */
+    async set(key, value) {
+        this.#map.set(key, deepClone(value));
+    }
+    /**
+     * 删除
+     * @param key 完整键
+     */
+    async del(key) {
+        this.#map.delete(key);
+    }
+    /**
+     * 批量操作
+     * @param ops 操作列表
+     */
+    async batch(ops) {
+        for (const op of ops) {
+            if (op.op === "set")
+                this.#map.set(op.key, deepClone(op.value));
+            else
+                this.#map.delete(op.key);
+        }
+    }
+    /**
+     * 按前缀扫描
+     * @param prefix 键前缀
+     * @returns 键值对迭代器
+     */
+    async *scan(prefix) {
+        // 先快照键集合：调用方在遍历中删除过期键是正常用法，
+        // 直接迭代 Map 会撞上"遍历中修改"的未定义顺序
+        for (const key of [...this.#map.keys()]) {
+            if (!key.startsWith(prefix))
+                continue;
+            const env = this.#map.get(key);
+            if (env === undefined)
+                continue;
+            yield [key, deepClone(env)];
+        }
+    }
+    /**
+     * 原生原子自增
+     *
+     * 单线程 JS 里同步的读改写天然原子，故内存驱动可以直接提供，
+     * 免掉上层的串行队列开销。
+     * @param key 完整键
+     * @param by 增量
+     * @param expireAt 首次创建时的过期时间点
+     * @returns 自增后的值
+     */
+    async incr(key, by, expireAt) {
+        const env = this.#map.get(key);
+        const alive = env !== undefined && !isExpired(env);
+        const current = alive && typeof env.v === "number" ? env.v : 0;
+        const next = current + by;
+        const keep = alive ? env.e : expireAt;
+        this.#map.set(key, keep === undefined ? { v: next } : { v: next, e: keep });
+        return next;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/store/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/store/memory.ts"],"names":[],"mappings":"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"}

package/dist/store/sql.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 模块职责：SQLite 关系存储（语句缓存、异步事务、迁移）
+ * 依赖方向：动态依赖可选原生模块 better-sqlite3；依赖 util/{lru,queue}、类型包
+ * 生命周期：`openSql()` 打开，`close()` 关闭
+ * 注意事项：**不引 ORM**，只暴露 run/all/get/transaction/migrate。
+ *
+ *          **事务手写 BEGIN/COMMIT 并用互斥锁串行化**：better-sqlite3 的 `db.transaction()`
+ *          只收同步函数，而本框架的接口是异步的（要容得下别的驱动）。一条连接上开不了两个
+ *          事务，故事务之间必须排队；嵌套事务改用 SAVEPOINT，不重复抢锁。
+ *
+ *          **语句缓存有界。** `prepare()` 有真实开销，但无上限的缓存在动态拼 SQL 的插件手里
+ *          就是内存泄漏。
+ */
+import type { SqlHandle, SqlMigration, SqlParam } from "@yunzai-ng/types";
+import { LruCache } from "../util/lru.js";
+import { Semaphore } from "../util/queue.js";
+/** better-sqlite3 的语句最小面 */
+interface SqliteStatement {
+    /** 执行不取行 */
+    run(...params: SqlParam[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** 取全部行 */
+    all(...params: SqlParam[]): unknown[];
+    /** 取首行 */
+    get(...params: SqlParam[]): unknown;
+}
+/** better-sqlite3 的连接最小面 */
+interface SqliteDb {
+    /** 预编译语句 */
+    prepare(sql: string): SqliteStatement;
+    /** 直接执行脚本（可含多条语句，不支持绑定参数） */
+    exec(sql: string): void;
+    /** 读写 pragma */
+    pragma(source: string): unknown;
+    /** 关闭连接 */
+    close(): void;
+}
+/** better-sqlite3 的构造签名 */
+type SqliteCtor = new (file: string, opts?: {
+    readonly?: boolean;
+}) => SqliteDb;
+/** 一条连接上的共享状态 */
+interface SqlState {
+    /** 连接 */
+    db: SqliteDb;
+    /** 语句缓存 */
+    stmts: LruCache<SqliteStatement>;
+    /** 事务互斥锁 */
+    mutex: Semaphore;
+    /** SAVEPOINT 命名计数器 */
+    savepoint: number;
+}
+/**
+ * 尝试加载 better-sqlite3
+ * @returns 构造函数；模块不可用时 undefined
+ */
+export declare function loadSqlite(): Promise<SqliteCtor | undefined>;
+/**
+ * SQLite 句柄
+ *
+ * 根句柄由 `openSql()` 创建；事务内传给回调的是 `depth > 0` 的子句柄，
+ * 它们共享同一条连接，因此**不能**在事务回调里持有子句柄留到事务外使用。
+ */
+export declare class SqliteHandle implements SqlHandle {
+    #private;
+    /**
+     * @param state 共享状态
+     * @param depth 事务嵌套深度
+     */
+    constructor(state: SqlState, depth?: number);
+    /**
+     * 执行不返回行的语句
+     *
+     * 不带参数且含多条语句时走 `exec()`，方便迁移里一次建表 + 建索引；
+     * 这种情况下无法报告受影响行数，返回 0。
+     * @param sql SQL 文本
+     * @param params 绑定参数
+     * @returns 受影响行数与最后插入 id
+     */
+    run(sql: string, params?: SqlParam[]): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+    /**
+     * 查询多行
+     * @param sql SQL 文本
+     * @param params 绑定参数
+     * @returns 结果行数组
+     */
+    all<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T[]>;
+    /**
+     * 查询首行
+     * @param sql SQL 文本
+     * @param params 绑定参数
+     * @returns 首行；无结果时 undefined
+     */
+    get<T = Record<string, unknown>>(sql: string, params?: SqlParam[]): Promise<T | undefined>;
+    /**
+     * 在事务中执行
+     *
+     * 最外层用 `BEGIN IMMEDIATE`（立刻拿写锁，避免升级锁时才发现冲突而整段重来）；
+     * 嵌套层用 SAVEPOINT，实现"内层回滚不牵连外层"。
+     * @param fn 事务体，抛错即回滚
+     * @returns 事务体的返回值
+     */
+    transaction<T>(fn: (tx: SqlHandle) => Promise<T>): Promise<T>;
+    /**
+     * 应用迁移
+     *
+     * 每条迁移单独一个事务：失败只回滚这一条，已成功的保持生效，修好后重跑从断点继续。
+     * 版本号落在迁移表里，故"这个库到哪一版了"有确定答案，不必靠"存在则忽略"的 try/catch。
+     * @param migrations 迁移列表
+     * @throws 版本号未严格递增，或某条迁移执行失败
+     */
+    migrate(migrations: SqlMigration[]): Promise<void>;
+}
+/** 打开 SQL 存储的参数 */
+export interface OpenSqlOptions {
+    /** 数据库文件绝对路径 */
+    file: string;
+    /** 构造函数，缺省自动加载 */
+    ctor?: SqliteCtor;
+}
+/** 已打开的 SQL 存储 */
+export interface SqlStore {
+    /** 句柄 */
+    readonly handle: SqlHandle;
+    /** 数据库文件路径 */
+    readonly file: string;
+    /** 关闭连接 */
+    close(): void;
+}
+/**
+ * 打开 SQLite 数据库
+ * @param opts 参数
+ * @returns 已打开的 SQL 存储；原生模块不可用时 undefined（调用方应降级为纯 KV）
+ */
+export declare function openSql(opts: OpenSqlOptions): Promise<SqlStore | undefined>;
+export {};
+//# sourceMappingURL=sql.d.ts.map

package/dist/store/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/store/sql.ts"],"names":[],"mappings":"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"}