@morlay/rdbkit 0.0.0-stage → 0.0.1-alpha.2

package/dist/testing.d.mts

@@ -0,0 +1,28 @@
+import { DatabaseSync } from "node:sqlite";
+/**
+ * 测试专用句柄：造损坏数据、读 `PRAGMA` 这类只有同步驱动才做得到的事。
+ *
+ * 生产路径不经过这里——业务侧拿的是 `Database`（`openDatabase`），没有同步口。
+ * @param path - SQLite 库文件路径。
+ * @param options - 与打开库时一致的 busy timeout / journal mode。
+ * @returns 同步句柄（用完要 `close()`）。
+ */
+export declare function openSqliteHandle(path: string, options?: {
+  journalMode?: string;
+  busyTimeout?: number;
+}): DatabaseSync;
+/** 一个临时的 PostgreSQL 测试库：用完必须 `drop()`。 */
+export interface PostgresTestDatabase {
+  connectionString: string;
+  drop: () => Promise<void>;
+}
+/**
+ * 建一个随机名的 PostgreSQL 测试库（用完 drop）。
+ *
+ * 建库是管理面操作：业务侧的 `Database` 不提供它，测试要独立库时用这里。
+ * @param options - `adminUrl` 指向有建库权限的连接串；省略时读 `TEST_PG_URL`。
+ * @returns 指向新库的连接串与清理函数。
+ */
+export declare function createPostgresTestDatabase(options?: {
+  adminUrl?: string;
+}): Promise<PostgresTestDatabase>;

package/dist/testing.mjs

@@ -0,0 +1,42 @@
+import { Client } from "pg";
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+// src/testing.ts
+/**
+* 测试专用句柄：造损坏数据、读 `PRAGMA` 这类只有同步驱动才做得到的事。
+*
+* 生产路径不经过这里——业务侧拿的是 `Database`（`openDatabase`），没有同步口。
+* @param path - SQLite 库文件路径。
+* @param options - 与打开库时一致的 busy timeout / journal mode。
+* @returns 同步句柄（用完要 `close()`）。
+*/
+function openSqliteHandle(path, options = {}) {
+	const client = new DatabaseSync(path);
+	client.exec(`PRAGMA busy_timeout = ${options.busyTimeout ?? 5e3}`);
+	if (options.journalMode !== void 0) client.exec(`PRAGMA journal_mode = ${options.journalMode}`);
+	return client;
+}
+/**
+* 建一个随机名的 PostgreSQL 测试库（用完 drop）。
+*
+* 建库是管理面操作：业务侧的 `Database` 不提供它，测试要独立库时用这里。
+* @param options - `adminUrl` 指向有建库权限的连接串；省略时读 `TEST_PG_URL`。
+* @returns 指向新库的连接串与清理函数。
+*/
+async function createPostgresTestDatabase(options = {}) {
+	const adminUrl = options.adminUrl ?? process.env["TEST_PG_URL"] ?? "postgres://postgres:postgres@localhost:25433/postgres";
+	const name = `dsh_test_${randomUUID().replaceAll("-", "")}`;
+	const admin = new Client({ connectionString: adminUrl });
+	await admin.connect();
+	await admin.query(`CREATE DATABASE "${name}"`);
+	const url = new URL(adminUrl);
+	url.pathname = `/${name}`;
+	return {
+		connectionString: url.toString(),
+		drop: async () => {
+			await admin.query(`DROP DATABASE IF EXISTS "${name}" WITH (FORCE)`);
+			await admin.end();
+		}
+	};
+}
+export { createPostgresTestDatabase, openSqliteHandle };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@morlay/rdbkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1-alpha.2",
+  "description": "Schema-first RDB kit for DeepSeek Harness plugins: one table definition drives the DDL, the typed table handles and the startup migration for SQLite and PostgreSQL alike; business code only ever sees an injected Database.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "postgres",
+    "rdb",
+    "schema",
+    "sqlite"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/dsh-plugin.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.mts",
+      "default": "./dist/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "pg": "^8.23.0",
+    "pg-cursor": "^2.22.1"
+  },
+  "devDependencies": {
+    "@local/devkit": "0.1.0",
+    "@local/tsdown-plugin-cordis": "0.1.0",
+    "@types/node": "^26.6.5",
+    "@types/pg": "^8.23.1",
+    "@types/pg-cursor": "^2.7.2"
+  },
+  "engines": {
+    "node": ">=24.11.0",
+    "dsh": ">= 0.2.2-alpha.2 < 0.2.3"
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown"
+  }
 }

