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

package/src/database/wrap.ts

@@ -0,0 +1,48 @@
+import { createDialect, type DialectName } from "../dialect.ts";
+import { fragment } from "../fragment.ts";
+import { indexCatalog } from "../catalog.ts";
+import { createDatabase } from "./create.ts";
+import type { Database } from "./types.ts";
+
+/** 把「已有执行面」包成 rdbkit 的 `Database`（宿主自己管连接与事务时用）。 */
+export function wrapDatabase(
+  dialectName: DialectName,
+  ports: {
+    iterate(text: string, params: readonly unknown[]): AsyncIterable<unknown>;
+    run(text: string, params: readonly unknown[]): Promise<void>;
+    /** 宿主自己管事务时提供：把当前事务的执行面做成 scoped `Database`（对应 Go 的 `Tx(ctx, fn)`）。 */
+    transaction?: <T>(fn: (scoped: Database) => Promise<T>) => Promise<T>;
+    close?(): Promise<void>;
+  },
+): Database {
+  const database = createDatabase(
+    createDialect(dialectName),
+    {
+      iterate: (text, params) => ports.iterate(text, params),
+      run: (text, params) => ports.run(text, params),
+      transaction: () => {
+        throw new Error(
+          "rdbkit: a wrapped database does not own transactions; use the host transaction",
+        );
+      },
+      close: async () => {
+        await ports.close?.();
+      },
+    },
+    indexCatalog([]),
+  );
+  return ports.transaction === undefined
+    ? database
+    : { ...database, transaction: ports.transaction };
+}
+
+/** 结构迁移读取现状用的最小查询面。 */
+export function shapeReader(database: Database): {
+  query<T>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+} {
+  return {
+    async query<T>(sql: string, params: readonly unknown[] = []): Promise<T[]> {
+      return await database.read<T>(fragment(sql, params));
+    },
+  };
+}

package/src/defs.ts

@@ -0,0 +1,82 @@
+import type { TableHandle } from "./table/handle.ts";
+import type { Database } from "./database/types.ts";
+// 表定义就是数据库结构的唯一来源：DDL、启动迁移、类型化的表句柄都从它算出来，
+// 所以再加一张表 / 一列时不需要另写迁移 SQL，也不需要在 sqlite 与 postgres 各写一遍。
+
+/** 列类型：只保留跨方言能一一映射的那几种。 */
+export type ColumnTypeName = "serial" | "integer" | "bigint" | "text" | "boolean";
+
+/** 外键的删除动作（与 SQL 的 ON DELETE 同名）。 */
+export type DeleteAction = "cascade" | "set null" | "restrict" | "no action";
+
+/** 一列的定义。 */
+export interface ColumnDef {
+  type: ColumnTypeName;
+  notNull?: boolean;
+  /** 单列主键；复合主键写在表级的 `primaryKey` 上。 */
+  primaryKey?: boolean;
+  default?: string | number;
+  unique?: boolean;
+  references?: {
+    table: string;
+    column: string;
+    onDelete?: DeleteAction;
+  };
+}
+
+/** 表级约束与索引。 */
+export interface CheckDef {
+  expression: string;
+}
+
+export interface UniqueDef {
+  columns: string[];
+}
+
+export interface IndexDef {
+  columns: string[];
+}
+
+/** 一张表的完整定义。 */
+export interface TableDef {
+  name: string;
+  columns: Record<string, ColumnDef>;
+  /** 复合主键（按顺序）；单列主键用列上的 `primaryKey`。 */
+  primaryKey?: readonly string[];
+  checks?: Record<string, CheckDef>;
+  uniques?: Record<string, UniqueDef>;
+  indexes?: Record<string, IndexDef>;
+}
+
+/** 一组表定义（一个库的结构）。 */
+export type Catalog = readonly TableDef[];
+
+/** `defineTable` 的返回值：表定义 + 操作钩子（`users.table(database)` 直接拿句柄）。 */
+export type Table<T extends TableDef> = T & {
+  table(database: Database): TableHandle<T>;
+};
+
+/** 声明一张表（形状原样保留，另挂一个取句柄的钩子）。 */
+export function defineTable<const T extends TableDef>(def: T): Table<T> {
+  if (!/^[a-z][a-z0-9_]*$/u.test(def.name)) {
+    throw new Error(`rdbkit: table name '${def.name}' must match [a-z][a-z0-9_]*`);
+  }
+  const names = Object.keys(def.columns);
+  if (names.length === 0) throw new Error(`rdbkit: table '${def.name}' declares no columns`);
+  for (const name of names) {
+    if (!/^[a-z][a-z0-9_]*$/u.test(name)) {
+      throw new Error(`rdbkit: table '${def.name}' column '${name}' must match [a-z][a-z0-9_]*`);
+    }
+  }
+  // 定义即操作钩子：`users.table(db)` 等价于 `db.table(users)`，业务侧不需要记两套写法。
+  return {
+    ...def,
+    table: (database: Database) => database.table(def) as TableHandle<T>,
+  } as Table<T>;
+}
+
+/** 声明一组表。 */
+export function defineCatalog<const T extends readonly TableDef[]>(tables: T): T {
+  for (const table of tables) defineTable(table);
+  return tables;
+}

