okmodel 0.5.1 → 0.7.0

package/dist/runtime/types.d.ts

@@ -7,8 +7,10 @@
 import type { DriverTimeouts, Notice } from "../contracts/driver.js";
 import type { SafeResult } from "../contracts/error.js";
 import type { QuerySchema } from "../dialects/pg/model.js";
+import type { Bucket } from "../dialects/pg/ops/bucket.js";
+import type { Window } from "../dialects/pg/ops/window.js";
 import type { Inc } from "../dialects/pg/ops/inc.js";
-import type { ArrAppend, ArrRemove, JsonSet, Or, RelationFilter } from "../dialects/pg/operators.js";
+import type { ArrAppend, ArrRemove, JsonSet, Or, RelationFilter, Relevance, SearchMatch } from "../dialects/pg/operators.js";
 import type { FieldWhere, IsJsonObject } from "../dialects/pg/where.js";
 import type { AppliedRule, ReadOp } from "./plan.js";
 export type { FieldWhere, WhereValue } from "../dialects/pg/where.js";
@@ -22,8 +24,20 @@ export type RelationsOf<S extends QuerySchema, K extends keyof S["~byName"]> = S
 } ? R : Record<string, never>;
 /** Array and JSON writes the column value type can accept. */
 type WriteOp<V> = [unknown] extends [V] ? JsonSet<unknown> | ArrAppend<unknown> | ArrRemove<unknown> : (V extends readonly (infer E)[] ? ArrAppend<E> | ArrRemove<E> : never) | (IsJsonObject<V> extends true ? JsonSet<unknown> : never);
-/** `has`, `none`, and `every` against the related row. */
+/**
+ * `inc` on a number or bigint column.
+ *
+ * A `string` column is not included. `text` is a string, and so is `numeric`
+ * or `bigint` when the codec keeps the decimal text. The statement still
+ * accepts `inc` on a numeric database type.
+ */
+type IncOf<V> = [unknown] extends [V] ? Inc<number> | Inc<bigint> : [NonNullable<V>] extends [number] ? Inc<number> : [NonNullable<V>] extends [bigint] ? Inc<bigint> : never;
+/** `has`, `none`, and `every` against the related row. A morph include is not a filter. */
 export type RelFilter<S extends QuerySchema, Rel> = Rel extends {
+    readonly morph: {
+        readonly targets: readonly string[];
+    };
+} ? never : Rel extends {
     readonly table: infer T extends string;
 } ? T extends keyof S["~byName"] ? RelationFilter<"has" | "none" | "every", FieldWhere<RowOf<S, T>>> : never : never;
 /** Known relation names. A string index (no declared relations) adds none. */
@@ -39,14 +53,34 @@ export type OrderBy<Row> = {
     readonly [K in keyof Row]?: "asc" | "desc" | {
         readonly dir: "asc" | "desc";
         readonly nulls?: "first" | "last";
-    } | undefined;
+    } | Relevance | undefined;
+};
+/**
+ * Text to look for.
+ *
+ * A string is enough when the table has one column built for search. `in`
+ * names the column when it has more than one.
+ */
+export type TextSearch<Row> = string | {
+    /** Text to look for. */
+    readonly for: string;
+    /** Column to search. Required when the table has more than one. */
+    readonly in?: keyof Row & string;
+    /** How to match. Omitted means `natural`. */
+    readonly match?: SearchMatch;
+    /** Text search language, such as `english`. Omitted uses the database default. */
+    readonly language?: string;
 };
 type Related<S extends QuerySchema, T extends keyof S["~byName"], Opt> = Opt extends {
     readonly select: infer Sel;
 } ? Selected<RowOf<S, T>, Sel> : RowOf<S, T>;
