okmodel 0.6.0 → 0.7.0

package/dist/runtime/traits/index.js

@@ -2,7 +2,7 @@ import"../../shared/qq3899ht.js";
 import {
   checkPresetNames,
   duplicatePreset
-} from "../../shared/nsva2a6b.js";
+} from "../../shared/znm0bpp5.js";
 import {
   checkTrait
 } from "../../shared/n0dgs0pb.js";
@@ -17,11 +17,12 @@ import {
   triggerObject
 } from "../../shared/y34a8714.js";
 import {
+  integer2,
   timestamptz2
-} from "../../shared/5yv4k6a6.js";
+} from "../../shared/vqrjpcqn.js";
 import {
   uuid2
-} from "../../shared/2jd1sn0e.js";
+} from "../../shared/hyh73qk6.js";
 import {
   snakeCase
 } from "../../shared/rpycarcr.js";
@@ -41,10 +42,12 @@ import {
   queryHandle,
   attachHttp,
   settleCall
-} from "../../shared/j60w0dvr.js";
+} from "../../shared/tbrvgw6z.js";
 import {
-  installArchiveInspect
-} from "../../shared/2z7wv5tj.js";
+  installArchiveInspect,
+  indexes,
+  isRecord
+} from "../../shared/67txcrcw.js";
 import {
   fitIdentifier2
 } from "../../shared/nfzc5z0w.js";
@@ -465,13 +468,13 @@ function refuse(host, table) {
 }
 var archiveMod;
 function loadArchive() {
-  archiveMod ??= import("../../shared/mb2ycs1p.js");
+  archiveMod ??= import("../../shared/bm22fvzr.js");
   return archiveMod;
 }
 async function settle(host, table, mods) {
   if (mods.uses === undefined)
     return mods;
-  const { resolve } = await import("../../shared/r6nwkxnt.js");
+  const { resolve } = await import("../../shared/m7n9h2a5.js");
   return { ...mods, presets: resolve(host.schema, table, mods.uses).wheres };
 }
 async function run(host, op, table, input, options, mods) {
@@ -484,6 +487,93 @@ async function run(host, op, table, input, options, mods) {
   }
 }
 
