@murumets-ee/db 0.1.5 → 0.3.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { PgTableWithColumns } from "drizzle-orm/pg-core";
+import { SQL } from "drizzle-orm";
+import { AnyPgColumn, PgColumnBuilderBase, PgTable, PgTableWithColumns, TableConfig } from "drizzle-orm/pg-core";
 
 //#region src/client.d.ts
 interface DbConfig {
@@ -19,9 +20,35 @@ declare function createDbClient(config: DbConfig): PostgresJsDatabase;
 declare function createReadOnlyClient(config: DbConfig): PostgresJsDatabase;
 //#endregion
 //#region src/migrate.d.ts
+/**
+ * Arguments passed to migration `up` / `down` functions.
+ *
+ * Intentionally tiny: we hand over a read-write Drizzle handle bound to
+ * the current transaction. If a migration needs anything beyond raw SQL
+ * (e.g. calling an AdminClient for a data backfill), it can import the
+ * relevant toolkit helpers inside the migration file — the CLI loader
+ * runs the migration in the same process as the config, so all package
+ * imports resolve normally.
+ */
+interface MigrateArgs {
+  db: PostgresJsDatabase;
+}
+/**
+ * Shape of a migration module loaded from a `.ts` file.
+ *
+ * At minimum a migration must export `up`. `down` is optional — when
+ * absent, `lumi migrate:rollback` refuses to roll that file back.
+ */
+interface MigrationModule {
+  up: (args: MigrateArgs) => Promise<void>;
+  down?: (args: MigrateArgs) => Promise<void>;
+}
 interface MigrationSource {
+  /** Absolute path to the migration file on disk. */
   path: string;
+  /** `project` for user migrations, `toolkit` for shipped-with-toolkit ones. */
   namespace: 'toolkit' | 'project';
+  /** Filename only, used for ordering + tracking. */
   name: string;
 }
 interface MigrationStatus {
@@ -29,17 +56,48 @@ interface MigrationStatus {
   pending: MigrationSource[];
 }
 /**
- * Discover migrations from both toolkit (.toolkit/) and project (migrations/) directories
+ * Loader callback — imports a migration `.ts` file and returns its exports.
+ *
+ * The CLI owns `jiti` (already used to load `toolkit.config.ts`), so
+ * `@murumets-ee/db` stays free of TS-runtime loader dependencies.
+ * Callers who never apply migrations (read-only servers, tests) never
+ * pay the loader cost.
  */
-declare function discoverMigrations(projectRoot: string): Promise<MigrationSource[]>;
+type MigrationLoader = (absolutePath: string) => Promise<MigrationModule>;
 /**
- * Get the status of migrations (applied vs pending)
+ * Discover all migration files under `projectRoot/migrations`.
+ *
+ * Layout:
+ *   migrations/
+ *     20260411_180000_add_articles.ts   ← user migrations (sort chronologically)
+ *     20260411_180000_add_articles.snapshot.json
+ *     .toolkit/
+ *       0001_initial_schema.ts          ← toolkit-owned migrations (sort numerically)
  */
+declare function discoverMigrations(projectRoot: string): Promise<MigrationSource[]>;
+/** Split discovered migrations into applied vs pending by consulting the tracking table. */
 declare function getMigrationStatus(db: PostgresJsDatabase, projectRoot: string): Promise<MigrationStatus>;
 /**
- * Run pending migrations
+ * Apply every pending migration in order.
+ *
+ * Each file runs inside its own transaction: the migration's `up()`
+ * executes first, then the `_toolkit_migrations` insert commits. If
+ * `up()` throws, the transaction rolls back and the whole command
+ * aborts — nothing gets half-applied.
+ *
+ * The `loader` callback is injected so `@murumets-ee/db` itself doesn't
+ * depend on a TS-runtime loader. Callers pass a jiti-backed loader from
+ * the CLI or their own equivalent.
+ */
+declare function runMigrations(db: PostgresJsDatabase, projectRoot: string, loader: MigrationLoader): Promise<void>;
+/**
+ * Roll back the most recent applied migration (or N most recent).
+ *
+ * Each file's `down()` runs in its own transaction. Files without a
+ * `down` export cause the rollback to abort before running anything —
+ * we never roll back some but not all of a requested batch.
  */
-declare function runMigrations(db: PostgresJsDatabase, projectRoot: string): Promise<void>;
+declare function rollbackMigrations(db: PostgresJsDatabase, projectRoot: string, loader: MigrationLoader, count?: number): Promise<void>;
 //#endregion
 //#region src/schema-registry.d.ts
 /**
@@ -74,5 +132,816 @@ declare const schemaRegistry: SchemaRegistryImpl;
  */
 declare function createSchemaRegistry(): SchemaRegistry;
 //#endregion
-export { type DbConfig, type MigrationSource, type MigrationStatus, type SchemaRegistry, createDbClient, createReadOnlyClient, createSchemaRegistry, discoverMigrations, getMigrationStatus, runMigrations, schemaRegistry };
+//#region src/table/types.d.ts
+/**
+ * The discriminating "kind" tag for a column factory.
+ *
+ * Used at the type level to gate features that only make sense for certain
+ * kinds — e.g. only `'jsonb'` columns accept dotted-path keys in the
+ * where-builder.
+ */
+type ColumnKind = 'uuid' | 'varchar' | 'text' | 'integer' | 'bigint' | 'double' | 'boolean' | 'timestamp' | 'jsonb' | 'uuidArray';
+/**
+ * Internal column factory.
+ *
+ * A `ColumnFactory` is a callable that, given a column name, produces the
+ * corresponding Drizzle column builder. The phantom type parameters
+ * (`__type`, `__kind`, `__notNull`) are used purely for compile-time
+ * inference of {@link Row} and {@link InsertRow} types — they have no runtime
+ * representation beyond a small metadata object.
+ *
+ * Users do not construct `ColumnFactory` values directly; they use the
+ * `column.*` builders from `./columns.ts`.
+ */
+interface ColumnFactory<TType = unknown, TKind extends ColumnKind = ColumnKind, TNotNull extends boolean = boolean, THasDefault extends boolean = boolean> {
+  /** Build the underlying Drizzle column for the given column name. */
+  (name: string): PgColumnBuilderBase;
+  readonly __type: TType;
+  readonly __kind: TKind;
+  readonly __notNull: TNotNull;
+  readonly __hasDefault: THasDefault;
+  /**
+   * Optional explicit Postgres column name. When set, the column uses this
+   * name in the database instead of the JS property name. Needed when porting
+   * existing tables that use snake_case column names to `defineTable`.
+   */
+  readonly __pgName?: string;
+  /** True when the column is declared as a primary key at the column level. */
+  readonly __primaryKey?: boolean;
+}
+/**
+ * Convenience helper: extract the JS value type for a single column.
+ *
+ * - `notNull: true` → `T`
+ * - `notNull: false` → `T | null`
+ */
+type ColumnValue<C> = C extends ColumnFactory<infer T, ColumnKind, infer N> ? N extends true ? T : T | null : never;
+/**
+ * Map a columns record to its row shape (the result of a SELECT).
+ */
+type Row<TCols extends Record<string, ColumnFactory>> = { [K in keyof TCols]: ColumnValue<TCols[K]> };
+/**
+ * Map a columns record to its insert shape.
+ *
+ * - Required columns: must be supplied unless they have a default
+ * - Nullable columns: optional, accept `null`
+ * - Columns with defaults (`defaultRandom`, `defaultNow`, explicit `default`): optional
+ */
+type InsertRow<TCols extends Record<string, ColumnFactory>> = { [K in keyof TCols as TCols[K] extends ColumnFactory<unknown, ColumnKind, true, false> ? K : never]: ColumnValue<TCols[K]> } & { [K in keyof TCols as TCols[K] extends ColumnFactory<unknown, ColumnKind, true, false> ? never : K]?: ColumnValue<TCols[K]> };
+/**
+ * Operator object for a single column.
+ *
+ * Each property is a comparison operator. Combine with `$and` / `$or` /
+ * `$not` at the parent level to build composite predicates.
+ *
+ * `ilike` and `startsWith` accept user-supplied strings — the table client
+ * automatically escapes `%` and `_` in the value before wrapping with
+ * pattern wildcards, so callers cannot inject pattern characters by accident.
+ *
+ * @example
+ * ```ts
+ * { status: 'open' }                      // shorthand for { eq: 'open' }
+ * { status: { in: ['open', 'pending'] } }
+ * { createdAt: { gte: new Date('2026-01-01') } }
+ * { name: { ilike: 'foo%' } }             // % escaped from value, only outer wildcards work
+ * { description: { isNull: true } }
+ * ```
+ */
+type ColumnOperators<T> = T | null | {
+  eq: T;
+} | {
+  ne: T;
+} | {
+  in: T[];
+} | {
+  notIn: T[];
+} | {
+  gt: T;
+} | {
+  gte: T;
+} | {
+  lt: T;
+} | {
+  lte: T;
+} | {
+  isNull: true;
+} | {
+  isNotNull: true;
+} | {
+  ilike: string;
+} | {
+  startsWith: string;
+};
+/**
+ * The full WhereClause type.
+ *
+ * Keys are either column names or dotted-path keys for jsonb columns
+ * (e.g. `'metadata.author.name'`). Values are operator objects per
+ * {@link ColumnOperators}.
+ *
+ * Combine with `$and` / `$or` / `$not` for composite predicates. All
+ * top-level keys are implicitly AND-ed together.
+ *
+ * The type intentionally accepts `string` for jsonb-path keys rather than
+ * a precisely-narrowed template literal, because the path's nested type is
+ * unknown to the column definition. Path segments are validated at runtime
+ * against `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` and the parent column must
+ * be a `jsonb` kind, otherwise the where-builder throws.
+ *
+ * @example
+ * ```ts
+ * // Simple equality
+ * { userId: 'u_123', status: 'active' }
+ *
+ * // Composite with $or
+ * { $or: [
+ *   { status: 'open' },
+ *   { status: 'pending', assignee: { isNull: true } },
+ * ] }
+ *
+ * // jsonb path access (column 'metadata' must be jsonb)
+ * { 'metadata.author.name': { ilike: 'alice%' } }
+ * ```
+ */
+type WhereClause<TCols extends Record<string, ColumnFactory>> = { [K in keyof TCols]?: ColumnOperators<ColumnValue<TCols[K]>> } & {
+  [key: `${string}.${string}`]: ColumnOperators<unknown>;
+} & {
+  $and?: WhereClause<TCols>[];
+  $or?: WhereClause<TCols>[];
+  $not?: WhereClause<TCols>;
+};
+/**
+ * Index definition for a table.
+ *
+ * Indexes are declared at the table level (not per-column) so composite
+ * indexes are first-class. Each index gets an auto-generated name unless
+ * `name` is supplied: `idx_<table>_<col1>_<col2>`.
+ */
+interface IndexDefinition<TCols extends Record<string, ColumnFactory>> {
+  on: (keyof TCols)[];
+  name?: string;
+}
+/**
+ * Unique constraint definition.
+ *
+ * Composite uniques (multi-column) are declared here. Single-column
+ * uniqueness is also supported here rather than as a column-level option,
+ * to keep the column builder API uniform.
+ */
+interface UniqueDefinition<TCols extends Record<string, ColumnFactory>> {
+  on: (keyof TCols)[];
+  name?: string;
+}
+/**
+ * The shape passed to `defineTable`.
+ *
+ * @example
+ * ```ts
+ * defineTable({
+ *   name: 'ticket_read_state',
+ *   columns: {
+ *     ticketId: column.uuid({ notNull: true }),
+ *     userId:   column.varchar({ length: 255, notNull: true }),
+ *     lastReadAt: column.timestamp({ notNull: true, defaultNow: true, withTimezone: true }),
+ *   },
+ *   primaryKey: ['ticketId', 'userId'],
+ *   indexes: [{ on: ['userId'] }],
+ * })
+ * ```
+ */
+interface TableDefinition<TCols extends Record<string, ColumnFactory>> {
+  /**
+   * Postgres table name. Convention: snake_case, prefix with package name
+   * (e.g. `toolkit_jobs`, `ticketing_read_state`).
+   *
+   * Validated at definition time against `/^[a-z][a-z0-9_]*$/` to prevent
+   * accidental quoting issues and to enforce a consistent naming scheme.
+   */
+  name: string;
+  columns: TCols;
+  /**
+   * Primary key column(s). May be a single column key or an array for
+   * composite keys.
+   *
+   * If omitted, the table has no primary key — only valid for tables that
+   * declare a column with `primaryKey: true` at the column level (e.g. via
+   * `column.uuid({ primaryKey: true, defaultRandom: true })`).
+   */
+  primaryKey?: keyof TCols | (keyof TCols)[];
+  unique?: UniqueDefinition<TCols>[];
+  indexes?: IndexDefinition<TCols>[];
+}
+//#endregion
+//#region src/table/columns.d.ts
+/**
+ * Type interface for the `column` builder namespace.
+ *
+ * Overloads discriminate on whether `default` is present, so
+ * `THasDefault` is inferred correctly:
+ *
+ * - `column.varchar({ length: 20, default: 'x' })` → `hasDefault = true`
+ * - `column.varchar({ length: 20 })`               → `hasDefault = false`
+ *
+ * Object-literal methods don't support overloads in TypeScript, so we
+ * declare the overloaded signatures on an interface and cast the
+ * implementation object.
+ */
+interface ColumnBuilders {
+  uuid<TPrimaryKey extends boolean = false, TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    primaryKey?: TPrimaryKey;
+    notNull?: TNotNull;
+    defaultRandom?: THasDefault;
+    pgName?: string;
+  }): ColumnFactory<string, 'uuid', TPrimaryKey extends true ? true : TNotNull extends true ? true : false, TPrimaryKey extends true ? true : THasDefault extends true ? true : false>;
+  varchar<TNotNull extends boolean = false>(opts: {
+    length: number;
+    notNull?: TNotNull;
+    default: string;
+    pgName?: string;
+  }): ColumnFactory<string, 'varchar', TNotNull extends true ? true : false, true>;
+  varchar<TNotNull extends boolean = false>(opts: {
+    length: number;
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<string, 'varchar', TNotNull extends true ? true : false, false>;
+  text<TNotNull extends boolean = false>(opts: {
+    notNull?: TNotNull;
+    default: string;
+    pgName?: string;
+  }): ColumnFactory<string, 'text', TNotNull extends true ? true : false, true>;
+  text<TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<string, 'text', TNotNull extends true ? true : false, false>;
+  integer<TNotNull extends boolean = false>(opts: {
+    notNull?: TNotNull;
+    default: number;
+    pgName?: string;
+  }): ColumnFactory<number, 'integer', TNotNull extends true ? true : false, true>;
+  integer<TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<number, 'integer', TNotNull extends true ? true : false, false>;
+  bigint<TMode extends 'number' | 'bigint' = 'number', TNotNull extends boolean = false>(opts: {
+    mode?: TMode;
+    notNull?: TNotNull;
+    default: TMode extends 'bigint' ? bigint : number;
+    pgName?: string;
+  }): ColumnFactory<TMode extends 'bigint' ? bigint : number, 'bigint', TNotNull extends true ? true : false, true>;
+  bigint<TMode extends 'number' | 'bigint' = 'number', TNotNull extends boolean = false>(opts?: {
+    mode?: TMode;
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<TMode extends 'bigint' ? bigint : number, 'bigint', TNotNull extends true ? true : false, false>;
+  double<TNotNull extends boolean = false>(opts: {
+    notNull?: TNotNull;
+    default: number;
+    pgName?: string;
+  }): ColumnFactory<number, 'double', TNotNull extends true ? true : false, true>;
+  double<TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<number, 'double', TNotNull extends true ? true : false, false>;
+  boolean<TNotNull extends boolean = false>(opts: {
+    notNull?: TNotNull;
+    default: boolean;
+    pgName?: string;
+  }): ColumnFactory<boolean, 'boolean', TNotNull extends true ? true : false, true>;
+  boolean<TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<boolean, 'boolean', TNotNull extends true ? true : false, false>;
+  timestamp<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    defaultNow?: THasDefault;
+    withTimezone?: boolean;
+    pgName?: string;
+  }): ColumnFactory<Date, 'timestamp', TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
+  jsonb<T = unknown, TNotNull extends boolean = false>(opts: {
+    notNull?: TNotNull;
+    default: T;
+    pgName?: string;
+  }): ColumnFactory<T, 'jsonb', TNotNull extends true ? true : false, true>;
+  jsonb<T = unknown, TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<T, 'jsonb', TNotNull extends true ? true : false, false>;
+  uuidArray<TNotNull extends boolean = false>(opts?: {
+    notNull?: TNotNull;
+    pgName?: string;
+  }): ColumnFactory<string[], 'uuidArray', TNotNull extends true ? true : false, false>;
+}
+/**
+ * Column builder namespace — overloaded interface applied via single
+ * assertion. Each builder's implementation returns `makeFactory(...)` with
+ * widened boolean params; the `ColumnBuilders` overloads narrow them for
+ * callers based on whether `default`/`primaryKey` etc. are present.
+ */
+declare const column: ColumnBuilders;
+//#endregion
+//#region src/table/client.d.ts
+/**
+ * Default page size for `findMany` when no `limit` is supplied.
+ *
+ * Chosen as a safe upper bound for "show me a page of stuff" — anything
+ * above this should be paginated explicitly.
+ */
+declare const DEFAULT_LIMIT = 100;
+/**
+ * Hard cap on `findMany.limit`. Caller-supplied values above this are
+ * clamped and a warning is emitted via `console.warn`.
+ */
+declare const MAX_LIMIT = 1000;
+/**
+ * Hard cap on `insertMany.values.length` per single call.
+ */
+declare const MAX_BATCH = 1000;
+/**
+ * A custom error thrown by the table client for any caller-side mistake
+ * (empty where on update/delete, batch too large, malformed where, …).
+ *
+ * Database errors are NOT wrapped — they propagate as-is from postgres-js
+ * so callers can match on Postgres error codes.
+ */
+declare class TableClientError extends Error {
+  constructor(message: string);
+}
+/**
+ * Order-by spec accepted by `findMany`.
+ */
+interface OrderBySpec<TCols extends Record<string, ColumnFactory>> {
+  column: keyof TCols & string;
+  dir?: 'asc' | 'desc';
+}
+/**
+ * `findMany` options.
+ */
+interface FindManyOptions<TCols extends Record<string, ColumnFactory>> {
+  where?: WhereClause<TCols>;
+  orderBy?: OrderBySpec<TCols>[];
+  limit?: number;
+  offset?: number;
+}
+/**
+ * Options for the `claim()` atomic locking operation.
+ *
+ * @see {@link TableClient.claim}
+ */
+interface ClaimOptions<TCols extends Record<string, ColumnFactory>> {
+  /** Filter for rows eligible to be claimed. Must be non-empty. */
+  where: WhereClause<TCols>;
+  /** Literal values to SET on claimed rows. */
+  set?: Partial<InsertRow<TCols>>;
+  /** Raw SQL expressions to SET (e.g. `{ attempts: sql\`attempts + 1\` }`). */
+  setSql?: Record<string, SQL>;
+  /** ORDER BY for the subselect — controls claim priority. */
+  orderBy?: OrderBySpec<TCols>[];
+  /** Maximum number of rows to claim. Must be 1..MAX_LIMIT. */
+  limit: number;
+}
+/**
+ * Specification for a single aggregate function.
+ */
+type AggregateSpec<TCols extends Record<string, ColumnFactory>> = {
+  fn: 'count';
+} | {
+  fn: 'count';
+  column: keyof TCols & string;
+} | {
+  fn: 'sum' | 'avg' | 'min' | 'max';
+  column: keyof TCols & string;
+};
+/**
+ * Options for the `aggregate()` method.
+ */
+interface AggregateOptions<TCols extends Record<string, ColumnFactory>> {
+  /** Named aggregate expressions. Each key becomes an output column. */
+  select: Record<string, AggregateSpec<TCols>>;
+  /** Columns to GROUP BY. Included automatically in the result. */
+  groupBy?: (keyof TCols & string)[];
+  /** Filter rows before aggregation (WHERE). */
+  where?: WhereClause<TCols>;
+  /** Order results. Can reference both grouped columns and aliases. */
+  orderBy?: OrderBySpec<TCols>[];
+  /** Limit the number of groups returned. */
+  limit?: number;
+}
+/**
+ * Generic CRUD client. Constructed by `defineTable` — never instantiated
+ * directly by callers.
+ *
+ * The same instance shape is exposed both at the top level (using the
+ * package's main `db` connection) and inside a `transaction()` callback
+ * (using the transactional `tx` handle), so user code is identical
+ * regardless of transactional context.
+ *
+ * @template TCols The columns record passed to `defineTable`.
+ */
+declare class TableClient<TCols extends Record<string, ColumnFactory>> {
+  /** The Drizzle table object. Exposed via `defineTable().table` for typed JOINs. */
+  readonly table: PgTable;
+  /** Per-column kind metadata. Used by the where-builder for jsonb path validation. */
+  private readonly columnKinds;
+  /**
+   * The active database handle. May be a top-level `PostgresJsDatabase`
+   * or a transaction handle of compatible shape — the client doesn't
+   * distinguish.
+   */
+  private readonly db;
+  /** Primary key column names. Required by `claim()`. Empty for tables without a declared PK. */
+  private readonly primaryKeyColumns;
+  /**
+   * @internal — instances are created by `defineTable()`.
+   */
+  constructor(/** The Drizzle table object. Exposed via `defineTable().table` for typed JOINs. */
+
+  table: PgTable, /** Per-column kind metadata. Used by the where-builder for jsonb path validation. */
+
+  columnKinds: Readonly<Record<string, ColumnKind>>,
+  /**
+   * The active database handle. May be a top-level `PostgresJsDatabase`
+   * or a transaction handle of compatible shape — the client doesn't
+   * distinguish.
+   */
+
+  db: PostgresJsDatabase, /** Primary key column names. Required by `claim()`. Empty for tables without a declared PK. */
+
+  primaryKeyColumns?: readonly string[]);
+  /**
+   * Find a single row matching the given where clause, or `null` if no row
+   * matches. Throws if the where is empty.
+   *
+   * @example
+   * ```ts
+   * await readState.client.findOne({ ticketId: 't_1', userId: 'u_1' })
+   * ```
+   */
+  findOne(where: WhereClause<TCols>): Promise<Row<TCols> | null>;
+  /**
+   * Find multiple rows. Pagination, ordering, and filtering are all
+   * optional but `limit` is hard-capped at {@link MAX_LIMIT}.
+   *
+   * @example
+   * ```ts
+   * await jobs.client.findMany({
+   *   where: { status: 'pending', runAt: { lte: new Date() } },
+   *   orderBy: [{ column: 'priority', dir: 'desc' }, { column: 'runAt', dir: 'asc' }],
+   *   limit: 25,
+   * })
+   * ```
+   */
+  findMany(options?: FindManyOptions<TCols>): Promise<Row<TCols>[]>;
+  /**
+   * Count rows matching the where clause. Returns an exact count via
+   * `SELECT COUNT(*)`. For estimated/cached counts on large tables, see
+   * `countEstimate()` and `countCached()` (added in a follow-up PR).
+   *
+   * @example
+   * ```ts
+   * const open = await jobs.client.count({ status: 'pending' })
+   * ```
+   */
+  count(where?: WhereClause<TCols>): Promise<number>;
+  /**
+   * Returns `true` if at least one row matches the where clause. Always
+   * uses `LIMIT 1` and short-circuits — cheaper than `count() > 0` on
+   * large tables.
+   */
+  exists(where: WhereClause<TCols>): Promise<boolean>;
+  /**
+   * Return unique non-null values for a single column.
+   *
+   * Null values are excluded by default — pass `includeNull: true` to
+   * include them. Results can be filtered with `where` and ordered with
+   * `orderBy` (ascending or descending on the distinct column).
+   *
+   * @example Get distinct entity types from the audit log
+   * ```ts
+   * const types = await audit.client.distinct('entityType', { orderBy: 'asc' })
+   * ```
+   *
+   * @example Distinct with a filter
+   * ```ts
+   * const actions = await audit.client.distinct('action', {
+   *   where: { userId: 'u_1' },
+   *   orderBy: 'asc',
+   * })
+   * ```
+   */
+  distinct<K extends keyof TCols & string>(column: K, options?: {
+    where?: WhereClause<TCols>;
+    orderBy?: 'asc' | 'desc'; /** Include null values in the result. Defaults to `false`. */
+    includeNull?: boolean;
+  }): Promise<ColumnValue<TCols[K]>[]>;
+  /**
+   * Insert a single row. Returns the inserted row (server-generated
+   * defaults populated).
+   */
+  insert(values: InsertRow<TCols>): Promise<Row<TCols>>;
+  /**
+   * Upsert: insert a row, or update an existing row if a unique constraint
+   * conflict occurs.
+   *
+   * `target` names the column(s) whose unique constraint should trigger
+   * the conflict path. `set` is the patch applied on conflict — when
+   * omitted, the conflict path applies the same `values` (i.e. "last
+   * write wins").
+   *
+   * `setWhere` adds a conditional WHERE to the conflict update path. If
+   * the condition does not match, the update is skipped and the existing
+   * row is returned unchanged (via a fallback SELECT). This enables
+   * patterns like "only update if the new version is higher than the
+   * existing one".
+   *
+   * @example Idempotent "mark as read" tracking
+   * ```ts
+   * await readState.client.upsert(
+   *   { ticketId, userId, lastReadAt: new Date() },
+   *   { target: ['ticketId', 'userId'] },
+   * )
+   * ```
+   *
+   * @example Conditional update — only bump if newer
+   * ```ts
+   * await state.client.upsert(
+   *   { key: 'sync', version: 5, data: '...' },
+   *   { target: 'key', setWhere: { version: { lt: 5 } } },
+   * )
+   * ```
+   */
+  upsert(values: InsertRow<TCols>, opts: {
+    target: (keyof TCols & string) | (keyof TCols & string)[];
+    set?: Partial<InsertRow<TCols>>; /** Conditional WHERE on the conflict update path. Empty objects are ignored. */
+    setWhere?: WhereClause<TCols>;
+  }): Promise<Row<TCols>>;
+  /**
+   * Insert many rows in a single statement. Capped at {@link MAX_BATCH}.
+   * Returns all inserted rows in input order.
+   */
+  insertMany(values: InsertRow<TCols>[]): Promise<Row<TCols>[]>;
+  /**
+   * Update **at most one** row matching the where clause. Returns the
+   * updated row, or `null` if no row matched.
+   *
+   * Throws `TableClientError` if:
+   * - the where is empty
+   * - the where matches more than one row
+   *
+   * The multi-row guard exists to prevent silent bulk updates from a
+   * mistakenly-broad where. If you genuinely want to update multiple
+   * rows in one call, use {@link updateMany}, which is explicit about
+   * its plurality.
+   *
+   * Implementation note: this issues a single `UPDATE … RETURNING` and
+   * inspects the returned row count *after* the fact. The extra rows
+   * over the wire are the cost of the safety check; the alternative
+   * (a SELECT round-trip first) would be more rows AND a race window.
+   * If the affected count is > 1 the update has *already* happened —
+   * the throw is to surface the bug, not to prevent it. Wrap in a
+   * transaction if you need atomic rollback.
+   */
+  update(where: WhereClause<TCols>, patch: Partial<InsertRow<TCols>>): Promise<Row<TCols> | null>;
+  /**
+   * Update all rows matching the where clause. Returns every updated row.
+   * Throws if the where is empty — there is no "update everything" path.
+   */
+  updateMany(where: WhereClause<TCols>, patch: Partial<InsertRow<TCols>>): Promise<Row<TCols>[]>;
+  /**
+   * Delete **at most one** row matching the where clause. Returns the
+   * deleted row, or `null` if no row matched.
+   *
+   * Throws `TableClientError` if:
+   * - the where is empty
+   * - the where matches more than one row
+   *
+   * Same multi-row safety guard as {@link update}. Use {@link deleteMany}
+   * for explicit bulk deletes.
+   *
+   * Implementation note: same as `update` — the delete has already
+   * happened by the time the throw fires. Wrap in a transaction if you
+   * need atomic rollback.
+   */
+  delete(where: WhereClause<TCols>): Promise<Row<TCols> | null>;
+  /**
+   * Delete all rows matching the where clause. Returns every deleted row.
+   * Throws if the where is empty — there is no "delete everything" path.
+   */
+  deleteMany(where: WhereClause<TCols>): Promise<Row<TCols>[]>;
+  /**
+   * Run a callback inside a database transaction. The callback receives a
+   * transactional `TableClient` instance with the same shape as the
+   * top-level client — write code identically inside or outside.
+   *
+   * Throwing from the callback rolls back; returning a value commits.
+   *
+   * @example
+   * ```ts
+   * await files.client.transaction(async (tx) => {
+   *   const row = await tx.insert(values)
+   *   await adapter.upload(row.key, buffer)  // if this throws, the row is rolled back
+   *   return row
+   * })
+   * ```
+   */
+  transaction<T>(fn: (tx: TableClient<TCols>) => Promise<T>): Promise<T>;
+  /**
+   * Atomically claim rows using `FOR UPDATE SKIP LOCKED`.
+   *
+   * Selects rows matching `where`, locks them (skipping any already locked
+   * by another worker), updates them with `set`/`setSql`, and returns the
+   * claimed rows in a single atomic operation. This is the standard pattern
+   * for job queues, task distribution, and any producer-consumer table.
+   *
+   * Requires the table to have a declared primary key (either via
+   * `column.uuid({ primaryKey: true })` or `defineTable({ primaryKey })`.
+   *
+   * @example Job queue claim
+   * ```ts
+   * const jobs = await client.claim({
+   *   where: { status: 'pending', runAt: { lte: new Date() } },
+   *   set: { status: 'processing', lockedBy: workerId, lockedAt: new Date() },
+   *   setSql: { attempts: sql`${jobsTable.table.attempts} + 1` },
+   *   orderBy: [{ column: 'priority', dir: 'desc' }, { column: 'createdAt', dir: 'asc' }],
+   *   limit: 5,
+   * })
+   * ```
+   */
+  claim(options: ClaimOptions<TCols>): Promise<Row<TCols>[]>;
+  /**
+   * Run an aggregate query with GROUP BY.
+   *
+   * Each key in `select` is an output alias mapped to an aggregate
+   * specification. The `groupBy` columns are included automatically in
+   * the result. Returns typed rows with grouped column values plus the
+   * computed aggregates.
+   *
+   * @example Count jobs by status
+   * ```ts
+   * const rows = await client.aggregate({
+   *   select: { count: { fn: 'count' } },
+   *   groupBy: ['status'],
+   * })
+   * // → [{ status: 'pending', count: 12 }, { status: 'completed', count: 45 }]
+   * ```
+   *
+   * @example Average priority of open jobs
+   * ```ts
+   * const [row] = await client.aggregate({
+   *   select: { avgPriority: { fn: 'avg', column: 'priority' } },
+   *   where: { status: 'open' },
+   * })
+   * ```
+   */
+  aggregate<TResult extends Record<string, unknown> = Record<string, unknown>>(options: AggregateOptions<TCols>): Promise<TResult[]>;
+  /**
+   * Fast approximate row count using Postgres `reltuples` statistics.
+   *
+   * Returns the estimated row count from `pg_class` — updated by
+   * `ANALYZE` and autovacuum. Much faster than `COUNT(*)` on large
+   * tables (no sequential scan), but may be stale by up to a few
+   * percent. Returns 0 for tables that have never been analyzed.
+   *
+   * Use `count()` when you need an exact number. Use `countEstimate()`
+   * for UI display, pagination hints, or "is this table large?" checks
+   * where ±5% accuracy is fine.
+   *
+   * @example
+   * ```ts
+   * const approx = await client.countEstimate()
+   * if (approx > 100_000) {
+   *   // Switch to keyset pagination instead of offset
+   * }
+   * ```
+   */
+  countEstimate(): Promise<number>;
+  /** Build a single aggregate SQL expression from a spec. */
+  private buildAggregateExpr;
+  private buildWhereOrThrow;
+  private validateLimit;
+}
+//#endregion
+//#region src/table/define.d.ts
+/**
+ * The result of `defineTable()`.
+ *
+ * @template TCols The columns record passed to `defineTable`.
+ */
+interface DefinedTable<TCols extends Record<string, ColumnFactory>> {
+  /**
+   * The underlying Drizzle `pgTable`. Exposed so callers can use it in
+   * typed JOINs (the one sanctioned escape valve), and so it can be
+   * included in `Plugin.tables` for migration discovery by `lumi migrate`.
+   */
+  table: PgTableWithColumns<TableConfig>;
+  /**
+   * The original schema metadata. Useful for introspection / tooling
+   * that needs to know about indexes, unique constraints, etc.
+   */
+  schema: TableDefinition<TCols>;
+  /**
+   * Per-column kind metadata (column name → kind tag). Used internally
+   * by the where-builder for jsonb path validation.
+   */
+  columnKinds: Readonly<Record<string, ColumnKind>>;
+  /**
+   * Primary key column names (JS property names). Detected from either
+   * `schema.primaryKey` or column-level `{ primaryKey: true }`. Empty
+   * array if no PK is declared. Required by `claim()`.
+   */
+  primaryKeyColumns: readonly string[];
+  /**
+   * Build a typed CRUD client wired to the given database handle.
+   *
+   * Callers typically construct one client per logical "module" and
+   * cache it. The client is stateless aside from the db handle, so it
+   * is safe to share.
+   */
+  makeClient(db: PostgresJsDatabase): TableClient<TCols>;
+}
+/**
+ * Define a typed table.
+ *
+ * The function signature uses two const-generic parameters to preserve
+ * column literal types end-to-end. This is what enables `Row`,
+ * `InsertRow`, and `WhereClause` to know exact column shapes at the call
+ * site.
+ *
+ * @throws if the table name doesn't match the snake_case regex, or if
+ *   the same name is registered twice with different table objects.
+ */
+declare function defineTable<const TCols extends Record<string, ColumnFactory>>(def: TableDefinition<TCols>): DefinedTable<TCols>;
+//#endregion
+//#region src/table/registry.d.ts
+declare class TableRegistryImpl {
+  private byName;
+  /**
+   * Register a defined table. Throws if a table with the same name is
+   * already registered (catches accidental double-registration from a
+   * file being imported under two paths).
+   */
+  register(name: string, table: PgTable, source?: string): void;
+  /**
+   * Get a defined table by name.
+   */
+  get(name: string): PgTable | undefined;
+  /**
+   * Returns true if a table with the given name has been registered.
+   */
+  has(name: string): boolean;
+  /**
+   * Return every registered table as a `{ [name]: PgTable }` map.
+   *
+   * Useful for `createTestDb().push(tableRegistry.allTables())` and
+   * runtime introspection.
+   */
+  allTables(): Record<string, PgTable>;
+  /**
+   * Clear the registry. **Test-only.**
+   *
+   * Production code should never call this — clearing the registry
+   * silently breaks migration discovery and any code path that looks
+   * up a table by name. The runtime guard below refuses to run when
+   * `NODE_ENV === 'production'` to catch accidental misuse.
+   *
+   * Test runners typically set `NODE_ENV=test` (Vitest does), but the
+   * guard is permissive about other values — it only blocks the one
+   * environment where calling it is definitely wrong.
+   */
+  clear(): void;
+}
+/**
+ * Process-wide table registry singleton.
+ *
+ * Tables register themselves on import via `defineTable()`. The registry
+ * is module-level state, which means a single Node process sees one
+ * consistent view of all defined tables across packages.
+ */
+declare const tableRegistry: TableRegistryImpl;
+/**
+ * Create an isolated registry — useful for unit tests that want to
+ * verify registration behaviour without polluting the global registry.
+ */
+declare function createTableRegistry(): TableRegistryImpl;
+//#endregion
+//#region src/table/where-builder.d.ts
+/**
+ * A custom error thrown by the where-builder for any caller-side mistake.
+ *
+ * Catching `WhereBuilderError` lets the table client surface a 400-style
+ * error to its caller without conflating it with database errors.
+ */
+declare class WhereBuilderError extends Error {
+  constructor(message: string);
+}
+/**
+ * Returns true if a {@link WhereClause} produces a non-trivial filter (at
+ * least one column predicate or sub-clause). Useful for rejecting empty
+ * `where` arguments to `update`/`delete`/`updateMany`/`deleteMany`.
+ *
+ * Note: this does not check whether `buildWhere()` would actually emit SQL
+ * for the clause — it just checks that the user supplied something.
+ */
+declare function isNonEmptyWhere(clause: unknown): boolean;
+//#endregion
+export { type AnyPgColumn, type ClaimOptions, type ColumnFactory, type ColumnKind, type ColumnOperators, type ColumnValue, DEFAULT_LIMIT, type DbConfig, type DefinedTable, type FindManyOptions, type IndexDefinition, type InsertRow, MAX_BATCH, MAX_LIMIT, type MigrateArgs, type MigrationLoader, type MigrationModule, type MigrationSource, type MigrationStatus, type OrderBySpec, type Row, type SchemaRegistry, TableClient, TableClientError, type TableDefinition, type UniqueDefinition, WhereBuilderError, type WhereClause, column, createDbClient, createReadOnlyClient, createSchemaRegistry, createTableRegistry, defineTable, discoverMigrations, getMigrationStatus, isNonEmptyWhere, rollbackMigrations, runMigrations, schemaRegistry, tableRegistry };
 //# sourceMappingURL=index.d.mts.map