palgres 0.0.0-stage → 0.2.0

package/types/palgres/src/query/typed.d.ts

@@ -0,0 +1,537 @@
+import type { ColIsOptionalOnInsert, ColumnBuilder, ColumnType, ColValue } from '../dsl/columns.js';
+import { type SchemaDef, type TableDef } from '../dsl/schema.js';
+import type { AtomicClient, DBClient, DBOps, RowLock, SearchOptions } from './client.js';
+import type { Search } from '../model.js';
+import { isColRef } from './guards.js';
+import { type AtomicOptions, type InsertManyOptions, type Page, type PageNavigation } from './options.js';
+import { type Materialized, type TxColumnExpr, type TxNow, type TxPlanHandle, type TxTable } from './tx-plan.js';
+import type { UniqueWhere } from './unique.js';
+/**
+ * One table's shapes: the full row, the insert payload, its unique keys and
+ * its relations — every foreign key it takes part in, both directions:
+ * `{ list: { to: "lists", kind: "one", via: "list_id" } }` on the child,
+ * `{ todos: { to: "todos", kind: "many", via: "list_id" } }` on the parent;
+ * `to` is the target's key, bare in public and "schema.table" otherwise.
+ */
+export interface TableTypes {
+    row: Record<string, unknown>;
+    insert: Record<string, unknown>;
+    uniqueKeys?: readonly (readonly string[])[];
+    relations: Record<string, {
+        to: string;
+        kind: 'one' | 'many';
+        via: string;
+    }>;
+    /** The table declares search: its entry has `search()`, and no other's does. */
+    searchable?: true;
+}
+/**
+ * The project's tables: `tables` by name (the framework's `Tables`), and
+ * `schemas` by schema then table (its `Schemas`). Unconstrained on purpose —
+ * an interface has no index signature, so it would not meet one.
+ */
+export interface Env<T = unknown, S = unknown> {
+    tables: T;
+    schemas: S;
+}
+/**
+ * A schema's tables as its own file types them — what palbase-env.d.ts says,
+ * read from the schema's type with nothing generated, so an app types
+ * `Database.public.<table>` from db/public.ts alone:
+ *
+ *   declare module "palbase/backend/env" { interface Tables extends TablesOf<typeof schema> {} }
+ *
+ * Relations cross files (a foreign key names another schema's table), so they
+ * are not read this way: `with` and `has` take none.
+ */
+export type TablesOf<S extends SchemaDef> = {
+    [K in keyof S['tables']]: {
+        row: RowShape<S['tables'][K]>;
+        insert: InsertShape<S['tables'][K]>;
+        relations: Record<never, never>;
+    } & (S['tables'][K] extends {
+        search: Search;
+    } ? {
+        searchable: true;
+    } : unknown);
+};
+/** No project tables: for a surface that names none (makeTypedDB's, a raw client's). */
+export type NoEnv = Env<Record<never, never>, Record<never, never>>;
+/** Columns only the database writes (an ALWAYS identity): on the row, on no insert or update shape. */
+type DatabaseOnlyKeys<C> = {
+    [K in keyof C]: C[K] extends ColumnBuilder<ColumnType, boolean, boolean, unknown, unknown, unknown, 'readonly'> ? K : never;
+}[keyof C];
+type RequiredKeys<C> = Exclude<{
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;
+}[keyof C], DatabaseOnlyKeys<C>>;
+type OptionalKeys<C> = Exclude<{
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;
+}[keyof C], DatabaseOnlyKeys<C>>;
+/** An INSERT payload: NOT NULL columns without a default required, the rest optional. */
+export type InsertShape<T extends TableDef> = {
+    [K in RequiredKeys<T['columns']>]: ColValue<T['columns'][K]>;
+} & {
+    [K in OptionalKeys<T['columns']>]?: ColValue<T['columns'][K]>;
+};
+/** A full row; a nullable column is `T | null`. */
+export type RowShape<T extends TableDef> = {
+    [K in keyof T['columns']]: ColValue<T['columns'][K]>;
+};
+/**
+ * A reference to a column — the one thing that may stand where a value goes
+ * in a comparison. Known by its brand, not its shape (guards.ts): a request
+ * body's `{"$col":"tenant_id"}` is not one.
+ */
+export type ColRef<N extends string = string> = {
+    readonly $col: N;
+};
+export { isColRef };
+/** `total > amount_paid`: the right side is a column, not a value. A wrong name is a compile error where the filter uses it. */
+export declare function col<const N extends string>(name: N): ColRef<N>;
+type PgFamily<V> = [NonNullable<V>] extends [boolean] ? 'bool' : [NonNullable<V>] extends [readonly (number | string)[]] ? 'array' : [NonNullable<V>] extends [Date] ? 'date' : [NonNullable<V>] extends [string | number] ? 'scalar' : 'opaque';
+type PgTag<V> = [NonNullable<V>] extends [{
+    readonly __pg?: infer N;
+}] ? ([N] extends [string] ? N : '?') : '?';
+/** integer, bigint and numeric compare with each other; every other type only with itself. */
+type PgKind<P> = P extends 'integer' | 'bigint' | 'numeric' ? 'num' : P;
+type BothBranded<A, B> = '?' extends PgTag<A> ? false : '?' extends PgTag<B> ? false : true;
+type PgSameKind<A, B> = [PgKind<PgTag<A>>] extends [PgKind<PgTag<B>>] ? ([PgKind<PgTag<B>>] extends [PgKind<PgTag<A>>] ? true : false) : false;
+type ColComparable<A, B> = BothBranded<A, B> extends true ? PgSameKind<A, B> : [PgFamily<A>] extends [PgFamily<B>] ? true : false;
+type ColumnsComparableTo<Row, V> = {
+    [K in keyof Row]-?: ColComparable<Row[K], V> extends true ? K : never;
+}[keyof Row];
+declare const NO_CONSTRAINT: unique symbol;
+export type NoColConstraint = {
+    readonly [NO_CONSTRAINT]: true;
+};
+/** A reference to one of Row's columns — those comparable with V, when V is given. */
+export type ColRefOf<Row, V = NoColConstraint> = [keyof Row] extends [never] ? never : [V] extends [NoColConstraint] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
+/** SQL that goes INTO the query: text in parts, values between them, never joined into one string. */
+export type SqlFragment = {
+    readonly $sql: {
+        readonly text: readonly string[];
+        readonly values: readonly unknown[];
+    };
+};
+/**
+ * The way into a query rather than out of it:
+ * `where: sqlFragment\`similarity(title, ${q}) > 0.3\`` keeps select, orderBy,
+ * limit and RLS. There is no identifier-embedding surface (no .raw): that is
+ * where Drizzle's CVE-2026-39356 and Knex's CVE-2019-10757 were born. Branded,
+ * so a fragment cannot be made from JSON.
+ */
+export declare function sqlFragment(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
+/** Retries `fn` on a retryable failure (40001, 40P01). Zero unless asked: a silent retry would run a transfer twice. `fn` must open a NEW transaction each time — $atomic does. */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: {
+    retry?: number;
+}): Promise<T>;
+/** Text operators only on text columns. */
+export type TextOps<V> = V extends string ? {
+    contains?: string;
+    icontains?: string;
+    startsWith?: string;
+    endsWith?: string;
+} : {
+    contains?: never;
+    icontains?: never;
+    startsWith?: never;
+    endsWith?: never;
+};
+/** An array column's filters: `contains` holds every given element (@>), `overlaps` any (&&). */
+export type ArrayOps<V> = PgTag<V> extends `${string}[]` ? [NonNullable<V>] extends [readonly (infer El)[]] ? {
+    contains?: El[];
+    overlaps?: El[];
+    icontains?: never;
+    startsWith?: never;
+    endsWith?: never;
+} : never : PgTag<V> extends '?' ? [NonNullable<V>] extends [readonly (infer El)[]] ? {
+    contains?: El[];
+    overlaps?: El[];
+    icontains?: never;
+    startsWith?: never;
+    endsWith?: never;
+} : never : never;
+type ListOrTextOps<V> = [ArrayOps<V>] extends [never] ? TextOps<V> & {
+    overlaps?: never;
+} : ArrayOps<V>;
+/** Where now() may be a comparison value: a timestamp column (or, unbranded, a string/Date one). */
+type NowComparable<V> = '?' extends PgTag<V> ? ([NonNullable<V>] extends [string | Date] ? TxNow : never) : PgTag<V> extends 'timestamp' ? TxNow : never;
+type WhereOpBody<V, C> = {
+    gt?: V | C | NowComparable<V>;
+    gte?: V | C | NowComparable<V>;
+    lt?: V | C | NowComparable<V>;
+    lte?: V | C | NowComparable<V>;
+    neq?: V | C | NowComparable<V>;
+    in?: V[];
+    /** IS NULL / IS NOT NULL — `= NULL` is never true. */
+    isNull?: boolean;
+} & ListOrTextOps<V>;
+export type WhereOp<V, Row = unknown> = WhereOpWith<V, ColRefOf<Row, V>>;
+/** The operator vocabulary with the column-reference position given from outside — the plan adds `Ref` there. */
+export type WhereOpWith<V, C> = V | C | NowComparable<V> | WhereOpBody<V, C>;
+/** THE filter: findMany, updateMany, deleteMany, count and the plans take this one. */
+export type WhereFilter<Row> = {
+    [K in keyof Row]?: WhereOp<Row[K], Row>;
+} & {
+    OR?: (WhereFilter<Row> | SqlFragment)[];
+    AND?: (WhereFilter<Row> | SqlFragment)[];
+    NOT?: WhereFilter<Row> | SqlFragment;
+};
+export type OrderBySpec<Row> = {
+    column: Extract<keyof Row, string>;
+    direction?: 'asc' | 'desc';
+    /** Where NULLs go; Postgres' default changes with the direction. */
+    nulls?: 'first' | 'last';
+};
+export type FindManyOpts<Row> = {
+    orderBy?: OrderBySpec<Row> | OrderBySpec<Row>[];
+    limit?: number;
+    offset?: number;
+};
+type RelatedTable<To, E extends Env> = To extends `${infer S}.${infer T}` ? S extends keyof E['schemas'] ? T extends keyof E['schemas'][S] ? E['schemas'][S][T] : never : never : To extends keyof E['tables'] ? E['tables'][To] : never;
+type RelatedRow<To, E extends Env> = RelatedTable<To, E> extends {
+    row: infer R;
+} ? R : Record<string, unknown>;
+type RelatedRels<To, E extends Env> = RelatedTable<To, E> extends {
+    relations: infer R;
+} ? R : unknown;
+type HasDepth = 0 | 1 | 2 | 3;
+type HasDec = [0, 0, 1, 2];
+type HasNest<Rels, D extends HasDepth, E extends Env> = [keyof Rels] extends [never] ? unknown : D extends 0 ? unknown : {
+    has?: HasFilter<Rels, E, HasDec[D]>;
+};
+type HasFilter<Rels, E extends Env, D extends HasDepth = 3> = {
+    [R in keyof Rels]?: Rels[R] extends {
+        to: infer To;
+    } ? WhereFilter<RelatedRow<To, E>> & HasNest<RelatedRels<To, E>, D, E> : never;
+};
+/** A filter through a relation — `{ has: { user_interests: { user_id } } }` is `id IN (SELECT …)`. */
+export type WhereWithRelations<Row, Rels, E extends Env = NoEnv> = WhereFilter<Row> & {
+    has?: HasFilter<Rels, E>;
+};
+/** The `has` branch alone, for the plan's filter; nothing for a table without relations. */
+export type HasOnly<Rels, E extends Env = NoEnv> = [unknown] extends [Rels] ? unknown : [keyof Rels] extends [never] ? unknown : {
+    has?: HasFilter<Rels, E>;
+};
+type HasBranch<Row, Rels, E extends Env> = [unknown] extends [Rels] ? never : [keyof Rels] extends [never] ? never : WhereWithRelations<Row, Rels, E>;
+type WithOpts<To, D extends HasDepth, E extends Env> = {
+    select?: readonly Extract<keyof RelatedRow<To, E>, string>[];
+    where?: WhereFilter<RelatedRow<To, E>>;
+    orderBy?: OrderBySpec<RelatedRow<To, E>> | readonly OrderBySpec<RelatedRow<To, E>>[];
+    limit?: number;
+    with?: D extends 1 ? never : [keyof RelatedRels<To, E>] extends [never] ? never : WithInput<RelatedRels<To, E>, HasDec[D], E>;
+};
+/** `with`: related rows fetched — `true` all columns, or narrowed. */
+export type WithInput<Rels, D extends HasDepth = 3, E extends Env = NoEnv> = {
+    [R in keyof Rels]?: Rels[R] extends {
+        to: infer To;
+    } ? true | WithOpts<To, D, E> : never;
+};
+type WithRowOf<Rels, R extends keyof Rels, Q, E extends Env> = Rels[R] extends {
+    to: infer To;
+    kind: infer K;
+} ? (Q extends {
+    select: readonly (infer C extends keyof RelatedRow<To, E>)[];
+} ? Pick<RelatedRow<To, E>, C> : RelatedRow<To, E>) & (Q extends {
+    with: infer W;
+} ? WithResult<RelatedRels<To, E>, W, E> : unknown) extends infer Row ? [K] extends ['many'] ? Row[] : Row | null : never : never;
+type RequestedWith<W> = {
+    [R in keyof W]-?: undefined extends W[R] ? never : R;
+}[keyof W];
+export type WithResult<Rels, W, E extends Env = NoEnv> = [RequestedWith<W>] extends [never] ? unknown : {
+    [R in RequestedWith<W> & keyof Rels]: WithRowOf<Rels, R, W[R], E>;
+};
+/** A read's one parameter: where, with, select (which narrows the row type), orderBy, limit, offset. */
+export type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown, E extends Env = NoEnv> = {
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels, E>;
+    /** Related rows in the same query; `many` is an array ([] when none), `one` a row or null. numeric and bigint stay exact. */
+    with?: [unknown] extends [Rels] ? never : [keyof Rels] extends [never] ? never : WithInput<Rels, 3, E>;
+    select?: readonly K[];
+} & FindManyOpts<Row>;
+export type PageInput<Row, K extends keyof Row = keyof Row, Rels = unknown, E extends Env = NoEnv> = Omit<QueryInput<Row, keyof Row, Rels, E>, 'limit' | 'offset' | 'select'> & {
+    select?: readonly K[];
+} & PageNavigation;
+/** A write's one parameter: which rows (`where`), what they become (`set`); `returning: false` for a count. */
+export type MutateInput<Row, Insert, Rels = unknown, E extends Env = NoEnv> = {
+    where: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels, E>;
+    set: SetShape<Insert>;
+    returning?: boolean;
+};
+type NumericCol<V> = '?' extends PgTag<V> ? (NonNullable<V> extends number | string ? TxColumnExpr : never) : PgKind<PgTag<V>> extends 'num' ? TxColumnExpr : never;
+/** An insert's value: the column's own, or — for a timestamp — the server's clock. */
+export type InsertValues<Insert> = {
+    [K in keyof Insert]: Insert[K] | NowComparable<Insert[K]>;
+};
+/** An update's value: the column's own, increment()/decrement() on a numeric column, now() on a timestamp. */
+export type SetValue<V> = V | NumericCol<V> | NowComparable<V>;
+export type SetShape<Insert> = {
+    [K in keyof Insert]?: SetValue<Insert[K]>;
+};
+type RelsOf<T> = T extends {
+    relations: infer R;
+} ? R : unknown;
+type SummableCols<Row> = {
+    [K in keyof Row]-?: '?' extends PgTag<Row[K]> ? (NonNullable<Row[K]> extends number | string ? K : never) : PgKind<PgTag<Row[K]>> extends 'num' ? K : never;
+}[keyof Row];
+type OrderableCols<Row> = {
+    [K in keyof Row]-?: '?' extends PgTag<Row[K]> ? (NonNullable<Row[K]> extends number | string | Date ? K : never) : PgTag<Row[K]> extends 'jsonb' ? never : K;
+}[keyof Row];
+type AggCols<Row> = Extract<SummableCols<Row>, string>;
+type AggOrderCols<Row> = Extract<OrderableCols<Row>, string>;
+export type AggregateInput<Row, Rels = unknown, E extends Env = NoEnv> = {
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels, E>;
+    sum?: readonly AggCols<Row>[];
+    avg?: readonly AggCols<Row>[];
+    min?: readonly AggOrderCols<Row>[];
+    max?: readonly AggOrderCols<Row>[];
+    /**
+     * `true`: how many rows. Named filters — `{ open: { done: false }, mine: { owner } }` —
+     * how many rows each matches, every one in the same statement (count(*)
+     * FILTER (WHERE …)), within `where` when it is given; `{}` is every row.
+     */
+    count?: boolean | {
+        readonly [name: string]: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels, E>;
+    };
+    /** Given: rows, each carrying its group's columns. */
+    groupBy?: readonly Extract<keyof Row, string>[];
+};
+type AggPart<Q, Row, F extends 'sum' | 'avg' | 'min' | 'max'> = Q extends {
+    [K in F]: readonly (infer C extends keyof Row)[];
+} ? {
+    [P in C]: F extends 'sum' | 'avg' ? string | null : Row[P] | null;
+} : never;
+type AggBody<Q, Row> = ([AggPart<Q, Row, 'sum'>] extends [never] ? unknown : {
+    sum: AggPart<Q, Row, 'sum'>;
+}) & ([AggPart<Q, Row, 'avg'>] extends [never] ? unknown : {
+    avg: AggPart<Q, Row, 'avg'>;
+}) & ([AggPart<Q, Row, 'min'>] extends [never] ? unknown : {
+    min: AggPart<Q, Row, 'min'>;
+}) & ([AggPart<Q, Row, 'max'>] extends [never] ? unknown : {
+    max: AggPart<Q, Row, 'max'>;
+}) & CountPart<Q>;
+type CountPart<Q> = Q extends {
+    count: true;
+} ? {
+    count: number;
+} : Q extends {
+    count: infer M extends {
+        readonly [name: string]: unknown;
+    };
+} ? {
+    count: {
+        [K in keyof M]: number;
+    };
+} : unknown;
+export type AggregateResult<Q, Row> = Q extends {
+    groupBy: readonly (infer G extends keyof Row)[];
+} ? ({
+    [P in G]: Row[P];
+} & AggBody<Q, Row>)[] : AggBody<Q, Row>;
+/** A search's options, its filter typed as findMany's. */
+export type SearchParams<Row, Rels = unknown, E extends Env = NoEnv> = Omit<SearchOptions, 'where'> & {
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels, E>;
+};
+/** What only a table that declares search has. */
+export interface Searchable<Row, Rels = unknown, E extends Env = NoEnv> {
+    /**
+     * The rows nearest to `query`, best first, each with its `_score`: by
+     * meaning and by word, fused ("hybrid"), under the caller's row-level
+     * security — a row they may not read is never found.
+     */
+    search(query: string, opts?: SearchParams<Row, Rels, E>): Promise<Array<Row & {
+        _score: number;
+    }>>;
+}
+/**
+ * One table of the project, typed by its palbase-env.d.ts entry; `E` resolves
+ * its relations' targets. `search()` is there for an entry that says
+ * `searchable: true` — a table that declares search — and for no other.
+ */
+export type EnvTypedTable<T extends TableTypes, E extends Env = NoEnv> = EnvTypedTableOps<T, E> & (T extends {
+    searchable: true;
+} ? Searchable<T['row'], RelsOf<T>, E> : unknown);
+/** What every table of the project has. */
+export interface EnvTypedTableOps<T extends TableTypes, E extends Env = NoEnv> {
+    /** The row with this unique key, or null; with `lock`, the row is locked in the same statement until the transaction ends. */
+    findUnique<K extends keyof T['row'] = keyof T['row'], W extends WithInput<RelsOf<T>, 3, E> = Record<never, never>>(q: {
+        where: UniqueWhere<T['row'], T['uniqueKeys']>;
+        select?: readonly K[];
+        with?: QueryInput<T['row'], keyof T['row'], RelsOf<T>, E>['with'] & W;
+        lock?: RowLock;
+    }): Promise<(Pick<T['row'], K> & WithResult<RelsOf<T>, W, E>) | null>;
+    /** Index-backed pages: the primary key is appended to orderBy, cursors are sealed to the query and the caller. */
+    page<K extends keyof T['row'] = keyof T['row'], W extends WithInput<RelsOf<T>, 3, E> = Record<never, never>>(q?: PageInput<T['row'], K, RelsOf<T>, E> & {
+        with?: W;
+    }): Promise<Page<Pick<T['row'], K> & WithResult<RelsOf<T>, W, E>>>;
+    insert(data: InsertValues<T['insert']>): Promise<T['row']>;
+    /** Many rows in one statement; every row the same keys (null for a missing value). An empty list is an empty result. */
+    insertMany(rows: readonly InsertValues<T['insert']>[], opts: InsertManyOptions<Extract<keyof T['row'], string>> & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(rows: readonly InsertValues<T['insert']>[], opts?: InsertManyOptions<Extract<keyof T['row'], string>> & {
+        returning?: true;
+    }): Promise<T['row'][]>;
+    insertMany(rows: readonly InsertValues<T['insert']>[], opts?: InsertManyOptions<Extract<keyof T['row'], string>>): Promise<T['row'][] | number>;
+    /** Claims an idempotency key; `inserted: false` is not an error — the row is the first call's. */
+    claim(unique: Partial<T['insert']>, extra?: Partial<InsertValues<T['insert']>>): Promise<{
+        inserted: boolean;
+        row: T['row'];
+    }>;
+    /** Insert, or overwrite on a collision of `onConflict` (columns a unique constraint or index covers). */
+    put(q: {
+        data: InsertValues<T['insert']>;
+        onConflict: readonly Extract<keyof T['row'], string>[];
+    }): Promise<T['row']>;
+    /** The row with this id updated, or null when none matched. */
+    update(q: {
+        where: {
+            id: string;
+        };
+        set: SetShape<T['insert']>;
+    }): Promise<T['row'] | null>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<T['row'] | null>;
+    findMany<K extends keyof T['row'] = keyof T['row'], W extends WithInput<RelsOf<T>, 3, E> = Record<never, never>>(q?: QueryInput<T['row'], K, RelsOf<T>, E> & {
+        with?: W;
+    }): Promise<Array<Pick<T['row'], K> & WithResult<RelsOf<T>, W, E>>>;
+    /** Every matching row updated in one statement; an empty filter is refused, zero rows is "the condition did not hold". */
+    updateMany<const Q extends MutateInput<T['row'], T['insert'], RelsOf<T>, E>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : T['row'][]>;
+    deleteMany(q: {
+        where: WhereFilter<T['row']> | SqlFragment | HasBranch<T['row'], RelsOf<T>, E>;
+    }): Promise<number>;
+    aggregate<const Q extends AggregateInput<T['row'], RelsOf<T>, E>>(q: Q): Promise<AggregateResult<Q, T['row']>>;
+    count(q?: {
+        where?: WhereFilter<T['row']> | SqlFragment | HasBranch<T['row'], RelsOf<T>, E>;
+    }): Promise<number>;
+}
+type Entry<X> = Extract<X, TableTypes>;
+/** Public's tables by name: `Database.public`. */
+export type EnvTables<T, S> = {
+    [K in keyof T]: EnvTypedTable<Entry<T[K]>, Env<T, S>>;
+};
+/** Every schema's tables: `Database.public.<table>` and `Database.<schema>.<table>`. */
+export type EnvSchemaSurface<T, S> = {
+    public: EnvTables<T, S>;
+} & {
+    [N in keyof S]: {
+        [K in keyof S[N]]: EnvTypedTable<Entry<S[N][K]>, Env<T, S>>;
+    };
+};
+type TxTablesOf<X, E extends Env> = {
+    [K in keyof X]: TxTable<Entry<X[K]>['row'], Entry<X[K]>['insert'], RelsOf<Entry<X[K]>>, E>;
+};
+/** Public's tables as PLAN operations. */
+export type TxTables<T, S> = TxTablesOf<T, Env<T, S>>;
+/** The plan handle's schemas — the same shape as Database's: `tx.public.x`, `tx.<schema>.x`. */
+export type TxSchemaSurface<T, S> = {
+    public: TxTables<T, S>;
+} & {
+    [N in keyof S]: TxTablesOf<S[N], Env<T, S>>;
+};
+/** What a `$transaction` callback gets: tables only. */
+export type TxPlan<T, S> = TxPlanHandle<TxTables<T, S>> & TxSchemaSurface<T, S>;
+/** `$` keeps the system's members apart from table and schema names: no schema name may start with it. */
+export type DollarOps<T> = {
+    [K in keyof T as `$${string & K}`]: T[K];
+};
+/** The service_role sibling, and an $atomic scope's handle: the same surface, without $asService. */
+export type EnvServiceDatabase<T, S> = EnvSchemaSurface<T, S> & {
+    /** Commits independently of the request; every retry is a new BEGIN … COMMIT. */
+    $atomic<R>(fn: (tx: AtomicDatabase<T, S>) => Promise<R>, options?: AtomicOptions): Promise<R>;
+    $query: DBClient['query'];
+    $insert: DBClient['insert'];
+    $insertMany: DBClient['insertMany'];
+    $update: DBClient['update'];
+    $delete: DBClient['delete'];
+    $findById: DBClient['findById'];
+    $findUnique: DBClient['findUnique'];
+    $diagnostics: DBClient['diagnostics'];
+    $findMany: DBClient['findMany'];
+    $page: DBClient['page'];
+    $put: DBClient['put'];
+    $updateMany: DBClient['updateMany'];
+    $deleteMany: DBClient['deleteMany'];
+    $count: DBClient['count'];
+    $search: DBClient['search'];
+    $aggregate: DBClient['aggregate'];
+    $claim: DBClient['claim'];
+    $lockRows: DBClient['lockRows'];
+    $lockRowsWhere: DBClient['lockRowsWhere'];
+    $advisoryXactLock: DBClient['advisoryXactLock'];
+    $attempt: DBClient['attempt'];
+    /** A plan: a savepoint in the current transaction. A nonzero `retry` is refused — use $atomic for whole-transaction retry. */
+    $transaction<R>(fn: (tx: TxPlan<T, S>) => R extends Promise<unknown> ? never : R, opts?: {
+        retry?: number;
+    }): Promise<Materialized<R>>;
+};
+/**
+ * The project's data: `Database.<schema>.<table>` plus the `$` members, for
+ * `T` the public tables (the framework's `Tables`) and `S` the other schemas'
+ * (`Schemas`). RLS holds by default — a signed-in caller is `authenticated`
+ * with their claims, anyone else `anon`; `$asService()` is the explicit,
+ * greppable way past it (service_role).
+ */
+export type EnvTypedDatabase<T, S> = EnvServiceDatabase<T, S> & {
+    /** The RLS-bypassing sibling; it has no $asService of its own. */
+    $asService(): EnvServiceDatabase<T, S>;
+};
+/** One root transaction's handle. */
+export type AtomicDatabase<T, S> = Omit<EnvServiceDatabase<T, S>, '$atomic'>;
+/** A table of a SchemaDef: `search()` where its declaration has one. */
+export type TypedTable<T extends TableDef> = TypedTableOps<T> & (T extends {
+    search: Search;
+} ? Searchable<RowShape<T>> : unknown);
+export interface TypedTableOps<T extends TableDef> {
+    findUnique<K extends keyof RowShape<T> = keyof RowShape<T>>(q: {
+        where: Partial<RowShape<T>>;
+        select?: readonly K[];
+        lock?: RowLock;
+    }): Promise<Pick<RowShape<T>, K> | null>;
+    page<K extends keyof RowShape<T> = keyof RowShape<T>>(q?: PageInput<RowShape<T>, K>): Promise<Page<Pick<RowShape<T>, K>>>;
+    insert(data: InsertValues<InsertShape<T>>): Promise<RowShape<T>>;
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts: InsertManyOptions & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts?: InsertManyOptions & {
+        returning?: true;
+    }): Promise<RowShape<T>[]>;
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts?: InsertManyOptions): Promise<RowShape<T>[] | number>;
+    put(q: {
+        data: InsertShape<T>;
+        onConflict: readonly string[];
+    }): Promise<RowShape<T>>;
+    update(q: {
+        where: {
+            id: string;
+        };
+        set: SetShape<InsertShape<T>>;
+    }): Promise<RowShape<T> | null>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<RowShape<T> | null>;
+    findMany<K extends keyof RowShape<T> = keyof RowShape<T>>(q?: QueryInput<RowShape<T>, K>): Promise<Pick<RowShape<T>, K>[]>;
+    updateMany<const Q extends MutateInput<RowShape<T>, InsertShape<T>>>(q: Q): Promise<Q extends {
+        returning: false;
+    } ? number : RowShape<T>[]>;
+    deleteMany(q: {
+        where: WhereFilter<RowShape<T>> | SqlFragment;
+    }): Promise<number>;
+    aggregate<const Q extends AggregateInput<RowShape<T>>>(q: Q): Promise<AggregateResult<Q, RowShape<T>>>;
+    count(q?: {
+        where?: WhereFilter<RowShape<T>> | SqlFragment;
+    }): Promise<number>;
+}
+/** A plan callback's handle over one schema's tables. */
+export type TypedTx<S extends SchemaDef> = TxPlanHandle<{
+    [K in keyof S['tables']]: TxTable<RowShape<S['tables'][K]>, InsertShape<S['tables'][K]>>;
+}>;
+export interface TypedDB<S extends SchemaDef> {
+    diagnostics: DBOps['diagnostics'];
+    tables: {
+        [K in keyof S['tables']]: TypedTable<S['tables'][K]>;
+    };
+    transaction<T>(fn: (tx: TypedTx<S>) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
+}
+/** A raw client typed by one SchemaDef: its tables by name, and a plan over them. */
+export declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: AtomicClient): TypedDB<S>;

