@rvoh/dream 2.34.0 → 2.36.0

package/dist/types/src/dream/Query.d.ts

@@ -177,6 +177,16 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * The distinct column to apply to the Query
      */
     private readonly distinctColumn;
+    /**
+     * @internal
+     *
+     * Whether the Query is ordered by its own order statements alone. The
+     * driver otherwise sorts by a similarity condition's rank, and by the
+     * declared `order` of the associations the Query is built on or joins,
+     * ahead of those statements. The keyset walks and cursor pagination set
+     * this, since their cursors compare only the Query's order statements.
+     */
+    private readonly bypassImplicitOrder;
     /**
      * @internal
      *
@@ -303,25 +313,49 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *
      * IMPORTANT: `findEach` always iterates in ascending primary key order.
      * Any `order` applied to the Query is discarded; passing one has no effect
-     * on the order records are visited in.
+     * on the order records are visited in. The same goes for the `order` an
+     * association declares, when the Query is an `associationQuery` or joins
+     * that association, and for the relevance ranking of a similarity condition
+     * (`ops.similarity`, `ops.wordSimilarity`, `ops.strictWordSimilarity`),
+     * which still decides which records are visited, but not in what order.
+     * `findEach` visits the records {@link Query.all} returns: a Query that
+     * joins a HasOne or HasMany association (directly, through an association
+     * it joins, or as the association an `associationQuery` goes through)
+     * returns a record once for each row the join matches, and `findEach`
+     * visits it once for each of those rows, the rows of one record in
+     * ascending order of the joined rows' primary keys. Call `distinct()` to
+     * visit each record once.
      *
      * This is not a limitation that can be lifted. `findEach` guarantees that
-     * every matching record is visited exactly once, and it delivers that by
-     * paginating on a keyset: each batch selects the next `batchSize` records
-     * with a primary key greater than the last record of the previous batch.
-     * That guarantee only holds over a stable, unique key. Ordering by a
-     * mutable, non-unique column would mean a record whose sort value changed
-     * partway through the iteration could be skipped entirely or visited twice.
-     * ({@link Query.cursorPaginate} can honor an arbitrary order precisely
-     * because a paginated UI tolerates that anomaly; a full traversal cannot.)
+     * every matching row is visited exactly once, and it delivers that by
+     * paginating on a keyset: each batch selects the next `batchSize` rows
+     * whose primary keys (the record's, then the joined rows') sort after the
+     * last row of the previous batch. That guarantee only holds over a stable,
+     * unique key. Ordering by a mutable, non-unique column would mean a record
+     * whose sort value changed partway through the iteration could be skipped
+     * entirely or visited twice. ({@link Query.cursorPaginate} can honor an
+     * arbitrary order precisely because a paginated UI tolerates that anomaly;
+     * a full traversal cannot.)
+     *
+     * A Query that keeps one record of each group (one that calls `distinct`,
+     * or an `associationQuery` of an association that declares `distinct`, or
+     * a Query that joins one) cannot be paginated that way: its own `order`, or
+     * the association's, chooses which record of each group it returns, and a
+     * batch that narrowed it to the rows after the previous batch would let it
+     * choose another. So `findEach` reads the keys of all of its rows before
+     * visiting the first, and visits those whose rows still match when their
+     * batch is read. It visits the rows the Query returned when the walk began,
+     * less any destroyed or changed so that they no longer match the Query's
+     * conditions, and not a row the Query returns only after the walk began,
+     * such as the next record of a group whose record the callback destroyed.
      *
      * If you need records processed in a particular order, load them with a
      * regular ordered query instead of `findEach`.
      *
-     * A `limit` or `offset` on the Query cannot compose with the batch windows
-     * — each batch re-applies the Query's conditions, so the limit would be
+     * A `limit` or `offset` on the Query cannot compose with the batches —
+     * each batch re-applies the Query's conditions, so the limit would be
      * silently replaced by `batchSize` and the offset re-applied to every
-     * window — so a limit- or offset-carrying Query throws at runtime.
+     * batch — so a limit- or offset-carrying Query throws at runtime.
      *
      * @param cb - The callback to call for each found record
      * @param __namedParameters - Options for batch processing
@@ -332,6 +366,80 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     findEach(this: Query<DreamInstance, QueryTypeOpts>, cb: (instance: DreamInstance) => void | Promise<void>, { batchSize }?: {
         batchSize?: number;
     }): Promise<void>;
+    /**
+     * @internal
+     *
+     * `findEach`, visiting each record once rather than once for each row a
+     * HasOne or HasMany join returns it in, for the operations that act on each
+     * record it visits (`destroy`, `reallyDestroy`, `undestroy` and `update`
+     * without `lock: true`).
+     */
+    private findEachRecordOnce;
+    /**
+     * @internal
+     *
+     * Calls `cb` with the record of each row this Query returns, telling its
+     * rows apart by `rowKeyColumns` (see `walkRowBatches`).
+     */
+    private findEachRow;
+    /**
+     * @internal
+     *
+     * The columns that tell apart the rows this Query returns: its primary key,
+     * then the primary keys of the rows HasOne and HasMany joins add (see
+     * `rowKeyColumnsOfJoinedRows`).
+     */
+    private rowKeyColumns;
+    /**
+     * @internal
+     *
+     * A HasOne or HasMany join returns a record once for each row it matches,
+     * and the primary keys of the joined rows, with the Query's own, tell those
+     * rows apart. These are those primary keys, namespaced, other than the
+     * Query's own. A Query that calls `distinct` returns one row for each value
+     * of its distinct column rather than one for each row the join matches, so
+     * it has none.
+     */
+    private rowKeyColumnsOfJoinedRows;
+    /**
+     * @internal
+     *
+     * Walks the rows this Query returns in batches, for `findEach` and
+     * `pluckEach`, and calls `visit` with what `readBatch` reads for each row,
+     * in ascending order of `rowKeyColumns`, the columns that tell its rows
+     * apart. `readBatch` reads a Query that returns a batch's rows, and returns
+     * each row's values of `rowKeyColumns` with what to visit for it, if
+     * anything. A row whose keys appear again in the same batch is visited once.
+     *
+     * A select that keeps one row of each group (DISTINCT ON) is walked from the
+     * keys of all of its rows, read before the first batch (see
+     * `walkRowBatchesFromKeys`); any other, by a cursor (see
+     * `walkRowBatchesByCursor`).
+     */
+    private walkRowBatches;
+    /**
+     * @internal
+     *
+     * Walks the rows this Query returns in batches of the next `batchSize` rows
+     * after the last row of the batch before, compared on `rowKeyColumns` by a
+     * where clause, which every driver applies (see `walkRowBatches`).
+     */
+    private walkRowBatchesByCursor;
+    /**
+     * @internal
+     *
+     * Walks a select that keeps one row of each group (DISTINCT ON), whose rows'
+     * values of `rowKeyColumns` are `distinctOnRowKeys`, read before the first
+     * batch (see `walkRowBatches`). Such a select cannot be walked by a cursor:
+     * narrowing it to the rows after the cursor before it chooses each group's
+     * row would let it choose a row it does not return. So each batch reads the
+     * rows of the next of those keys that still match, by their keys alone and
+     * unordered, since each group's row is chosen already, and puts them back
+     * in the order of those keys. The walk visits the rows the select returned
+     * when it began, less any destroyed or changed so that they no longer match;
+     * a row the select returns only after the walk began is not visited.
+     */
+    private walkRowBatchesFromKeys;
     /**
      * Load each specified association using a single SQL query.
      * See {@link Query.preload} for preloading in separate queries.
@@ -357,7 +465,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *
      *
      * ```ts
-     * const posts = await user.associationQuery('posts').leftJoinPreload('comments', { visibilty: 'public' }, 'replies').all()
+     * const posts = await user.associationQuery('posts').leftJoinPreload('comments', { and: { visibility: 'public' } }, 'replies').all()
      * console.log(posts[0].comments[0].replies[0])
      * // [Reply{id: 1}, Reply{id: 2}]
      * ```
@@ -365,7 +473,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A cloned Query with the joinLoad statement applied
      */
