@prisma-next/sql-orm-client 0.9.0-dev.3 → 0.9.0-dev.4

package/dist/index.d.mts

@@ -516,57 +516,489 @@ declare class Collection<TContract extends Contract<SqlStorage>, ModelName exten
   /** @internal */
   readonly includeRefinementMode: boolean;
   constructor(ctx: CollectionContext<TContract>, modelName: ModelName, options?: CollectionInit<TContract>);
+  /**
+   * Narrow the collection with a `WHERE` predicate. Returns a new
+   * collection — chain further builders or run a terminal on it.
+   *
+   * Accepts a callback receiving a typed model accessor, a raw
+   * `WhereArg` expression, or a shorthand field/value object. Multiple
+   * calls are AND-combined.
+   *
+   * ```typescript
+   * // Callback form with column-level operators:
+   * const matches = await db.orm.User.where((u) => u.email.eq('alice@example.com')).all();
+   *
+   * // Shorthand object form:
+   * const user = await db.orm.User.where({ id: 1, active: true }).first();
+   *
+   * // Chained AND — still a builder, run a terminal to execute:
+   * const adults = await db.orm.User.where({ active: true }).where((u) => u.age.gt(18)).all();
+   * ```
+   */
   where(fn: (model: ModelAccessor<TContract, ModelName>) => WhereDirectInput): Collection<TContract, ModelName, Row, WithWhereState<State>>;
   where(input: WhereDirectInput): Collection<TContract, ModelName, Row, WithWhereState<State>>;
   where(fn: (model: ModelAccessor<TContract, ModelName>) => WhereArg): Collection<TContract, ModelName, Row, WithWhereState<State>>;
   where(filters: ShorthandWhereFilter<TContract, ModelName>): Collection<TContract, ModelName, Row, WithWhereState<State>>;
+  /**
+   * Narrow a polymorphic model to a specific variant. The returned
+   * collection has the variant's row shape and a discriminator filter
+   * is automatically applied. Chaining `.variant(...)` again replaces
+   * the previous variant filter.
+   *
+   * ```typescript
+   * // Read only admin users (STI):
+   * const admins = await db.orm.User.variant('Admin').all();
+   *
+   * // Iterate the rows:
+   * for await (const admin of db.orm.User.variant('Admin').all()) {
+   *   console.log(admin.role);
+   * }
+   *
+   * // Insert under a variant — discriminator is injected automatically:
+   * await db.orm.User.variant('Admin').create({ name: 'Ada', role: 'super' });
+   * ```
+   */
   variant<V extends VariantNames<TContract, ModelName>>(variantName: V): Collection<TContract, ModelName, VariantModelRow<TContract, ModelName, V>, WithVariantState<WithWhereState<State>, V>>;
+  /**
+   * Eagerly load a related model. The relation appears on every
+   * returned row under its declared name; to-one relations are mapped
+   * to a single object (or `null`), to-many relations to an array.
+   *
+   * An optional refinement callback receives a child collection that
+   * can be further constrained, projected, ordered, paginated, or
+   * reduced to scalars via `count()`/`sum()`/etc. or to multiple
+   * sub-aggregates via `combine()`.
+   *
+   * ```typescript
+   * // Simple include — every user comes back with its posts array:
+   * const users = await db.orm.User.include('posts').all();
+   *
+   * // Refine the related collection:
+   * const withRecent = await db.orm.User.include('posts', (posts) =>
+   *   posts.where({ published: true }).orderBy((p) => p.createdAt.desc()).take(5),
+   * ).all();
+   *
+   * // Reduce a to-many relation to a scalar value:
+   * const withCounts = await db.orm.User.include('posts', (posts) => posts.count()).all();
+   *
+   * // Multiple sub-views via combine():
+   * const overview = await db.orm.User.include('posts', (posts) =>
+   *   posts.combine({ recent: posts.take(3), total: posts.count() }),
+   * ).all();
+   * ```
+   */
   include<RelName extends RelationNames<TContract, ModelName>, RelatedName extends RelatedModelName<TContract, ModelName, RelName> & string = RelatedModelName<TContract, ModelName, RelName> & string, IsToMany extends boolean = IsToManyRelation<TContract, ModelName, RelName>, RefinedResult extends IncludeRefinementResult<TContract, RelatedName, IsToMany> = IncludeRefinementCollection<TContract, RelatedName, DefaultModelRow<TContract, RelatedName>, CollectionTypeState, IsToMany>>(relationName: RelName, refineFn?: (collection: IncludeRefinementCollection<TContract, RelatedName, DefaultModelRow<TContract, RelatedName>, DefaultCollectionTypeState, IsToMany>) => RefinedResult): Collection<TContract, ModelName, SimplifyDeep<Row & { [K in RelName]: IncludeRefinementValue<TContract, ModelName, K, DefaultModelRow<TContract, RelatedName>, RefinedResult> }>, State>;
