@rvoh/dream 2.35.0 → 2.36.1

package/dist/cjs/src/dream/Query.js

@@ -1,3 +1,4 @@
+import * as crypto from 'crypto';
 import { SOFT_DELETE_SCOPE_NAME } from '../decorators/class/SoftDelete.js';
 import acquireStabilizedSortableBatchLocks from '../decorators/field/sortable/helpers/acquireStabilizedSortableBatchLocks.js';
 import { invalidateSortableRowCache } from '../decorators/field/sortable/helpers/sortableRowCache.js';
@@ -23,7 +24,9 @@ import isObject from '../helpers/isObject.js';
 import namespaceColumn from '../helpers/namespaceColumn.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { toSafeObject } from '../helpers/toSafeObject.js';
+import uniq from '../helpers/uniq.js';
 import ops from '../ops/index.js';
+import assertRecognizedAssociationConditionKeys, { ASSOCIATION_CONDITION_KEYS, } from './internal/associations/assertRecognizedAssociationConditionKeys.js';
 import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
@@ -211,6 +214,16 @@ export default class Query {
      * The distinct column to apply to the Query
      */
     distinctColumn = null;
+    /**
+     * @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.
+     */
+    bypassImplicitOrder = false;
     /**
      * @internal
      *
@@ -276,6 +289,7 @@ export default class Query {
         this.distinctColumn = opts.distinctColumn || null;
         this.connectionOverride = opts.connection;
         this.shouldReallyDestroy = opts.shouldReallyDestroy || false;
+        this.bypassImplicitOrder = opts.bypassImplicitOrder || false;
         this.originalOpts = Object.freeze(opts);
     }
     /**
@@ -340,6 +354,7 @@ export default class Query {
             transaction: opts.transaction || this.dreamTransaction,
             connection: opts.connection || this.connectionOverride,
             shouldReallyDestroy: opts.shouldReallyDestroy !== undefined ? opts.shouldReallyDestroy : this.shouldReallyDestroy,
+            bypassImplicitOrder: opts.bypassImplicitOrder !== undefined ? opts.bypassImplicitOrder : this.bypassImplicitOrder,
         });
     }
     /**
@@ -438,25 +453,49 @@ export default class Query {
      *
      * 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
@@ -465,33 +504,149 @@ export default class Query {
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
     async findEach(cb, { batchSize = Query.BATCH_SIZES.FIND_EACH } = {}) {
+        await this.findEachRow(this.rowKeyColumns(), cb, batchSize);
+    }
+    /**
+     * @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`).
+     */
+    async findEachRecordOnce(cb, { batchSize = Query.BATCH_SIZES.FIND_EACH } = {}) {
+        await this.findEachRow([this.namespacedPrimaryKey], cb, batchSize);
+    }
+    /**
+     * @internal
+     *
+     * Calls `cb` with the record of each row this Query returns, telling its
+     * rows apart by `rowKeyColumns` (see `walkRowBatches`).
+     */
+    async findEachRow(rowKeyColumns, cb, batchSize) {
         if (this.joinLoadActivated)
             throw new LeftJoinPreloadIncompatibleWithFindEach();
-        // a limit or offset cannot compose with the batch windows: the window
-        // queries would re-apply it per batch — the limit silently replaced by
-        // batchSize, the offset skipping rows inside every window
+        // a limit or offset 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 batch
         if (this.limitStatement || this.offsetStatement)
             throw new BatchingIncompatibleWithLimitOrOffset();
-        let records;
-        const query = this.order(null)
-            .order(this.namespacedPrimaryKey)
+        // read as the attribute, since primaryKeyValue() reads a primary key of 0 as null
+        const primaryKey = this.dreamInstance['_primaryKey'];
+        const primaryKeyOf = (record) => record[primaryKey];
+        await this.walkRowBatches(rowKeyColumns, batchSize, async (batchQuery) => {
+            if (rowKeyColumns.length === 1) {
+                const records = await batchQuery.all();
+                return records.map(record => ({ rowKeys: [primaryKeyOf(record)], item: record }));
+            }
+            // a record carries no joined row's keys, so the batch's rows are read
+            // for them first, and each is paired with its record by primary key
+            const rows = (await this.dbDriverInstance(batchQuery).pluck(...rowKeyColumns));
+            const records = new Map((await batchQuery.all()).map(record => [rowKeysIdentity([primaryKeyOf(record)]), record]));
+            return rows.map(rowKeys => ({ rowKeys, item: records.get(rowKeysIdentity([rowKeys[0]])) }));
+        }, cb);
+    }
+    /**
+     * @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`).
+     */
+    rowKeyColumns() {
+        return [this.namespacedPrimaryKey, ...this.rowKeyColumnsOfJoinedRows()];
+    }
+    /**
+     * @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.
+     */
+    rowKeyColumnsOfJoinedRows() {
+        if (this.distinctColumn)
+            return [];
+        return uniq(this.dbDriverInstance().joinedRowKeyColumns()).filter(column => column !== this.namespacedPrimaryKey);
+    }
+    /**
+     * @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`).
+     */
+    async walkRowBatches(rowKeyColumns, batchSize, readBatch, visit) {
+        const distinctOnRowKeys = await this.dbDriverInstance().pluckDistinctOnRowKeys(rowKeyColumns);
+        if (distinctOnRowKeys) {
+            await this.walkRowBatchesFromKeys(distinctOnRowKeys, rowKeyColumns, batchSize, readBatch, visit);
+        }
+        else {
+            await this.walkRowBatchesByCursor(rowKeyColumns, batchSize, readBatch, visit);
+        }
+    }
+    /**
+     * @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`).
+     */
+    async walkRowBatchesByCursor(rowKeyColumns, batchSize, readBatch, visit) {
+        const rowKeyOrder = rowKeyColumns.map(column => ({
+            column,
+            direction: 'asc',
+        }));
+        const orderedQuery = this.clone({ order: null, bypassImplicitOrder: true })
+            .clone({ order: rowKeyOrder })
             .limit(batchSize);
-        // the cursor is compared against a sentinel rather than tested for
-        // truthiness, since a primary key of 0 is a legitimate cursor value that
-        // would otherwise reset the window to the start of the set
-        let lastId = undefined;
+        let lastRowKeys = undefined;
+        let rowCount;
         do {
-            if (lastId === undefined)
-                records = await query.all();
-            else
-                records = await query
-                    .where({ [this.dreamInstance['_primaryKey']]: ops.greaterThan(lastId) })
-                    .all();
-            for (const record of records) {
-                await cb(record);
-            }
-            lastId = records.at(-1)?.primaryKeyValue?.();
-        } while (records.length > 0 && records.length === batchSize);
+            const batchQuery = lastRowKeys
+                ? orderedQuery.whereAny(whereRowsSortingAfter(rowKeyOrder, lastRowKeys, 0))
+                : orderedQuery;
+            const rows = await readBatch(batchQuery);
+            await visitWalkedRows(rows, visit);
+            rowCount = rows.length;
+            lastRowKeys = rows.at(-1)?.rowKeys;
+        } while (rowCount > 0 && rowCount === batchSize);
+    }
+    /**
+     * @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.
+     */
+    async walkRowBatchesFromKeys(distinctOnRowKeys, rowKeyColumns, batchSize, readBatch, visit) {
+        const unorderedQuery = this.clone({ order: null });
+        const rowKeysList = uniq(distinctOnRowKeys, rowKeysIdentity);
+        const readSize = Math.min(batchSize, ROW_KEYS_PER_READ);
+        for (let start = 0; start < rowKeysList.length; start += readSize) {
+            const batchRowKeys = rowKeysList.slice(start, start + readSize);
+            const positions = new Map(batchRowKeys.map((rowKeys, position) => [rowKeysIdentity(rowKeys), position]));
+            const position = (row) => positions.get(rowKeysIdentity(row.rowKeys)) ?? 0;
+            const rows = await readBatch(unorderedQuery.whereAny(whereRowKeysAmong(rowKeyColumns, batchRowKeys)));
+            await visitWalkedRows(rows.sort((a, b) => position(a) - position(b)), visit);
+        }
     }
     /**
      * Load each specified association using a single SQL query.
@@ -518,7 +673,7 @@ export default class Query {
      *
      *
      * ```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}]
      * ```
@@ -540,7 +695,7 @@ export default class Query {
      * 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}]
      * ```
@@ -699,6 +854,9 @@ export default class Query {
             //
         }
         else if (isObject(nextAssociationStatement) && previousAssociationName) {
+            // the node this copies into also holds nested association containers, so an
+            // unrecognized key must be rejected here, while it is still distinguishable
+            assertRecognizedAssociationConditionKeys(nextAssociationStatement, ASSOCIATION_CONDITION_KEYS, previousAssociationName);
             const clonedNextAssociationStatement = cloneDeepSafe(nextAssociationStatement);
             const keys = Object.keys(clonedNextAssociationStatement);
             keys.forEach((key) => {
@@ -1364,34 +1522,25 @@ export default class Query {
             throw new MissingRequiredCallbackFunctionToPluckEach('pluckEach', args);
         if (providedOpts !== undefined && !providedOpts?.batchSize)
             throw new CannotPassAdditionalFieldsToPluckEachAfterCallback('pluckEach', args);
-        // a limit or offset cannot compose with the batch windows: the window
-        // queries would replace the limit with batchSize and the offset with the
-        // running window offset, silently ignoring both
+        // a limit or offset 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 batch
         if (this.limitStatement || this.offsetStatement)
             throw new BatchingIncompatibleWithLimitOrOffset();
         const onlyColumns = args.filter((_, index) => index < providedCbIndex);
         const batchSize = providedOpts?.batchSize || Query.BATCH_SIZES.PLUCK_EACH_THROUGH;
-        let offset = 0;
-        let records;
-        do {
-            const onlyIncludesPrimaryKey = onlyColumns.find(column => column === this.dreamClass.primaryKey || column === this.namespacedPrimaryKey);
-            const columnsIncludingPrimaryKey = onlyIncludesPrimaryKey
-                ? onlyColumns
-                : [this.namespacedPrimaryKey, ...onlyColumns];
-            const query = this.offset(offset)
-                .order(null)
-                .order(this.namespacedPrimaryKey)
-                .limit(batchSize);
-            records = await this.dbDriverInstance(query).pluck(...columnsIncludingPrimaryKey);
-            // In order to batch, we need to order by primary key, so the primary key must be plucked.
-            // If the developer did not include the primary key in the columns to pluck, then we prepended it above
-            // and need to remove it from each group of plucked columns prior to passing them into the callback functions
-            const vals = onlyIncludesPrimaryKey ? records : records.map(valueArr => valueArr.slice(1));
-            for (const val of vals) {
-                await providedCb(...val);
-            }
-            offset += batchSize;
-        } while (records.length > 0 && records.length === batchSize);
+        const rowKeyColumns = this.rowKeyColumns();
+        // the row keys lead, so that a batch's rows can be told apart; a column
+        // asked for that is one of them is read once
+        const pluckedColumns = uniq([...rowKeyColumns, ...onlyColumns], column => this.namespaceColumn(column));
+        const valueIndexes = onlyColumns.map(column => pluckedColumns.findIndex(plucked => this.namespaceColumn(plucked) === this.namespaceColumn(column)));
+        await this.walkRowBatches(rowKeyColumns, batchSize, async (batchQuery) => {
+            const rows = (await this.dbDriverInstance(batchQuery).pluck(...pluckedColumns));
+            return rows.map(row => ({
+                rowKeys: row.slice(0, rowKeyColumns.length),
+                item: valueIndexes.map(index => row[index]),
+            }));
+        }, values => providedCb(...values));
     }
     /**
      * Retrieves an array containing all records matching the Query.
@@ -1464,6 +1613,13 @@ export default class Query {
      * // 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)
@@ -1506,9 +1662,47 @@ export default class Query {
      * 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)
@@ -1546,9 +1740,48 @@ export default class Query {
      * 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)
@@ -1583,107 +1816,123 @@ export default class Query {
             throw new CannotPaginateWithOffset();
         if (this.joinLoadActivated)
             throw new CannotPaginateWithLeftJoinPreload();
-        const orderIncludesPrimaryKey = this.orderStatements.some(orderStatement => orderStatement.column === this.dreamClass.primaryKey ||
-            orderStatement.column === this.namespacedPrimaryKey);
-        let query = orderIncludesPrimaryKey
-            ? this
-            : this.order({ [this.namespacedPrimaryKey]: 'desc' });
+        // An association's declared `order` sorts ahead of the Query's own order
+        // statements, so the cursor takes both, in that order, as the statements it
+        // pages by. The query then orders by those statements alone: anything else
+        // the driver would sort by (a similarity condition's rank) is not something
+        // the cursor compares, and would strand records between pages. A column
+        // listed twice sorts only by its first appearance, so only that one is
+        // kept; a later duplicate would contradict it in the cursor's comparison.
+        const cursorOrderStatements = uniq([...this.dbDriverInstance().associationOrderStatements(), ...this.orderStatements], orderStatement => this.namespaceColumn(orderStatement.column));
+        const primaryKeyStatement = cursorOrderStatements.find(orderStatement => orderStatement.column === this.dreamClass.primaryKey ||
+            orderStatement.column === this.namespacedPrimaryKey) ?? { column: this.namespacedPrimaryKey, direction: 'desc' };
+        // The primary keys of the rows a HasOne or HasMany join adds, which tell
+        // apart the rows it returns a record in, follow the Query's own primary key
+        // as the last statements the cursor pages by, those not already ordered
+        // by, so that the rows a record is returned for sort the same way on every
+        // page.
+        const joinedRowKeyColumns = this.rowKeyColumnsOfJoinedRows();
+        const orderedColumns = new Set([...cursorOrderStatements, primaryKeyStatement].map(orderStatement => this.namespaceColumn(orderStatement.column)));
+        const orderStatements = [
+            ...cursorOrderStatements,
+            ...(cursorOrderStatements.includes(primaryKeyStatement) ? [] : [primaryKeyStatement]),
+            ...joinedRowKeyColumns
+                .filter(column => !orderedColumns.has(column))
+                .map(column => ({ column, direction: primaryKeyStatement.direction })),
+        ];
+        const primaryKeyIndex = orderStatements.indexOf(primaryKeyStatement);
+        const rowKeyIndexes = [
+            primaryKeyIndex,
+            ...joinedRowKeyColumns.map(column => orderStatements.findIndex(orderStatement => this.namespaceColumn(orderStatement.column) === column)),
+        ];
+        const rowKeyColumns = rowKeyIndexes.map(index => orderStatements[index].column);
+        const orderedQuery = this.clone({ order: null, bypassImplicitOrder: true }).clone({
+            order: orderStatements,
+        });
+        const pageQuery = orderedQuery.limit(pageSize);
+        let rowsSortingAfter = null;
         if (options.cursor) {
-            const orderStatements = query.orderStatements;
-            if (orderStatements.length === 1) {
-                /**
-                 * Since we add a primary key above if it wasn't already included, we know
-                 * that if there is only one order statement, then it must be ordering on
-                 * the primary key
-                 */
-                const orderStatement = orderStatements[0];
-                switch (orderStatement.direction) {
-                    case 'asc':
-                        query = query.where({
-                            [orderStatement.column]: ops.greaterThan(options.cursor),
-                        });
-                        break;
-                    case 'desc':
-                        query = query.where({
-                            [orderStatement.column]: ops.lessThan(options.cursor),
-                        });
-                        break;
-                }
-            }
-            else {
-                const endOfPreviousPageComparisonValues = (await query
-                    .removeDefaultScopeExceptOnAssociations(SOFT_DELETE_SCOPE_NAME)
-                    .where({ [this.namespacedPrimaryKey]: options.cursor })
-                    .limit(1)
-                    .order(null)
-                    .pluck(...orderStatements.map(orderStatement => orderStatement.column)))[0];
-                if (endOfPreviousPageComparisonValues) {
-                    const whereAnyMaybeEqualArray = [];
-                    for (let index = 0; index < endOfPreviousPageComparisonValues.length; index++) {
-                        /**
-                         * This nested loop enables us to give priority to the left-most order clause,
-                         * then the left-most and next left-most, etc., replicating what ordering on
-                         * multiple clauses does:
-                         *
-                         *  const results = await Pet.query()
-                         *    .leftJoin('user')
-                         *    // The primary key is implicitly added if not explicitly present, so these two
-                         *    // order clauses appear in the query with an additional primary key clause.
-                         *    // This supports pagination when the earlier order clauses match multiple records.
-                         *    .order({ 'pets.name': 'asc', 'user.id': 'asc' })
-                         *    .cursorPaginate({ pageSize: 2, cursor: undefined })
-                         *
-                         * Results in:
-                         *
-                         * SELECT
-                         * 	"pets".*
-                         * FROM
-                         * 	"pets"
-                         * 	LEFT JOIN "users" AS "user" ON "pets"."user_id" = "user"."id"
-                         * 		AND "user"."deleted_at" IS NULL
-                         * WHERE ("pets"."deleted_at" IS NULL
-                         * 	AND (
-                         *    "pets"."name" > $1
-                         * 		OR (
-                         *    "pets"."name" = $2 AND "user"."id" > $3
-                         * 		) OR (
-                         *    "pets"."name" = $4 AND "user"."id" = $5 AND "pets"."id" < $6
-                         *   )))
-                         * ORDER BY
-                         * 	"pets"."name" ASC nulls FIRST,
-                         * 	"user"."id" ASC nulls FIRST,
-                         * 	"pets"."id" DESC nulls LAST
-                         * LIMIT $7
-                         */
-                        const whereAnyMaybeEqual = {};
-                        whereAnyMaybeEqualArray.push(whereAnyMaybeEqual);
-                        for (let nestedIndex = 0; nestedIndex <= index; nestedIndex++) {
-                            const valueToCompare = endOfPreviousPageComparisonValues[nestedIndex];
-                            const orderStatement = orderStatements[nestedIndex];
-                            if (nestedIndex < index) {
-                                whereAnyMaybeEqual[orderStatement.column] = valueToCompare;
-                            }
-                            else if (nestedIndex === index) {
-                                switch (orderStatement.direction) {
-                                    case 'asc':
-                                        whereAnyMaybeEqual[orderStatement.column] = ops.greaterThan(valueToCompare);
-                                        break;
-                                    case 'desc':
-                                        whereAnyMaybeEqual[orderStatement.column] = ops.lessThan(valueToCompare);
-                                        break;
-                                }
-                            }
-                        }
-                    }
-                    query = query.whereAny(whereAnyMaybeEqualArray);
-                }
+            const boundaryValues = await this.cursorBoundaryValues(orderedQuery, {
+                cursor: options.cursor,
+                orderStatements,
+                rowKeyColumns,
+            });
+            if (boundaryValues) {
+                rowsSortingAfter = whereRowsSortingAfter(orderStatements, boundaryValues, primaryKeyIndex);
             }
         }