package/types/palgres/src/query/unique.d.ts

@@ -0,0 +1,16 @@
+/** Every declared unique key, primary first, each once. */
+export declare function uniqueKeysOf(table: {
+    columns?: Record<string, unknown>;
+    primaryKey?: readonly string[];
+    unique?: readonly {
+        columns: readonly string[];
+    }[];
+}): string[][];
+/** Exactly one declared key, every column of it equal to a non-null scalar: NULLs in a UNIQUE constraint are not unique. */
+export declare function assertUniqueLookup(table: string, keys: readonly (readonly string[])[], where: Record<string, unknown>): void;
+/** A union of exact keys, not a partial row that could match many. */
+export type UniqueWhere<Row, Keys> = Keys extends readonly (infer Key extends readonly string[])[] ? Key extends unknown ? {
+    [K in Extract<Key[number], keyof Row>]-?: NonNullable<Row[K]>;
+} & {
+    [K in Exclude<keyof Row, Key[number]>]?: never;
+} : never : never;

package/types/palgres/src/search-worker.d.ts

@@ -0,0 +1,36 @@
+import type { Roles } from './plan.js';
+import { type SqlDriver } from './query/driver.js';
+import { type Embed } from './query/search.js';
+export interface SearchWorkerOptions {
+    /** The app's pool, as createDatabase takes it; the worker's transactions are the service role's. */
+    sql: SqlDriver;
+    /** What embeds: the same the app's createDatabase was given. */
+    embed: Embed;
+    /** The database's roles, when they are not anon, authenticated and service_role. */
+    roles?: Partial<Roles>;
+    log?: (line: string) => void;
+}
+export interface SearchWorker {
+    /**
+     * Embeds every row that is due, once, and promotes each generation that is
+     * full: how many vectors it wrote, and the tables ("schema.table") whose
+     * new generation took over. A row whose call fails is left for its next
+     * attempt, and nothing more is claimed after a batch in which every call
+     * failed. `max`: stop once that many are written; `timeoutMs`: claim
+     * nothing more after it.
+     */
+    drain(options?: {
+        max?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        embedded: number;
+        promoted: string[];
+    }>;
+    /** Drains from now on: at once when a write to a table with search commits in this process, and by itself — a second after it found work, up to fifteen when it finds none. */
+    start(): void;
+    /** Stops: nothing more is claimed, and what is being embedded is given a few seconds to end. */
+    stop(): Promise<void>;
+    /** Drain now, not at the next look. */
+    kick(): void;
+}
+export declare function createSearchWorker(options: SearchWorkerOptions): SearchWorker;