-    leftJoinPreload<Q extends Query<DreamInstance, any>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>, Incompatible extends Q['queryTypeOpts'] extends Readonly<{
+    leftJoinPreload<Q extends Query<DreamInstance, any>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr, LastArg>, Incompatible extends Q['queryTypeOpts'] extends Readonly<{
         allowLeftJoinPreload: false;
     }> ? true : false, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, Incompatible extends true ? [] : [...Arr, LastArg]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = Query<DreamInstance, ExtendQueryType<QueryTypeOpts, Readonly<{
         joinedAssociations: JoinedAssociations;
@@ -379,7 +487,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * See {@link Query.leftJoinPreload} for preloading in a single query.
      *
      * ```ts
-     * const user = await User.query().preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * const user = await User.query().preload('posts', 'comments', { and: { visibility: 'public' } }, 'replies').first()
      * console.log(user.posts[0].comments[0].replies[0])
      * // [Reply{id: 1}, Reply{id: 2}]
      * ```
@@ -450,7 +558,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A cloned Query with the joins clause applied
      */
-    innerJoin<DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    innerJoin<DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = Query<DreamInstance, ExtendQueryType<QueryTypeOpts, Readonly<{
@@ -462,7 +570,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A cloned Query with the joins clause applied
      */
-    leftJoin<DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoin<DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends DreamInstance['table'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = Query<DreamInstance, ExtendQueryType<QueryTypeOpts, Readonly<{
@@ -1007,10 +1115,20 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 3
      * ```
      *
-     * A `limit` or `offset` on the Query cannot compose with the batch windows
-     * — each window replaces the limit with the batch size and the offset with
-     * the running window offset, silently ignoring both — so a limit- or
-     * offset-carrying Query throws at runtime.
+     * `pluckEach` reads the rows {@link Query.findEach} visits, in the same
+     * batches and the same order: ascending primary key, then, for a Query
+     * that joins a HasOne or HasMany association, the joined rows' primary
+     * keys, so each row the join returns is plucked once. Like `findEach`, it
+     * discards the Query's `order`, an association's declared `order` and the
+     * relevance ranking of a similarity condition, and it reads a Query that
+     * keeps one record of each group (one that calls `distinct`, or over an
+     * association that declares `distinct`) from the keys of all of its rows,
+     * read before the first batch.
+     *
+     * A `limit` or `offset` on the Query cannot compose with the batches —
+     * each batch re-applies the Query's conditions, so the limit would be
+     * silently replaced by the batch size and the offset re-applied to every
+     * batch — so a limit- or offset-carrying Query throws at runtime.
      *
      * @param args - a list of column names to pluck, followed by a callback function to call for each set of found fields
      * @returns void
@@ -1077,6 +1195,13 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 2
      * ```
      *
+     * Under a similarity condition (`ops.similarity`, `ops.wordSimilarity`,
+     * `ops.strictWordSimilarity`), pages come best match first: records are
+     * ordered by relevance ahead of the Query's `order` (or, without one, the
+     * descending primary key). For best-match-first pages, use `paginate`
+     * rather than {@link Query.cursorPaginate}, which does not order by
+     * relevance.
+     *
      * @param opts - Pagination options
      * @param opts.page - the page number that you want to fetch results for
      * @param opts.pageSize - the number of results per page (optional)
@@ -1096,9 +1221,47 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
-     * Default order is ascending primary key. If an order has already been
-     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
-     * then the implicit primary key ordering will be omitted.
+     * Pages follow the Query's `order`, preceded by the `order` declared on any
+     * association the Query is built on or joins (so an `associationQuery` of
+     * an ordered association pages in that association's order), with
+     * ascending primary key as the final tiebreaker; with neither, pages run in
+     * ascending primary key order. If those orders already include the primary
+     * key (e.g.: `id: 'asc'`), the implicit primary key ordering is omitted.
+     *
+     * A Query that joins a HasOne or HasMany association (directly, through an
+     * association it joins, or as the association an `associationQuery` goes
+     * through) returns a record once for each row the join matches, as
+     * {@link Query.all} does, and the pages return each of those rows once,
+     * sorting the rows of one record by the joined rows' primary keys after the
+     * primary key. The cursor of such a Query is an opaque string that names
+     * its last row by primary keys, the record's and the joined rows' (readable
+     * by whoever holds it; it is not encrypted), and the next page starts after
+     * that row, or, if the row is gone, after the record's first row. Any other
+     * Query's cursor is its last record's primary key. A record's primary key
+     * is always accepted as a cursor: the next page starts after that record's
+     * first row. A cursor carries no other value its row sorts by: those are
+     * read from the database when the next page is.
+     *
+     * A Query that calls `distinct` on its primary key (as `distinct()` does,
+     * e.g.: `User.innerJoin('posts').distinct()`) returns each record once, as
+     * {@link Query.all} does, and so do its pages, whose cursor is the last
+     * record's primary key. A Query that calls `distinct` on another column has
+     * to be ordered by that column first (e.g.:
+     * `Post.distinct('category').order({ category: 'asc', createdAt: 'desc' })`),
+     * or the database rejects its pages. Its pages return the records
+     * {@link Query.all} returns, the one its order keeps for each value of that
+     * column (the newest post of each category), and its cursor is also the
+     * last record's primary key. Over an association that declares `distinct`
+     * and an `order` led by its distinct column (an `associationQuery` of it, or
+     * a Query that joins it), the pages return the rows {@link Query.all}
+     * returns: the row the association's `order` keeps for each value of its
+     * distinct column.
+     *
+     * A similarity condition (`ops.similarity`, `ops.wordSimilarity`,
+     * `ops.strictWordSimilarity`) still decides which records match, but its
+     * relevance ranking does not order the pages: a cursor can only resume from
+     * values it compares, and the rank is not one of them. For best-match-first
+     * pages, use {@link Query.paginate}.
      *
      * ```ts
      * // First page (using undefined to start from beginning)
@@ -1131,9 +1294,48 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
-     * Default order is descending primary key. If an order has already been
-     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
-     * then the implicit primary key ordering will be omitted.
+     * Pages follow the Query's `order`, preceded by the `order` declared on any
+     * association the Query is built on or joins (so an `associationQuery` of
+     * an ordered association pages in that association's order), with
+     * descending primary key as the final tiebreaker; with neither, pages run
+     * in descending primary key order. If those orders already include the
+     * primary key (e.g.: `id: 'asc'`), the implicit primary key ordering is
+     * omitted.
+     *
+     * A Query that joins a HasOne or HasMany association (directly, through an
+     * association it joins, or as the association an `associationQuery` goes
+     * through) returns a record once for each row the join matches, as
+     * {@link Query.all} does, and the pages return each of those rows once,
+     * sorting the rows of one record by the joined rows' primary keys after the
+     * primary key. The cursor of such a Query is an opaque string that names
+     * its last row by primary keys, the record's and the joined rows' (readable
+     * by whoever holds it; it is not encrypted), and the next page starts after
+     * that row, or, if the row is gone, after the record's first row. Any other
+     * Query's cursor is its last record's primary key. A record's primary key
+     * is always accepted as a cursor: the next page starts after that record's
+     * first row. A cursor carries no other value its row sorts by: those are
+     * read from the database when the next page is.
+     *
+     * A Query that calls `distinct` on its primary key (as `distinct()` does,
+     * e.g.: `User.innerJoin('posts').distinct()`) returns each record once, as
+     * {@link Query.all} does, and so do its pages, whose cursor is the last
+     * record's primary key. A Query that calls `distinct` on another column has
+     * to be ordered by that column first (e.g.:
+     * `Post.distinct('category').order({ category: 'asc', createdAt: 'desc' })`),
+     * or the database rejects its pages. Its pages return the records
+     * {@link Query.all} returns, the one its order keeps for each value of that
+     * column (the newest post of each category), and its cursor is also the
+     * last record's primary key. Over an association that declares `distinct`
+     * and an `order` led by its distinct column (an `associationQuery` of it, or
+     * a Query that joins it), the pages return the rows {@link Query.all}
+     * returns: the row the association's `order` keeps for each value of its
+     * distinct column.
+     *
+     * A similarity condition (`ops.similarity`, `ops.wordSimilarity`,
+     * `ops.strictWordSimilarity`) still decides which records match, but its
+     * relevance ranking does not order the pages: a cursor can only resume from
+     * values it compares, and the rank is not one of them. For best-match-first
+     * pages, use {@link Query.paginate}.
      *
      * ```ts
      * // First page (using undefined to start from beginning)
@@ -1160,6 +1362,21 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     cursorPaginate<Q extends Query<DreamInstance, any>, Incompatible extends Q['queryTypeOpts'] extends Readonly<{
         allowPaginate: false;
     }> ? true : false>(this: Q, opts: Incompatible extends true ? 'scrollPaginate is incompatible with limit, offset, and leftJoinPreload'[] : CursorPaginatedDreamQueryOptions): Promise<CursorPaginatedDreamQueryResult<DreamInstance>>;
+    /**
+     * @internal
+     *
+     * The values the row a cursor names sorts by now, in the order of
+     * `orderStatements`, or undefined when no such row is found.
+     *
+     * Unless the primary key is the only order statement, the values are read
+     * from the database, a soft-deleted record included, so that a page can
+     * follow a record removed since the cursor was issued. A cursor that names its row by keys this Query's rows carry is
+     * resumed from that row. Any other cursor (a primary key, as every cursor
+     * issued before 2.36.0 is, or a cursor from a Query that joins other
+     * associations), and a cursor whose row is gone, is resumed from the first
+     * row of the record whose primary key it is or carries.
+     */
+    private cursorBoundaryValues;
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *
@@ -1700,12 +1917,32 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *   record (`reload`, `associationQuery`, ...) likewise run on a separate
      *   connection and snapshot. Derive the attributes and return them; Dream
      *   performs the write inside the batch's transaction.
-     * - **`lock: false` can throw mid-run when racing a deleter.** On the
-     *   unlocked paths, a matched record that a concurrent transaction destroys
-     *   between a batch's read and that record's write aborts the run with an
-     *   error: earlier batches stay committed, and no count is returned. Use
-     *   `lock: true` when deleters may race the update — claimed rows are held
-     *   under their locks until written.
+     * - **Without `lock: true`, a record is not re-checked before it is
+     *   written.** The unlocked per-record paths — an attributes object without
+     *   `lock: true` or `skipHooks: true`, and a callback under `lock: false` —
+     *   read a batch, then write each record by its primary key alone, with no
+     *   compare-and-set. What a concurrent delete between that read and a
+     *   record's write does depends on what the delete leaves behind. A soft
+     *   delete (`destroy()` on a `@SoftDelete` model, which generated models are
+     *   by default) leaves the row in place, so the write lands on the
+     *   soft-deleted record: its update hooks run, it is counted, and its
+     *   `deletedAt` stays set. A hard delete (`reallyDestroy()`, a Query's
+     *   `delete()`, or `destroy()` on a model without `@SoftDelete`) removes the
+     *   row, so that record's write throws `CannotSaveMissingDream` — after its
+     *   `beforeUpdate` and `beforeSave` hooks have run — and the run rejects
+     *   without returning a count. Every record written before it, in its own
+     *   batch as well as earlier ones, stays committed, unless the Query carries
+     *   `.txn(txn)`, which puts those writes in the caller's transaction. (A
+     *   record whose write turns out to be a no-op emits no SQL, so it does not
+     *   throw even if its row is gone, and it is counted.) The single-statement
+     *   `skipHooks` attributes form is one `UPDATE ... WHERE` that carries the
+     *   Query's default scopes, so it never writes a soft-deleted record and
+     *   cannot fail part-way through. Use `lock: true` when deleters may race
+     *   the update: its locked re-read re-applies the Query's conditions and
+     *   default scopes, so a soft- or hard-deleted record drops out of the run,
+     *   neither written nor counted. (A Query that removes the
+     *   `dream:SoftDelete` default scope reads and writes soft-deleted records
+     *   on every path.)
      * - **A `limit` or `offset` on the Query is incompatible with `update` on
      *   every path.** The batched paths re-apply the Query's conditions to each
      *   batch window, where a limit or offset would skip or truncate rows
@@ -1753,6 +1990,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @throws MissingRequiredLockOptionForUpdateCallback if a callback is passed without an options object carrying a boolean `lock`
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      * @throws CannotSetEncryptedColumnInQueryUpdate if the single-statement `skipHooks` form's attributes name an `@Encrypted` backing column with anything other than `null`
+     * @throws CannotSaveMissingDream if, on an unlocked per-record path, a record's row is hard-deleted between its batch's read and a write that is not a no-op
      */
     update(cb: (record: DreamInstance) => UpdateableProperties<DreamInstance> | undefined | Promise<UpdateableProperties<DreamInstance> | undefined>, options: {
         lock: boolean;
@@ -1830,4 +2068,5 @@ export interface QueryOpts<DreamInstance extends Dream, ColumnType extends Dream
     transaction?: DreamTransaction<Dream> | null | undefined;
     connection?: DbConnectionType | undefined;
     shouldReallyDestroy?: boolean | undefined;
+    bypassImplicitOrder?: boolean | undefined;
 }

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -2,7 +2,7 @@ import { CompiledQuery, DeleteQueryBuilder, SelectQueryBuilder, UpdateQueryBuild
 import type { DreamDbConfig } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
-import { AssociationStatement } from '../../types/associations/shared.js';
+import { AssociationStatement, OrderQueryStatement } from '../../types/associations/shared.js';
 import { DbConnectionType, LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 import { DreamColumnNames, DreamConstructorType, DreamTableSchema } from '../../types/dream.js';
 import { PreloadedDreamsAndWhatTheyPointTo, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../../types/query.js';
@@ -435,6 +435,68 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns An array of plucked values
      */
     pluck(...fields: DreamColumnNames<DreamInstance>[]): Promise<any[]>;
+    /**
+     * @internal
+     *
+     * The order statements that the declared `order` of the associations the
+     * Query is built on or joins contributes to its ORDER BY, in the order they
+     * sort, each column namespaced by the alias it is read from. Cursor
+     * pagination folds these into its cursor.
+     *
+     * @returns An array of namespaced order statements
+     */
+    associationOrderStatements(): OrderQueryStatement<string>[];
+    /**
+     * @internal
+     *
+     * The primary key of each table the Query reaches through a HasOne or
+     * HasMany association (one it joins, one an association it joins goes
+     * through, or one its association query is built on), namespaced by the
+     * alias it is read from, in join order. Such a join can return a row of the
+     * Query's table once for each row it matches, and these keys, with the
+     * Query's own primary key, tell those rows apart. Cursor pagination pages by
+     * them after the Query's own primary key.
+     *
+     * @returns An array of namespaced primary key columns
+     */
+    joinedRowKeyColumns(): string[];
+    /**
+     * @internal
+     *
+     * A page of a select that keeps one row of each group (DISTINCT ON, as a
+     * Query that calls `distinct`, or an association that declares `distinct`,
+     * produces), or null for any other select, whose pages cursor pagination
+     * reads as it reads any select's.
+     *
+     * The page is the values of the Query's order statement columns for each
+     * row the select returns that matches any of `rowsAfter` (every row when it
+     * is null), sorted by the Query's order statements and limited by its
+     * limit. The select chooses each group's row before `rowsAfter` narrows the
+     * rows, so that the page holds only rows the select returns.
+     *
+     * A driver whose selects never keep one row of each group returns null.
+     *
+     * @param rowsAfter - where statements, any of which a row of the page matches
+     * @returns The page's rows, each an array of its order statement columns' values, or null
+     */
+    pluckDistinctOnPage(rowsAfter: Record<string, unknown>[] | null): Promise<unknown[][] | null>;
+    /**
+     * @internal
+     *
+     * For a select that keeps one row of each group (DISTINCT ON, as a Query
+     * that calls `distinct`, or an association that declares `distinct`,
+     * produces), the values of `rowKeyColumns` for every row it returns, sorted
+     * by those columns, ascending; null for any other select. `findEach` and
+     * `pluckEach` read a select that keeps one row of each group from these
+     * keys rather than by a cursor, which would narrow the select before it
+     * chooses each group's row.
+     *
+     * A driver whose selects never keep one row of each group returns null.
+     *
+     * @param rowKeyColumns - the namespaced columns that tell the select's rows apart
+     * @returns The rows' values of `rowKeyColumns`, or null
+     */
+    pluckDistinctOnRowKeys(rowKeyColumns: string[]): Promise<unknown[][] | null>;
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used
      * in a sub Query

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -4,7 +4,7 @@ import { DialectProviderCb } from '../../db/DreamDbConnection.js';
 import { DreamDbConfig } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/ASTBuilder.js';
-import { AssociationStatement } from '../../types/associations/shared.js';
+import { AssociationStatement, OrderQueryStatement } from '../../types/associations/shared.js';
 import { DbConnectionType, LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 import { DreamColumnNames, DreamTableSchema, OrderDir, SqlCommandType } from '../../types/dream.js';
 import { PreloadedDreamsAndWhatTheyPointTo, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../../types/query.js';
@@ -12,6 +12,21 @@ import DreamTransaction from '../DreamTransaction.js';
 import Query from '../Query.js';
 import QueryDriverBase from './Base.js';
 export default class KyselyQueryDriver<DreamInstance extends Dream> extends QueryDriverBase<DreamInstance> {
+    /**
+     * @internal
+     *
+     * While `associationOrderStatements` builds a select, the order statements
+     * that association joins add to it, in the order they are added.
+     */
+    private associationOrderCollector;
+    /**
+     * @internal
+     *
+     * While `joinedRowKeyColumns` builds a select, the namespaced primary keys of
+     * the tables that HasOne and HasMany joins add to it, in the order they are
+     * added.
+     */
+    private joinedRowKeyCollector;
     dbFor(sqlCommandType: SqlCommandType): Kysely<DreamInstance['DB']> | KyselyTransaction<DreamInstance['DB']>;
     static dbFor<I extends Dream>(connectionName: string, dbConnectionType: DbConnectionType, dreamTransaction?: DreamTransaction<I> | null): Kysely<I['DB']> | KyselyTransaction<I['DB']>;
     static dialectProvider(connectionName: string, dbConnectionType: DbConnectionType): DialectProviderCb;
@@ -400,6 +415,75 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     }>;
     private buildDelete;
     private buildSelect;
+    /**
+     * @internal
+     *
+     * The select's source, joins, conditions, DISTINCT ON and similarity
+     * ranking, before the Query's own order statements, limit, offset and
+     * selection are applied, together with the connection the select runs on.
+     */
+    private buildSelectCore;
+    /**
+     * @internal
+     *
+     * The order statements that the declared `order` of the associations the
+     * Query is built on or joins contributes to its ORDER BY, in the order they
+     * sort, each column namespaced by the alias it is read from. They are read
+     * off the same join code that emits them, by building the select.
+     *
+     * @returns An array of namespaced order statements
+     */
+    associationOrderStatements(): OrderQueryStatement<string>[];
+    /**
+     * @internal
+     *
+     * The primary key of each table the Query reaches through a HasOne or
+     * HasMany association (one it joins, one an association it joins goes
+     * through, or one its association query is built on), namespaced by the
+     * alias it is read from, in join order. They are read off the same join code
+     * that emits the joins, by building the select.
+     *
+     * @returns An array of namespaced primary key columns
+     */
+    joinedRowKeyColumns(): string[];
+    /**
+     * @internal
+     *
+     * A page of a select that carries DISTINCT ON (as a Query that calls
+     * `distinct`, or an association that declares `distinct`, produces), or null
+     * for any other select.
+     *
+     * Such a select keeps the row of each group that sorts first in its ORDER
+     * BY, so narrowing it to the rows after a cursor would let it keep a row it
+     * does not return (a group's later row, once the cursor has passed the
+     * group's first). It is read as a derived table instead, and narrowed to
+     * `rowsAfter`, sorted and limited outside it. The Query's order statements
+     * follow the select's own ORDER BY, if it has one, so that the select keeps
+     * the same row of each group every time it runs, and each of their columns
+     * is read out of it under a short alias (as `pluck` reads them), since a
+     * joined table's column cannot be named outside it.
+     *
+     * @param rowsAfter - where statements, any of which a row of the page matches
+     * @returns The page's rows, each an array of its order statement columns' values, or null
+     */
+    pluckDistinctOnPage(rowsAfter: Record<string, unknown>[] | null): Promise<unknown[][] | null>;
+    /**
+     * @internal
+     *
+     * For a select that carries DISTINCT ON (as a Query that calls `distinct`,
+     * or an association that declares `distinct`, produces), the values of
+     * `rowKeyColumns` for every row it returns, sorted by those columns,
+     * ascending; null for any other select.
+     *
+     * The select runs as `all()` runs it, with its own ORDER BY choosing each
+     * group's row, and is read as a derived table, sorted outside it. Each of
+     * `rowKeyColumns` is read out of it under a short alias (as `pluck` reads
+     * them), since a joined table's column cannot be named outside it.
+     *
+     * @param rowKeyColumns - the namespaced columns that tell the select's rows apart
+     * @returns The rows' values of `rowKeyColumns`, or null
+     */
+    pluckDistinctOnRowKeys(rowKeyColumns: string[]): Promise<unknown[][] | null>;
     orderByDirection(direction: OrderDir | null): (obj: OrderByItemBuilder) => OrderByItemBuilder;
     private buildUpdate;
     /**

package/dist/types/src/dream/internal/associations/assertRecognizedAssociationConditionKeys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The keys a condition object on an association accepts, whether it is
+ * passed in a chain (`preload('posts', { and: { ... } })`), returned from a
+ * `preloadFor`/`loadFor` modifier, or passed to `associationQuery`.
+ */
+export declare const ASSOCIATION_CONDITION_KEYS: readonly ["and", "andNot", "andAny"];
+/**
+ * The keys accepted by `destroyAssociation`, `reallyDestroyAssociation`
+ * and `undestroyAssociation`.
+ */
+export declare const DESTROY_ASSOCIATION_OPTION_KEYS: readonly ["and", "andNot", "andAny", "bypassAllDefaultScopes", "defaultScopesToBypass", "cascade", "skipHooks"];
+/**
+ * The keys accepted by `updateAssociation`.
+ */
+export declare const UPDATE_ASSOCIATION_OPTION_KEYS: readonly ["and", "andNot", "andAny", "bypassAllDefaultScopes", "defaultScopesToBypass", "skipHooks"];
+/**
+ * Throws UnrecognizedAssociationConditionKeys when `value` is an object
+ * carrying any own key outside `acceptedKeys`, including a key whose value
+ * is `undefined`. Dream reads only the accepted keys, so an unrecognized key
+ * would otherwise be silently ignored (and, for the destroy family, act on
+ * every associated row instead of the ones the caller meant to select).
+ * Non-object values (`undefined`, `null`) pass through untouched.
+ *
+ * @param value - The condition object or options object to check
+ * @param acceptedKeys - The keys `value` may carry
+ * @param associationName - The association the object applies to, for the error message
+ * @param methodName - The public method the options were passed to, or null for a chain condition
+ */
+export default function assertRecognizedAssociationConditionKeys(value: unknown, acceptedKeys: readonly string[], associationName: string | number | symbol, methodName?: string | null): void;