package/src/dialect.ts

@@ -0,0 +1,219 @@
+import type { ColumnDef, TableDef } from "./defs.ts";
+
+/** 支持的方言。 */
+export type DialectName = "sqlite" | "postgres";
+
+/** 现有结构的一小块：迁移只关心「有没有这张表 / 这一列 / 这个索引」。 */
+export interface TableShape {
+  columns: ReadonlySet<string>;
+  indexes: ReadonlySet<string>;
+}
+
+/** 一个方言：类型映射、标识符、DDL 片段，以及读现有结构的查询。 */
+export interface Dialect {
+  readonly name: DialectName;
+  /** 标识符引用（表名 / 列名 / 索引名）。 */
+  quote(identifier: string): string;
+  /** 带 schema 的表名（sqlite 忽略 schema）。 */
+  tableName(table: string, schema?: string): string;
+  /** 列类型（含自增主键的特殊写法）。 */
+  columnType(column: ColumnDef): string;
+  /** 读现有表的列与索引；表不存在返回 undefined。 */
+  readShape(database: ShapeReader, table: string, schema?: string): Promise<TableShape | undefined>;
+}
+
+/** 读结构所需的最小执行面（`database/wrap.ts` 的 `shapeReader` 把 `Database` 包成它）。 */
+export interface ShapeReader {
+  query<T>(text: string, params?: readonly unknown[]): Promise<T[]>;
+}
+
+const SQLITE_KEYWORDS = /^[a-z][a-z0-9_]*$/u;
+
+function assertIdentifier(kind: string, name: string): void {
+  if (!SQLITE_KEYWORDS.test(name)) throw new Error(`rdbkit: invalid ${kind} '${name}'`);
+}
+
+export function createDialect(name: DialectName): Dialect {
+  return name === "sqlite" ? sqliteDialect() : postgresDialect();
+}
+
+function sqliteDialect(): Dialect {
+  return {
+    name: "sqlite",
+    quote(identifier) {
+      assertIdentifier("identifier", identifier);
+      return `"${identifier}"`;
+    },
+    tableName(table) {
+      assertIdentifier("table", table);
+      return `"${table}"`;
+    },
+    columnType(column) {
+      // `serial` 在 SQLite 就是「整型主键 + 自增」；其它类型都能直接映射。
+      if (column.type === "serial") return "INTEGER";
+      if (column.type === "boolean") return "INTEGER";
+      if (column.type === "bigint" || column.type === "integer") return "INTEGER";
+      return "TEXT";
+    },
+    async readShape(database, table) {
+      const exists = await database.query<{ name: string }>(
+        "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
+        [table],
+      );
+      if (exists.length === 0) return undefined;
+      const columns = await database.query<{ name: string }>(`PRAGMA table_info("${table}")`);
+      const indexes = await database.query<{ name: string }>(`PRAGMA index_list("${table}")`);
+      return {
+        columns: new Set(columns.map((row) => row.name)),
+        indexes: new Set(indexes.map((row) => row.name)),
+      };
+    },
+  };
+}
+
+function postgresDialect(): Dialect {
+  return {
+    name: "postgres",
+    quote(identifier) {
+      assertIdentifier("identifier", identifier);
+      return `"${identifier}"`;
+    },
+    tableName(table, schema = "public") {
+      assertIdentifier("schema", schema);
+      assertIdentifier("table", table);
+      return `"${schema}"."${table}"`;
+    },
+    columnType(column) {
+      switch (column.type) {
+        case "serial":
+          return "SERIAL";
+        case "boolean":
+          return "BOOLEAN";
+        case "bigint":
+          return "BIGINT";
+        case "integer":
+          return "INTEGER";
+        default:
+          return "TEXT";
+      }
+    },
+    async readShape(database, table, schema = "public") {
+      const columns = await database.query<{ column_name: string }>(
+        "SELECT column_name FROM information_schema.columns WHERE table_schema = ? AND table_name = ?",
+        [schema, table],
+      );
+      if (columns.length === 0) return undefined;
+      const indexes = await database.query<{ indexname: string }>(
+        "SELECT indexname FROM pg_indexes WHERE schemaname = ? AND tablename = ?",
+        [schema, table],
+      );
+      return {
+        columns: new Set(columns.map((row) => row.column_name)),
+        indexes: new Set(indexes.map((row) => row.indexname)),
+      };
+    },
+  };
+}
+
+/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）。 */
+export function columnSql(dialect: Dialect, name: string, column: ColumnDef): string {
+  assertIdentifier("column", name);
+  const parts = [dialect.quote(name), dialect.columnType(column)];
+  if (column.type === "serial" && dialect.name === "sqlite")
+    parts.push("PRIMARY KEY AUTOINCREMENT");
+  else if (column.primaryKey === true) parts.push("PRIMARY KEY");
+  if (column.notNull === true) parts.push("NOT NULL");
+  if (column.unique === true) parts.push("UNIQUE");
+  if (column.default !== undefined)
+    parts.push(`DEFAULT ${literal(dialect, column.default, column.type)}`);
+  if (column.references !== undefined) {
+    const { table, column: referenced, onDelete } = column.references;
+    assertIdentifier("table", table);
+    assertIdentifier("column", referenced);
+    parts.push(
+      `REFERENCES ${dialect.tableName(table)}(${dialect.quote(referenced)})` +
+        (onDelete === undefined ? "" : ` ON DELETE ${onDelete.toUpperCase()}`),
+    );
+  }
+  return parts.join(" ");
+}
+
+function literal(dialect: Dialect, value: string | number, type: ColumnDef["type"]): string {
+  if (type === "boolean") {
+    if (typeof value === "number") {
+      return dialect.name === "postgres" ? (value === 0 ? "FALSE" : "TRUE") : String(value);
+    }
+    return dialect.name === "postgres"
+      ? value.toUpperCase()
+      : /^(true|1)$/iu.test(value)
+        ? "1"
+        : "0";
+  }
+  if (typeof value === "number") return String(value);
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+/** 建表语句（IF NOT EXISTS；列与表级约束都由定义算出来）。 */
+export function createTableSql(dialect: Dialect, table: TableDef, schema?: string): string {
+  const parts = Object.entries(table.columns).map(([name, column]) =>
+    columnSql(dialect, name, column),
+  );
+  const primaryKey =
+    table.primaryKey === undefined
+      ? undefined
+      : table.primaryKey.map((name) => dialect.quote(name)).join(", ");
+  if (primaryKey !== undefined) parts.push(`PRIMARY KEY (${primaryKey})`);
+  for (const [name, check] of Object.entries(table.checks ?? {})) {
+    assertIdentifier("constraint", name);
+    parts.push(`CONSTRAINT ${dialect.quote(name)} CHECK (${check.expression})`);
+  }
+  for (const [name, unique] of Object.entries(table.uniques ?? {})) {
+    assertIdentifier("constraint", name);
+    parts.push(
+      `CONSTRAINT ${dialect.quote(name)} UNIQUE (${unique.columns
+        .map((column) => dialect.quote(column))
+        .join(", ")})`,
+    );
+  }
+  return (
+    `CREATE TABLE IF NOT EXISTS ${dialect.tableName(table.name, schema)} (\n  ` +
+    `${parts.join(",\n  ")}\n)`
+  );
+}
+
+/** 索引语句（`unique` 时是唯一索引）。 */
+export function createIndexSql(
+  dialect: Dialect,
+  table: TableDef,
+  name: string,
+  columns: readonly string[],
+  unique = false,
+): string {
+  assertIdentifier("index", name);
+  return (
+    `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ${dialect.quote(name)} ` +
+    `ON ${dialect.tableName(table.name)} (${columns.map((column) => dialect.quote(column)).join(", ")})`
+  );
+}
+
+/** 删列（只在显式允许破坏性变更时用）。 */
+export function dropColumnSql(dialect: Dialect, table: string, name: string): string {
+  assertIdentifier("column", name);
+  return `ALTER TABLE ${dialect.tableName(table)} DROP COLUMN ${dialect.quote(name)}`;
+}
+
+/** 删索引（只在显式允许破坏性变更时用）。 */
+export function dropIndexSql(dialect: Dialect, name: string): string {
+  assertIdentifier("index", name);
+  return `DROP INDEX IF EXISTS ${dialect.quote(name)}`;
+}
+
+/** 加列语句（启动迁移只做「缺列则补」，不改类型、不删列）。 */
+export function addColumnSql(
+  dialect: Dialect,
+  table: string,
+  name: string,
+  column: ColumnDef,
+): string {
+  return `ALTER TABLE ${dialect.tableName(table)} ADD COLUMN ${columnSql(dialect, name, column)}`;
+}

package/src/error.ts

@@ -0,0 +1,72 @@
+import type { DialectName } from "./dialect.ts";
+
+/** 数据库错误的可判定类别（调用方据此决定重试 / 上报 / 走业务分支）。 */
+export type DbErrorKind =
+  | "unique"
+  | "foreign-key"
+  | "not-null"
+  | "check"
+  | "timeout"
+  | "connection"
+  | "unknown";
+
+/** 统一的数据库错误：`kind` 是方言无关的判定，原始错误在 `cause`。 */
+export class DbError extends Error {
+  constructor(
+    readonly kind: DbErrorKind,
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "DbError";
+  }
+}
+
+/**
+ * 把驱动错误翻译成 {@link DbErrorKind}：SQLite 用错误文本前缀，PostgreSQL 用 SQLSTATE。
+ * @param error - 驱动抛出的错误。
+ * @param dialect - 产生它的方言。
+ * @returns 已分类的错误（原错误在 `cause`）。
+ */
+export function classifyError(error: unknown, dialect: DialectName): DbError {
+  if (error instanceof DbError) return error;
+  const cause = error as { code?: unknown; message?: unknown } | undefined;
+  const code = typeof cause?.code === "string" ? cause.code : undefined;
+  const message = typeof cause?.message === "string" ? cause.message : String(error);
+
+  if (dialect === "postgres") {
+    switch (code) {
+      case "23505":
+        return new DbError("unique", message, { cause: error });
+      case "23503":
+        return new DbError("foreign-key", message, { cause: error });
+      case "23502":
+        return new DbError("not-null", message, { cause: error });
+      case "23514":
+        return new DbError("check", message, { cause: error });
+      case "57014":
+      case "55P03":
+        return new DbError("timeout", message, { cause: error });
+      case "53300":
+        return new DbError("connection", message, { cause: error });
+      default:
+        if (code !== undefined && code.startsWith("08")) {
+          return new DbError("connection", message, { cause: error });
+        }
+        return new DbError("unknown", message, { cause: error });
+    }
+  }
+
+  if (/UNIQUE constraint failed/iu.test(message))
+    return new DbError("unique", message, { cause: error });
+  if (/FOREIGN KEY constraint failed/iu.test(message))
+    return new DbError("foreign-key", message, { cause: error });
+  if (/NOT NULL constraint failed/iu.test(message))
+    return new DbError("not-null", message, { cause: error });
+  if (/CHECK constraint failed/iu.test(message))
+    return new DbError("check", message, { cause: error });
+  if (/SQLITE_BUSY|database is locked|database table is locked/iu.test(message)) {
+    return new DbError("timeout", message, { cause: error });
+  }
+  return new DbError("unknown", message, { cause: error });
+}