+  /**
+   * Project the row down to a subset of scalar fields. Previously
+   * included relations are preserved on the resulting row shape; only
+   * scalar columns are narrowed.
+   *
+   * ```typescript
+   * const summaries = await db.orm.User.select('id', 'email').all();
+   * // typeof summaries[number] === { id: ...; email: ... }
+   *
+   * for await (const row of db.orm.User.select('id', 'email').all()) {
+   *   console.log(row.id, row.email);
+   * }
+   * ```
+   */
   select<Fields extends readonly [keyof DefaultModelRow<TContract, ModelName> & string, ...(keyof DefaultModelRow<TContract, ModelName> & string)[]]>(...fields: Fields): Collection<TContract, ModelName, SimplifyDeep<Pick<DefaultModelRow<TContract, ModelName>, Fields[number]> & IncludedRelationsForRow<TContract, ModelName, Row>>, State>;
+  /**
+   * Append an `ORDER BY` clause. Pass a single selector callback or an
+   * array of callbacks; each receives a typed model accessor whose
+   * columns expose `.asc()` and `.desc()`. Multiple calls append to the
+   * existing list (left-to-right ordering preserved).
+   *
+   * Calling `orderBy(...)` unlocks `cursor(...)` and `distinctOn(...)`,
+   * which both require a defined sort order.
+   *
+   * ```typescript
+   * const newest = await db.orm.User.orderBy((u) => u.createdAt.desc()).all();
+   *
+   * const byName = await db.orm.User
+   *   .orderBy([(u) => u.lastName.asc(), (u) => u.firstName.asc()])
+   *   .all();
+   * ```
+   */
   orderBy(selection: ((model: ModelAccessor<TContract, ModelName>) => OrderByItem) | ReadonlyArray<(model: ModelAccessor<TContract, ModelName>) => OrderByItem>): Collection<TContract, ModelName, Row, WithOrderByState<State>>;
+  /**
+   * Switch to grouped-aggregate mode. Returns a `GroupedCollection`
+   * whose `.aggregate(...)` terminal produces one row per group with
+   * the chosen key columns plus the requested aggregates.
+   *
+   * ```typescript
+   * const stats = await db.orm.Post
+   *   .where({ published: true })
+   *   .groupBy('userId')
+   *   .aggregate((agg) => ({ count: agg.count(), totalViews: agg.sum('views') }));
+   * // [{ userId: 1, count: 3, totalViews: 120 }, ...]
+   * ```
+   */
   groupBy<Fields extends readonly [keyof DefaultModelRow<TContract, ModelName> & string, ...(keyof DefaultModelRow<TContract, ModelName> & string)[]]>(...fields: Fields): GroupedCollection<TContract, ModelName, Fields>;
+  /**
+   * Scalar reducer — reduces a to-many relation to the number of
+   * related rows. Use inside an `include(...)` refinement callback as
+   * `include(..., (rel) => rel.count())`; throws if called elsewhere.
+   * The parent row's relation field becomes that count instead of an
+   * array.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) => posts.count()).all();
+   * // each user row: { ...user, posts: number }
+   * ```
+   */
   count(): IncludeScalar<number>;
+  /**
+   * Scalar reducer — reduces a to-many relation to the sum of `field`
+   * across related rows. Returns `null` when there are no related
+   * rows. Use inside an `include(...)` refinement callback; throws if
+   * called elsewhere.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) => posts.sum('views')).all();
+   * // each user row: { ...user, posts: number | null }
+   * ```
+   */
   sum<FieldName extends NumericFieldNames<TContract, ModelName>>(field: FieldName): IncludeScalar<number | null>;
