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

package/src/migration.ts

@@ -0,0 +1,82 @@
+import type { Catalog, TableDef } from "./defs.ts";
+import { defineTable } from "./defs.ts";
+import type { Database } from "./database/types.ts";
+import { ensureSchema } from "./migrate.ts";
+
+/** 内置迁移账本：一条已执行的数据迁移一行（`f_id` 唯一）。 */
+export const schemaMigrations = defineTable({
+  name: "t_schema_migrations",
+  columns: {
+    f_id: { type: "text", primaryKey: true, notNull: true },
+    f_applied_at: { type: "bigint", notNull: true },
+  },
+});
+
+/** 一条数据迁移：`id` 唯一且按字典序执行；`up` 在事务里跑，抛错则整条不记。 */
+export interface Migration {
+  readonly id: string;
+  /**
+   * 返回 `false` 表示这次无需执行（例如旧表还不存在），**不记账**——下次打开还会再试。
+   * 返回其它值（含 `undefined`）表示已执行，记账。
+   */
+  readonly up: (database: Database) => Promise<boolean | void>;
+}
+
+/** 迁移注册表：业务把自己的迁移登记进来，打开库时一起执行。 */
+export class MigrationRegistry {
+  readonly #migrations = new Map<string, Migration>();
+
+  register(migration: Migration): this {
+    if (this.#migrations.has(migration.id)) {
+      throw new Error(`rdbkit: migration '${migration.id}' is registered twice`);
+    }
+    this.#migrations.set(migration.id, migration);
+    return this;
+  }
+
+  list(): readonly Migration[] {
+    return [...this.#migrations.values()].sort((left, right) => left.id.localeCompare(right.id));
+  }
+}
+
+/** 打开库时做的事：结构（catalog diff）+ 数据迁移（注册表）。 */
+export interface RunMigrationsOptions {
+  /** 业务表定义（`ensureSchema` 用）。 */
+  catalog?: Catalog;
+  migrations: readonly Migration[] | MigrationRegistry;
+}
+
+/**
+ * 先按 catalog 对齐结构（建表 / 补列 / 补索引），再执行未应用的数据迁移。
+ *
+ * 账本是 rdbkit 内置的 `t_schema_migrations`：每条迁移在**同一个事务**里执行并记账，
+ * 失败即回滚，重跑时只跑没记过的。返回本次实际执行了哪些 `id`。
+ */
+export async function runMigrations(
+  database: Database,
+  options: RunMigrationsOptions,
+): Promise<readonly string[]> {
+  const migrations =
+    options.migrations instanceof MigrationRegistry
+      ? options.migrations.list()
+      : [...options.migrations];
+  const catalog: Catalog = [...(options.catalog ?? []), schemaMigrations as TableDef];
+  await ensureSchema(database, catalog);
+
+  const ledger = database.table(schemaMigrations);
+  const applied = new Set<string>();
+  for await (const row of ledger.select({ id: ledger.f_id })) applied.add(row.id);
+
+  const executed: string[] = [];
+  for (const migration of migrations) {
+    if (applied.has(migration.id)) continue;
+    const appliedNow = await database.transaction(async (tx) => {
+      const result = await migration.up(tx);
+      if (result === false) return false;
+      await tx.table(schemaMigrations).insert({ f_id: migration.id, f_applied_at: Date.now() });
+      return true;
+    });
+    if (appliedNow) executed.push(migration.id);
+  }
+  return executed;
+}

package/src/table/handle.ts

@@ -0,0 +1,142 @@
+import type { TableDef } from "../defs.ts";
+import type { ColumnRef, Condition, Operand } from "../expr.ts";
+import type { Fragment } from "../fragment.ts";
+import type { Database } from "../database/types.ts";
+import {
+  type ColumnName,
+  type InsertRow,
+  type Projected,
+  type Projection,
+  type RowOf,
+  type UpdatePatch,
+} from "./types.ts";
+import { selectQuery, type SelectQuery } from "./select.ts";
+import {
+  deleteOf,
+  insertFromSelectOf,
+  insertManyOf,
+  insertOf,
+  updateOf,
+  upsertExprOf,
+} from "./render.ts";
+
+/** 列访问器：`t.f_domain` 就是这一列的引用（带值类型）。 */
+export type ColumnAccessors<Row> = { readonly [K in ColumnName<Row>]: ColumnRef<Row[K]> };
+
+/** 一张表的业务面：投影查询 + 写入，调用方不接触方言与 SQL。 */
+export type TableHandle<T extends TableDef> = TableHandleBase<T> & ColumnAccessors<RowOf<T>>;
+
+export interface TableHandleBase<T extends TableDef> {
+  readonly name: string;
+  readonly definition: T;
+  /** 拿一列（带值类型的引用），投影 / 条件里用。 */
+  column<K extends ColumnName<RowOf<T>>>(name: K): ColumnRef<RowOf<T>[K]>;
+  /** 投影省略时取全部列（结果按列名原样）。 */
+  select<P extends Projection = Record<string, ColumnRef>>(
+    projection?: P,
+  ): SelectQuery<Projected<P>>;
+  /** 插入；传 `returning` 时拿回这些列（`RETURNING`，两方言都支持）。 */
+  insert(
+    row: InsertRow<RowOf<T>>,
+    returning?: readonly ColumnName<RowOf<T>>[],
+  ): Promise<RowOf<T>[]>;
+  insertIgnore(row: InsertRow<RowOf<T>>, conflict: readonly ColumnName<RowOf<T>>[]): Promise<void>;
+  /** `INSERT … SELECT`：把一条查询的结果按列顺序插进来（Go 的 `InsertFrom`）。 */
+  insertFromSelect(
+    columns: readonly ColumnName<RowOf<T>>[],
+    source: Fragment,
+    options?: {
+      conflict?: readonly ColumnName<RowOf<T>>[];
+      update?: readonly ColumnName<RowOf<T>>[];
+    },
+  ): Promise<void>;
+  /** 批量插入；传 `conflict` / `update` 时是批量 upsert（`ON CONFLICT … DO UPDATE`）。 */
+  insertMany(
+    rows: readonly InsertRow<RowOf<T>>[],
+    options?: {
+      conflict?: readonly ColumnName<RowOf<T>>[];
+      update?: readonly ColumnName<RowOf<T>>[];
+    },
+  ): Promise<void>;
+  upsert(
+    row: InsertRow<RowOf<T>>,
+    conflict: readonly ColumnName<RowOf<T>>[],
+    update?: readonly ColumnName<RowOf<T>>[],
+  ): Promise<void>;
+  update(
+    patch: UpdatePatch<RowOf<T>>,
+    condition?: Condition,
+    returning?: readonly ColumnName<RowOf<T>>[],
+  ): Promise<RowOf<T>[]>;
+  /** `ON CONFLICT ... DO UPDATE SET 列 = 表达式`（如自增计数）。 */
+  upsertExpr(
+    row: InsertRow<RowOf<T>>,
+    conflict: readonly ColumnName<RowOf<T>>[],
+    assignments: Record<string, Operand>,
+  ): Promise<void>;
+  /** 删除；传 `returning` 时拿回被删行的这些列（`RETURNING`）。 */
+  delete(condition?: Condition, returning?: readonly ColumnName<RowOf<T>>[]): Promise<RowOf<T>[]>;
+}
+
+export function createTableHandle<T extends TableDef>(
+  database: Database,
+  definition: T,
+): TableHandle<T> {
+  const name = definition.name;
+  const handle: TableHandleBase<T> = {
+    name,
+    definition,
+    column: (column) => ({ kind: "column", table: name, name: column }) as never,
+    select: (projection) =>
+      selectQuery(
+        database,
+        definition,
+        projection ??
+          (Object.fromEntries(
+            Object.keys(definition.columns).map((name) => [
+              name,
+              { kind: "column", table: definition.name, name },
+            ]),
+          ) as Projection),
+      ) as never,
+    async insert(row, returning) {
+      return await database.write<RowOf<T>>(
+        insertOf(definition, row, "insert", undefined, undefined, returning),
+      );
+    },
+    async insertIgnore(row, conflict) {
+      await database.run(insertOf(definition, row, "ignore", conflict));
+    },
+    async insertFromSelect(columns, source, options) {
+      await database.run(insertFromSelectOf(definition, columns, source, options));
+    },
+    async insertMany(rows, options) {
+      await database.run(insertManyOf(definition, rows, options));
+    },
+    async upsert(row, conflict, update) {
+      await database.run(insertOf(definition, row, "upsert", conflict, update));
+    },
+    async update(patch, condition, returning) {
+      return await database.write<RowOf<T>>(updateOf(definition, patch, condition, returning));
+    },
+    async upsertExpr(row, conflict, assignments) {
+      await database.run(upsertExprOf(definition, row, conflict, assignments));
+    },
+    async delete(condition, returning) {
+      if (returning !== undefined && returning.length > 0) {
+        return await database.write<RowOf<T>>(deleteOf(definition, condition, returning));
+      }
+      await database.run(deleteOf(definition, condition));
+      return [];
+    },
+  };
+  // 列名直接当属性读：`t.f_domain` 等价于 `t.column("f_domain")`。
+  return new Proxy(handle, {
+    get(target, property, receiver) {
+      if (typeof property === "string" && definition.columns[property] !== undefined) {
+        return { kind: "column", table: name, name: property } satisfies ColumnRef;
+      }
+      return Reflect.get(target, property, receiver) as unknown;
+    },
+  }) as TableHandle<T>;
+}

package/src/table/index.ts

@@ -0,0 +1,14 @@
+export { createTableHandle, type ColumnAccessors, type TableHandle, type TableHandleBase } from "./handle.ts";
+export { count, selectQuery, sum, type GroupByItem, type SelectQuery } from "./select.ts";
+export {
+  type Aggregate,
+  type ColumnName,
+  type ColumnValue,
+  type InsertRow,
+  type Projected,
+  type Projection,
+  type RowOf,
+  type UpdatePatch,
+} from "./types.ts";
+export { columnSql } from "../expr.ts";
+export { render } from "../fragment.ts";

package/src/table/render.ts

@@ -0,0 +1,140 @@
+import type { TableDef } from "../defs.ts";
+import { concat, fragment, param, text, type Fragment } from "../fragment.ts";
+import { operandSql, type Condition, type Operand } from "../expr.ts";
+
+export function returningClause(returning?: readonly string[]): Fragment | string {
+  return returning === undefined || returning.length === 0
+    ? ""
+    : text(`RETURNING ${returning.map((name) => `"${name}"`).join(", ")}`);
+}
+
+export function insertOf(
+  table: TableDef,
+  row: Record<string, unknown>,
+  mode: "insert" | "ignore" | "upsert",
+  conflict?: readonly string[],
+  update?: readonly string[],
+  returning?: readonly string[],
+): Fragment {
+  const columns = Object.keys(row).filter((name) => table.columns[name] !== undefined);
+  if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+  const sql =
+    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) ` +
+    `VALUES (${columns.map(() => "?").join(", ")})`;
+  const base = fragment(
+    sql,
+    columns.map((name) => row[name]),
+  );
+  if (mode === "insert") return concat([base, returningClause(returning)], " ");
+  const target = (conflict ?? []).map((name) => `"${name}"`).join(", ");
+  if (mode === "ignore") return concat([base, `ON CONFLICT (${target}) DO NOTHING`], " ");
+  const updates =
+    (update ?? []).length === 0
+      ? "DO NOTHING"
+      : `DO UPDATE SET ${(update ?? [])
+          .map((name) => `"${name}" = excluded."${name}"`)
+          .join(", ")}`;
+  return concat([base, `ON CONFLICT (${target}) ${updates}`, returningClause(returning)], " ");
+}
+
+export function insertManyOf(
+  table: TableDef,
+  rows: readonly Record<string, unknown>[],
+  options: { conflict?: readonly string[]; update?: readonly string[] } = {},
+): Fragment {
+  if (rows.length === 0) return fragment("SELECT 1 WHERE 1 = 0");
+  const columns = Object.keys(rows[0]!).filter((name) => table.columns[name] !== undefined);
+  if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+  for (const row of rows) {
+    for (const column of columns) {
+      if (row[column] === undefined) {
+        throw new Error(`rdbkit: insertMany into "${table.name}" is missing column '${column}'`);
+      }
+    }
+  }
+  const tuple = `(${columns.map(() => "?").join(", ")})`;
+  const sql =
+    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) ` +
+    `VALUES ${rows.map(() => tuple).join(", ")}`;
+  const insert = fragment(
+    sql,
+    rows.flatMap((row) => columns.map((name) => row[name])),
+  );
+  return concat([insert, conflictClause(options)], " ");
+}
+
+export function insertFromSelectOf(
+  table: TableDef,
+  columns: readonly string[],
+  source: Fragment,
+  options: { conflict?: readonly string[]; update?: readonly string[] } = {},
+): Fragment {
+  if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+  const head = text(
+    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")})`,
+  );
+  return concat([head, source, conflictClause(options)], " ");
+}
+
+/** `ON CONFLICT …` 子句（没有冲突列时为空）。 */
+export function conflictClause(options: {
+  conflict?: readonly string[];
+  update?: readonly string[];
+}): Fragment | string {
+  const conflict = options.conflict ?? [];
+  if (conflict.length === 0) return "";
+  const target = conflict.map((name) => `"${name}"`).join(", ");
+  const updates =
+    (options.update ?? []).length === 0
+      ? "DO NOTHING"
+      : `DO UPDATE SET ${(options.update ?? [])
+          .map((name) => `"${name}" = excluded."${name}"`)
+          .join(", ")}`;
+  return text(`ON CONFLICT (${target}) ${updates}`);
+}
+
+export function upsertExprOf(
+  table: TableDef,
+  row: Record<string, unknown>,
+  conflict: readonly string[],
+  assignments: Record<string, Operand>,
+): Fragment {
+  const base = insertOf(table, row, "insert");
+  const target = conflict.map((name) => `"${name}"`).join(", ");
+  const sets = Object.entries(assignments).map(([name, ref]) =>
+    concat([text(`"${name}" =`), operandSql(ref)], " "),
+  );
+  return concat([base, text(`ON CONFLICT (${target}) DO UPDATE SET`), concat(sets, ", ")], " ");
+}
+
+export function updateOf(
+  table: TableDef,
+  patch: Record<string, unknown>,
+  condition?: Condition,
+  returning?: readonly string[],
+): Fragment {
+  const columns = Object.keys(patch).filter((name) => table.columns[name] !== undefined);
+  if (columns.length === 0) throw new Error(`rdbkit: update "${table.name}" has no columns`);
+  // 值可以是表达式（列自增、取大等）：只有普通值才绑参数。
+  const sets = columns.map((name) => {
+    const value = patch[name];
+    const assigned =
+      typeof value === "object" && value !== null && "kind" in value
+        ? operandSql(value as Operand)
+        : param(value);
+    return concat([text(`"${name}" =`), assigned], " ");
+  });
+  const head = concat([text(`UPDATE "${table.name}" SET`), concat(sets, ", ")], " ");
+  const body = condition === undefined ? head : concat([head, text("WHERE"), condition], " ");
+  return concat([body, returningClause(returning)], " ");
+}
+
+export function deleteOf(
+  table: TableDef,
+  condition?: Condition,
+  returning?: readonly string[],
+): Fragment {
+  const head = text(`DELETE FROM "${table.name}"`);
+  const body = condition === undefined ? head : concat([head, text("WHERE"), condition], " ");
+  return concat([body, returningClause(returning)], " ");
+}

