@rebasepro/types 0.23.0 → 0.24.1-canary.g19596ef

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,61 @@ 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
+ * generated `Database`, so a nested `include` is checked against the *target's*
+ * relations in turn.
+ *
+ * A name, a dotted path starting with one, or `"*"`; or the tree, keyed by
+ * relation name. A name that is not a relation is a 400 `UNKNOWN_RELATION`
+ * from the server, and a compile error here.
+ *
+ * @group Data
+ */
+export type IncludeSpecFor<DB, R> = readonly (Extract<keyof R, string> | "*" | `${Extract<keyof R, string>}.${string}`)[] | {
+    [K in Extract<keyof R, string>]?: true | IncludeOptionsFor<DB, R[K]>;
+};
+/**
+ * {@link IncludeOptions} for a relation that reaches the generated collection
+ * `T`: its nested `include` is checked against `T`'s relations.
+ *
+ * @group Data
+ */
+export interface IncludeOptionsFor<DB, T> extends Omit<IncludeOptions, "include"> {
+    include?: T extends keyof DB ? IncludeOf<DB[T], DB> : IncludeSpec;
+}
+/**
+ * The include a generated `Database` entry takes — {@link IncludeSpecFor} over
+ * its `Relations` — or the unchecked {@link IncludeSpec} for anything that does
+ * not declare its relations (a hand-written row type, an older generated file).
+ *
+ * @group Data
+ */
+export type IncludeOf<Entry, DB> = Entry extends {
+    Relations: infer R;
+} ? IncludeSpecFor<DB, R> : IncludeSpec;
+/**
+ * One argument of the fluent `.include(...)`: an element of the include list, a
+ * whole list, or the tree.
+ *
+ * @group Data
+ */
+export type IncludeArgOf<Inc> = Inc extends readonly (infer E)[] ? E | Inc : Inc;
 /**
  * Hops an {@link IncludeSpec} may nest. `comments.author` is two.
  *
@@ -171,14 +319,16 @@ 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
  */