package/src/__tests__/database-introspect.spec.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineTable, ensureSchema, openDatabase } from "../index.ts";
+
+const dirs: string[] = [];
+afterEach(async () => {
+  for (const dir of dirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+async function tempFile(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "rdbkit-pragma-"));
+  dirs.push(dir);
+  return join(dir, "store.sqlite");
+}
+
+const notes = defineTable({
+  name: "t_introspect_notes",
+  columns: { f_id: { type: "text", primaryKey: true, notNull: true } },
+});
+
+describe("库级操作（业务侧不写 PRAGMA / VACUUM）", () => {
+  it("objectNames：返回现有的表与视图名", async () => {
+    const database = await openDatabase({ dialect: "sqlite", path: ":memory:" });
+    try {
+      await ensureSchema(database, [notes]);
+      expect(await database.objectNames()).toContain("t_introspect_notes");
+    } finally {
+      await database.close();
+    }
+  });
+
+  it("sqlitePragma：读写库身份（user_version / application_id / journal_mode）", async () => {
+    // journal_mode 在 `:memory:` 上只能是 `memory`，所以用文件库。
+    const database = await openDatabase({ dialect: "sqlite", path: await tempFile() });
+    try {
+      expect(await database.sqlitePragma("user_version")).toBe(0);
+      await database.setSqlitePragma("user_version", 7);
+      expect(await database.sqlitePragma("user_version")).toBe(7);
+      await database.setSqlitePragma("application_id", 12345);
+      expect(await database.sqlitePragma("application_id")).toBe(12345);
+      await database.setSqlitePragma("journal_mode", "wal");
+      expect(await database.sqlitePragma("journal_mode")).toBe("wal");
+    } finally {
+      await database.close();
+    }
+  });
+
+  it("setSqlitePragma 拒绝拼进 SQL 的值", async () => {
+    const database = await openDatabase({ dialect: "sqlite", path: ":memory:" });
+    try {
+      await expect(database.setSqlitePragma("user_version", "0; DROP TABLE x")).rejects.toThrow(
+        /invalid pragma value/,
+      );
+    } finally {
+      await database.close();
+    }
+  });
+
+  it("vacuum：两种方言各有自己的写法，业务侧只调方法", async () => {
+    const database = await openDatabase({ dialect: "sqlite", path: ":memory:" });
+    try {
+      await ensureSchema(database, [notes]);
+      await database.vacuum();
+      expect(await database.objectNames()).toContain("t_introspect_notes");
+    } finally {
+      await database.close();
+    }
+  });
+});

package/src/__tests__/expr-functions.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { column, E, operandSql, render } from "../index.ts";
+
+/** 表达式 → 某方言的 SQL 文本（不需要连库）。 */
+function sqlOf(expression: import("../index.ts").Operand, dialect: "sqlite" | "postgres"): string {
+  return render(operandSql(expression), dialect).text;
+}
+
+describe("业务表达式（方言相关的由 rdbkit 渲染）", () => {
+  it("add：列自增与 upsert 里的 excluded 累加", () => {
+    expect(sqlOf(E.add(column("f_revision"), 1), "sqlite")).toBe('"f_revision" + ?');
+    expect(sqlOf(E.add(column("f_count"), E.excluded("f_count")), "postgres")).toBe(
+      '"f_count" + excluded."f_count"',
+    );
+  });
+
+  it("toInt / countIf：布尔条件当整数列与条件计数", () => {
+    expect(sqlOf(E.toInt(E.eq(column("f_origin", "t_sessions"), "subagent")), "sqlite")).toBe(
+      "CASE WHEN \"t_sessions\".\"f_origin\" = ? THEN 1 ELSE 0 END",
+    );
+    expect(sqlOf(E.countIf(E.eq(column("f_type"), "turn/start")), "postgres")).toBe(
+      'SUM(CASE WHEN "f_type" = $1 THEN 1 ELSE 0 END)',
+    );
+  });
+
+  it("maxOf：只增不减（两方言同一份 CASE 表达式）", () => {
+    expect(sqlOf(E.maxOf(column("f_last_event_at"), 42), "sqlite")).toBe(
+      'CASE WHEN COALESCE("f_last_event_at", 0) < ? THEN ? ELSE COALESCE("f_last_event_at", 0) END',
+    );
+  });
+
+  it("localDay：按本地时区把毫秒时间戳渲染成 YYYY-MM-DD", () => {
+    expect(sqlOf(E.localDay(column("f_created_at")), "sqlite")).toBe(
+      "date(\"f_created_at\" / 1000, 'unixepoch', 'localtime')",
+    );
+    expect(sqlOf(E.localDay(column("f_created_at")), "postgres")).toBe(
+      "to_char(to_timestamp(\"f_created_at\" / 1000.0), 'YYYY-MM-DD')",
+    );
+  });
+
+  it("jsonText / jsonInt：JSON 提取按方言渲染，路径不拼进 SQL 文本", () => {
+    expect(sqlOf(E.jsonText(column("f_data"), "$.data.message.source.provider"), "sqlite")).toBe(
+      'json_extract("f_data", ?)',
+    );
+    expect(sqlOf(E.jsonText(column("f_data"), "$.data.message.source.provider"), "postgres")).toBe(
+      `"f_data"::json #>> '{data,message,source,provider}'`,
+    );
+    expect(sqlOf(E.jsonInt(column("f_data"), "$.data.usage.inputTokens"), "sqlite")).toBe(
+      'json_extract("f_data", ?)',
+    );
+    expect(sqlOf(E.jsonInt(column("f_data"), "$.data.usage.inputTokens"), "postgres")).toBe(
+      `("f_data"::json #>> '{data,usage,inputTokens}')::integer`,
+    );
+  });
+
+  it("方言分支只保留本方言的占位符（不产生多余绑定参数）", () => {
+    const expression = E.localDay(column("f_created_at"));
+    expect(render(operandSql(expression), "sqlite").params).toEqual([]);
+    expect(render(operandSql(expression), "postgres").params).toEqual([]);
+    const withParam = E.add(column("f_count"), 7);
+    expect(render(operandSql(withParam), "sqlite").params).toEqual([7]);
+    expect(render(operandSql(withParam), "postgres").params).toEqual([7]);
+  });
+});

package/src/__tests__/migration.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  MigrationRegistry,
+  defineTable,
+  openDatabase,
+  runMigrations,
+  schemaMigrations,
+} from "../index.ts";
+
+const notes = defineTable({
+  name: "t_notes",
+  columns: {
+    f_id: { type: "text", primaryKey: true, notNull: true },
+    f_body: { type: "text" },
+  },
+});
+
+describe("迁移注册表", () => {
+  it("按 id 顺序执行一次、记账、幂等；失败的迁移不记账", async () => {
+    const database = await openDatabase({ dialect: "sqlite", path: ":memory:" });
+    try {
+      const ran: string[] = [];
+      const registry = new MigrationRegistry()
+        .register({
+          id: "002-second",
+          up: async (tx) => {
+            ran.push("002");
+            await tx.table(notes).insert({ f_id: "b", f_body: "second" });
+          },
+        })
+        .register({
+          id: "001-first",
+          up: async (tx) => {
+            ran.push("001");
+            await tx.table(notes).insert({ f_id: "a", f_body: "first" });
+          },
+        })
+        .register({
+          id: "003-broken",
+          up: async () => {
+            ran.push("003");
+            throw new Error("boom");
+          },
+        });
+
+      await expect(
+        runMigrations(database, { catalog: [notes], migrations: registry }),
+      ).rejects.toThrow("boom");
+      // 001、002 已记账；003 失败回滚，不记账。
+      expect(ran).toEqual(["001", "002", "003"]);
+
+      const notesTable = database.table(notes);
+      const bodyById = new Map<string, string | null>();
+      for await (const row of notesTable.select({ id: notesTable.f_id, body: notesTable.f_body })) {
+        bodyById.set(row.id, row.body);
+      }
+      expect(bodyById.get("a")).toBe("first");
+      expect(bodyById.get("b")).toBe("second");
+
+      // 已经记过账的不会再跑；003 仍然失败（账本里没有它）。
+      ran.length = 0;
+      await expect(
+        runMigrations(database, { catalog: [notes], migrations: registry }),
+      ).rejects.toThrow("boom");
+      expect(ran).toEqual(["003"]);
+
+      // 去掉失败的迁移后，只剩「无需执行」。
+      const healthy = new MigrationRegistry().register({
+        id: "001-first",
+        up: async () => {},
+      });
+      expect(await runMigrations(database, { catalog: [notes], migrations: healthy })).toEqual([]);
+      const ledger = database.table(schemaMigrations);
+      const ledgerRows: string[] = [];
+      for await (const row of ledger.select({ id: ledger.f_id })) ledgerRows.push(row.id);
+      expect(ledgerRows.sort()).toEqual(["001-first", "002-second"]);
+    } finally {
+      await database.close();
+    }
+  });
+});

