@murumets-ee/db 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,8 @@
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { AnyPgColumn, PgColumnBuilderBase, PgTable, PgTableWithColumns } from "drizzle-orm/pg-core";
+import * as _$drizzle_orm0 from "drizzle-orm";
+import { InferInsertModel, SQL } from "drizzle-orm";
+import * as _$drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+import { AnyPgColumn, PgColumnBuilderBase, PgTable, PgTableWithColumns, TableConfig } from "drizzle-orm/pg-core";
 
 //#region src/client.d.ts
 interface DbConfig {
@@ -159,6 +162,14 @@ interface ColumnFactory<TType = unknown, TKind extends ColumnKind = ColumnKind,
   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.
@@ -325,124 +336,110 @@ interface TableDefinition<TCols extends Record<string, ColumnFactory>> {
 //#endregion
 //#region src/table/columns.d.ts
 /**
- * Column builder namespace.
+ * Type interface for the `column` builder namespace.
  *
- * Each builder produces a {@link ColumnFactory}. Pass the result to a
- * `defineTable` `columns` field. The builders are typed so that the
- * resulting `Row` and `InsertRow` types track each column's value type
- * and nullability.
+ * Overloads discriminate on whether `default` is present, so
+ * `THasDefault` is inferred correctly:
  *
- * @example
- * ```ts
- * import { column, defineTable } from '@murumets-ee/db'
+ * - `column.varchar({ length: 20, default: 'x' })` → `hasDefault = true`
+ * - `column.varchar({ length: 20 })`               → `hasDefault = false`
  *
- * const jobs = defineTable({
- *   name: 'toolkit_jobs',
- *   columns: {
- *     id:       column.uuid({ primaryKey: true, defaultRandom: true }),
- *     type:     column.varchar({ length: 100, notNull: true }),
- *     payload:  column.jsonb<{ subject: string; body: string }>({ notNull: true }),
- *     status:   column.varchar({ length: 20, notNull: true, default: 'pending' }),
- *     priority: column.integer({ notNull: true, default: 0 }),
- *     runAt:    column.timestamp({ notNull: true, defaultNow: true, withTimezone: true }),
- *   },
- * })
- * ```
+ * Object-literal methods don't support overloads in TypeScript, so we
+ * declare the overloaded signatures on an interface and cast the
+ * implementation object.
  */
-declare const column: {
-  /**
-   * UUID column.
-   *
-   * For primary keys, use `{ primaryKey: true, defaultRandom: true }` to
-   * get a server-generated UUIDv4.
-   */
-  uuid<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
-    primaryKey?: boolean;
-    notNull?: TNotNull; /** Server-side `gen_random_uuid()` default. Counts as a default for type inference. */
+interface ColumnBuilders {
+  uuid<TPrimaryKey extends boolean = false, TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    primaryKey?: TPrimaryKey;
+    notNull?: TNotNull;
     defaultRandom?: THasDefault;
-  }): ColumnFactory<string, "uuid", TNotNull extends true ? true : false, THasDefault extends true ? true : boolean extends THasDefault ? false : false>;
-  /**
-   * Variable-length string column. `length` is required and must be a
-   * positive integer up to Postgres' actual `varchar` ceiling
-   * (1073741823 — i.e. ~1GB / 4 bytes per char). For unbounded text use
-   * `column.text()` instead — it stores the same way and skips the
-   * length check at write time.
-   *
-   * Conventional sizes for reference:
-   * - 50–100: short identifiers, slugs, status codes
-   * - 255: legacy "common max length" — fits a tweet, an email, etc.
-   * - 1024: file paths, URLs
-   * - 10000+: prefer `text` instead, varchar with very large lengths
-   *   buys you nothing
-   */
-  varchar<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts: {
+    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?: THasDefault extends true ? string : string | undefined;
-  }): ColumnFactory<string, "varchar", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * Unbounded text column.
-   */
-  text<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    default: string;
+    pgName?: string;
+  }): ColumnFactory<string, 'varchar', TNotNull extends true ? true : false, true>;
+  varchar<TNotNull extends boolean = false>(opts: {
+    length: number;
     notNull?: TNotNull;
-    default?: THasDefault extends true ? string : string | undefined;
-  }): ColumnFactory<string, "text", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * 32-bit integer column.
-   */
-  integer<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    pgName?: string;
+  }): ColumnFactory<string, 'varchar', TNotNull extends true ? true : false, false>;
+  text<TNotNull extends boolean = false>(opts: {
     notNull?: TNotNull;
-    default?: THasDefault extends true ? number : number | undefined;
-  }): ColumnFactory<number, "integer", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * 64-bit integer column. `mode: 'number'` returns a JS number (safe for
-   * values up to 2^53), `mode: 'bigint'` returns a JS BigInt.
-   */
-  bigint<TMode extends "number" | "bigint" = "number", TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    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?: THasDefault extends true ? (TMode extends "bigint" ? bigint : number) : (TMode extends "bigint" ? bigint : number) | undefined;
-  }): ColumnFactory<TMode extends "bigint" ? bigint : number, "bigint", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * Double-precision floating-point column.
-   */
-  double<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    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;
-    default?: THasDefault extends true ? number : number | undefined;
-  }): ColumnFactory<number, "double", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * Boolean column. Defaults to `false` if no explicit default is supplied
-   * AND `notNull` is true — matches the entity package convention.
-   */
-  boolean<TNotNull extends boolean = false, THasDefault extends boolean = false>(opts?: {
+    pgName?: string;
+  }): ColumnFactory<TMode extends 'bigint' ? bigint : number, 'bigint', TNotNull extends true ? true : false, false>;
+  double<TNotNull extends boolean = false>(opts: {
     notNull?: TNotNull;
-    default?: THasDefault extends true ? boolean : boolean | undefined;
-  }): ColumnFactory<boolean, "boolean", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * Timestamp column. `withTimezone: true` is strongly recommended for all
-   * timestamps in this codebase — entity audit fields use it consistently.
-   */
+    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; /** Server-side `NOW()` default. Counts as a default for type inference. */
+    notNull?: TNotNull;
     defaultNow?: THasDefault;
     withTimezone?: boolean;
