@rvoh/dream 2.35.0 → 2.36.1

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

@@ -21,26 +21,29 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
     /**
      * Loads the requested associations upon execution
      *
+     * **IMPORTANT:** `load().execute()` returns a **new clone** of the model with the
+     * associations loaded. It does NOT modify the original instance.
+     *
      * NOTE: {@link Dream#preload} is often a preferrable way of achieving the
      * same goal.
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
-     *   await user
+     *   const loadedUser = await user
      *    .txn(txn)
-     *    .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     *    .load('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
      *    .load('images')
      *    .execute()
      *
-     *   user.posts[0].comments[0].replies[0]
+     *   loadedUser.posts[0].comments[0].replies[0]
      *   // Reply{}
      *
-     *   user.images[0]
+     *   loadedUser.images[0]
      *   // Image{}
      * })
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LoadBuilder instance
      */
     load<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DreamInstance, DB, Schema, TableName, Arr>]): LoadBuilder<DreamInstance>;
@@ -96,32 +99,34 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * Load each specified association using a single SQL query.
      * See {@link #load} for loading in separate queries.
      *
-     * Note: since leftJoinPreload loads via single query, it has
-     * some downsides and that may be avoided using {@link #load}:
+     * **IMPORTANT:** Like `load()`, `leftJoinLoad().execute()` returns a **new clone** of the
+     * model with associations loaded. It does NOT modify the original instance.
+     *
+     * Note: since leftJoinLoad loads via single query, it has
+     * some downsides that may be avoided using {@link #load}:
      * 1. `limit` and `offset` will be automatically removed
      * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
-     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinLoad('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
-     * Loads the requested associations upon execution
-     *
-     * NOTE: {@link Dream#leftJoinPreload} is often a preferrable way of achieving the
-     * same goal.
      *
      * ```ts
-     * await user.txn(txn)
-     *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
-     *  .leftJoinLoad('images')
-     *  .execute()
+     * await ApplicationModel.transaction(async txn => {
+     *   const loadedUser = await user
+     *    .txn(txn)
+     *    .leftJoinLoad('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
+     *    .leftJoinLoad('images')
+     *    .execute()
      *
-     * user.posts[0].comments[0].replies[0]
-     * // Reply{}
+     *   loadedUser.posts[0].comments[0].replies[0]
+     *   // Reply{}
      *
-     * user.images[0]
-     * // Image{}
+     *   loadedUser.images[0]
+     *   // Image{}
+     * })
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LeftJoinLoadBuilder instance
      */
     leftJoinLoad<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>]): LeftJoinLoadBuilder<DreamInstance>;
@@ -135,10 +140,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the inner join clause applied
      */
-    innerJoin<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    innerJoin<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], 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 = QueryWithJoinedAssociationsType<Query<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -152,10 +157,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the left join clause applied
      */
-    leftJoin<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoin<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], 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 = QueryWithJoinedAssociationsType<Query<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -228,6 +233,12 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To bypass custom-defined setters, use {@link Dream.updateAttributes | updateAttributes} instead.
      *
@@ -252,6 +263,18 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * An encrypted property (e.g. `secret`) is still encrypted. Its
+     * `@Encrypted` backing column (e.g. `encryptedSecret`) accepts only
+     * ciphertext that decrypts with this app's column encryption keys, or
+     * `null`; anything else throws before anything is saved (see
+     * {@link Dream.setAttribute | setAttribute}).
+     *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To update the values without bypassing any custom-defined
      * setters, use {@link Dream.update | update} instead.
@@ -297,6 +320,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * Upon updating an instance, the update timestamp (if defined)
      * will be updated on the model.
      *
+     * A column whose value is `undefined` is skipped, not written: a new
+     * record gets the column's database default, and a persisted record
+     * keeps the value stored for it. Set a column to `null` to clear it.
+     *
      * ```ts
      * const user = User.new({ email: 'how@yadoin' })
      *

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

@@ -23,17 +23,17 @@ export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
     constructor(dream: Dream, dreamTransaction?: (DreamTransaction<any> | null) | undefined);
     passthrough<I extends LeftJoinLoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
     /**
-     * Attaches a load statement to the load builder
+     * Attaches a leftJoinLoad statement to the load builder
      *
      * ```ts
      * const user = await User.firstOrFail()
      * await user
-     *   .load('settings')
-     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .leftJoinLoad('settings')
+     *   .leftJoinLoad('posts', 'comments', 'replies', ['image', 'localizedText'])
      *   .execute()
      * ```
      */
-    leftJoinLoad<I extends LeftJoinLoadBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>>(this: I, ...args: [...Arr, LastArg]): I;
+    leftJoinLoad<I extends LeftJoinLoadBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr, LastArg>>(this: I, ...args: [...Arr, LastArg]): I;
     /**
      * Executes the left-join load query, returning a **clone** of the original model
      * with all requested associations loaded. The original instance is not modified.

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

@@ -84,7 +84,7 @@ export default class LoadBuilder<DreamInstance extends Dream> {
      *   .execute()
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses to load
      * @returns A chainable LoadBuilder instance
      */
     load<I extends LoadBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DreamInstance, DB, Schema, TableName, Arr>]): I;

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