@rebasepro/types 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/controllers/data.d.ts

@@ -1,7 +1,7 @@
 import type { VectorSearchParams } from "./data_driver.js";
 import type { ComputedSortField, SearchMatch } from "../types/search.js";
 import { Entity, EntityValues } from "../types/entities.js";
-import { WhereFilterOp, FieldPath, NonColumnFieldPath, FilterValues, NullsPlacement, OrderBySpec, RelationAggregateSort } from "../types/filter-operators.js";
+import { WhereFilterOp, FieldPath, NonColumnFieldPath, FilterValues, NullsPlacement, OrderBySpec, OrderByTuple, RelationAggregateSort } from "../types/filter-operators.js";
 /**
  * The element type of an array column, and the column's own type otherwise.
  *
@@ -44,8 +44,10 @@ export type WhereElementOf<T> = ElementOf<T> | IdOf<ElementOf<T>>;
  * - `array-contains` → one element of the column (or a related row's id).
  * - `in` / `not-in` / `array-contains-any` → a list of elements; a bare element
  *   is read as the one-element list, and `null` is a null check.
- * - `like` / `ilike` / `not-like` / `not-ilike` → a SQL pattern. Always a
- *   string, including on numeric and date columns, which the driver casts.
+ * - `like` / `ilike` / `not-like` / `not-ilike` → a SQL pattern, always a
+ *   string. It matches a text column, or an enum by its label; on a number,
+ *   a date or any other column the Postgres driver refuses it with a 400
+ *   (`INVALID_FILTER_OPERATOR`).
  * - `is-null` / `is-not-null` → nothing; the value is ignored everywhere.
  * - everything else → the column's own type, or `null` for a null comparison.
  *
@@ -54,6 +56,33 @@ export type WhereElementOf<T> = ElementOf<T> | IdOf<ElementOf<T>>;
  * permissive as it was.
  */
 export type WhereValueFor<Op extends WhereFilterOp, T> = Op extends "array-contains" ? WhereElementOf<T> : Op extends "in" | "not-in" | "array-contains-any" ? readonly WhereElementOf<T>[] | WhereElementOf<T> | null : Op extends "like" | "ilike" | "not-like" | "not-ilike" ? string : Op extends "is-null" | "is-not-null" ? null | undefined : T | null;
+/**
+ * One `[operator, value]` condition on a column of type `T`, with the value
+ * typed for the operator exactly as the fluent `where(column, op, value)` types
+ * it — a union with one tuple per operator, so `["array-contains", "featured"]`
+ * on a `string[]` column compiles and `["array-contains", ["featured"]]` (which
+ * builds `@> ARRAY[$1]` and matches nothing) does not.
+ */
+export type WhereConditionFor<T> = {
+    [Op in WhereFilterOp]: [Op, WhereValueFor<Op, T>];
+}[WhereFilterOp];
+/**
+ * The object-form `where` for row type `M`: each column takes conditions typed
+ * against that column, as the fluent form does.
+ *
+ * `FilterValues` typed the key and left the value `unknown`, so the very
+ * shapes the fluent form was fixed to refuse — a wrong value type, an array
+ * where `array-contains` wants one element — compiled in `find({ where })`,
+ * the form `listen`, `observe`, `count` and `iterate` all take.
+ *
+ * A path that is not a column (`author.name`, `metadata->>tier`) has no type to
+ * check against and stays `unknown`, as in {@link FieldPath}. An untyped `M`
+ * (`Record<string, unknown>`, every key) collapses to plain `FilterValues`, so
+ * an untyped client is exactly as permissive as before.
+ */
+export type WhereFor<M extends Record<string, unknown>> = string extends keyof M ? FilterValues<FieldPath<M>> : {
+    [K in Extract<keyof M, string>]?: WhereConditionFor<M[K]> | WhereConditionFor<M[K]>[];
+} & FilterValues<NonColumnFieldPath>;
 /**
  * A group of conditions combined with `and`, `or`, or negated with `not`.
  *
@@ -79,6 +108,53 @@ export interface FilterCondition {
     operator: WhereFilterOp;
     value: unknown;
 }
+/**
+ * One {@link FilterCondition} on row type `M`: the column is one of `M`'s and
+ * the value is typed for the operator against that column, exactly as the
+ * fluent `where(column, op, value)` types it. A path that is not a column
+ * (`author.name`, `metadata->>tier`) has nothing to check against and stays
+ * `unknown`, as in {@link WhereFor}.
+ *
+ * An untyped `M` (`Record<string, unknown>`) collapses to plain
+ * `FilterCondition`, so an untyped client is exactly as permissive as before.
+ */
+export type FilterConditionFor<M extends Record<string, unknown>> = ColumnConditions<M>[keyof ColumnConditions<M>] | {
+    column: NonColumnFieldPath;
+    operator: WhereFilterOp;
+    value: unknown;
+};
+/**
+ * Per column, the union of its typed conditions; an index-signature key (an
+ * untyped row) maps to plain {@link FilterCondition}.
+ *
+ * A key-remapped mapped type rather than a conditional over `keyof M`, for the
+ * reason {@link NumericKeyOf} gives: tsc measures the conditional form as
+ * invariant in `M`, and a typed `SDKCollectionClient<Post>` stopped widening to
+ * the wide `SDKCollectionClient`.
+ */
+type ColumnConditions<M extends Record<string, unknown>> = {
+    [K in keyof M as K extends string ? K : never]: string extends K ? FilterCondition : {
+        [Op in WhereFilterOp]: {
+            column: K;
+            operator: Op;
+            value: WhereValueFor<Op, M[K]>;
+        };
+    }[WhereFilterOp];
+};
+/**
+ * A {@link LogicalCondition} whose every condition, at any depth, is a
+ * {@link FilterConditionFor} row type `M`.
+ *
+ * `cond()` cannot know the row it will be used on, so it returns its column,
+ * operator and value exactly as written; this is where they are checked.
+ * `FindParams.logical` and the builders' `.where(group)` take it, so
+ * `posts.where(or(cond("titel", "==", 1)))` is a compile error on a typed
+ * client rather than the server's 400.
+ */
+export interface LogicalConditionFor<M extends Record<string, unknown>> {
+    type: "and" | "or" | "not";
+    conditions: (FilterConditionFor<M> | LogicalConditionFor<M>)[];
+}
 /**
  * How one relation is loaded by {@link FindParams.include}.
  *
@@ -123,6 +199,19 @@ export interface IncludeOptions {
     fields?: string[];
     /** Relations of the related row to load in turn. */
     include?: IncludeSpec;