+  /**
+   * Scalar reducer — reduces a to-many relation to the average of
+   * `field` across related rows. Returns `null` when there are no
+   * related rows. Use inside an `include(...)` refinement callback;
+   * throws if called elsewhere.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) => posts.avg('views')).all();
+   * // each user row: { ...user, posts: number | null }
+   * ```
+   */
   avg<FieldName extends NumericFieldNames<TContract, ModelName>>(field: FieldName): IncludeScalar<number | null>;
+  /**
+   * Scalar reducer — reduces a to-many relation to the minimum value
+   * of `field` across related rows. Returns `null` when there are no
+   * related rows. Use inside an `include(...)` refinement callback;
+   * throws if called elsewhere.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) => posts.min('views')).all();
+   * ```
+   */
   min<FieldName extends NumericFieldNames<TContract, ModelName>>(field: FieldName): IncludeScalar<number | null>;
+  /**
+   * Scalar reducer — reduces a to-many relation to the maximum value
+   * of `field` across related rows. Returns `null` when there are no
+   * related rows. Use inside an `include(...)` refinement callback;
+   * throws if called elsewhere.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) => posts.max('views')).all();
+   * ```
+   */
   max<FieldName extends NumericFieldNames<TContract, ModelName>>(field: FieldName): IncludeScalar<number | null>;
+  /**
+   * Produce multiple named sub-views of a to-many relation in a
+   * single `include(...)`. Each branch is either another refined
+   * collection (mapped to a row array on the parent) or a scalar
+   * reducer such as `count()`/`sum(...)`. Only valid inside an
+   * `include(...)` refinement callback for to-many relations.
+   *
+   * ```typescript
+   * const users = await db.orm.User.include('posts', (posts) =>
+   *   posts.combine({
+   *     recent: posts.where({ published: true }).take(3),
+   *     total: posts.count(),
+   *     averageViews: posts.avg('views'),
+   *   }),
+   * ).all();
+   * // each user row: {
+   * //   ...user,
+   * //   posts: { recent: Post[]; total: number; averageViews: number | null };
+   * // }
+   * ```
+   */
   combine<Spec extends Record<string, Collection<TContract, ModelName, unknown, CollectionTypeState> | IncludeScalar<unknown>>>(spec: Spec): IncludeCombine<{ [K in keyof Spec]: Spec[K] extends IncludeScalar<infer ScalarResult> ? ScalarResult : Spec[K] extends Collection<TContract, ModelName, infer BranchRow, CollectionTypeState> ? BranchRow[] : never }>;
+  /**
+   * Resume pagination from a known cursor position. Requires a prior
+   * `orderBy(...)` so the cursor has a stable basis; provide a value
+   * for every column referenced by the active `orderBy(...)` so each
+   * ordered axis has a defined boundary.
+   *
+   * ```typescript
+   * const page1 = await db.orm.Post
+   *   .orderBy((p) => p.createdAt.desc())
+   *   .take(20)
+   *   .all();
+   *
+   * const last = page1[page1.length - 1]!;
+   * const page2 = await db.orm.Post
+   *   .orderBy((p) => p.createdAt.desc())
+   *   .cursor({ createdAt: last.createdAt })
+   *   .take(20)
+   *   .all();
+   * ```
+   */
   cursor(cursorValues: State['hasOrderBy'] extends true ? Partial<Record<keyof DefaultModelRow<TContract, ModelName> & string, unknown>> : never): Collection<TContract, ModelName, Row, State>;
+  /**
+   * Emit `SELECT DISTINCT` keyed on the given fields. Replaces any
+   * previous `distinct(...)` / `distinctOn(...)` selection.
+   *
+   * ```typescript
+   * const groups = await db.orm.User.distinct('country', 'role').all();
+   * ```
+   */
   distinct<Fields extends readonly [keyof DefaultModelRow<TContract, ModelName> & string, ...(keyof DefaultModelRow<TContract, ModelName> & string)[]]>(...fields: Fields): Collection<TContract, ModelName, Row, State>;
+  /**
+   * Emit `SELECT DISTINCT ON (fields)` — keep the first row per
+   * distinct key according to the current `orderBy(...)`. Requires a
+   * prior `orderBy(...)`; replaces any previous `distinct(...)` /
+   * `distinctOn(...)` selection.
+   *
+   * ```typescript
+   * // Latest post per user:
+   * const latestPerUser = await db.orm.Post
+   *   .orderBy([(p) => p.userId.asc(), (p) => p.createdAt.desc()])
+   *   .distinctOn('userId')
+   *   .all();
+   * ```
+   */
   distinctOn<Fields extends readonly [keyof DefaultModelRow<TContract, ModelName> & string, ...(keyof DefaultModelRow<TContract, ModelName> & string)[]]>(...fields: State['hasOrderBy'] extends true ? Fields : never): Collection<TContract, ModelName, Row, State>;