-        const results = await query.limit(pageSize).all();
-        return {
-            cursor: (results.length === pageSize && results.at(-1)?.primaryKeyValue().toString()) || null,
-            results,
-        };
+        // A select that keeps one row of each group (as a Query that calls
+        // `distinct`, or an association that declares `distinct`, produces)
+        // chooses that row from the rows it reads, so it is not narrowed to the
+        // rows sorting after the cursor, which would let it choose a row it does
+        // not return: the driver reads its page, choosing each group's row before
+        // narrowing. Any other select is narrowed by its own conditions.
+        const distinctOnPageRows = await pageQuery.dbDriverInstance().pluckDistinctOnPage(rowsSortingAfter);
+        const query = rowsSortingAfter ? pageQuery.whereAny(rowsSortingAfter) : pageQuery;
+        // Otherwise, without a HasOne or HasMany join, a record is returned once,
+        // so its primary key identifies the row the next page starts after.
+        if (!distinctOnPageRows && !joinedRowKeyColumns.length) {
+            const results = await query.all();
+            return {
+                cursor: (results.length === pageSize && results.at(-1)?.primaryKeyValue().toString()) || null,
+                results,
+            };
+        }
+        // The page's rows are read first, and the records then by the keys of
+        // those rows, so the records returned are the rows the page holds. A HasOne
+        // or HasMany join can return a record for several rows, so the cursor of
+        // such a Query names the last row by its keys: the record's primary key and
+        // the joined rows' primary keys. Any other Query's cursor is the last row's
+        // primary key.
+        const pageRows = distinctOnPageRows ??
+            (await query.pluck(...orderStatements.map(orderStatement => orderStatement.column)));
+        if (!pageRows.length)
+            return { cursor: null, results: [] };
+        const pageRowKeys = pageRows.map(row => rowKeyIndexes.map(index => row[index]));
+        const results = await orderedQuery.whereAny(whereRowKeysAmong(rowKeyColumns, pageRowKeys)).all();
+        const lastRowKeys = pageRowKeys.at(-1);
+        let cursor = null;
+        if (pageRows.length === pageSize) {
+            cursor = joinedRowKeyColumns.length
+                ? encodeRowKeysCursor({ tableName: this.tableName, rowKeyColumns, rowKeys: lastRowKeys })
+                : String(lastRowKeys[0]);
+        }
+        return { cursor, results };
+    }
+    /**
+     * @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.
+     */
+    async cursorBoundaryValues(orderedQuery, { cursor, orderStatements, rowKeyColumns, }) {
+        const { primaryKey, rowKeys } = decodeCursorRowKeys(cursor, { tableName: this.tableName, rowKeyColumns });
+        // the only order statement is the primary key, so the cursor is the value
+        if (orderStatements.length === 1)
+            return [primaryKey];
+        const boundaryQuery = orderedQuery
+            .removeDefaultScopeExceptOnAssociations(SOFT_DELETE_SCOPE_NAME)
+            .limit(1);
+        const orderColumns = orderStatements.map(orderStatement => orderStatement.column);
+        if (rowKeys) {
+            const [boundaryRow] = (await boundaryQuery
+                .where(Object.fromEntries(rowKeyColumns.map((column, index) => [column, rowKeys[index]])))
+                .pluck(...orderColumns));
+            if (boundaryRow)
+                return boundaryRow;
+        }
+        const [firstRowOfRecord] = (await boundaryQuery
+            .where({ [this.namespacedPrimaryKey]: primaryKey })
+            .pluck(...orderColumns));
+        return firstRowOfRecord;
     }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