+// src/runtime/sort-bind.ts
+function rewriteSortable(self, tables, casing, schemaTraits, group) {
+  return tables.map((item) => {
+    if (!applies2(self, item, schemaTraits))
+      return item;
+    refusePath(item);
+    return withIndex(item, casing, schemaTraits, group);
+  });
+}
+function applies2(self, item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  if (own.includes(self))
+    return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  return schemaTraits?.includes(self) ?? false;
+}
+function refusePath(item) {
+  const tenancy = item.options?.tenancy;
+  if (typeof tenancy === "object" && tenancy !== null && "via" in tenancy) {
+    definition(`sortable() on ${item.name} does not combine with via(). Position needs the tenant columns on the row.`);
+  }
+}
+function withIndex(item, casing, schemaTraits, group) {
+  const options = item.options;
+  const prior = options?.indexes;
+  const tenantKeys = options?.tenantKeys ?? [];
+  const fields = [];
+  for (const field of tenantKeys)
+    if (!fields.includes(field))
+      fields.push(field);
+  if (group !== undefined && !fields.includes(group))
+    fields.push(group);
+  fields.push("position");
+  const predicate = archivedPredicate(item, casing, schemaTraits);
+  const indexes = (handles) => {
+    const calls = prior === undefined ? [] : prior(handles);
+    const columns = fields.map((field) => {
+      const handle = handles[field];
+      if (handle === undefined) {
+        definition(`sortable() on ${item.name} needs a column named ${field}.`);
+      }
+      return handle.name;
+    });
+    return [...Array.isArray(calls) ? calls : [], uniqueIndex(columns, predicate)];
+  };
+  return {
+    ...item,
+    options: { ...options, indexes }
+  };
+}
+function archivedPredicate(item, casing, schemaTraits) {
+  if (!archivable(item, schemaTraits))
+    return;
+  return casing === "snake" ? "(archived_at IS NULL)" : '("archivedAt" IS NULL)';
+}
+function archivable(item, schemaTraits) {
+  const options = item.options;
+  const own = Array.isArray(options?.traits) ? options.traits : [];
+  for (const trait of own)
+    if (marked2(trait))
+      return true;
+  if (options?.omitDefaults !== undefined)
+    return false;
+  if (schemaTraits === undefined)
+    return false;
+  for (const trait of schemaTraits)
+    if (marked2(trait))
+      return true;
+  return false;
+}
+function marked2(value) {
+  return value["~archive"] === true;
+}
+function uniqueIndex(columns, predicate) {
+  const call = {
+    columns,
+    isUnique: true,
+    ...predicate !== undefined ? { predicate } : {},
+    unique() {
+      return call;
+    }
+  };
+  return call;
+}
+
 // src/runtime/traits/index.ts
 function trait(name, input) {
   if (input.presets !== undefined)
@@ -561,7 +651,7 @@ function timestamps(options) {
 function stamped() {
   return timestamptz2().defaultSql("now()").guarded();
 }
-function archivable(options) {
+function archivable2(options) {
   installArchiveContributions();
   const cascade = readCascade(options);
   const base = trait("archivable", {
@@ -585,6 +675,78 @@ function archivable(options) {
   };
   return self;
 }
+function versioned() {
+  return trait("versioned", {
+    fields: {
+      version: integer2().defaultSql("1").guarded()
+    },
+    sealed: ["version"]
+  });
+}
+function sortable(groupBy) {
+  if (groupBy !== undefined && groupBy.length === 0) {
+    definition("sortable() groupBy must be a column name.");
+  }
+  if (groupBy === "position")
+    definition("sortable() cannot group by position.");
+  const base = trait("sortable", {
+    fields: {
+      position: integer2().guarded()
+    },
+    sealed: ["position"]
+  });
+  const self = {
+    ...base,
+    ...groupBy !== undefined ? { group: groupBy } : {},
+    "~sort": true,
+    apply(model, ctx) {
+      if (groupBy !== undefined && !Object.hasOwn(model.columns, groupBy)) {
+        definition(`sortable() on ${ctx.table} needs a column named ${groupBy}.`);
+      }
+      base.apply(model, ctx);
+    },
+    rewrite(tables, casing, schemaTraits) {
+      return rewriteSortable(self, tables, casing, schemaTraits, groupBy);
+    },
+    hook: attachSort
+  };
+  return self;
+}
+function attachSort(target, ctx) {
+  const tableName = ctx.table;
+  const session = ctx.session;
+  if (tableName === undefined || session === undefined)
+    return;
+  const host = session;
+  const table = indexes(host.schema).get(tableName);
+  if (table === undefined)
+    return;
+  let sortableTable = false;
+  for (const item of table.model.traits ?? []) {
+    if (item.name === "sortable")
+      sortableTable = true;
+  }
+  if (!sortableTable)
+    return;
+  const order = { position: "asc" };
+  for (const field of table.model.primary) {
+    if (field !== "position")
+      order[field] = "asc";
+  }
+  wrapOrder(target, "find", order);
+  wrapOrder(target, "page", order);
+  const view = ctx.view;
+  target.move = (id, place) => import("../../shared/9y3mmmh1.js").then((mod) => mod.move(host, tableName, id, place, view));
+}
+function wrapOrder(target, key, order) {
+  const previous = target[key];
+  if (typeof previous !== "function")
+    return;
+  target[key] = (options = {}) => {
+    const next = isRecord(options) && options.orderBy !== undefined ? options : { ...options, orderBy: order };
+    return previous.call(target, next);
+  };
+}
 function readCascade(options) {
   if (options === undefined)
     return [];
@@ -647,7 +809,9 @@ function addFields(name, fields, model, ctx) {
   }
 }
 export {
-  archivable,
+  archivable2 as archivable,
+  sortable,
   timestamps,
-  trait
+  trait,
+  versioned
 };

package/dist/runtime/tree.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `descendants` and `ancestors` (spec §13 tool 11).
+ *
+ * One recursive statement walks a self-relation's parent column. A row already
+ * on the path is not entered again, so a cycle in the data returns. `depth`
+ * stops the walk earlier. `ltree` is not read: the extension is a later index,
+ * and this statement does not require it.
+ *
+ * Tenancy and the active set apply on the start row, on every step, and on
+ * the rows that come back. `where` and presets filter those rows and do not
+ * cut the walk short. A missing id returns no rows, including with `self`.
+ * The root has no ancestors. Loaded on the first call.
+ */
+import type { ColumnModel } from "../dialects/pg/model.js";
+import { type Mods, type Session } from "./client.js";
+import { type ArchiveView, type Indexed } from "./plan.js";
+/**
+ * Builds the handle for one `descendants` or `ancestors` call.
+ *
+ * @param session - Client session
+ * @param table - Table name
+ * @param options - The packed call: the id, the direction, and the caller's options
+ * @param mods - Presets, signal, and timeout
+ * @param view - Archive visibility
+ * @returns A handle that resolves to the walked rows
+ */
+export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined): Promise<unknown> & Record<string, unknown>;
+/**
+ * The primary key the caller passes, without the tenant key.
+ *
+ * A tree walk and `sync` both address one column. A composite key beside the
+ * tenant key is refused.
+ *
+ * @param session - Client session, for the tenant key
+ * @param table - The table
+ * @returns That column
+ */
+export declare function identityColumn(session: Session, table: Indexed): ColumnModel;

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>;