-export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> {
     /**
      * Maximum number of items to return.
      *
@@ -193,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;
     /**
@@ -215,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.
@@ -236,11 +387,14 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * Not checked against `M` here: a relation name comes from the collection's
      * `relations`, not from its columns, so nothing in a *hand-written* row type
      * can validate one. A **generated** `Database` narrows this to the
-     * collection's actual relation keys, recursively — see `rebase codegen`.
+     * collection's actual relation keys, recursively — see
+     * {@link IncludeSpecFor}. The row a read returns still types each relation
+     * as optional; the generated `RowWith<A, I>` names the row with the
+     * included ones required.
      *
      * An unknown name is a 400 `UNKNOWN_RELATION`. It used to be ignored.
      */
-    include?: IncludeSpec;
+    include?: Inc;
     /**
      * Columns to return, instead of all of them.
      *
@@ -263,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;
     /**
@@ -324,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.
@@ -352,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;
@@ -395,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.
@@ -415,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.
      *
@@ -443,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.
      *
@@ -463,9 +656,9 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * absent implementation in a stub that says so rather than returning a
      * number nothing counted.
      */
-    aggregate?(params: AggregateParams<M>): Promise<AggregateRow[]>;
+    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>;
@@ -492,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;
@@ -587,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.
@@ -605,14 +820,15 @@ export type AggregateRow = Record<string, unknown>;
  * What {@link SDKCollectionClient.aggregate} takes: the same narrowing a
  * `find()` takes, minus the parts of it that describe a *page* of rows.
  *
- * `limit` survives and means what it means on the REST route — a bound on the
- * number of **groups**, because grouping by a high-cardinality column is a whole
- * table's worth of rows in one response. It is ignored when there is no
- * `groupBy`, since an ungrouped aggregate is one row.
+ * `limit` and `offset` page through the **groups**, as they page a listing's
+ * rows, because grouping by a high-cardinality column is a whole table's worth
+ * of rows in one response. Over HTTP a grouped aggregate with no `limit` gets
+ * the listing default (50 groups) — read {@link AggregateResult.meta} to know
+ * when there were more. Without `groupBy` there is one row: `limit` does nothing
+ * there and `offset` is refused.
  *
- * `orderBy`, `include`, `after` and the rest are absent on purpose: an
- * aggregate has no rows to sort, no relations to load and no page to continue.
- * They were silently ignored on the REST route; here they do not typecheck.
+ * `include`, `after` and the rest are absent on purpose: an aggregate has no
+ * relations to load and no row to continue after.
  *
  * @group Data
  */
@@ -622,20 +838,81 @@ 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. Ignored without `groupBy`. */
+    /** 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>>[];
 }
 /**
- * Which column an iteration seeks on, for keyset ("seek") pagination.
+ * 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.
+ *
+ * @group Data
+ */
+export interface AggregateMeta {
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * What {@link SDKCollectionClient.aggregate} resolves to: the rows, as an
+ * array, carrying the page they are as `meta`.
+ *
+ * `meta` is present on a grouped aggregate that was cut at a `limit` — which,
+ * over HTTP, is every grouped one, since the route applies the listing default
+ * when none is given. `hasMore: true` means the groups did not all fit: page on
+ * with `offset`, or raise `limit`. It is a non-enumerable property, so a spread,
+ * `JSON.stringify` or `Object.keys` of the result sees only the rows.
+ *
+ * @group Data
+ */
+export interface AggregateResult extends Array<AggregateRow> {
+    readonly meta?: AggregateMeta;
+}
+/**
+ * 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
  */
@@ -657,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" })) { … }
@@ -691,9 +968,12 @@ 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>> = Omit<FindParams<M>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
+export type IterateParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = Omit<FindParams<M, Inc>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
 /**
  * Parameters accepted by {@link SDKCollectionClient.findAll}: the iteration
  * parameters plus the ceiling that keeps a whole collection from being pulled
@@ -701,7 +981,7 @@ export type IterateParams<M extends Record<string, unknown> = Record<string, unk
  *
  * @group Data
  */
-export type FindAllParams<M extends Record<string, unknown> = Record<string, unknown>> = IterateParams<M> & {
+export type FindAllParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = IterateParams<M, Inc> & {
     /**
      * Most rows to materialise. Defaults to 10 000. Exceeding it **throws**
      * — a truncated array returned as if it were the whole answer is the
@@ -716,7 +996,7 @@ export type FindAllParams<M extends Record<string, unknown> = Record<string, unk
  *
  * @group Data
  */
-export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> {
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     /**
      * Filter on a relation path (`author.name`) or a JSON path
@@ -733,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.
@@ -753,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;
@@ -761,12 +1041,12 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      * Load relations — names, dotted paths (`"comments.author"`), or the
      * parametrised tree. Repeated calls merge rather than replace.
      */
-    include(...relations: (string | IncludeSpec)[]): this;
+    include(...relations: IncludeArgOf<Inc>[]): this;
     /**
      * 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`. */
@@ -777,9 +1057,10 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      *
      * The builder's `where`/`logical`/`search` narrow which rows are
      * aggregated; its `orderBy`, `include` and window do not apply and are
-     * ignored, exactly as they are on the REST route.
+     * ignored, exactly as they are on the REST route. Page the groups with the
+     * `limit`/`offset` passed here.
      */
-    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateRow[]>;
+    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateResult>;
     /**
      * Page through everything this query matches, one row at a time.
      *
@@ -867,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
@@ -879,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 = 
@@ -906,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.
  *
@@ -944,22 +1243,40 @@ export interface BatchRef {
     /** `<ref name>.<field>`, e.g. `order.id`. */
     $ref: string;
 }
-/** One entry of a batch request. @group Data */
+/**
+ * A row's values in a batch: the collection's own columns, each of which may
+ * instead be a {@link BatchRef} to a value an earlier operation produces.
+ *
+ * Homomorphic over the row type, so a column the row type requires is required
+ * here too — a create in a batch is the same insert `create()` is. There used
+ * to be an `& Record<string, unknown>` on the end, which let a misspelt column
+ * compile and come back as a 400 `VALIDATION_UNKNOWN_FIELDS`.
+ */
+type BatchValues<T> = {
+    [F in keyof T]: T[F] | BatchRef;
+};
+/**
+ * One entry of a batch request.
+ *
+ * `collection` is the collection's **accessor** on a typed client — the name
+ * `client.data.<accessor>` takes, and the key of the generated `Database`
+ * (`orderItems`). The client resolves it to the slug the route knows
+ * (`order_items`) through its `collections` dictionary; a slug that is not an
+ * accessor is sent as written.
+ *
+ * @group Data
+ */
 export type BatchOperation<DB = Record<string, unknown>> = {
     [K in Extract<keyof DB, string>]: {
         op: "create";
         collection: K;
-        values: {
-            [F in keyof InsertOf<DB[K]>]?: InsertOf<DB[K]>[F] | BatchRef;
-        } & Record<string, unknown>;
+        values: BatchValues<InsertOf<DB[K]>>;
         /** Name this row so a later operation can reference its columns. */
         ref?: string;
     } | {
         op: "upsert";
         collection: K;
-        values: {
-            [F in keyof InsertOf<DB[K]>]?: InsertOf<DB[K]>[F] | BatchRef;
-        } & Record<string, unknown>;
+        values: BatchValues<InsertOf<DB[K]>>;
         /** See {@link UpsertOptions.onConflict}. Defaults to the primary key. */
         onConflict?: readonly string[];
         ref?: string;
@@ -968,8 +1285,8 @@ 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;
-        } & Record<string, unknown>;
+            [F in keyof UpdateOf<DB[K]>]?: UpdateOf<DB[K]>[F] | FieldOperationFor<UpdateOf<DB[K]>[F]> | BatchRef;
+        };
         ref?: string;
     } | {
         op: "delete";
@@ -1021,6 +1338,10 @@ export interface WriteOptions {
      * attempt is still being answered gets `IDEMPOTENCY_KEY_IN_PROGRESS` (409)
      * and should be sent again. A server that cannot store keys ignores the
      * header rather than refusing the write.
+     *
+     * The in-process accessor (`context.data`, `rebase.data`) has no store to
+     * keep keys in, and refuses one with `UNSUPPORTED_OPTION` rather than
+     * writing as though it had been checked.
      */
     idempotencyKey?: string;
     /**
@@ -1035,7 +1356,9 @@ export interface WriteOptions {
      *
      * Reach for it on imports and fire-and-forget writes. The method resolves
      * to `undefined` (or `[]`) when it is set, so a caller cannot accidentally
-     * use a row the server never sent.
+     * use a row the server never sent — and `create`, `update` and `upsert`
+     * are typed `M | undefined` for a literal `returning: false`, so reading a
+     * field off the result is a compile error rather than a `TypeError`.
      */
     returning?: boolean;
     /**
@@ -1051,11 +1374,75 @@ export interface WriteOptions {
      *
      * `"*"` asserts only that the row exists.
      *
-     * Honoured on `update` and `delete`.
+     * Honoured on `update` and `delete` over HTTP. The in-process accessor
+     * (`context.data`, `rebase.data`) cannot check a precondition yet, and
+     * refuses one with `UNSUPPORTED_OPTION` rather than writing unconditionally.
      */
     ifMatch?: string;
 }
-export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>> {
+/**
+ * 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> {
     /**
      * Find multiple records with optional filtering, pagination, and sorting.
      *
@@ -1079,7 +1466,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * it is where the pagination metadata lives, and it is present exactly when
      * there is some.
      */
-    find(params?: FindParams<M>): Promise<FindResult<M>>;
+    find(params?: FindParams<M, Inc>): Promise<FindResult<M>>;
     /**
      * Walk every record matching a query, one row at a time, fetching pages as
      * the consumer consumes them.
@@ -1099,14 +1486,15 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *
      * ## 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({
@@ -1117,7 +1505,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *     await handle(job);
      * }
      */
-    iterate(params?: IterateParams<M>): AsyncIterableIterator<M>;
+    iterate(params?: IterateParams<M, Inc>): AsyncIterableIterator<M>;
     /**
      * {@link iterate}, collected into an array.
      *
@@ -1128,7 +1516,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * {@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.
      *
@@ -1138,11 +1526,12 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *     cursor: "id"
      * });
      */
-    findAll(params?: FindAllParams<M>): Promise<M[]>;
+    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.
      *
@@ -1183,8 +1572,11 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *   on anything else (a `sku`, a composite key), there is no `id` column to
      *   receive it — put the key in `data` instead, where it belongs among the
      *   columns.
-     * @returns The created row
+     * @returns The created row — or nothing, with `returning: false`.
      */
+    create(data: I, id: string | number | undefined, options: WriteOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     create(data: I, id?: string | number, options?: WriteOptions): Promise<M>;
     /**
      * Write many records in a single request and a single transaction.
@@ -1236,6 +1628,9 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * that retry from a second deliberate edit — which on a `PATCH` that
      * increments or appends is a second edit applied.
      */
+    update(id: string | number, data: U | UpdateValues<U>, options: WriteOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     update(id: string | number, data: U | UpdateValues<U>, options?: WriteOptions): Promise<M>;
     /**
      * Insert the row, or replace the one already occupying its key.
@@ -1253,6 +1648,10 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * `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
@@ -1260,12 +1659,15 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *
      * @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"] }
      * );
      * ```
      */
+    upsert(data: I, options: UpsertOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     upsert(data: I, options?: UpsertOptions): Promise<M>;
     /**
      * Update many records in a single request and a single transaction.
@@ -1367,16 +1769,36 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * `observe()` degrades to a single fetch instead of throwing, which is the
      * other reason to reach for it instead.
      */
-    listen(params: FindParams<M> | 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;
+    listen(params: FindParams<M, Inc> | undefined, onUpdate: (response: FindResult<M>) => 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.
      *
      * Always present; see {@link listen} for what a transport that cannot serve
      * it does instead.
      */
-    count(params?: FindParams<M>): Promise<number>;
+    count(params?: FindParams<M, Inc>): Promise<number>;
     /**
      * `count`/`sum`/`avg`/`min`/`max` over the matching rows, optionally
      * grouped — the SDK half of `GET /<collection>/aggregate`.
@@ -1401,33 +1823,33 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * naming the capability rather than an empty result set, which would read
      * as "nothing matched".
      */
-    aggregate(params: AggregateParams<M>): Promise<AggregateRow[]>;
-    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M>;
+    aggregate(params: AggregateParams<M>): Promise<AggregateResult>;
+    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>;
-    where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
-    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", nulls?: NullsPlacement): SDKQueryBuilderInterface<M>;
-    limit(count: number): SDKQueryBuilderInterface<M>;
-    offset(count: number): SDKQueryBuilderInterface<M>;
+    where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): 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>;
     search(searchString: string, options?: {
         explain?: boolean;
-    }): SDKQueryBuilderInterface<M>;
+    }): SDKQueryBuilderInterface<M, Inc>;
     /**
      * Order rows by nearest-neighbour distance to `vector`, closest first.
      * 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>;
-    include(...relations: (string | IncludeSpec)[]): SDKQueryBuilderInterface<M>;
+    }): SDKQueryBuilderInterface<M, Inc>;
+    include(...relations: IncludeArgOf<Inc>[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.fields} */
-    fields(...columns: (FieldPath<M> | string)[]): SDKQueryBuilderInterface<M>;
+    fields(...columns: Extract<keyof M, string>[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.distinct} */
-    distinct(enabled?: boolean): SDKQueryBuilderInterface<M>;
+    distinct(enabled?: boolean): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.after} */
-    after(cursor: string): SDKQueryBuilderInterface<M>;
+    after(cursor: string): SDKQueryBuilderInterface<M, Inc>;
 }
 /**
  * The unified data access object for the **admin panel** (Entity-shaped).
@@ -1524,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) => …)`.
@@ -1544,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.
      *
@@ -1553,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]>>;
-} : {
+} & (unknown extends DB ? {
     /**
      * Dynamic flat collection accessor.
      * Access any collection by its slug as a property.
@@ -1564,4 +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 {};