+    /**
+     * Also serve how many related rows there are in all, per parent, under
+     * the row's `_count` ({@link INCLUDE_COUNT_KEY}) — `{ tags: [...], _count:
+     * { tags: 37 } }`. Counted by the same query that reads the rows, over the
+     * same rows a read without `limit` would return (the include's `where`,
+     * soft delete, row-level security), so `limit` caps what is sent and the
+     * count says what was left out.
+     *
+     * To-many relations only: a to-one relation is a 400.
+     *
+     * @since 0.24
+     */
+    count?: boolean;
 }
 /**
  * The relations a read loads, as a list of (possibly dotted) names or as a
@@ -131,7 +220,11 @@ export interface IncludeOptions {
  * - `["author", "comments.author"]` — a dotted path is the same thing as the
  *   nested object form, spelled flat. It is what the REST `?include=` parameter
  *   carries, and the two forms compile to the same request.
- * - `["*"]` — every relation, one hop deep. The admin panel's shape.
+ * - `["*"]` — every relation the collection declares, one hop deep, those
+ *   declared only for a record's tabs included — so on a list it can embed
+ *   every row of a to-many relation no column shows. Name the relations the
+ *   view renders instead; the admin panel does, and sends `*` only when it
+ *   cannot resolve a collection's relations in the browser.
  * - `{ comments: { limit: 5, include: { author: true } } }` — the parametrised
  *   form.
  *
@@ -143,6 +236,20 @@ export interface IncludeOptions {
  * @group Data
  */
 export type IncludeSpec = string[] | Record<string, true | IncludeOptions>;
+/**
+ * What a read of one record by id takes besides the id — `findById` and
+ * `listenById`.
+ *
+ * @group Data
+ */
+export interface ByIdReadOptions<Inc = IncludeSpec> {
+    /**
+     * Relations to load into the row, as {@link FindParams.include} loads them
+     * into each row of a list. A to-many relation not named here is absent
+     * from the row — not empty.
+     */
+    include?: Inc;
+}
 /**
  * An include checked against one generated collection's relations: `R` is its
  * `Relations` map (relation name → the accessor it reaches) and `DB` the
@@ -212,10 +319,12 @@ export declare const MAX_INCLUDE_DEPTH = 3;
  *
  * ## Pagination precedence
  *
- * `limit`/`offset` and `page` describe the same window two ways. If **both
- * `offset` and `page` are provided, `page` wins** — the backend computes
- * `offset = (page - 1) * (limit ?? DEFAULT_LIST_LIMIT)` and ignores the
- * explicit `offset`. Pick one style per query.
+ * `limit`/`offset` and `page` describe the same window two ways, so send one.
+ * `page` is `offset = (page - 1) * (limit ?? DEFAULT_LIST_LIMIT)`. A read with
+ * **both** is refused with `PAGE_WITH_OFFSET` — a 400 from the server, and a
+ * `RebaseClientError` with that code from a client before any request — rather
+ * than quietly applying one of them. `after` is refused beside either
+ * (`CURSOR_WITH_OFFSET`).
  *
  * @group Data
  */