package/src/table/select.ts

@@ -0,0 +1,229 @@
+import type { TableDef } from "../defs.ts";
+import { concat, fragment, only, text, type Fragment } from "../fragment.ts";
+import {
+  and,
+  columnSql,
+  type ColumnRef,
+  type Condition,
+  type ExprOperand,
+} from "../expr.ts";
+import { forUpdate as forUpdateSql, withCtes, type Cte } from "../compound.ts";
+import type { Database } from "../database/types.ts";
+import type { Aggregate, Projection } from "./types.ts";
+
+/** 表达式的片段：方言相关的表达式自带片段，普通的按 `sql` + 绑定参数编。 */
+function exprFragment(expression: ExprOperand): Fragment {
+  return expression.fragment ?? fragment(expression.sql, expression.params);
+}
+
+/** COUNT(*)，投影里写 `{ n: count() }`。 */
+export function count(): Aggregate<number | bigint> {
+  return { kind: "expr", sql: "COUNT(*)", params: [] };
+}
+
+/**
+ * SUM(列)；多表查询时传表名避免歧义。
+ *
+ * PostgreSQL 的 `SUM(bigint)` 返回 `numeric`（驱动给字符串），SQLite 返回整数——统一 cast 回 int8，
+ * 声明的 `number | bigint` 才成立。列类型只有 integer / bigint，所以这个 cast 不丢小数。
+ */
+export function sum(name: string, table?: string): Aggregate<number | bigint> {
+  const target = table === undefined ? `"${name}"` : `"${table}"."${name}"`;
+  return {
+    kind: "expr",
+    sql: "",
+    params: [],
+    fragment: concat(
+      [
+        only("sqlite", text(`SUM(${target})`)),
+        only("postgres", text(`SUM(${target})::bigint`)),
+      ],
+      "",
+    ),
+  };
+}
+
+/** 一个查询：实现 `AsyncIterable`，`for await` 直接消费（对应 Golang 的 `iter.Seq2`）。 */
+export interface SelectQuery<T> extends AsyncIterable<T> {
+  where(condition: Condition): this;
+  /** `cross` 不需要 ON；`alias` 给被 join 的表起别名（投影里用 `column(名字, 别名)`）。 */
+  join(
+    table: TableDef,
+    on?: Condition,
+    kind?: "inner" | "left" | "right" | "full" | "cross",
+    alias?: string,
+  ): this;
+  /** `WITH "name" AS (<query>)`，多条按顺序拼。 */
+  with(
+    name: string,
+    query: Fragment,
+    options?: { recursive?: boolean; columns?: readonly string[] },
+  ): this;
+  /** 分组：列名（主表）、带表名的列引用或表达式。 */
+  groupBy(...columns: GroupByItem[]): this;
+  having(condition: Condition): this;
+  distinct(): this;
+  orderBy(column: string | ColumnRef | ExprOperand, direction?: "asc" | "desc"): this;
+  limit(count: number): this;
+  offset(count: number): this;
+  /** 行锁（PostgreSQL 生效，SQLite 渲染时丢弃）。 */
+  forUpdate(options?: { of?: readonly string[]; noWait?: boolean; skipLocked?: boolean }): this;
+  toFragment(): Fragment;
+}
+
+/** `groupBy` 的入参：列名、带表名的列引用或表达式。 */
+export type GroupByItem = string | ColumnRef | ExprOperand;
+
+export function selectQuery<T>(
+  database: Database,
+  table: TableDef,
+  projection: Projection,
+): SelectQuery<T> {
+  const state: {
+    condition?: Condition | undefined;
+    joins: {
+      table: TableDef;
+      on?: Condition | undefined;
+      kind: "inner" | "left" | "right" | "full" | "cross";
+      alias?: string | undefined;
+    }[];
+    ctes: Cte[];
+    lock?: Fragment | undefined;
+    having?: Condition | undefined;
+    distinct: boolean;
+    order: { column: string | ColumnRef | ExprOperand; direction: "asc" | "desc" }[];
+    group: GroupByItem[];
+    limit?: number | undefined;
+    offset?: number | undefined;
+  } = { joins: [], ctes: [], distinct: false, order: [], group: [] };
+
+  /**
+   * 结果行的值归一：`bigint` 列统一成 JS `bigint`。
+   * SQLite 的 INTEGER 由驱动给 number，PostgreSQL 的 int8 已经是 BigInt（见 `bigintTypes`）——
+   * 读出来的类型不能跟着驱动走，否则同一份表定义在两种方言下值类型不同。
+   */
+  const normalize = (row: Record<string, unknown>): T => {
+    for (const [alias, entry] of Object.entries(projection)) {
+      if (entry.kind !== "column") continue;
+      const owner = entry.table === undefined ? table : tableOf(entry.table);
+      if (owner?.columns[entry.name]?.type !== "bigint") continue;
+      const value = row[alias];
+      if (value === null || value === undefined || typeof value === "bigint") continue;
+      row[alias] = BigInt(value as number | string);
+    }
+    return row as T;
+  };
+
+  const tableOf = (name: string): TableDef | undefined => {
+    if (name === table.name) return table;
+    for (const join of state.joins) {
+      if ((join.alias ?? join.table.name) === name) return join.table;
+    }
+    return undefined;
+  };
+
+  const toFragment = (): Fragment => {
+    const items = Object.entries(projection).map(([alias, entry]) =>
+      entry.kind === "column"
+        ? text(
+            `${entry.table === undefined ? "" : `"${entry.table}".`}"${entry.name}" AS "${alias}"`,
+          )
+        : concat([exprFragment(entry), text(`AS "${alias}"`)], " "),
+    );
+    const parts: (Fragment | string)[] = [
+      state.distinct ? text("SELECT DISTINCT") : text("SELECT"),
+      concat(items, ", "),
+      text(`FROM "${table.name}"`),
+    ];
+    for (const join of state.joins) {
+      const target =
+        join.alias === undefined
+          ? `"${join.table.name}"`
+          : `"${join.table.name}" AS "${join.alias}"`;
+      if (join.kind === "cross") {
+        parts.push(text(`CROSS JOIN ${target}`));
+        continue;
+      }
+      const keyword = join.kind === "inner" ? "JOIN" : `${join.kind.toUpperCase()} JOIN`;
+      parts.push(text(`${keyword} ${target} ON`), join.on ?? text("1 = 1"));
+    }
+    if (state.condition !== undefined) parts.push(text("WHERE"), state.condition);
+    if (state.group.length > 0) {
+      const groupParts = state.group.map((item) =>
+        typeof item === "string"
+          ? text(`"${table.name}"."${item}"`)
+          : item.kind === "column"
+            ? text(columnSql(item))
+            : exprFragment(item),
+      );
+      parts.push(text("GROUP BY"), concat(groupParts, ", "));
+    }
+    if (state.having !== undefined) parts.push(text("HAVING"), state.having);
+    if (state.order.length > 0) {
+      const orderParts = state.order.map((order) => {
+        const ref =
+          typeof order.column === "string"
+            ? text(`"${table.name}"."${order.column}"`)
+            : order.column.kind === "column"
+              ? text(columnSql(order.column))
+              : exprFragment(order.column);
+        return concat([ref, text(order.direction.toUpperCase())], " ");
+      });
+      parts.push(text("ORDER BY"), concat(orderParts, ", "));
+    }
+    if (state.limit !== undefined) parts.push(fragment("LIMIT ?", [state.limit]));
+    if (state.offset !== undefined) parts.push(fragment("OFFSET ?", [state.offset]));
+    if (state.lock !== undefined) parts.push(state.lock);
+    return withCtes(state.ctes, concat(parts, " "));
+  };
+
+  const query: SelectQuery<T> = {
+    where(condition) {
+      state.condition = state.condition === undefined ? condition : and(state.condition, condition);
+      return query;
+    },
+    join(joined, on, kind = "inner", alias) {
+      state.joins.push({ table: joined, on, kind, alias });
+      return query;
+    },
+    with(name, queryText, options = {}) {
+      state.ctes.push({ name, query: queryText, ...options });
+      return query;
+    },
+    forUpdate(options) {
+      state.lock = forUpdateSql(options);
+      return query;
+    },
+    groupBy(...columns) {
+      state.group.push(...columns);
+      return query;
+    },
+    having(condition) {
+      state.having = condition;
+      return query;
+    },
+    distinct() {
+      state.distinct = true;
+      return query;
+    },
+    orderBy(column, direction = "asc") {
+      state.order.push({ column, direction });
+      return query;
+    },
+    limit(count) {
+      state.limit = count;
+      return query;
+    },
+    offset(count) {
+      state.offset = count;
+      return query;
+    },
+    toFragment,
+    async *[Symbol.asyncIterator]() {
+      for await (const row of database.iterate<Record<string, unknown>>(toFragment())) {
+        yield normalize(row);
+      }
+    },
+  };
+  return query;
+}