@@ -1945,7 +2194,7 @@ export default class Query {
         if (lock) {
             return await this.lockedDestroy(options, resolvedBatchSize);
         }
-        await this.findEach(async (result) => {
+        await this.findEachRecordOnce(async (result) => {
             const subquery = this.dreamTransaction
                 ? result.txn(this.dreamTransaction)
                 : result;
@@ -2067,7 +2316,10 @@ export default class Query {
         if (this.limitStatement || this.offsetStatement)
             throw new BatchingIncompatibleWithLimitOrOffset();
         const primaryKey = this.dreamInstance['_primaryKey'];
-        const orderedQuery = this.order(null)
+        // ordered by primary key alone, so that each window holds the next
+        // batchSize records after the cursor
+        const orderedQuery = this.clone({ bypassImplicitOrder: true })
+            .order(null)
             .order(this.namespacedPrimaryKey)
             .limit(batchSize);
         let counter = 0;
@@ -2204,7 +2456,7 @@ export default class Query {
         if (!this.dreamClass['softDelete'])
             throw new CannotCallUndestroyOnANonSoftDeleteModel(this.dreamClass);
         let counter = 0;
-        await this.removeDefaultScope(SOFT_DELETE_SCOPE_NAME).findEach(async (result) => {
+        await this.removeDefaultScope(SOFT_DELETE_SCOPE_NAME).findEachRecordOnce(async (result) => {
             const subquery = this.dreamTransaction
                 ? result.txn(this.dreamTransaction)
                 : result;
@@ -2286,7 +2538,7 @@ export default class Query {
         if (!cb && skipHooks)
             return await this.updateWithoutCallingModelHooks(attributesOrCb);
         let counter = 0;
-        await this.findEach(async (result) => {
+        await this.findEachRecordOnce(async (result) => {
             // as on the locked path, the callback receives a clone, so only the
             // attributes it returns are written
             const attributes = cb
@@ -2374,3 +2626,126 @@ export default class Query {
         return query;
     }
 }
+/**
+ * Calls `visit` with the item of each of `rows` that has one, in the order of
+ * `rows`, once for each row's keys.
+ */
+async function visitWalkedRows(rows, visit) {
+    const visitedRowKeys = new Set();
+    for (const { rowKeys, item } of rows) {
+        const rowKeysId = rowKeysIdentity(rowKeys);
+        if (item === undefined || visitedRowKeys.has(rowKeysId))
+            continue;
+        visitedRowKeys.add(rowKeysId);
+        await visit(item);
+    }
+}
+/**
+ * The most rows a batch of `walkRowBatchesFromKeys` reads by their keys in one
+ * statement, so that the keys it binds stay well under Postgres's limit of
+ * 65,535 parameters in a statement, alongside those the Query binds.
+ */
+const ROW_KEYS_PER_READ = 1000;
+/**
+ * The where clauses, any one of which matches a row whose values of
+ * `rowKeyColumns` are one of `rowKeysList`.
+ */
+function whereRowKeysAmong(rowKeyColumns, rowKeysList) {
+    if (rowKeyColumns.length === 1)
+        return [{ [rowKeyColumns[0]]: rowKeysList.map(rowKeys => rowKeys[0]) }];
+    return rowKeysList.map(rowKeys => Object.fromEntries(rowKeyColumns.map((column, index) => [column, rowKeys[index]])));
+}
+/**
+ * A string that two rows' keys share only when they are equal, whatever type
+ * the driver returned each key as.
+ */
+function rowKeysIdentity(rowKeys) {
+    return JSON.stringify(rowKeys.map(value => value === null || value === undefined ? null : String(value)));
+}
+function whereRowsSortingAfter(orderStatements, boundaryValues, primaryKeyIndex) {
+    const whereStatements = [];
+    for (let index = 0; index < orderStatements.length; index++) {
+        const equalityPrefix = {};
+        for (let nestedIndex = 0; nestedIndex < index; nestedIndex++) {
+            equalityPrefix[orderStatements[nestedIndex].column] = boundaryValues[nestedIndex];
+        }
+        const valueToCompare = boundaryValues[index];
+        const orderStatement = orderStatements[index];
+        const comparisonsSortingAfter = [];
+        switch (orderStatement.direction) {
+            case 'asc':
+                comparisonsSortingAfter.push(valueToCompare === null ? ops.not.equal(null) : ops.greaterThan(valueToCompare));
+                break;
+            case 'desc':
+                if (valueToCompare !== null)
+                    comparisonsSortingAfter.push(ops.lessThan(valueToCompare));
+                if (valueToCompare !== null && index !== primaryKeyIndex)
+                    comparisonsSortingAfter.push(null);
+                break;
+        }
+        for (const comparison of comparisonsSortingAfter) {
+            whereStatements.push({ ...equalityPrefix, [orderStatement.column]: comparison });
+        }
+    }
+    return whereStatements;
+}
+/**
+ * Prefix of a cursor that names its row by keys: the record's primary key,
+ * then the primary key of each row a HasOne or HasMany join matched to it. A
+ * primary key (an integer or a UUID) never contains a `.`, so a cursor that is
+ * a primary key is never read as one of these.
+ */
+const ROW_KEYS_CURSOR_PREFIX = 'v2.';
+/**
+ * A short digest of the table and columns a cursor's keys were read from, so
+ * that a cursor passed to a Query that reads other columns resumes from its
+ * primary key rather than matching its keys against the wrong columns.
+ */
+function cursorSignature(tableAndColumns) {
+    return crypto.createHash('sha256').update(JSON.stringify(tableAndColumns)).digest('base64url').slice(0, 12);
+}
+function encodeRowKeysCursor({ tableName, rowKeyColumns, rowKeys, }) {
+    const payload = JSON.stringify({ s: cursorSignature([tableName, rowKeyColumns]), k: rowKeys });
+    return ROW_KEYS_CURSOR_PREFIX + Buffer.from(payload, 'utf8').toString('base64url');
+}
+/**
+ * The primary key a cursor is or carries, and the keys of the row it names
+ * when it names one of the Query's rows by `rowKeyColumns` (otherwise null).
+ * A cursor that cannot be read as one Dream issues is taken to be a primary
+ * key.
+ */
+function decodeCursorRowKeys(cursor, { tableName, rowKeyColumns }) {
+    const rowKeysPayload = cursorPayload(cursor, ROW_KEYS_CURSOR_PREFIX);
+    const keys = rowKeysPayload?.k;
+    if (rowKeysPayload && Array.isArray(keys) && isCursorPrimaryKey(keys[0])) {
+        const namesQueryRow = rowKeysPayload.s === cursorSignature([tableName, rowKeyColumns]) &&
+            keys.length === rowKeyColumns.length &&
+            keys.every(isCursorRowKey);
+        return { primaryKey: keys[0], rowKeys: namesQueryRow ? keys : null };
+    }
+    return { primaryKey: cursor, rowKeys: null };
+}
+/**
+ * The object a cursor that starts with `prefix` encodes, or null when the
+ * cursor does not start with it or cannot be read.
+ */
+function cursorPayload(cursor, prefix) {
+    if (!cursor.startsWith(prefix))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(cursor.slice(prefix.length), 'base64url').toString('utf8'));
+        return isObject(payload) ? payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isCursorPrimaryKey(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}
+/**
+ * A joined row's key is NULL in a row a LEFT JOIN matched to no row.
+ */
+function isCursorRowKey(value) {
+    return value === null || isCursorPrimaryKey(value);
+}