@@ -234,13 +343,14 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      */
     limit?: number;
     /**
-     * Number of items to skip. Ignored when {@link FindParams.page} is also
-     * set — `page` takes precedence.
+     * Number of items to skip. Not with {@link FindParams.page}: the pair is
+     * refused with `PAGE_WITH_OFFSET`.
      */
     offset?: number;
     /**
-     * Page number (1-indexed), alternative to {@link FindParams.offset}.
-     * When set, overrides `offset` as `(page - 1) * (limit ?? DEFAULT_LIST_LIMIT)`.
+     * Page number (1-indexed), alternative to {@link FindParams.offset}: it
+     * skips `(page - 1) * (limit ?? DEFAULT_LIST_LIMIT)` rows. Sent with
+     * `offset`, the read is refused with `PAGE_WITH_OFFSET`.
      */
     page?: number;
     /**
@@ -256,13 +366,13 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * { role: ["in", ["admin", "editor"]] }
      * { age: [[">=", 18], ["<", 65]] }
      */
-    where?: FilterValues<FieldPath<M>>;
+    where?: WhereFor<M>;
     /**
      * Logical grouping conditions (AND/OR). Use this for anything `where`
      * can't express — notably OR-ing conditions. AND-ed with `where` and
      * `searchString` when present (see the interface docs).
      */
-    logical?: LogicalCondition;
+    logical?: LogicalConditionFor<M>;
     /**
      * Sort order as a `[field, direction]` tuple, or a list of them applied in
      * order of significance — the second key breaks ties on the first, and so on.
@@ -307,8 +417,10 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * projection (which it always is) every row is already distinct. Pair it
      * with `fields` naming the columns you actually want the distinct values of.
      *
-     * `meta.total` counts distinct rows too, so a distinct listing's `hasMore`
-     * describes the set it is paging.
+     * A distinct read is not counted, whichever door it goes through: over
+     * HTTP its `meta.total` is absent, and in-process it is the rows up to the
+     * end of the page — as for {@link FindParams.count} `"none"`. `hasMore`
+     * is exact either way.
      */
     distinct?: boolean;
     /**
@@ -368,6 +480,23 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * carries a `searchString`; there is nothing to explain otherwise.
      */
     searchExplain?: boolean;
+    /**
+     * Whether to count the whole matching set for `meta.total`.
+     *
+     * `"exact"`, the default, runs a `COUNT(*)` over every row the query
+     * matches beside the page — and on a large table that count, not the page,
+     * is most of what a list read costs: it reads every matching row to report
+     * one number. `"none"` skips it. `meta.hasMore` is still exact (the read
+     * asks for one row past the page and reports whether it came back), so
+     * nothing that pages — `iterate()`, `findAll()`, a "load more" button —
+     * needs the count.
+     *
+     * Without the count there is no `total` to report: over HTTP `meta.total`
+     * is absent, and in-process it is the rows up to the end of this page
+     * (`offset` + the page), the figure a driver that cannot count reports.
+     * Sent as `?count=none`.
+     */
+    count?: "exact" | "none";
 }
 /**
  * Paginated response from a collection query.
@@ -396,7 +525,7 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
  */
 export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
-    where(logicalCondition: LogicalCondition): this;
+    where(logicalCondition: LogicalConditionFor<M>): this;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     limit(count: number): this;
     offset(count: number): this;
@@ -439,7 +568,7 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     /**
      * Find a single record by its ID.
      */
-    findById(id: string | number): Promise<Entity<M> | undefined>;
+    findById(id: string | number, options?: ByIdReadOptions): Promise<Entity<M> | undefined>;
     /**
      * Create a new record.
      * @param data The entity data to create.
@@ -459,9 +588,16 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
     }): Promise<Entity<M>[]>;
     /**
      * Update an existing record by ID.
+     *
+     * `options.ifMatch` is the version the edit was made against
+     * ({@link Entity.etag}): the write is refused with `412
+     * PRECONDITION_FAILED` when the row has changed since. A data source that
+     * cannot check one ignores it, and the write is unconditional.
      * @returns The updated entity
      */
-    update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>>;
+    update(id: string | number, data: Partial<EntityValues<M>>, options?: {
+        ifMatch?: string;
+    }): Promise<Entity<M>>;
     /**
      * Update many records in a single transaction.
      *
@@ -487,10 +623,23 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
     /**
-     * Subscribe to a single record for real-time updates.
+     * Subscribe to a single record for real-time updates: every frame is the
+     * record as `findById(id, options)` reads it.
      * Optional method.
      */