-/** One include. To-many needs `limit`. */
+/** One include. To-many needs `limit`. A morph include is `true`. */
 export type IncludeOf<S extends QuerySchema, K extends keyof S["~byName"]> = {
     readonly [R in RelationKeys<RelationsOf<S, K>>]?: RelationsOf<S, K>[R] extends {
+        readonly morph: {
+            readonly targets: readonly string[];
+        };
+    } ? true : RelationsOf<S, K>[R] extends {
         readonly kind: "many";
         readonly table: infer T extends string;
     } ? T extends keyof S["~byName"] ? {
@@ -63,14 +97,40 @@ export type IncludeOf<S extends QuerySchema, K extends keyof S["~byName"]> = {
         readonly orderBy?: OrderBy<RowOf<S, T>>;
     } : never : never;
 };
+/**
+ * Rows a morph include can return.
+ *
+ * Each target's row, plus the type field set to that table name, or null when
+ * the target row is missing.
+ */
+/** Flattens an intersection so a morph arm is one object type. */
+type Flat<T> = {
+    readonly [K in keyof T]: T[K];
+};
+/** One arm of a morph union. Distributes over the closed target list. */
+type MorphArm<S extends QuerySchema, T extends string, Field extends string> = T extends keyof S["~byName"] ? Flat<RowOf<S, T> & {
+    readonly [P in Field]: T;
+}> : never;
+type MorphUnion<S extends QuerySchema, Targets extends readonly string[], Field extends string> = MorphArm<S, Targets[number], Field> | null;
 /** Columns kept by `select`. The full row when `select` is omitted. */
 export type Selected<Row, Sel> = [Sel] extends [readonly (infer P)[]] ? [P] extends [keyof Row] ? {
     readonly [K in P & keyof Row]: Row[K];
-} : Row : Row;
+} : boolean extends HasWindow<P> ? Pick<Row, Extract<P, keyof Row>> & WindowFields<Row, P> : [P] extends [Window<string, string | number>] ? WindowFields<Row, P> : Row : Row;
+/** `true` when a select entry is a window. A mix of fields and windows is `boolean`. */
+type HasWindow<P> = P extends Window<string, string | number> ? true : false;
+/** Result keys a window helper adds. A field name contributes nothing. */
+type WindowFields<Row, P> = Intersect<P extends Window<infer A, infer V> ? {
+    readonly [K in A]: V extends keyof Row ? NonNullable<Row[V]> | null : number;
+} : {}>;
 type IncludeRows<S extends QuerySchema, K extends keyof S["~byName"], Inc> = [Inc] extends [
     Record<string, unknown>
 ] ? {
     readonly [R in keyof Inc & keyof RelationsOf<S, K>]: RelationsOf<S, K>[R] extends {
+        readonly morph: {
+            readonly targets: infer Targets extends readonly string[];
+            readonly typeField: infer Field extends string;
+        };
+    } ? MorphUnion<S, Targets, Field> : RelationsOf<S, K>[R] extends {
         readonly kind: "many";
         readonly table: infer T extends keyof S["~byName"];
     } ? readonly Related<S, T, Inc[R]>[] : RelationsOf<S, K>[R] extends {
@@ -109,7 +169,8 @@ export type CallOptions = {
 /** Options shared by reads. */
 export type ReadOptions<S extends QuerySchema, K extends keyof S["~byName"]> = CallOptions & {
     readonly where?: WhereOf<S, K>;
-    readonly select?: readonly (keyof RowOf<S, K> & string)[];
+    /** Field names, or a window helper (`rowNumber`, `rank`, `denseRank`, `runningTotal`). */
+    readonly select?: readonly ((keyof RowOf<S, K> & string) | Window<string, string | number>)[];
     readonly orderBy?: OrderBy<RowOf<S, K>>;
     readonly include?: IncludeOf<S, K>;
 };
@@ -118,6 +179,7 @@ export type ReadOptions<S extends QuerySchema, K extends keyof S["~byName"]> = C
  *
  * `wait` says what happens when a row is locked by another transaction: `nowait`
  * fails at once (kind `lock_timeout`) and `skip` leaves that row out.
+ * `lock: "skip"` is not a read lock. It claims rows on `update`.
  */
 export type LockOptions = {
     readonly lock?: "update" | "share";
@@ -126,6 +188,48 @@ export type LockOptions = {
 /** `find` options. `limit` is required unless the caller uses `.all(reason)`. */
 export type FindOptions<S extends QuerySchema, K extends keyof S["~byName"]> = ReadOptions<S, K> & {
     readonly limit?: number;
+    /** Text to look for. The closest matches come first unless `orderBy` is set. */
+    readonly search?: TextSearch<RowOf<S, K>>;
+};
+/**
+ * Options for `descendants` and `ancestors`.
+ *
+ * `depth` is how many steps from the starting row. Omit it to walk the whole
+ * tree. `self` includes that row. `relation` names which self-relation when
+ * the table has more than one.
+ */
+export type TreeOptions<S extends QuerySchema, K extends keyof S["~byName"]> = CallOptions & {
+    readonly where?: WhereOf<S, K>;
+    readonly select?: readonly (keyof RowOf<S, K> & string)[];
+    readonly orderBy?: OrderBy<RowOf<S, K>>;
+    readonly depth?: number;
+    /** Include the starting row. Omitted leaves it out. */
+    readonly self?: boolean;
+    /** Which self-relation. Required when the table has more than one. */
+    readonly relation?: string;
+};
+/** Links `sync` added and removed. Values are the related row's primary key. */
+export type SyncResult = {
+    readonly added: readonly unknown[];
+    readonly removed: readonly unknown[];
+};
+/** Options for `sync`. `expect` matches an update: the count is links added plus links removed. */
+export type SyncOptions = CallOptions & {
+    readonly expect?: number;
+};
+/** The handle `sync` returns. */
+export type SyncHandle = Promise<SyncResult> & {
+    /** The statement, before it runs. */
+    sql(): Promise<{
+        readonly statements: readonly {
+            readonly text: string;
+            readonly params?: readonly (string | null)[];
+        }[];
+    }>;
+    /** `{ ok, value }` or `{ ok, error }`. */
+    safe(): Promise<SafeResult<SyncResult>>;
+    /** Throws `not_found` when the number of added and removed links is not `count`. */
+    expect(count: number): SyncHandle;
 };
 /** A query handle. Await it, or inspect it before it runs. */
 export type Query<T> = Promise<T> & {
@@ -148,15 +252,27 @@ export type Read<T> = Query<T> & {
     all(reason: string): Read<T>;
     /** Turns a null `one()` into `not_found`. */
     required(): Read<NonNullable<T>>;
-    /** Streams rows when the driver has `stream`. Otherwise OKM1111. */
-    stream(): AsyncIterable<T extends readonly (infer R)[] ? R : T>;
+    /**
+     * Yields rows in keyset batches on every driver.
+     *
+     * `batch` is how many rows one query fetches. The default is 1000.
+     * `limit` on the find is the total. A table with no primary key is OKM1120.
+     */
+    stream(options?: {
+        readonly batch?: number;
+    }): AsyncIterable<T extends readonly (infer R)[] ? R : T>;
 };
 /** One page: the rows, and the cursor for the next page. `next` is `null` on the last page. */
 export type Page<Row> = {
     readonly items: readonly Row[];
     readonly next: string | null;
 };
-/** `page` options. `after` is the `next` of the page before. */
+/**
+ * `page` options. `after` is the `next` of the page before.
+ *
+ * `page` refuses a window helper when the call runs (OKM1120). The keyset
+ * cursor has no window value to encode.
+ */
 export type PageOptions<S extends QuerySchema, K extends keyof S["~byName"]> = ReadOptions<S, K> & {
     /** Rows in the page. At least 1. */
     readonly limit: number;
@@ -172,25 +288,51 @@ export type PageOptions<S extends QuerySchema, K extends keyof S["~byName"]> = R
 type NumericKeys<Row> = {
     readonly [F in keyof Row]-?: [NonNullable<Row[F]>] extends [number | string] ? F : never;
 }[keyof Row] & string;
+/** One `orderBy` value. `asc` is nulls last and `desc` is nulls first unless `nulls` is set. */
+type SortDir = "asc" | "desc" | {
+    readonly dir: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+};
 /** `aggregate` options. A hidden field is refused at runtime. */
 export type AggregateOptions<S extends QuerySchema, K extends keyof S["~byName"]> = CallOptions & {
     readonly where?: WhereOf<S, K>;
     /** One result row per distinct combination. Needs `limit`, or `.all(reason)`. */
-    readonly groupBy?: readonly (keyof RowOf<S, K> & string)[];
+    readonly groupBy?: readonly ((keyof RowOf<S, K> & string) | Bucket<string, string, string>)[];
     /** Adds `count`, the number of rows in the group. */
     readonly count?: true;
     readonly sum?: readonly NumericKeys<RowOf<S, K>>[];
     readonly avg?: readonly NumericKeys<RowOf<S, K>>[];
     readonly min?: readonly (keyof RowOf<S, K> & string)[];
     readonly max?: readonly (keyof RowOf<S, K> & string)[];
-    /** Orders the groups. Only `groupBy` fields. Without it, groups come in `groupBy` order. */
-    readonly orderBy?: OrderBy<RowOf<S, K>>;
+    /**
+     * Orders the groups. A `groupBy` field or a bucket `as`.
+     * Without it, groups come in `groupBy` order.
+     */
+    readonly orderBy?: OrderBy<RowOf<S, K>> | {
+        readonly [key: string]: SortDir | undefined;
+    };
     readonly limit?: number;
 };
+/** `true` when a group entry is a bucket. A mix of fields and buckets is `boolean`. */
+type HasBucket<G> = G extends Bucket<string, string, string> ? true : false;
+/** One bucket key. A string group contributes nothing. */
+type BucketPiece<Row, G> = G extends Bucket<infer C, infer U, infer A> ? {
+    readonly [K in A]: (U extends "second" | "minute" | "hour" ? Temporal.Instant : Temporal.PlainDate) | (C extends keyof Row ? (null extends Row[C] ? null : never) : null);
+} : {};
+/** Intersection of a union of group pieces. */
+type Intersect<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : unknown;
+/**
+ * Group keys on an aggregate row.
+ *
+ * A plain field list stays `Pick`. A bucket list adds each `as` key. The value
+ * is `Temporal.PlainDate` for a calendar unit and `Temporal.Instant` for a
+ * clock unit, and includes `null` when the column does.
+ */
+type GroupOf<Row, G> = boolean extends HasBucket<G> ? Pick<Row, Extract<G, keyof Row>> & Intersect<BucketPiece<Row, G>> : [G] extends [Bucket<string, string, string>] ? Intersect<BucketPiece<Row, G>> : Pick<Row, G & keyof Row>;
 /** A group: its fields, and the aggregates the call named. */
 export type AggregateRow<Row, O> = Show<(O extends {
     readonly groupBy: readonly (infer G)[];
-} ? Pick<Row, G & keyof Row> : unknown) & (O extends {
+} ? GroupOf<Row, G> : unknown) & (O extends {
     readonly count: true;
 } ? {
     readonly count: number;
@@ -311,9 +453,15 @@ export type InsertOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~
 export type UpdateOf<S extends QuerySchema, K extends keyof S["~byName"]> = S["~byName"][K] extends {
     readonly "~update": infer U;
 } ? U : never;
-/** `set` values. `undefined` leaves the field unchanged. `inc` adds to it. `set` and `arr` write json and arrays. */
+/**
+ * `set` values.
+ *
+ * `undefined` leaves the field unchanged. `null` sets null, and only on a
+ * nullable column. `inc` adds to a number or bigint column. A null number
+ * stays null. `json.set` and `arr` write json and arrays.
+ */
 export type UpdateSet<S extends QuerySchema, K extends keyof S["~byName"]> = {
-    readonly [F in keyof UpdateOf<S, K>]?: UpdateOf<S, K>[F] | Inc<NonNullable<UpdateOf<S, K>[F]>> | WriteOp<NonNullable<UpdateOf<S, K>[F]>>;
+    readonly [F in keyof UpdateOf<S, K>]?: UpdateOf<S, K>[F] | IncOf<UpdateOf<S, K>[F]> | WriteOp<NonNullable<UpdateOf<S, K>[F]>>;
 };
 /** Conflict handling on `insert` (spec §11). */
 export type OnConflict<S extends QuerySchema, K extends keyof S["~byName"]> = "error" | "ignore" | {
@@ -337,7 +485,7 @@ export type InsertOptions<S extends QuerySchema, K extends keyof S["~byName"]> =
 };
 /** Options for `update` and `delete`. */
 export type WriteOptions<S extends QuerySchema, K extends keyof S["~byName"]> = {
-    readonly returning?: readonly (keyof RowOf<S, K> & string)[];
+    readonly returning?: true | readonly (keyof RowOf<S, K> & string)[];
     /** Guarded fields this call may set. `delete` ignores it. */
     readonly allow?: readonly (keyof RowOf<S, K> & string)[];
     readonly expect?: number;
@@ -372,19 +520,32 @@ type AllowedSet<S extends QuerySchema, K extends keyof S["~byName"], Allow exten
 type AllowedUpdate<S extends QuerySchema, K extends keyof S["~byName"], Allow extends readonly (keyof RowOf<S, K> & string)[]> = {
     readonly where?: WhereOf<S, K>;
     readonly set: AllowedSet<S, K, Allow>;
+    readonly version?: number;
 } | readonly {
     readonly id?: unknown;
     readonly where?: WhereOf<S, K>;
     readonly set: AllowedSet<S, K, Allow>;
+    readonly version?: number;
 }[];
-/** One update, or a per-row list in one statement. */
+/**
+ * One update, or a per-row list in one statement.
+ *
+ * `lock: "skip"` with `limit` claims that many matching rows and leaves rows
+ * another transaction already holds. It is not valid on a list.
+ */
 export type UpdateTarget<S extends QuerySchema, K extends keyof S["~byName"]> = {
     readonly where?: WhereOf<S, K>;
     readonly set: UpdateSet<S, K>;
+    readonly limit?: number;
+    readonly lock?: "skip";
+    /** Version read from the row. Required at runtime when the table is `versioned()`. */
+    readonly version?: number;
 } | readonly {
     readonly id?: unknown;
     readonly where?: WhereOf<S, K>;
     readonly set: UpdateSet<S, K>;
+    /** Version read from the row. Required at runtime when the table is `versioned()`. */
+    readonly version?: number;
 }[];
 /** `{ count, archiveId }` from one `archive()` call. */
 export type ArchiveCount = {
@@ -462,6 +623,7 @@ export type TableApi<S extends QuerySchema, K extends keyof S["~byName"] & strin
     };
     count(options?: CallOptions & {
         readonly where?: WhereOf<S, K>;
+        readonly search?: TextSearch<RowOf<S, K>>;
     }): Read<number>;
     exists(options?: CallOptions & {
         readonly where?: WhereOf<S, K>;
@@ -482,15 +644,49 @@ export type TableApi<S extends QuerySchema, K extends keyof S["~byName"] & strin
      * database default for that row; `null` stays NULL.
      */
     insert(data: readonly (RequiredInsert<InsertOf<S, K>> & OptionalInsert<InsertOf<S, K>>)[], options?: InsertOptions<S, K>): Write<readonly Show<RowOf<S, K>>[]>;
-    /** Updates matching rows, or a per-row list in one statement. `where` is required. */
-    update<const Allow extends readonly (keyof RowOf<S, K> & string)[]>(target: AllowedUpdate<S, K, Allow>, options: WriteOptions<S, K> & {
+    /**
+     * Updates matching rows, or a per-row list in one statement. `where` is required.
+     *
+     * `{ allow, returning: true }` returns the written rows. `{ allow }` without
+     * `returning: true` returns `{ count }`.
+     */
+    update<const Allow extends readonly (keyof RowOf<S, K> & string)[], const Opt extends WriteOptions<S, K> & {
         readonly allow: Allow;
-    }): Write<WriteCount>;
+    }>(target: AllowedUpdate<S, K, Allow>, options: Opt): [Opt["returning"]] extends [true] ? Write<readonly Show<RowOf<S, K>>[]> : Write<WriteCount>;
+    update(target: UpdateTarget<S, K>, options: WriteOptions<S, K> & {
+        readonly returning: true;
+    }): Write<readonly Show<RowOf<S, K>>[]>;
     update(target: UpdateTarget<S, K>, options?: WriteOptions<S, K>): Write<WriteCount>;
-    /** Deletes matching rows. `where` is required. */
+    /**
+     * Deletes matching rows. `where` is required.
+     *
+     * `{ returning: true }` is not accepted. Pass the field names, or omit
+     * `returning` for `{ count }`.
+     */
     delete(target: {
         readonly where?: WhereOf<S, K>;
-    }, options?: WriteOptions<S, K>): Write<WriteCount>;
+    }, options?: Omit<WriteOptions<S, K>, "returning"> & {
+        readonly returning?: Exclude<WriteOptions<S, K>["returning"], true>;
+    }): Write<WriteCount>;
+    /**
+     * Rows below `id`, walking the table's self-relation.
+     *
+     * One statement. A row already seen is not entered again, so a cycle in the
+     * data returns. A missing id returns no rows. `where` and a preset filter
+     * the rows that come back. Tenancy and the active set apply at every step.
+     */
+    descendants<const O extends TreeOptions<S, K>>(id: unknown, options?: O): Query<readonly ResultRow<S, K, O>[]>;
+    /** Rows above `id`. The options match {@link TableApi.descendants}. */
+    ancestors<const O extends TreeOptions<S, K>>(id: unknown, options?: O): Query<readonly ResultRow<S, K, O>[]>;
+    /**
+     * Sets a to-many relation to exactly `ids`.
+     *
+     * One statement. A join table gains and loses link rows. A nullable foreign
+     * key is set or cleared, and the related row stays. A link that would have
+     * to delete a row is refused. Duplicate ids count once. An id that is not
+     * in the related table is `not_found`, and nothing is written.
+     */
+    sync(id: unknown, relation: string, ids: readonly unknown[], options?: SyncOptions): SyncHandle;
 } & (S["~byName"][K] extends {
     readonly "~archive": true;
 } ? ArchiveOps<S, K, L> : unknown) & PresetApi<S, K, L> & TableExtras<S, K>;
@@ -647,6 +843,16 @@ type ViewApi<Row> = {
         readonly where?: FieldWhere<Row>;
     }): Read<boolean>;
 };
+/**
+ * `refresh()` on a materialized view.
+ *
+ * No arguments. It runs `REFRESH MATERIALIZED VIEW`, with `CONCURRENTLY` when
+ * the view declares `refresh: "concurrently"`. It is a write, so it uses the
+ * primary. It is not tenant-scoped: a scoped client still refreshes the whole view.
+ */
+type MaterializedViewApi<Row> = ViewApi<Row> & {
+    refresh(): Promise<void>;
+};
 /** `db.views`, typed from `schema({ views })`. Absent when the schema declares none. */
 type ViewsClient<S> = S extends {
     readonly "~views": infer V extends readonly unknown[];
@@ -654,7 +860,9 @@ type ViewsClient<S> = S extends {
     readonly views: {
         readonly [D in V[number] as D extends {
             readonly name: infer N extends string;
-        } ? CamelName<N> : never]: ViewApi<Show<ViewRow<D>>>;
+        } ? CamelName<N> : never]: D extends {
+            readonly "~kind": "materialized";
+        } ? MaterializedViewApi<Show<ViewRow<D>>> : ViewApi<Show<ViewRow<D>>>;
     };
 } : unknown;
 /** A client whose tables are already inside one tenant or an unscoped reason. */

package/dist/runtime/validate/index.js

@@ -1,12 +1,12 @@
 import {
   validationGate
-} from "../../shared/9m80mkac.js";
+} from "../../shared/ze4hxsmy.js";
 import {
   addSchemaHook
-} from "../../shared/5enne4ma.js";
+} from "../../shared/xnxsed62.js";
 import {
   queryHandle
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 import {
   OkmError2
 } from "../../shared/52szzakm.js";
@@ -14,7 +14,7 @@ import {
 // src/runtime/validate/load.ts
 var engine;
 function loadEngine() {
-  engine ??= import("../../shared/8rsy3hxz.js");
+  engine ??= import("../../shared/h15jx9bc.js");
   return engine;
 }
 

package/dist/runtime/version.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Optimistic version checks.
+ *
+ * Loaded on the first update of a `versioned()` table. A plain update does
+ * not import it. The check and the bump are one statement: a stale row is
+ * not written, and the caller hears category `conflict`.
+ */
+import type { Statement } from "../contracts/driver.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+import { type Outputs } from "./plan.js";
+import { type Indexed } from "./plan.js";
+import { type WriteMods } from "./write.js";
+/** What {@link planVersioned} hands back to the write path. */
+export type VersionPlan = {
+    readonly statements: readonly Statement[];
+    readonly outputs: Outputs;
+    readonly shape: "count" | "rows";
+    readonly expect: number | undefined;
+    /** Fields the caller tried to write, and the versions they sent. */
+    readonly versioned: {
+        readonly fields: readonly string[];
+        readonly sent: readonly number[];
+    };
+};
+/**
+ * Plans an update that checks `version` and bumps it.
+ *
+ * A list carries one version per row. `lock: "skip"` claims rows at that
+ * version and leaves locked rows. `.all()` is refused. An upsert is refused
+ * by the insert planner, not here.
+ *
+ * @param schema - Connected schema
+ * @param table - Target table
+ * @param input - `{ where, set, version }` or a per-row list
+ * @param options - Returning, expect, signal, timeout
+ * @param mods - `.expect`. `.all` is refused
+ * @returns One statement, and the versions the caller sent
+ */
+export declare function planVersioned(schema: QuerySchema, table: Indexed, input: unknown, options: Record<string, unknown>, mods: WriteMods): VersionPlan;

package/dist/runtime/window.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Window helpers in `select` (spec §10, §13 tool 12).
+ *
+ * Loaded on the first `find` or `one` whose `select` contains a helper.
+ * A plain list of field names never loads this module. `page` does not take
+ * a window: its select is field names, and the keyset cursor has no window
+ * value to encode.
+ */
+import type { QuerySchema } from "../dialects/pg/model.js";
+import { type ReadCall } from "./plan.js";
+/**
+ * Plans a read whose `select` contains a window helper.
+ *
+ * The returned call writes the statement. Includes, tenancy, and presets stay
+ * on the planner the plain read uses.
+ *
+ * @param schema - Connected schema
+ * @param call - The read, with a window in `select`
+ * @returns The same read, with its statement builder set
+ */
+export declare function attach(schema: QuerySchema, call: ReadCall): ReadCall;

package/dist/runtime/write.d.ts

@@ -6,9 +6,9 @@
  */
 import type { ExecuteOptions, ExecuteResult, Statement } from "../contracts/driver.js";
 import type { IdGenerators } from "../contracts/generator.js";
-import type { PresetUse } from "../dialects/pg/model.js";
+import type { ColumnModel, PresetUse } from "../dialects/pg/model.js";
 import type { QuerySchema } from "../dialects/pg/model.js";
-import { type ArchiveView, type CallScope } from "./plan.js";
+import { type ArchiveView, type CallScope, type Indexed, type Sink } from "./plan.js";
 import { type RunHost } from "./tx.js";
 /** Statements in one insert stay under this many parameters. The protocol limit is 65535. */
 export declare const WRITE_PARAM_BUDGET = 2048;
@@ -39,8 +39,15 @@ export type PreparedWrite = {
     readonly statements: readonly Statement[];
     readonly options: ExecuteOptions | undefined;
     /** Set when `finish` can refuse a statement that already ran. `batch` refuses such a write (D183). */
-    readonly checked?: "restore" | "expect";
+    readonly checked?: "restore" | "expect" | "parent";
     finish(results: readonly ExecuteResult[]): unknown;
+    /**
+     * More statements once the planned ones have run.
+     *
+     * First-or-create uses this when the insert returned fewer rows than it was
+     * given. Empty means the insert already returned every row.
+     */
+    follow?(results: readonly ExecuteResult[]): readonly Statement[];
 };
 /**
  * Runs a write and decodes it.
@@ -71,3 +78,48 @@ export declare function executeWrite(host: WriteHost, op: WriteOp, table: string
 export declare function explainWrite(schema: QuerySchema, op: WriteOp, table: string, input: unknown, options: object, mods: WriteMods, generators?: IdGenerators, scope?: CallScope): Promise<{
     readonly statements: readonly Statement[];
 }>;
+export declare function updateSliceBody(schema: QuerySchema, table: Indexed, rows: readonly {
+    readonly where: unknown;
+    readonly set: Record<string, unknown>;
+}[], sql: Sql, wrapWhere?: boolean, hooks?: {
+    afterWhere?(sql: Sql, index: number): void;
+    afterSet?(sql: Sql): void;
+}): void;
+export declare function rejectDuplicateTargets(table: Indexed, rows: readonly {
+    readonly where: unknown;
+}[]): void;
+export declare function emitSet(sql: Sql, table: Indexed, set: Record<string, unknown>, alias: string): void;
+export declare class Sql {
+    private readonly parts;
+    private readonly params;
+    text(value: string): void;
+    /**
+     * Binds one parameter.
+     *
+     * An empty data type leaves the parameter uncast so `where` can infer it.
+     */
+    param(wire: string | null, dataType: string): void;
+    sink(): Sink;
+    statement(): Statement;
+}
+export declare function writeSet(table: Indexed, value: unknown, allow: ReadonlySet<string>, tenancy: QuerySchema["tenancy"]): Record<string, unknown>;
+/**
+ * A list that sets one field with an operator in one row and a plain value,
+ * or a different operator, in another.
+ */
+export declare function rejectMixedSets(rows: readonly {
+    readonly set: Record<string, unknown>;
+}[]): void;
+/**
+ * `lock: "skip"` with `limit` on one update. Absent when the caller named neither.
+ *
+ * @param input - The update target
+ * @returns The row cap, or `undefined` when this update does not claim
+ */
+export declare function readClaim(input: Record<string, unknown>): number | undefined;
+export declare function rejectUpdateKeys(input: Record<string, unknown>, row: boolean): void;
+export declare function requireFilter(table: Indexed, where: unknown, mods: WriteMods, op: WriteOp): void;
+export declare function returningOption(table: Indexed, value: unknown): readonly ColumnModel[] | undefined;
+export declare function expectOf(options: Record<string, unknown>, mods: WriteMods): number | undefined;
+export declare function allowSet(table: Indexed, value: unknown): ReadonlySet<string>;
+export declare function noteGuarded(table: Indexed, allow: ReadonlySet<string>, op: "insert" | "update"): void;

package/dist/shared/{krxx77g0.js → 14vx95q4.js}

@@ -6,7 +6,7 @@ import {
   runCall,
   EMPTY_NOTICES,
   resultFrom
-} from "./cgbamx3e.js";
+} from "./kb2sdhfb.js";
 
 // src/adapters/pg/postgresjs.ts
 import net from "node:net";
@@ -62,13 +62,15 @@ class PoolSockets {
   }
   wake() {
     for (const socket of this.held)
-      socket.ref();
+      if (socket.writable)
+        socket.ref();
   }
   park() {
     if (this.busy > 0 || this.listeners > 0)
       return;
     for (const socket of this.held)
-      socket.unref();
+      if (socket.writable)
+        socket.unref();
   }
 }
 function driverOptions(config, state) {
@@ -115,26 +117,18 @@ function open2(config) {
     execute(text, params, options) {
       return sockets.occupy(() => runCall(closed, options, (watch) => root.query(text, params, watch)));
     },
-    async batch(statements, options) {
-      return sockets.occupy(async () => {
-        const { checkout } = await import("./caw8b9d8.js");
-        const connection = await checkout(held);
-        try {
-          return await connection.batch(statements, options);
-        } finally {
-          await connection.release();
-        }
-      });
+    batch(statements, options) {
+      return sockets.occupy(() => import("./je4axnm8.js").then((mod) => mod.runBatch(held, statements, options)));
     },
     reserve() {
       const gate = sockets.busyGate();
       gate.enter();
-      return import("./caw8b9d8.js").then((mod) => mod.holdCheckout(gate, () => mod.checkout(held)), (error) => {
+      return import("./je4axnm8.js").then((mod) => mod.holdCheckout(gate, () => mod.checkout(held)), (error) => {
         gate.leave();
         throw error;
       });
     },
-    describe: (text, params) => sockets.occupy(() => import("./caw8b9d8.js").then((mod) => mod.describe(sql, text, params))),
+    describe: (text, params) => sockets.occupy(() => import("./je4axnm8.js").then((mod) => mod.describe(sql, text, params))),
     stream(text, params) {
       const gate = sockets.busyGate();
       return async function* () {
@@ -149,7 +143,7 @@ function open2(config) {
     listen(channel, onNotify) {
       const gate = sockets.listenerGate();
       gate.enter();
-      return import("./caw8b9d8.js").then((mod) => mod.holdListener(gate, async () => {
+      return import("./je4axnm8.js").then((mod) => mod.holdListener(gate, async () => {
         const listening = await sql.listen(channel, onNotify);
         return async () => {
           await listening.unlisten();
@@ -219,7 +213,7 @@ class PgSession {
       onAbort();
     else
       watch.signal.addEventListener("abort", onAbort, { once: true });
-    return import("./caw8b9d8.js").then((mod) => mod.watchQuery(pending, watch, onAbort, {
+    return import("./je4axnm8.js").then((mod) => mod.watchQuery(pending, watch, onAbort, {
       start,
       text,
       notices: this.notices,
@@ -271,7 +265,7 @@ class PgSession {
   }
 }
 async function* loadStream(sql, text, params) {
-  const { stream } = await import("./caw8b9d8.js");
+  const { stream } = await import("./je4axnm8.js");
   yield* stream(sql, text, params);
 }
 function send(sql, text, params, named) {