+  /**
+   * Apply `LIMIT n`. Replaces any previous limit set on this collection.
+   *
+   * ```typescript
+   * const firstTen = await db.orm.User.orderBy((u) => u.id.asc()).take(10).all();
+   * ```
+   */
   take(n: number): Collection<TContract, ModelName, Row, State>;
+  /**
+   * Apply `OFFSET n`. Replaces any previous offset set on this collection.
+   *
+   * ```typescript
+   * const page2 = await db.orm.User
+   *   .orderBy((u) => u.id.asc())
+   *   .skip(10)
+   *   .take(10)
+   *   .all();
+   * ```
+   */
   skip(n: number): Collection<TContract, ModelName, Row, State>;
   /**
-   * Read terminal: stream all rows matching the current state.
+   * Read terminal: execute the query and stream every matching row.
+   *
+   * The returned `AsyncIterableResult<Row>` is BOTH a thenable that
+   * resolves to `Row[]` (so `await` collects all rows into an array)
+   * AND an async iterable (so `for await` streams rows as they
+   * arrive, without buffering the whole result set in memory). Pick
+   * whichever fits the caller. A single result can only be consumed
+   * once.
+   *
+   * Streaming is the default and the expected execution model. The
+   * only scenarios that fall back to buffering internally before
+   * yielding are drivers that cannot expose a cursor to the
+   * underlying database, and — for queries with `include(...)` —
+   * targets whose SQL dialect supports neither lateral joins nor
+   * correlated subqueries (so child rows cannot be stitched in a
+   * single streaming query). These are implementation details below
+   * the public API; the iteration shape itself is genuinely
+   * streaming whenever the driver and plan allow it.
+   *
+   * ```typescript
+   * // Thenable — collect to an array:
+   * const users = await db.orm.User.all();
+   * for (const user of users) console.log(user.id);
+   *
+   * // Async iterable — stream rows as they arrive:
+   * for await (const user of db.orm.User.all()) {
+   *   console.log(user.id);
+   * }
+   * ```
    *
    * Accepts an optional `configure` callback that receives a
    * `MetaBuilder<'read'>` so the caller can attach typed user
    * annotations to the executed plan. `meta.annotate(...)` enforces
    * applicability at the type level and at runtime; annotations are
    * merged into `plan.meta.annotations` at compile time.
+   *
+   * ```typescript
+   * await db.orm.User.all((meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+   * ```
    */
   all(configure?: (meta: MetaBuilder<'read'>) => void): AsyncIterableResult<Row>;
+  /**
+   * Read terminal: return the first matching row, or `null` if none
+   * match. Optionally accepts a filter (callback or shorthand object)
+   * followed by a `configure` callback for typed read annotations.
+   *
+   * To attach annotations without further narrowing, pass `undefined`
+   * as the filter (or chain `.where(...)` first):
+   *
+   * ```typescript
+   * // No filter — first row in the collection:
+   * const someone = await db.orm.User.first();
+   *
+   * // Shorthand filter:
+   * const alice = await db.orm.User.first({ email: 'alice@example.com' });
+   *
+   * // Callback filter:
+   * const old = await db.orm.User.first((u) => u.age.gt(60));
+   *
+   * // Annotate without filtering further:
+   * await db.orm.User.first(undefined, (meta) =>
+   *   meta.annotate(cacheAnnotation({ ttl: 60 })),
+   * );
+   * ```
+   */
   first(): Promise<Row | null>;
   first(filter: undefined, configure: (meta: MetaBuilder<'read'>) => void): Promise<Row | null>;
   first(filter: (model: ModelAccessor<TContract, ModelName>) => WhereArg, configure?: (meta: MetaBuilder<'read'>) => void): Promise<Row | null>;
   first(filter: ShorthandWhereFilter<TContract, ModelName>, configure?: (meta: MetaBuilder<'read'>) => void): Promise<Row | null>;
   /**
    * Read terminal: run an aggregate query (count, sum, avg, min, max)
-   * built via the `AggregateBuilder` callback.
+   * built via the `AggregateBuilder` callback. Returns one object
+   * with the requested aggregate values keyed by the aliases supplied
+   * in the spec.
+   *
+   * ```typescript
+   * const stats = await db.orm.Post
+   *   .where({ published: true })
+   *   .aggregate((agg) => ({
+   *     total: agg.count(),
+   *     averageViews: agg.avg('views'),
+   *     maxViews: agg.max('views'),
+   *   }));
+   * // { total: 42, averageViews: 17.3, maxViews: 9001 }
+   * ```
    *
    * Accepts an optional `configure` callback that receives a
    * `MetaBuilder<'read'>` for attaching typed annotations.
    * Annotations are merged into the compiled plan's `meta.annotations`.
    */
   aggregate<Spec extends AggregateSpec>(fn: (aggregate: AggregateBuilder<TContract, ModelName>) => Spec, configure?: (meta: MetaBuilder<'read'>) => void): Promise<AggregateResult<Spec>>;