-  }): ColumnFactory<Date, "timestamp", TNotNull extends true ? true : false, THasDefault extends true ? true : false>;
-  /**
-   * JSONB column. The phantom type parameter `T` propagates to row reads
-   * and where-clause shorthand for the whole-column case. For dotted-path
-   * access via the where-builder, the value type at the path is `unknown`
-   * (TypeScript can't follow runtime path navigation).
-   */
+    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;
-  }): ColumnFactory<T, "jsonb", TNotNull extends true ? true : false, false>;
-  /**
-   * UUID array column (`uuid[]`).
-   */
+    pgName?: string;
+  }): ColumnFactory<T, 'jsonb', TNotNull extends true ? true : false, false>;
   uuidArray<TNotNull extends boolean = false>(opts?: {
     notNull?: TNotNull;
-  }): ColumnFactory<string[], "uuidArray", TNotNull extends true ? true : false, false>;
-};
+    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
 /**
@@ -487,6 +484,50 @@ interface FindManyOptions<TCols extends Record<string, ColumnFactory>> {
   limit?: number;
   offset?: number;
 }
+/**
+ * Options for the `claim()` atomic locking operation.
+ *
+ * @see {@link TableClient.claim}
+ */
+interface ClaimOptions<TCols extends Record<string, ColumnFactory>, TTable extends PgTable = PgTable> {
+  /** Filter for rows eligible to be claimed. Must be non-empty. */
+  where: WhereClause<TCols>;
+  /** Literal values to SET on claimed rows. */
+  set?: Partial<InferInsertModel<TTable>>;
+  /** 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.
@@ -496,11 +537,17 @@ interface FindManyOptions<TCols extends Record<string, ColumnFactory>> {
  * (using the transactional `tx` handle), so user code is identical
  * regardless of transactional context.
  *
- * @template TCols The columns record passed to `defineTable`.
+ * @template TCols The columns record passed to `defineTable`. Drives the
+ *   where-builder DSL and the `Row<TCols>` / `InsertRow<TCols>` shapes.
+ * @template TTable The underlying Drizzle pgTable type, inferred from the
+ *   table value passed to `new TableClient(...)`. Carrying this through
+ *   lets `.insert().values(...)`, `.update().set(...)`, and `.returning()`
+ *   use Drizzle's own `InferInsertModel` / `InferSelectModel` instead of
+ *   falling back to `as never` casts.
  */
-declare class TableClient<TCols extends Record<string, ColumnFactory>> {
+declare class TableClient<TCols extends Record<string, ColumnFactory>, TTable extends PgTable = PgTable> {
   /** The Drizzle table object. Exposed via `defineTable().table` for typed JOINs. */
-  readonly table: PgTable;
+  readonly table: TTable;
   /** Per-column kind metadata. Used by the where-builder for jsonb path validation. */
   private readonly columnKinds;
   /**
@@ -509,12 +556,14 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * 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. */
+  table: TTable, /** Per-column kind metadata. Used by the where-builder for jsonb path validation. */
 
   columnKinds: Readonly<Record<string, ColumnKind>>,
   /**
@@ -523,7 +572,23 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * distinguish.
    */
 
-  db: PostgresJsDatabase);
+  db: PostgresJsDatabase, /** Primary key column names. Required by `claim()`. Empty for tables without a declared PK. */
+
+  primaryKeyColumns?: readonly string[]);
+  /**
+   * The table typed as the non-generic `PgTable` base.
+   *
+   * Drizzle's `.from()` (select) uses a conditional type
+   * `TableLikeHasEmptySelection<TTable>` that TypeScript cannot evaluate
+   * against a bounded generic `TTable extends PgTable` — it can only
+   * resolve when the argument is the concrete base `PgTable`. `.insert()`,
+   * `.update()`, and `.delete()` have simpler signatures (`<T extends
+   * PgTable>(t: T)`) that DO accept the generic directly, so those call
+   * sites keep `this.table` and still get `InferInsertModel<TTable>` /
+   * `InferSelectModel<TTable>` inference for `.values()`, `.set()`, and
+   * `.returning()`.
+   */
+  private get _selectTable();
   /**
    * Find a single row matching the given where clause, or `null` if no row
    * matches. Throws if the where is empty.
@@ -565,11 +630,36 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * 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>>;
+  insert(values: InferInsertModel<TTable>): Promise<Row<TCols>>;
   /**
    * Upsert: insert a row, or update an existing row if a unique constraint
    * conflict occurs.
@@ -577,9 +667,13 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * `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"). The PR 1 version does not support `setWhere`
-   * (conditional updates on conflict); see PR 3 for the atomic-locking
-   * pattern that uses it.
+   * 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
@@ -589,23 +683,24 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * )
    * ```
    *
-   * @example Counter increment
+   * @example Conditional update — only bump if newer
    * ```ts
-   * await counters.client.upsert(
-   *   { key: 'page_views', value: 1 },
-   *   { target: 'key', set: { value: sql`${counters.table.value} + 1` } as never },
+   * await state.client.upsert(
+   *   { key: 'sync', version: 5, data: '...' },
+   *   { target: 'key', setWhere: { version: { lt: 5 } } },
    * )
    * ```
    */
-  upsert(values: InsertRow<TCols>, opts: {
+  upsert(values: InferInsertModel<TTable>, opts: {
     target: (keyof TCols & string) | (keyof TCols & string)[];
-    set?: Partial<InsertRow<TCols>>;
+    set?: Partial<InferInsertModel<TTable>>; /** 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>[]>;
+  insertMany(values: InferInsertModel<TTable>[]): Promise<Row<TCols>[]>;
   /**
    * Update **at most one** row matching the where clause. Returns the
    * updated row, or `null` if no row matched.
@@ -627,12 +722,12 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * 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(where: WhereClause<TCols>, patch: Partial<InferInsertModel<TTable>>): 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>[]>;
+  updateMany(where: WhereClause<TCols>, patch: Partial<InferInsertModel<TTable>>): Promise<Row<TCols>[]>;
   /**
    * Delete **at most one** row matching the where clause. Returns the
    * deleted row, or `null` if no row matched.
@@ -670,7 +765,79 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
    * })
    * ```
    */
-  transaction<T>(fn: (tx: TableClient<TCols>) => Promise<T>): Promise<T>;
+  transaction<T>(fn: (tx: TableClient<TCols, TTable>) => 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, TTable>): 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;
 }
@@ -680,14 +847,19 @@ declare class TableClient<TCols extends Record<string, ColumnFactory>> {
  * The result of `defineTable()`.
  *
  * @template TCols The columns record passed to `defineTable`.
+ * @template TTable The concrete Drizzle `pgTable` type produced by the
+ *   definition. Defaulted to the non-generic `PgTable` for callers that
+ *   pass `DefinedTable` around without propagating inference — inside
+ *   `defineTable` itself, the actual `typeof table` is captured so
+ *   `makeClient` returns a fully-typed `TableClient<TCols, typeof table>`.
  */
-interface DefinedTable<TCols extends Record<string, ColumnFactory>> {
+interface DefinedTable<TCols extends Record<string, ColumnFactory>, TTable extends PgTable = PgTableWithColumns<TableConfig>> {
   /**
    * The underlying Drizzle `pgTable`. Exposed so callers can use it in
    * typed JOINs (the one sanctioned escape valve), and so it can be
-   * referenced from `drizzle.config.ts` for migration generation.
+   * included in `Plugin.tables` for migration discovery by `lumi migrate`.
    */
-  table: PgTable;
+  table: TTable;
   /**
    * The original schema metadata. Useful for introspection / tooling
    * that needs to know about indexes, unique constraints, etc.
@@ -698,6 +870,12 @@ interface DefinedTable<TCols extends Record<string, ColumnFactory>> {
    * 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.
    *
@@ -705,7 +883,7 @@ interface DefinedTable<TCols extends Record<string, ColumnFactory>> {
    * cache it. The client is stateless aside from the db handle, so it
    * is safe to share.
    */
-  makeClient(db: PostgresJsDatabase): TableClient<TCols>;
+  makeClient(db: PostgresJsDatabase): TableClient<TCols, TTable>;
 }
 /**
  * Define a typed table.
@@ -718,7 +896,59 @@ interface DefinedTable<TCols extends Record<string, ColumnFactory>> {
  * @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>;
+declare function defineTable<const TCols extends Record<string, ColumnFactory>>(def: TableDefinition<TCols>): {
+  table: PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: _$drizzle_orm_pg_core0.PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: _$drizzle_orm0.ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>;
+  schema: TableDefinition<TCols>;
+  columnKinds: Readonly<Record<string, ColumnKind>>;
+  primaryKeyColumns: readonly string[];
+  makeClient: (db: PostgresJsDatabase) => TableClient<TCols, PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: _$drizzle_orm_pg_core0.PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: _$drizzle_orm0.ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>>;
+};
 //#endregion
 //#region src/table/registry.d.ts
 declare class TableRegistryImpl {
@@ -740,8 +970,8 @@ declare class TableRegistryImpl {
   /**
    * Return every registered table as a `{ [name]: PgTable }` map.
    *
-   * Useful for `createTestDb().push(tableRegistry.allTables())` and for
-   * exposing a single import target to `drizzle.config.ts`.
+   * Useful for `createTestDb().push(tableRegistry.allTables())` and
+   * runtime introspection.
    */
   allTables(): Record<string, PgTable>;
   /**
@@ -792,5 +1022,5 @@ declare class WhereBuilderError extends Error {
  */
 declare function isNonEmptyWhere(clause: unknown): boolean;
 //#endregion
-export { type AnyPgColumn, 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 };
+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