-    listenById?(id: string | number, onUpdate: (entity: Entity<M> | undefined) => void, onError?: (error: Error) => void): () => void;
+    listenById?(id: string | number, onUpdate: (entity: Entity<M> | undefined) => void, onError?: (error: Error) => void, options?: ByIdReadOptions): () => void;
+    /**
+     * {@link SDKCollectionClient.listenCount}: the matching rows' count, live.
+     * Optional method; absent where the data source cannot subscribe.
+     */
+    listenCount?(params: FindParams<M> | undefined, onCount: (total: number) => void, onError?: (error: Error) => void): () => void;
+    /**
+     * The rows a soft delete stamped, and the delete that removes a row for
+     * good: what {@link SDKCollectionClient.trash} is built from. A restore is
+     * an ordinary {@link update}. Optional; absent where the data source
+     * cannot read a collection's trash.
+     */
+    trash?: CollectionTrashAccessor<M>;
     /**
      * Count the number of records matching the given filter.
      *
@@ -509,7 +658,7 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     aggregate?(params: AggregateParams<M>): Promise<AggregateResult>;
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): QueryBuilderInterface<M>;
-    where(logicalCondition: LogicalCondition): QueryBuilderInterface<M>;
+    where(logicalCondition: LogicalConditionFor<M>): QueryBuilderInterface<M>;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
     limit(count: number): QueryBuilderInterface<M>;
     offset(count: number): QueryBuilderInterface<M>;
@@ -536,6 +685,11 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
  * @group Data
  */
 export interface PaginationMeta {
+    /**
+     * Every row the query matches, counted. Not counted — and absent from an
+     * HTTP response — when the query asked for {@link FindParams.count}
+     * `"none"`, and on a `distinct` read over HTTP.
+     */
     total: number;
     limit: number;
     offset: number;
@@ -631,9 +785,26 @@ export type AggregateSelect<M extends Record<string, unknown> = Record<string, u
     fn: "count";
     field?: Extract<keyof M, string>;
 } | {
-    fn: "sum" | "avg" | "min" | "max";
+    fn: "sum" | "avg";
+    field: NumericKeyOf<M>;
+} | {
+    fn: "min" | "max";
     field: Extract<keyof M, string>;
 };
+/**
+ * The columns of `M` that hold numbers — what `sum` and `avg` can add up. Any
+ * column used to be accepted, and `sum` of a text column was a 400. An untyped
+ * row (every key `string`) keeps every name.
+ *
+ * Written as the keys of a key-remapped mapped type, not as a conditional over
+ * `keyof M`: tsc measures the conditional form as invariant in `M`, which made
+ * a typed `SDKCollectionClient<Post>` unassignable to the wide
+ * `SDKCollectionClient` that helpers taking any collection accept. A mapped
+ * type is related structurally, so a typed client still widens.
+ */
+export type NumericKeyOf<M extends Record<string, unknown>> = Extract<keyof {
+    [K in keyof M as string extends K ? K : NonNullable<M[K]> extends number ? K : never]: M[K];
+}, string>;
 /**
  * One row of an aggregate result: the `groupBy` columns, plus one key per
  * {@link AggregateSelect} under its derived alias.
@@ -667,16 +838,48 @@ export interface AggregateParams<M extends Record<string, unknown> = Record<stri
     /** Columns to group by. Omit for a single row over everything that matches. */
     groupBy?: Extract<keyof M, string>[];
     /** Filter conditions, as {@link FindParams.where}. */
-    where?: FilterValues<FieldPath<M>>;
+    where?: WhereFor<M>;
     /** An `and`/`or`/`not` group, AND-ed with `where`. */
-    logical?: LogicalCondition;
+    logical?: LogicalConditionFor<M>;
     /** Text search, AND-ed with the filters. */
     searchString?: string;
     /** Most groups to return. Grouped aggregates only. */
     limit?: number;
     /** Groups to skip, to page past `limit`. Grouped aggregates only. */
     offset?: number;
+    /**
+     * Sort the groups — by a `groupBy` column or by an aggregate's alias
+     * (`"count"`, `"sum_total"`, see {@link AggregateAlias}). One
+     * `[key, "asc" | "desc"]` tuple, or several applied in order. Groups the
+     * sort leaves tied keep their `groupBy` order. Grouped aggregates only:
+     * without `groupBy` there is one row, and over HTTP an `orderBy` beside it is
+     * refused with `INVALID_AGGREGATE_WINDOW`. A key that is neither a group
+     * column nor a selected aggregate is refused with `INVALID_ORDER_BY`.
+     *
+     * ```ts
+     * await client.data.orders.aggregate({
+     *     select: [{ fn: "sum", field: "total" }],
+     *     groupBy: ["status"],
+     *     orderBy: ["sum_total", "desc"]
+     * });
+     * ```
+     */
+    orderBy?: OrderByTuple<AggregateOrderKey<M>> | OrderByTuple<AggregateOrderKey<M>>[];
 }
+/**
+ * The key an {@link AggregateSelect} comes back under: `count` for `count()`,
+ * `<fn>_<field>` otherwise (`sum_total`, `max_created_at`).
+ *
+ * @group Data
+ */
+export type AggregateAlias<M extends Record<string, unknown> = Record<string, unknown>> = "count" | `${"count" | "min" | "max"}_${Extract<keyof M, string>}` | `${"sum" | "avg"}_${NumericKeyOf<M>}`;
+/**
+ * What {@link AggregateParams.orderBy} can sort the groups by: a column (to
+ * group by) or an aggregate's alias.
+ *
+ * @group Data
+ */
+export type AggregateOrderKey<M extends Record<string, unknown> = Record<string, unknown>> = Extract<keyof M, string> | AggregateAlias<M>;
 /**
  * Where a grouped aggregate's page of groups sits: the `limit` it was cut at,
  * the `offset` it started from, and whether more groups follow.
@@ -704,11 +907,12 @@ export interface AggregateResult extends Array<AggregateRow> {
     readonly meta?: AggregateMeta;
 }
 /**
- * Which column an iteration seeks on, for keyset ("seek") pagination.
+ * Which column an iteration sorts by when it is asked to seek, for keyset
+ * ("seek") pagination.
  *
  * Either the column name on its own — sorted ascending — or the column plus an
- * explicit direction. The column must be **unique** and must be the column the
- * query is ordered by; see {@link PageWalkOptions.cursor}.
+ * explicit direction. It is used only when the query names no `orderBy`; see
+ * {@link PageWalkOptions.cursor}.
  *
  * @group Data
  */