package/src/table/types.ts

@@ -0,0 +1,53 @@
+import type { ColumnDef, TableDef } from "../defs.ts";
+import type { ColumnRef, ExprOperand, Operand } from "../expr.ts";
+
+/**
+ * 一列对外的 TS 值类型：文本 → string、布尔 → boolean、64 位整数（`bigint`）→ JS `bigint`（精确，
+ * 对应 Go 的 int64 / uint64；不能用 number，超过 `2^53` 会丢精度）、其余 → number。
+ * 非 NOT NULL 允许 null。
+ */
+export type ColumnValue<C extends ColumnDef> = C["type"] extends "text"
+  ? string
+  : C["type"] extends "boolean"
+    ? boolean
+    : C["type"] extends "bigint"
+      ? bigint
+      : number;
+
+export type RowOf<T extends TableDef> = {
+  [K in keyof T["columns"]]: T["columns"][K] extends { notNull: true }
+    ? ColumnValue<T["columns"][K]>
+    : T["columns"][K] extends { type: "serial" }
+      ? ColumnValue<T["columns"][K]>
+      : ColumnValue<T["columns"][K]> | null;
+};
+
+/** 写入时 `bigint` 列也接受 number（安全整数范围内两者等价）。 */
+type Writable<T> = T extends bigint ? bigint | number : T;
+
+/**
+ * 写入行：列可选（有默认值 / 自增列不必给）。值允许 number 写进 `bigint` 列，业务不必到处写 `n` 后缀；
+ * 读回来仍然是 `bigint`（不丢精度）。
+ */
+export type InsertRow<Row> = Partial<{ [K in keyof Row]: Writable<Row[K]> }>;
+
+/** 更新时的值：普通值（绑定参数）或表达式（`expr('"f_revision" + 1')` 等）。 */
+export type UpdatePatch<Row> = { [K in keyof Row]?: Writable<Row[K]> | Operand };
+
+/** 列名（字符串键）。 */
+export type ColumnName<Row> = Extract<keyof Row, string>;
+
+/**
+ * 聚合表达式（`count()` / `sum(col)`）：投影与条件里都能用。
+ *
+ * 值是 64 位整数：PostgreSQL 给 `bigint`、SQLite 给 number，业务要 number 时显式 `Number(x)`。
+ */
+export type Aggregate<T = number | bigint> = ExprOperand<T>;
+
+/** 投影：别名 → 列引用或聚合。结果类型由它推导。 */
+export type Projection = Record<string, ColumnRef<any> | Aggregate<any>>;
+
+/** 投影的强类型结果。 */
+export type Projected<P extends Projection> = {
+  [K in keyof P]: P[K] extends ColumnRef<infer T> ? T : P[K] extends Aggregate<infer T> ? T : never;
+};