+  /**
+   * Write terminal: insert one row and return it (with any configured
+   * `select(...)` / `include(...)` projections applied to the returned
+   * shape).
+   *
+   * Related rows can be created or linked through relation callbacks
+   * on parent/child-owned relations (one-to-one or one-to-many).
+   * The callback receives a mutator exposing `create(...)` and
+   * `connect(...)`; `disconnect(...)` is only supported in nested
+   * `update(...)` mutations. Many-to-many relations are not yet
+   * supported as nested-mutation targets.
+   *
+   * ```typescript
+   * // Simple insert:
+   * const user = await db.orm.User.create({
+   *   email: 'alice@example.com',
+   *   name: 'Alice',
+   * });
+   *
+   * // Nested create on a child-owned to-many relation:
+   * const author = await db.orm.User.create({
+   *   email: 'bob@example.com',
+   *   posts: (posts) => posts.create([
+   *     { title: 'Hello' },
+   *     { title: 'World' },
+   *   ]),
+   * });
+   *
+   * // Connect a child-owned post to an existing parent author:
+   * const reply = await db.orm.Post.create({
+   *   title: 'Re: Hello',
+   *   author: (author) => author.connect({ id: 1 }),
+   * });
+   * ```
+   *
+   * Accepts an optional `configure` callback that receives a
+   * `MetaBuilder<'write'>` for attaching typed annotations.
+   * Annotations are merged into the compiled mutation plan's
+   * `meta.annotations`.
+   *
+   * Note: when the input contains nested-mutation callbacks, the
+   * operation is executed as a graph of internal queries via
+   * `withMutationScope`. In that path, annotations apply to the
+   * logical `create()` call but do not currently flow into each
+   * constituent SQL statement issued for the related rows.
+   */
   create(data: ResolvedCreateInput<TContract, ModelName, State['variantName']>, configure?: (meta: MetaBuilder<'write'>) => void): Promise<Row>;
   create(data: MutationCreateInputWithRelations<TContract, ModelName>, configure?: (meta: MetaBuilder<'write'>) => void): Promise<Row>;
+  /**
+   * Write terminal: insert many rows and stream the inserted rows.
+   *
+   * The returned `AsyncIterableResult<Row>` is BOTH a thenable that
+   * resolves to `Row[]` AND an async iterable that streams inserted
+   * rows as they arrive. Use whichever shape fits the caller — but
+   * only consume it once. Streaming is the default; some
+   * driver/plan combinations may still buffer internally before
+   * yielding.
+   *
+   * ```typescript
+   * // Thenable — collect all inserted rows into an array:
+   * const created = await db.orm.User.createAll([
+   *   { email: 'a@example.com' },
+   *   { email: 'b@example.com' },
+   * ]);
+   *
+   * // Async iterable — stream inserted rows as they arrive:
+   * for await (const row of db.orm.User.createAll(seedUsers)) {
+   *   console.log('inserted', row.id);
+   * }
+   * ```
+   *
+   * Accepts an optional `configure` callback that receives a
+   * `MetaBuilder<'write'>` for attaching typed annotations to the
+   * compiled insert plan.
+   */
   createAll(data: readonly ResolvedCreateInput<TContract, ModelName, State['variantName']>[], configure?: (meta: MetaBuilder<'write'>) => void): AsyncIterableResult<Row>;
