@yunzai-ng/core 0.1.0

package/src/store/level.ts

@@ -0,0 +1,167 @@
+/**
+ * 模块职责：内嵌 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"
+import { ensureDir } from "../util/fs.js"
+
+/** 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 async function loadLevel(): Promise<LevelCtor | undefined> {
+  try {
+    const mod = (await import("classic-level")) as unknown as { ClassicLevel?: LevelCtor }
+    return mod.ClassicLevel
+  } catch {
+    return undefined
+  }
+}
+
+/** 内嵌 LevelDB KV 驱动 */
+export class LevelKvDriver implements KvDriver {
+  /** 驱动 id */
+  readonly id = "level"
+
+  /** 数据库目录 */
+  readonly #dir: string
+  /** 构造函数 */
+  readonly #ctor: LevelCtor
+  /** 数据库实例 */
+  #db: LevelDb | undefined
+
+  /**
+   * @param dir 数据库目录
+   * @param ctor classic-level 构造函数，由 `loadLevel()` 提供
+   */
+  constructor(dir: string, ctor: LevelCtor) {
+    this.#dir = dir
+    this.#ctor = ctor
+  }
+
+  /** 数据库目录 */
+  get dir(): string {
+    return this.#dir
+  }
+
+  /**
+   * 打开数据库
+   * @throws 目录被另一个进程锁住时（LevelDB 是单进程独占）
+   */
+  async open(): Promise<void> {
+    await ensureDir(this.#dir)
+    const db = new this.#ctor(this.#dir, { valueEncoding: "json" })
+    await db.open()
+    this.#db = db
+  }
+
+  /** 关闭数据库 */
+  async close(): Promise<void> {
+    const db = this.#db
+    this.#db = undefined
+    if (db) await db.close()
+  }
+
+  /**
+   * 读取
+   * @param key 完整键
+   * @returns 值信封；不存在时 undefined
+   */
+  async get(key: string): Promise<StoredEnvelope | undefined> {
+    return this.#require().get(key)
+  }
+
+  /**
+   * 写入
+   * @param key 完整键
+   * @param value 值信封
+   */
+  async set(key: string, value: StoredEnvelope): Promise<void> {
+    await this.#require().put(key, value)
+  }
+
+  /**
+   * 删除
+   * @param key 完整键
+   */
+  async del(key: string): Promise<void> {
+    await this.#require().del(key)
+  }
+
+  /**
+   * 批量操作（LevelDB 的原子批写）
+   * @param ops 操作列表
+   */
+  async batch(ops: KvBatchOp[]): Promise<void> {
+    if (ops.length === 0) return
+    await this.#require().batch(
+      ops.map(op => (op.op === "set" ? { type: "put" as const, key: op.key, value: op.value } : { type: "del" as const, key: op.key }))
+    )
+  }
+
+  /**
+   * 按前缀扫描
+   *
+   * 只给出 `gte` 而不给上界，依靠"键按字节序排列 ⇒ 同前缀的键连续"提前结束。
+   * 较自行计算 `lt` 上界更可靠：手工计算上界一旦遇到 emoji 一类四字节字符即会漏键。
+   * @param prefix 键前缀
+   * @returns 键值对迭代器
+   */
+  async *scan(prefix: string): AsyncIterableIterator<readonly [string, StoredEnvelope]> {
+    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(): LevelDb {
+    if (!this.#db) throw new Error("LevelDB 尚未打开，请先调用 open()")
+    return this.#db
+  }
+}

package/src/store/memory.ts

@@ -0,0 +1,109 @@
+/**
+ * 模块职责：内存 KV 驱动（测试与"仅内存"模式）
+ * 依赖方向：依赖类型包与 util/deep
+ * 生命周期：`close()` 后可再 `open()`
+ * 注意事项：**存取都做深拷贝**。若直接存引用，调用方在 set 之后修改对象会连带改掉
+ *          "已落盘"的值；这样内存驱动下能跑通的代码换到 level/json 驱动就会出错，
+ *          属于最难查的一类问题。宁可多一次拷贝，也要让三种驱动语义完全一致。
+ */
+import type { KvBatchOp, KvDriver, StoredEnvelope } from "@yunzai-ng/types"
+import { deepClone } from "../util/deep.js"
+import { isExpired } from "./kv.js"
+
+/** 内存 KV 驱动 */
+export class MemoryKvDriver implements KvDriver {
+  /** 驱动 id */
+  readonly id = "memory"
+
+  /** 数据表 */
+  readonly #map = new Map<string, StoredEnvelope>()
+
+  /** 键数量（含未清理的过期键），仅用于调试与面板展示 */
+  get size(): number {
+    return this.#map.size
+  }
+
+  /** 打开（内存驱动无需准备） */
+  async open(): Promise<void> {
+    // 无操作
+  }
+
+  /** 关闭并清空 */
+  async close(): Promise<void> {
+    this.#map.clear()
+  }
+
+  /**
+   * 读取
+   * @param key 完整键
+   * @returns 值信封的副本
+   */
+  async get(key: string): Promise<StoredEnvelope | undefined> {
+    const env = this.#map.get(key)
+    return env === undefined ? undefined : deepClone(env)
+  }
+
+  /**
+   * 写入
+   * @param key 完整键
+   * @param value 值信封
+   */
+  async set(key: string, value: StoredEnvelope): Promise<void> {
+    this.#map.set(key, deepClone(value))
+  }
+
+  /**
+   * 删除
+   * @param key 完整键
+   */
+  async del(key: string): Promise<void> {
+    this.#map.delete(key)
+  }
+
+  /**
+   * 批量操作
+   * @param ops 操作列表
+   */
+  async batch(ops: KvBatchOp[]): Promise<void> {
+    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: string): AsyncIterableIterator<readonly [string, StoredEnvelope]> {
+    // 先快照键集合：调用方在遍历中删除过期键是正常用法，
+    // 直接迭代 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: string, by: number, expireAt?: number): Promise<number> {
+    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
+  }
+}

package/src/store/sql.test.ts

@@ -0,0 +1,204 @@
+/**
+ * 模块职责：SQLite 存储的行为测试
+ * 依赖方向：测试文件
+ * 生命周期：每个用例一个临时数据库文件
+ * 注意事项：better-sqlite3 是可选原生模块，装不上时整组跳过而不是报红。
+ *          重点覆盖异步事务的正确性 —— 这是本模块唯一有真实并发风险的地方。
+ */
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import type { SqlHandle, SqlMigration } from "@yunzai-ng/types"
+import { loadSqlite, openSql, type SqlStore } from "./sql.js"
+
+const ctor = await loadSqlite()
+
+describe.skipIf(!ctor)("SQLite 存储", () => {
+  let dir: string
+  let store: SqlStore
+  let db: SqlHandle
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "yzng-sql-"))
+    const opened = await openSql({ file: join(dir, "data.db"), ctor })
+    store = opened!
+    db = store.handle
+    await db.run("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT, n INTEGER DEFAULT 0)")
+  })
+
+  afterEach(async () => {
+    store.close()
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it("run / all / get 的基本语义", async () => {
+    const inserted = await db.run("INSERT INTO t (name, n) VALUES (?, ?)", ["甲", 1])
+    expect(inserted.changes).toBe(1)
+    expect(Number(inserted.lastInsertRowid)).toBe(1)
+
+    await db.run("INSERT INTO t (name, n) VALUES (?, ?)", ["乙", 2])
+    expect(await db.all("SELECT name FROM t ORDER BY id")).toEqual([{ name: "甲" }, { name: "乙" }])
+    expect(await db.get("SELECT n FROM t WHERE name = ?", ["乙"])).toEqual({ n: 2 })
+    // 无结果统一返回 undefined，而不是 null
+    expect(await db.get("SELECT n FROM t WHERE name = ?", ["丙"])).toBeUndefined()
+  })
+
+  it("不带参数的多语句脚本可以一次执行（迁移常用）", async () => {
+    await db.run(`
+      CREATE TABLE a (id INTEGER PRIMARY KEY);
+      CREATE INDEX idx_a ON a (id);
+    `)
+    const tables = await db.all<{ name: string }>("SELECT name FROM sqlite_master WHERE type = 'table'")
+    expect(tables.map(r => r.name)).toContain("a")
+  })
+
+  it("语句里的分号字面量不会被误判成多语句", async () => {
+    await db.run("INSERT INTO t (name) VALUES (?)", ["带;分号"])
+    expect(await db.get("SELECT name FROM t WHERE name = ?", ["带;分号"])).toEqual({ name: "带;分号" })
+  })
+
+  it("事务提交后数据可见", async () => {
+    await db.transaction(async tx => {
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["甲"])
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["乙"])
+    })
+    expect(await db.get("SELECT COUNT(*) AS c FROM t")).toEqual({ c: 2 })
+  })
+
+  it("事务体抛错时整体回滚，错误照原样冒出", async () => {
+    await expect(
+      db.transaction(async tx => {
+        await tx.run("INSERT INTO t (name) VALUES (?)", ["甲"])
+        throw new Error("业务失败")
+      })
+    ).rejects.toThrow("业务失败")
+
+    expect(await db.get("SELECT COUNT(*) AS c FROM t")).toEqual({ c: 0 })
+  })
+
+  it("事务里 await 别的异步操作也不会串台（互斥锁生效）", async () => {
+    // 两个事务同时开：若没有互斥锁，第二个 BEGIN 会撞上
+    // "cannot start a transaction within a transaction"
+    const one = db.transaction(async tx => {
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["甲"])
+      await new Promise(r => setTimeout(r, 30))
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["乙"])
+    })
+    const two = db.transaction(async tx => {
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["丙"])
+    })
+
+    await Promise.all([one, two])
+    expect(await db.get("SELECT COUNT(*) AS c FROM t")).toEqual({ c: 3 })
+  })
+
+  it("并发事务不会互相回滚对方的写入", async () => {
+    await db.run("INSERT INTO t (id, name, n) VALUES (1, '计数', 0)")
+
+    const bump = () =>
+      db.transaction(async tx => {
+        const row = await tx.get<{ n: number }>("SELECT n FROM t WHERE id = 1")
+        await tx.run("UPDATE t SET n = ? WHERE id = 1", [(row?.n ?? 0) + 1])
+      })
+
+    await Promise.all(Array.from({ length: 20 }, bump))
+    expect(await db.get("SELECT n FROM t WHERE id = 1")).toEqual({ n: 20 })
+  })
+
+  it("嵌套事务用 SAVEPOINT：内层回滚不牵连外层", async () => {
+    await db.transaction(async tx => {
+      await tx.run("INSERT INTO t (name) VALUES (?)", ["外层"])
+      await expect(
+        tx.transaction(async inner => {
+          await inner.run("INSERT INTO t (name) VALUES (?)", ["内层"])
+          throw new Error("内层失败")
+        })
+      ).rejects.toThrow("内层失败")
+    })
+
+    const names = await db.all<{ name: string }>("SELECT name FROM t")
+    expect(names.map(r => r.name)).toEqual(["外层"])
+  })
+
+  it("迁移按版本号依次执行且幂等", async () => {
+    const log: string[] = []
+    const migrations: SqlMigration[] = [
+      {
+        version: 2,
+        name: "加索引",
+        up: async tx => {
+          log.push("v2")
+          await tx.run("CREATE INDEX idx_name ON t (name)")
+        }
+      },
+      {
+        version: 1,
+        name: "建表",
+        up: async tx => {
+          log.push("v1")
+          await tx.run("CREATE TABLE m (id INTEGER PRIMARY KEY)")
+        }
+      }
+    ]
+
+    await db.migrate(migrations)
+    expect(log).toEqual(["v1", "v2"])
+
+    // 再跑一次什么都不该发生
+    await db.migrate(migrations)
+    expect(log).toEqual(["v1", "v2"])
+
+    // 新增一条只跑新的
+    migrations.push({
+      version: 3,
+      name: "再加一张表",
+      up: async tx => {
+        log.push("v3")
+        await tx.run("CREATE TABLE m2 (id INTEGER PRIMARY KEY)")
+      }
+    })
+    await db.migrate(migrations)
+    expect(log).toEqual(["v1", "v2", "v3"])
+  })
+
+  it("迁移失败时该条回滚，且不会被记为已应用", async () => {
+    const migrations: SqlMigration[] = [
+      {
+        version: 1,
+        name: "会失败的迁移",
+        up: async tx => {
+          await tx.run("CREATE TABLE ok (id INTEGER PRIMARY KEY)")
+          await tx.run("这不是 SQL")
+        }
+      }
+    ]
+
+    await expect(db.migrate(migrations)).rejects.toThrow()
+
+    const tables = await db.all<{ name: string }>("SELECT name FROM sqlite_master WHERE type = 'table'")
+    expect(tables.map(r => r.name)).not.toContain("ok")
+    expect(await db.get("SELECT COUNT(*) AS c FROM _yzng_migrations")).toEqual({ c: 0 })
+  })
+
+  it("版本号重复直接报错，而不是随机执行一条", async () => {
+    await expect(
+      db.migrate([
+        { version: 1, name: "甲", up: async () => undefined },
+        { version: 1, name: "乙", up: async () => undefined }
+      ])
+    ).rejects.toThrow(/重复/)
+  })
+
+  it("重开文件后数据仍在", async () => {
+    await db.run("INSERT INTO t (name) VALUES (?)", ["持久"])
+    const file = store.file
+    store.close()
+
+    const reopened = (await openSql({ file, ctor }))!
+    expect(await reopened.handle.get("SELECT name FROM t")).toEqual({ name: "持久" })
+    reopened.close()
+    // afterEach 会再 close 一次，close 必须可重复调用
+    store = reopened
+  })
+})