package/src/__tests__/pg.spec.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import {
+  createPostgresTestDatabase,
+  type PostgresTestDatabase,
+} from "../testing.ts";
+import {
+  count,
+  defineCatalog,
+  defineTable,
+  ensureSchema,
+  fragment,
+  openDatabase,
+  sum,
+} from "../index.ts";
+
+const items = defineTable({
+  name: "t_items",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_owner: { type: "text", notNull: true },
+    f_count: { type: "integer", notNull: true, default: 0 },
+    f_active: { type: "boolean", notNull: true, default: 1 },
+    // `bigint` 在 PostgreSQL 上默认由驱动给字符串；rdbkit 的值类型是 bigint（BigInt），要有用例盯住。
+    f_at: { type: "bigint", notNull: true, default: 0 },
+  },
+  indexes: { idx_items_owner: { columns: ["f_owner"] } },
+});
+
+const parts = defineTable({
+  name: "t_parts",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_owner: { type: "text", notNull: true },
+    f_amount: { type: "integer", notNull: true },
+    // `SUM(bigint)` 在 PostgreSQL 上返回 numeric（驱动给字符串），rdbkit 的 sum 要 cast 回 int8。
+    f_big: { type: "bigint", notNull: true, default: 0 },
+  },
+});
+
+describe.skipIf(!process.env.TEST_PG_URL)("PostgreSQL 上同一套构建", () => {
+  it("建表 / 投影聚合 / join / 批量插入 / 事务回滚 / 迁移差异", async () => {
+    const testDatabase: PostgresTestDatabase = await createPostgresTestDatabase();
+    const database = await openDatabase({
+      dialect: "postgres",
+      connectionString: testDatabase.connectionString,
+      catalog: defineCatalog([items, parts]),
+    });
+    try {
+      const statements = await ensureSchema(database, [items, parts]);
+      expect(
+        statements.some((statement) =>
+          statement.includes('CREATE TABLE IF NOT EXISTS "public"."t_items"'),
+        ),
+      ).toBe(true);
+      expect(
+        statements.some((statement) =>
+          statement.includes('CREATE TABLE IF NOT EXISTS "public"."t_parts"'),
+        ),
+      ).toBe(true);
+      // 幂等
+      expect(await ensureSchema(database, [items, parts])).toEqual([]);
+
+      const table = database.table("t_items");
+      const partTable = database.table("t_parts");
+      const [created] = await table.insert(
+        { f_owner: "a", f_count: 1, f_at: 1_788_852_417_123 },
+        ["f_id", "f_owner", "f_at"],
+      );
+      expect(created).toMatchObject({ f_owner: "a" });
+      // 64 位整数读回来是 BigInt：超过 2^53 的 uint64 / int64 不会丢精度。
+      expect(created?.f_at).toBe(1_788_852_417_123n);
+      await table.insertMany([{ f_owner: "b", f_count: 2 }]);
+      await partTable.insertMany([
+        { f_owner: "a", f_amount: 5, f_big: 5_000_000_000n },
+        { f_owner: "a", f_amount: 6, f_big: 6n },
+      ]);
+
+      const totals: { owner: string; total: number | bigint; big: number | bigint }[] = [];
+      for await (const row of table
+        .select({
+          owner: table.column("f_owner"),
+          total: sum("f_amount", "t_parts"),
+          big: sum("f_big", "t_parts"),
+        })
+        .join(parts, fragment('"t_parts"."f_owner" = "t_items"."f_owner"'))
+        .groupBy("f_owner")
+        .orderBy("f_owner")) {
+        totals.push(row);
+      }
+      // PostgreSQL 的 SUM 返回 int8 → BigInt；`SUM(bigint)` 是 numeric，sum() 会 cast 回 int8。
+      expect(totals).toEqual([{ owner: "a", total: 11n, big: 5_000_000_006n }]);
+
+      // 真游标：逐行读，提前 break 也要把连接还回去（再开新查询不挂）。
+      const streamed: string[] = [];
+      for await (const row of table.select({ owner: table.column("f_owner") }).orderBy("f_owner")) {
+        streamed.push(row.owner);
+        break;
+      }
+      expect(streamed).toEqual(["a"]);
+
+      const [before] = await collect(table.select({ n: count() }));
+      expect(Number(before?.n)).toBe(2);
+
+      await expect(
+        database.transaction(async (tx) => {
+          await tx.table("t_items").insert({ f_owner: "c" });
+          throw new Error("boom");
+        }),
+      ).rejects.toThrow("boom");
+      const [after] = await collect(table.select({ n: count() }));
+      expect(Number(after?.n)).toBe(2);
+    } finally {
+      await database.close();
+      await testDatabase.drop();
+    }
+  });
+});
+
+async function collect<T>(rows: AsyncIterable<T>): Promise<T[]> {
+  const result: T[] = [];
+  for await (const row of rows) result.push(row);
+  return result;
+}