+  /**
+   * Write terminal: insert many rows without materializing the
+   * inserted rows, returning the number of inserted records.
+   *
+   * Prefer `createAll(...)` when you need the returned rows; prefer
+   * this when you only need to know how many rows were inserted (the
+   * compiled plan skips `RETURNING`).
+   *
+   * ```typescript
+   * const inserted = await db.orm.User.createCount([
+   *   { email: 'a@example.com' },
+   *   { email: 'b@example.com' },
+   * ]);
+   * // inserted === 2
+   * ```
+   *
+   * Not supported on MTI variants — use `createAll(...)` instead.
+   */
   createCount(data: readonly ResolvedCreateInput<TContract, ModelName, State['variantName']>[], configure?: (meta: MetaBuilder<'write'>) => void): Promise<number>;
   /**
-   * Passing `update: {}` makes this behave like a conditional create.
-   * On conflict, `ON CONFLICT DO NOTHING RETURNING ...` may return zero rows,
-   * so this method may issue a follow-up reload query to return the existing row.
+   * Write terminal: insert a row, or update the existing row on
+   * conflict. Returns the resulting row (the inserted one or the
+   * updated/existing one).
+   *
+   * `conflictOn` selects which unique constraint drives the conflict
+   * resolution — omit to use the model's primary key.
+   *
+   * ```typescript
+   * // Insert-or-update on email uniqueness:
+   * await db.orm.User.upsert({
+   *   create: { email: 'alice@example.com', name: 'Alice' },
+   *   update: { name: 'Alice (updated)' },
+   *   conflictOn: { email: 'alice@example.com' },
+   * });
+   *
+   * // Conditional create — `update: {}` keeps the existing row
+   * // unchanged. `conflictOn` must reference the constraint that
+   * // makes the row "already exist"; omit only when the conflict is
+   * // on the primary key. On conflict,
+   * // `ON CONFLICT DO NOTHING RETURNING ...` may return zero rows,
+   * // so a follow-up reload is issued to fetch and return the
+   * // existing row.
+   * await db.orm.User.upsert({
+   *   create: { email: 'alice@example.com', name: 'Alice' },
+   *   update: {},
+   *   conflictOn: { email: 'alice@example.com' },
+   * });
+   * ```
+   *
+   * Not supported on MTI variants.
    */
   upsert(input: {
     create: ResolvedCreateInput<TContract, ModelName, State['variantName']>;
@@ -575,7 +1007,30 @@ declare class Collection<TContract extends Contract<SqlStorage>, ModelName exten
   }, configure?: (meta: MetaBuilder<'write'>) => void): Promise<Row>;
   /**
    * Write terminal: update matching rows and return the first one (or
-   * null when no row matched).
+   * `null` when no row matched). Requires a prior `.where(...)` —
+   * calling `update(...)` on an unfiltered collection is a type error.
+   *
+   * Related rows can be created or relinked through relation
+   * callbacks on parent/child-owned relations (one-to-one or
+   * one-to-many). The callback receives a mutator exposing
+   * `create(...)`, `connect(...)`, and `disconnect(...)`. Nested
+   * updates against existing related rows, and many-to-many relations
+   * as nested-mutation targets, are not supported through this API.
+   *
+   * ```typescript
+   * // Update one row by id:
+   * const updated = await db.orm.User
+   *   .where({ id: 1 })
+   *   .update({ name: 'Alice Renamed' });
+   *
+   * // Update + relink — runs as a graph of internal mutations:
+   * await db.orm.User
+   *   .where({ id: 1 })
+   *   .update({
+   *     name: 'Alice',
+   *     posts: (posts) => posts.connect([{ id: 5 }]),
+   *   });
+   * ```
    *
    * Accepts an optional `configure` callback that receives a
    * `MetaBuilder<'write'>` for attaching typed annotations.
@@ -587,17 +1042,97 @@ declare class Collection<TContract extends Contract<SqlStorage>, ModelName exten
    * statement issued for the related rows.
    */
   update(data: State['hasWhere'] extends true ? MutationUpdateInput<TContract, ModelName> : never, configure?: (meta: MetaBuilder<'write'>) => void): Promise<Row | null>;