@@ -730,23 +934,23 @@ export interface PageWalkOptions<M extends Record<string, unknown> = Record<stri
      */
     pageSize?: number;
     /**
-     * Paginate by **seeking on a column** instead of by offset.
+     * **Require** seeking: fail rather than fall back to offset paging.
      *
-     * Offset paging — the default — re-counts rows on every request, so a row
-     * inserted or deleted *while the iteration runs* shifts the window and the
-     * walk silently skips or repeats rows. Seeking is immune to that: each page
-     * asks for rows strictly after the last one seen, so concurrent writes
-     * before the cursor cannot move it.
+     * Every walk already seeks when it can. After the first page it hands the
+     * server's `meta.nextCursor` back as `after`, so each page asks for rows
+     * strictly after the last one seen — concurrent writes before that row
+     * cannot shift the window, and the database never skips rows by count.
+     * Where the server issues no cursor (a relevance-ordered search, a vector
+     * search, a `distinct` read, a server that predates cursors), the default
+     * walk pages by offset instead, which a concurrent insert or delete can
+     * make skip or repeat a row.
      *
-     * Prefer this whenever the collection has a unique, sortable column
-     * (typically its primary key). The column must be unique — a repeated value
-     * at a page boundary either skips rows or stalls, and the iterator throws
-     * rather than looping — and the query is ordered by it, so a `cursor` and a
-     * conflicting `orderBy` is an error, not a silent override.
-     *
-     * Implemented with the parameters `find()` already takes (an `orderBy` plus
-     * a `>` / `<` filter on the cursor column), so it works on every transport
-     * and needs nothing new from the server.
+     * Passing `cursor` turns that fallback into an error: a listing with no
+     * cursor throws `cursor-missing`, and a cursor that stops advancing throws
+     * `cursor-stalled`. It also names the column to sort by when the query has
+     * no `orderBy`; an explicit `orderBy` wins, and the cursor follows whatever
+     * the query is sorted by, multi-key sorts and nullable keys included. The
+     * row id breaks the final tie, so the order is always total.
      *
      * @example
      * for await (const job of client.data.jobs.iterate({ cursor: "id" })) { … }
@@ -764,6 +968,9 @@ export interface PageWalkOptions<M extends Record<string, unknown> = Record<stri
  * `find()` takes except the window itself (`limit`, `offset`, `page`), which
  * the iterator owns, plus the walk options.
  *
+ * `count` is accepted and ignored: no page of a walk is counted, since nothing
+ * a walk returns carries a total (see {@link FindParams.count}).
+ *
  * @group Data
  */
 export type IterateParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = Omit<FindParams<M, Inc>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
@@ -806,7 +1013,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      * errors on a typed client.
      */
     where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): this;
-    where(logicalCondition: LogicalCondition): this;
+    where(logicalCondition: LogicalConditionFor<M>): this;
     /**
      * Sort by a column, a relation or JSON path, `_score`, or an aggregate over
      * a to-many relation — the same key set {@link FindParams.orderBy} takes.
@@ -826,7 +1033,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      *
      * The query embedding is the caller's to produce.
      */