package/src/__tests__/query-join.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import {
+  and,
+  between,
+  column,
+  defineCatalog,
+  defineTable,
+  eq,
+  fragment,
+  gt,
+  inList,
+  not,
+  openDatabase,
+  raw,
+  sum,
+  value,
+} from "../index.ts";
+
+const users = defineTable({
+  name: "t_users",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_name: { type: "text", notNull: true },
+    f_active: { type: "boolean", notNull: true, default: 1 },
+  },
+});
+
+const orders = defineTable({
+  name: "t_orders",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_user: { type: "text", notNull: true },
+    f_amount: { type: "integer", notNull: true },
+  },
+});
+
+describe("关联 / 聚合 / 条件（两方言同一套构建）", () => {
+  it("join + group by + having、distinct、between、not、raw", async () => {
+    const database = await openDatabase({
+      dialect: "sqlite",
+      path: ":memory:",
+      catalog: defineCatalog([users, orders]),
+    });
+    try {
+      await database.run(
+        fragment(
+          'CREATE TABLE "t_users" ("f_id" INTEGER PRIMARY KEY AUTOINCREMENT, "f_name" TEXT NOT NULL, "f_active" INTEGER NOT NULL DEFAULT 1)',
+        ),
+      );
+      await database.run(
+        fragment(
+          'CREATE TABLE "t_orders" ("f_id" INTEGER PRIMARY KEY AUTOINCREMENT, "f_user" TEXT NOT NULL, "f_amount" INTEGER NOT NULL)',
+        ),
+      );
+
+      const userTable = database.table("t_users");
+      const orderTable = database.table("t_orders");
+      await userTable.insertMany([{ f_name: "ada" }, { f_name: "bob" }, { f_name: "carol" }]);
+      await orderTable.insertMany([
+        { f_user: "ada", f_amount: 3 },
+        { f_user: "ada", f_amount: 4 },
+        { f_user: "bob", f_amount: 1 },
+      ]);
+
+      // join + 聚合 + having + 排序
+      const totals: { name: string; total: number | bigint }[] = [];
+      for await (const row of userTable
+        .select({ name: userTable.column("f_name"), total: sum("f_amount", "t_orders") })
+        .join(orders, eq(column("f_user", "t_orders"), column("f_name", "t_users")))
+        .groupBy("f_name")
+        .having(gt(sum("f_amount", "t_orders"), value(2)))
+        .orderBy("f_name")) {
+        totals.push(row);
+      }
+      expect(totals).toEqual([{ name: "ada", total: 7 }]);
+
+      // distinct 投影
+      const actives: boolean[] = [];
+      for await (const row of userTable
+        .select({ active: userTable.column("f_active") })
+        .distinct()) {
+        actives.push(row.active);
+      }
+      expect(actives).toEqual([1]);
+
+      // between / not / raw / inList
+      const picked: number[] = [];
+      for await (const row of orderTable
+        .select({ id: orderTable.column("f_id") })
+        .where(
+          and(
+            between(column("f_amount"), value(2), value(5)),
+            not(inList(column("f_user"), ["bob"])),
+            raw('"f_amount" <> ?', [99]),
+          ),
+        )) {
+        picked.push(row.id);
+      }
+      expect(picked).toEqual([1, 2]);
+
+      // 左连接 + 计数：没有订单的用户也出现
+      const counts: { name: string; total: number | bigint }[] = [];
+      for await (const row of userTable
+        .select({ name: userTable.column("f_name"), total: sum("f_amount", "t_orders") })
+        .join(orders, eq(column("f_user", "t_orders"), column("f_name", "t_users")), "left")
+        .groupBy("f_name")) {
+        counts.push(row);
+      }
+      expect(counts.some((row) => row.name === "bob" && Number(row.total) === 1)).toBe(true);
+    } finally {
+      await database.close();
+    }
+  });
+});