+  /**
+   * Write terminal: update every matching row and stream the updated
+   * rows. Requires a prior `.where(...)` filter.
+   *
+   * The returned `AsyncIterableResult<Row>` is BOTH a thenable that
+   * resolves to `Row[]` AND an async iterable that streams updated
+   * rows as they arrive. Use whichever fits; a result can only be
+   * consumed once. Streaming is the default; some driver/plan
+   * combinations may still buffer internally before yielding.
+   *
+   * ```typescript
+   * // Thenable — collect updated rows into an array:
+   * const updated = await db.orm.Post
+   *   .where({ published: false })
+   *   .updateAll({ published: true });
+   *
+   * // Async iterable — stream updated rows as they arrive:
+   * for await (const row of db.orm.Post.where({ draft: true }).updateAll({ draft: false })) {
+   *   console.log('published', row.id);
+   * }
+   * ```
+   *
+   * Accepts an optional `configure` callback that receives a
+   * `MetaBuilder<'write'>` for attaching typed annotations.
+   */
   updateAll(data: State['hasWhere'] extends true ? Partial<DefaultModelRow<TContract, ModelName>> : never, configure?: (meta: MetaBuilder<'write'>) => void): AsyncIterableResult<Row>;
+  /**
+   * Write terminal: update every matching row without returning them,
+   * resolving to the count of rows that were updated. Requires a prior
+   * `.where(...)` filter.
+   *
+   * Prefer `updateAll(...)` when you need the updated rows; prefer
+   * this when you only need the affected-row count.
+   *
+   * ```typescript
+   * const count = await db.orm.Post
+   *   .where({ published: false })
+   *   .updateCount({ published: true });
+   * ```
+   */
   updateCount(data: State['hasWhere'] extends true ? Partial<DefaultModelRow<TContract, ModelName>> : never, configure?: (meta: MetaBuilder<'write'>) => void): Promise<number>;
   /**
-   * Write terminal: delete matching rows and return the first one (or
-   * null when no row matched).
+   * Write terminal: delete matching rows and return the first deleted
+   * row (or `null` when no row matched). Requires a prior `.where(...)`
+   * — calling `delete()` on an unfiltered collection is a type error.
+   *
+   * ```typescript
+   * const deleted = await db.orm.User.where({ id: 1 }).delete();
+   * if (deleted) console.log('deleted', deleted.email);
+   * ```
    *
    * Accepts an optional `configure` callback that receives a
    * `MetaBuilder<'write'>` for attaching typed annotations.
    */
   delete(this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never, configure?: (meta: MetaBuilder<'write'>) => void): Promise<Row | null>;
+  /**
+   * Write terminal: delete every matching row and stream the deleted
+   * rows. Requires a prior `.where(...)` filter.
+   *
+   * The returned `AsyncIterableResult<Row>` is BOTH a thenable that
+   * resolves to `Row[]` AND an async iterable that streams deleted
+   * rows as they arrive. Use whichever fits; a result can only be
+   * consumed once. Streaming is the default; some driver/plan
+   * combinations may still buffer internally before yielding.
+   *
+   * ```typescript
+   * // Thenable — collect the deleted rows into an array:
+   * const deleted = await db.orm.Post.where({ archived: true }).deleteAll();
+   *
+   * // Async iterable — stream deleted rows as they arrive:
+   * for await (const row of db.orm.Post.where({ archived: true }).deleteAll()) {
+   *   console.log('removed', row.id);
+   * }
+   * ```
+   *
+   * Accepts an optional `configure` callback that receives a
+   * `MetaBuilder<'write'>` for attaching typed annotations.
+   */
   deleteAll(this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never, configure?: (meta: MetaBuilder<'write'>) => void): AsyncIterableResult<Row>;
+  /**
+   * Write terminal: delete every matching row without returning them,
+   * resolving to the count of rows that were deleted. Requires a prior
+   * `.where(...)` filter.
+   *
+   * Prefer `deleteAll(...)` when you need the deleted rows; prefer
+   * this when you only need the affected-row count.
+   *
+   * ```typescript
+   * const removed = await db.orm.Post.where({ archived: true }).deleteCount();
+   * ```
+   */
   deleteCount(this: State['hasWhere'] extends true ? Collection<TContract, ModelName, Row, State> : never, configure?: (meta: MetaBuilder<'write'>) => void): Promise<number>;
 }
 //#endregion