-    vectorSearch(property: string, vector: number[], options?: {
+    vectorSearch(property: Extract<keyof M, string>, vector: number[], options?: {
         distance?: "cosine" | "l2" | "inner_product";
         threshold?: number;
     }): this;
@@ -839,7 +1046,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      * Return only these columns. A real projection: the columns are what is
      * read from the database, not what survives a trim of the response.
      */
-    fields(...columns: (FieldPath<M> | string)[]): this;
+    fields(...columns: Extract<keyof M, string>[]): this;
     /** `SELECT DISTINCT` over the projection — see {@link FindParams.distinct}. */
     distinct(enabled?: boolean): this;
     /** Continue after a previous page's `meta.nextCursor`. */
@@ -941,10 +1148,13 @@ export declare const BATCH_REF_KEY = "$ref";
  * one, which is the case worth catching.
  *
  * Any `$`-prefixed key counts, because `{ $increment: 1 }` written to a number
- * column as a JSON document is the failure this exists to prevent. No collection
- * can declare a column whose value legitimately has a key beginning with `$`: a
- * `map` property's sub-keys are declared, and `$` is not valid in the
- * identifiers the DDL generators emit.
+ * column as a JSON document is the failure this exists to prevent.
+ *
+ * Except on a `map` (pass `propertyType`): a map's value is a JSON document,
+ * and one may legitimately carry `$` keys — a JSON Schema's `$schema`, a
+ * MongoDB-style export. There, only a single-key object whose key is one of
+ * {@link FIELD_OPERATORS} is an operation, and anything else is data. A caller
+ * that does not know the property type gets the strict reading.
  *
  * The one exception is `{ $ref: … }`, the batch's backward reference. It stands
  * where a *value* goes and is resolved to one before the row is written, so it
@@ -953,7 +1163,7 @@ export declare const BATCH_REF_KEY = "$ref";
  *
  * @group Data
  */
-export declare function isFieldOperation(value: unknown): boolean;
+export declare function isFieldOperation(value: unknown, propertyType?: string): boolean;
 /** True when any value in a write payload is (or is attempting to be) one. @group Data */
 export declare function hasFieldOperation(values: Record<string, unknown> | undefined): boolean;
 export type FieldOperation = 
@@ -980,8 +1190,23 @@ export type FieldOperation =
  * @group Data
  */
 export type UpdateValues<U> = {
-    [K in keyof U]?: U[K] | FieldOperation;
+    [K in keyof U]?: U[K] | FieldOperationFor<U[K]>;
 };
+/**
+ * The field operations a column of type `T` takes: `$inc` on a number, `$push`
+ * / `$pull` on an array, `$merge` on a map. Any operation on any column used to
+ * compile — `update(id, { title: { $inc: 1 } })` — and the server answered 400.
+ * A column whose type says nothing (`unknown`, an untyped client) takes them all.
+ */
+export type FieldOperationFor<T> = unknown extends T ? FieldOperation : (NonNullable<T> extends number ? {
+    $inc: number;
+} : never) | (NonNullable<T> extends readonly unknown[] ? {
+    $push: unknown;
+} | {
+    $pull: unknown;
+} : never) | (NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends Record<string, unknown> ? {
+    $merge: Record<string, unknown>;
+} : never);
 /**
  * Where an upsert looks for the row it might be replacing.
  *
@@ -1060,7 +1285,7 @@ export type BatchOperation<DB = Record<string, unknown>> = {
         collection: K;
         id: string | number | BatchRef;
         values: {
-            [F in keyof UpdateOf<DB[K]>]?: UpdateOf<DB[K]>[F] | FieldOperation | BatchRef;
+            [F in keyof UpdateOf<DB[K]>]?: UpdateOf<DB[K]>[F] | FieldOperationFor<UpdateOf<DB[K]>[F]> | BatchRef;
         };
         ref?: string;
     } | {
@@ -1155,6 +1380,66 @@ export interface WriteOptions {
      */
     ifMatch?: string;
 }
+/**
+ * The entity-shaped half of {@link TrashClient}, on a {@link CollectionAccessor}.
+ */
+export interface CollectionTrashAccessor<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** The trashed rows matching `params`. */
+    find(params?: FindParams<M>): Promise<FindResponse<M>>;
+    /** How many trashed rows match `params`. */
+    count(params?: FindParams<M>): Promise<number>;
+    /** Delete a row for good, trashed or live. */
+    purge(id: string | number): Promise<void>;
+    /** {@link purge} for several rows, as one transaction, where the data source can. */
+    purgeMany?(ids: (string | number)[]): Promise<void>;
+}
+/**
+ * Options for {@link TrashClient.restore} and {@link TrashClient.restoreMany}.
+ */
+export interface RestoreOptions<M extends Record<string, unknown> = Record<string, unknown>> extends WriteOptions {
+    /**
+     * The collection's soft-delete field, as declared in `softDelete`.
+     * Defaults to `deletedAt`, the field `softDelete: true` uses; pass the
+     * name a `softDelete: { field: "archivedAt" }` collection declares.
+     *
+     * A restore is an ordinary update setting this field to `null`, which is
+     * the one update the server lets reach a trashed row.
+     */
+    field?: keyof M & string;
+}
+/**
+ * The trash of a collection that declares `softDelete`: the rows a delete
+ * stamped rather than removed. `client.data.<slug>.trash` in the browser,
+ * `context.data.<slug>.trash` and `rebase.data.<slug>.trash` on the server.
+ *
+ * For a collection that declares `softDelete`. On one that does not, `find`
+ * and `count` answer for the live rows, `restore` is refused for a field the
+ * collection does not have, and `purge` is an ordinary delete.
+ *
+ * Where the data source cannot read a trash, every method is a stub that
+ * throws when called.
+ */
+export interface TrashClient<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> {
+    /** The trashed rows matching `params` — `GET /data/<slug>?deleted=only`. */
+    find(params?: FindParams<M, Inc>): Promise<FindResult<M>>;
+    /** How many trashed rows match `params` — `GET /data/<slug>/count?deleted=only`. */
+    count(params?: FindParams<M, Inc>): Promise<number>;
+    /**
+     * Bring a trashed row back: the update setting the soft-delete field to
+     * `null` (`PATCH /data/<slug>/<id>`). Resolves with the restored row.
+     */
+    restore(id: string | number, options?: RestoreOptions<M>): Promise<M>;
+    /** {@link TrashClient.restore} for several rows, as one transaction (`PATCH /data/<slug>/bulk`). */
+    restoreMany(ids: (string | number)[], options?: RestoreOptions<M>): Promise<M[]>;
+    /**
+     * Delete a row for good — `DELETE /data/<slug>/<id>?hard=true`. It cannot
+     * be restored afterwards. Needs the same permission an ordinary delete
+     * does, and works on a live row as well as a trashed one.
+     */
+    purge(id: string | number, options?: WriteOptions): Promise<void>;
+    /** {@link TrashClient.purge} for several rows, as one transaction (`POST /data/<slug>/bulk/delete?hard=true`). */
+    purgeMany(ids: (string | number)[], options?: WriteOptions): Promise<void>;
+}
 export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>, 
 /** The include this collection takes; {@link IncludeOf} for a generated `Database`. */
 Inc = IncludeSpec> {
@@ -1201,14 +1486,15 @@ Inc = IncludeSpec> {
      *
      * ## Consistency
      *
-     * By default this pages by **offset**, which is only as stable as the table
-     * is still: a row inserted or deleted ahead of the cursor between two
-     * requests shifts every later window, so the walk can skip a row or hand
-     * back the same one twice. That is inherent to offset paging, not a bug
-     * here. On a collection with a unique sortable column, pass
-     * {@link PageWalkOptions.cursor} to seek on it instead — the walk then
-     * asks for rows strictly after the last one it saw, which concurrent writes
-     * cannot perturb.
+     * After the first page the walk **seeks**: it hands the server's
+     * `meta.nextCursor` back as `after`, so each page asks for rows strictly
+     * after the last one it saw, which concurrent writes cannot perturb. A
+     * listing the server issues no cursor for — relevance, a vector search, a
+     * `distinct` read — is paged by **offset** instead, which is only as stable
+     * as the table is still: a row inserted or deleted ahead of the window
+     * between two requests shifts every later one, so the walk can skip a row
+     * or hand back the same one twice. Pass {@link PageWalkOptions.cursor} to
+     * make seeking a requirement rather than a preference.
      *
      * @example
      * for await (const job of client.data.jobs.iterate({
@@ -1230,7 +1516,7 @@ Inc = IncludeSpec> {
      * {@link FindAllParams.maxRows} when the data really is bigger, or switch to
      * `iterate()` and stream it.
      *
-     * The offset-drift caveat on {@link iterate} applies here too.
+     * The consistency notes on {@link iterate} apply here too.
      *
      * @throws When more rows match than `maxRows` allows.
      *
@@ -1242,9 +1528,10 @@ Inc = IncludeSpec> {
      */
     findAll(params?: FindAllParams<M, Inc>): Promise<M[]>;
     /**
-     * Find a single record by its ID.
+     * Find a single record by its ID. `options.include` loads its relations,
+     * as `find({ include })` does for each row of a list.
      */
-    findById(id: string | number): Promise<M | undefined>;
+    findById(id: string | number, options?: ByIdReadOptions<Inc>): Promise<M | undefined>;
     /**
      * Read one record by its ID, or throw if it is not there.
      *
@@ -1361,6 +1648,10 @@ Inc = IncludeSpec> {
      * `unique` index. Anything else is a 400 rather than a Postgres error
      * raised half-way through a transaction.
      *
+     * Refused (400 `INVALID_CONFLICT_TARGET`) on the auth collection, whose
+     * rows are the users: a create and an update of a user follow different
+     * rules, and an upsert only learns which it is inside the write.
+     *
      * The `on_create` timestamp of a row that already existed is left alone: a
      * conflict means the row's creation is a fact about the past, and a nightly
      * re-import that reset `createdAt` on everything it touched would take
@@ -1368,9 +1659,9 @@ Inc = IncludeSpec> {
      *
      * @example
      * ```ts
-     * await client.data.users.upsert(
-     *     { email: "a@b.c", name: "Ada" },
-     *     { onConflict: ["email"] }
+     * await client.data.products.upsert(
+     *     { sku: "LAMP-01", name: "Desk lamp" },
+     *     { onConflict: ["sku"] }
      * );
      * ```
      */
@@ -1479,8 +1770,28 @@ Inc = IncludeSpec> {
      * other reason to reach for it instead.
      */
     listen(params: FindParams<M, Inc> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
-    /** {@link listen} for a single row. Prefer `observeById()`. */
-    listenById(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
+    /**
+     * {@link listen} for a single row. Prefer `observeById()`. Every frame is
+     * the row as `findById(id, options)` reads it, relations included.
+     */
+    listenById(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void, options?: ByIdReadOptions<Inc>): () => void;
+    /**
+     * The number of rows matching `params`, kept current: `onCount` is called
+     * with the total once it is known, and again whenever a write changes it.
+     * The live counterpart of {@link count} — a list's total, or a "select all
+     * N" offer, that does not go stale while other people add and remove rows.
+     * Only the filter (`where`, `logical`, `searchString`) counts; the window
+     * and sort are ignored.
+     *
+     * Always present; on a client that cannot subscribe it is a stub that
+     * throws, as {@link listen} is.
+     */
+    listenCount(params: FindParams<M, Inc> | undefined, onCount: (total: number) => void, onError?: (error: Error) => void): () => void;
+    /**
+     * The collection's trash: list, count, restore and purge the rows a soft
+     * delete stamped. See {@link TrashClient}.
+     */
+    trash: TrashClient<M, Inc>;
     /**
      * Count the number of records matching the given filter.
      *
@@ -1516,7 +1827,7 @@ Inc = IncludeSpec> {
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M, Inc>;
     /** A relation path (`author.name`) or a JSON path (`metadata->>tier`). */
     where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): SDKQueryBuilderInterface<M, Inc>;
-    where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M, Inc>;
+    where(logicalCondition: LogicalConditionFor<M>): SDKQueryBuilderInterface<M, Inc>;
     orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", nulls?: NullsPlacement): SDKQueryBuilderInterface<M, Inc>;
     limit(count: number): SDKQueryBuilderInterface<M, Inc>;
     offset(count: number): SDKQueryBuilderInterface<M, Inc>;
@@ -1528,13 +1839,13 @@ Inc = IncludeSpec> {
      * Postgres only, over a `type: "vector"` property. See
      * {@link SDKQueryBuilderInterface.vectorSearch}.
      */
-    vectorSearch(property: string, vector: number[], options?: {
+    vectorSearch(property: Extract<keyof M, string>, vector: number[], options?: {
         distance?: "cosine" | "l2" | "inner_product";
         threshold?: number;
     }): SDKQueryBuilderInterface<M, Inc>;
     include(...relations: IncludeArgOf<Inc>[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.fields} */
-    fields(...columns: (FieldPath<M> | string)[]): SDKQueryBuilderInterface<M, Inc>;
+    fields(...columns: Extract<keyof M, string>[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.distinct} */
     distinct(enabled?: boolean): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.after} */
@@ -1635,6 +1946,31 @@ export type InsertOf<T> = T extends {
 export type UpdateOf<T> = T extends {
     Update: infer U extends Record<string, unknown>;
 } ? U : Partial<RowOf<T>>;
+/**
+ * The slugs a generated `Database` declares, from the `Slug` each entry
+ * carries beside the accessor codegen chose for it.
+ * @group Data
+ */
+export type SlugOf<DB> = {
+    [K in keyof DB]: DB[K] extends {
+        Slug: infer S extends string;
+    } ? S : never;
+}[keyof DB];
+/** The generated `Database` entry whose `Slug` is `S`. */
+type EntryOfSlug<DB, S extends string> = DB[{
+    [K in keyof DB]: DB[K] extends {
+        Slug: S;
+    } ? K : never;
+}[keyof DB]];
+/**
+ * `collection(slug)` for a slug the registered `Database` declares: the same
+ * typed client as the slug's accessor (`collection("my-notes")` is
+ * `myNotes`). A slug it does not declare, or one computed at runtime, is
+ * served by the untyped overload.
+ */
+type TypedSlugCollection<DB> = {
+    collection<S extends SlugOf<DB>>(slug: S): SDKCollectionClient<RowOf<EntryOfSlug<DB, S>>, InsertOf<EntryOfSlug<DB, S>>, UpdateOf<EntryOfSlug<DB, S>>, IncludeOf<EntryOfSlug<DB, S>, DB>>;
+};
 /**
  * Note on the untyped branch below: its index signature is
  * `SDKCollectionClient`, NOT `SDKCollectionClient | ((slug: string) => …)`.
@@ -1655,7 +1991,7 @@ export type UpdateOf<T> = T extends {
  * compile for any of them. Do not restore the arm; use `collection(slug)` if a
  * caller genuinely needs the by-slug function.
  */
-export type RebaseSdkData<DB = unknown> = {
+export type RebaseSdkData<DB = unknown> = (unknown extends DB ? unknown : TypedSlugCollection<DB>) & {
     /**
      * Get a flat collection accessor by slug.
      *
@@ -1664,9 +2000,7 @@ export type RebaseSdkData<DB = unknown> = {
      * await accessor.find({ limit: 10 });
      */
     collection<M extends Record<string, unknown> = Record<string, unknown>>(slug: string): SDKCollectionClient<M>;
-} & (DB extends Record<string, unknown> ? {
-    [K in keyof DB]: SDKCollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>, IncludeOf<DB[K], DB>>;
-} : {
+} & (unknown extends DB ? {
     /**
      * Dynamic flat collection accessor.
      * Access any collection by its slug as a property.
@@ -1675,5 +2009,7 @@ export type RebaseSdkData<DB = unknown> = {
      * data.products.find({ where: { status: ["==", "published"] } })
      */
     [collectionSlug: string]: SDKCollectionClient;
+} : {
+    [K in keyof DB]: SDKCollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>, IncludeOf<DB[K], DB>>;
 });
 export {};