@rvoh/dream 2.26.0 → 2.28.0

package/dist/esm/src/decorators/field/sortable/helpers/prepareSortableFieldsForDestroy.js

@@ -0,0 +1,56 @@
+import acquireStabilizedSortableScopeLocks from './acquireStabilizedSortableScopeLocks.js';
+import clearCachedSortableValues from './clearCachedSortableValues.js';
+import { cacheSortableSnapshots, clearSortableSnapshot } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * The sortable preparation phase of a destroy. Called from `destroyDream` after
+ * every user `beforeDestroy` hook has run and before the delete — a phase, not
+ * a hook among them — so the operation's whole advisory key set, across every
+ * sortable field, is taken in one sorted stabilized acquisition, with one
+ * snapshot SELECT covering all fields. Per-field acquisition would take
+ * multi-field keys in declaration order, which deadlocks against the paths
+ * that acquire sorted.
+ *
+ * Pre-delete is the only seat available for the snapshot read: on a hard
+ * destroy the row is gone afterwards, and a soft destroy nulls the position
+ * columns in the same UPDATE as `deletedAt`. The lock is taken around the read
+ * so the snapshot cannot be invalidated between the read and the compaction;
+ * it is transaction-scoped, and `destroyDream` opens a transaction that spans
+ * the delete and the after-destroy hooks, so one acquisition covers both.
+ *
+ * The per-field compactions (`performSortableDestroyWork`) consume the cached
+ * snapshots.
+ *
+ * @returns false when the snapshot read found no row — this destroy has nothing
+ *   to vacate, and compacting from the instance's remembered position would
+ *   shift a scope some other writer has already closed. The delete's own
+ *   affected-row count is the stronger signal (a writer outside the sortable
+ *   path can remove the row after this read), so the caller checks both.
+ */
+export default async function prepareSortableFieldsForDestroy(dream, txn) {
+    const sortableFields = dream.constructor['sortableFields'];
+    if (!sortableFields.length)
+        return true;
+    const { rowExists, snapshots } = await acquireStabilizedSortableScopeLocks(dream, txn, sortableFields);
+    cacheSortableSnapshots(dream, snapshots);
+    return rowExists;
+}
+/**
+ * @internal
+ *
+ * Discards what the preparation phase stashed on the instance. The per-field
+ * compaction clears its own snapshot as it consumes it, so this
+ * exists for the path where that compaction never runs: a destroy that removed
+ * nothing leaves the snapshot behind, and a later save or destroy of the same
+ * instance would compute its shift from a reading of a row this operation
+ * already found gone.
+ */
+export function clearSortableFieldsForDestroy(dream) {
+    const sortableFields = (dream.constructor['sortableFields'] ??
+        []);
+    for (const { positionField } of sortableFields) {
+        clearCachedSortableValues(dream, positionField);
+        clearSortableSnapshot(dream, positionField);
+    }
+}

package/dist/esm/src/decorators/field/sortable/helpers/prepareSortableFieldsForSave.js

@@ -0,0 +1,84 @@
+import positionIsInvalid from './positionIsInvalid.js';
+import sortableCacheValuesName from './sortableCacheValuesName.js';
+/**
+ * @internal
+ *
+ * The sortable preparation phase of a save. Called from `saveDream` after every
+ * consumer before-hook has run — a phase, not a hook among them — so the
+ * decision is made from the final state of the instance: a position or scope
+ * change introduced by a `beforeSave` hook registered after Sortable's gets the
+ * same handling as one made before `save` was called, and a cache is never
+ * carried over from a state an intervening hook has made stale.
+ *
+ * For each sortable field this caches the values the position work needs and
+ * applies the position sentinel, then returns the fields whose position work
+ * this save will perform — the fields that make the save need a transaction of
+ * its own, so that the write and the position write that follows it commit
+ * together under one scope lock.
+ *
+ * - every create on a model with sortable fields performs position work;
+ * - an update performs it only when the save changes the position or one of the
+ *   sortable scope columns.
+ *
+ * A save that skips hooks performs no position work at all, so it needs no
+ * transaction.
+ */
+export default function prepareSortableFieldsForSave(dream, { alreadyPersisted, skipHooks }) {
+    if (skipHooks)
+        return [];
+    const sortableFields = dream.constructor['sortableFields'];
+    if (!sortableFields.length)
+        return [];
+    sortableFields.forEach(config => prepareSortableFieldForSave(dream, config));
+    if (!alreadyPersisted)
+        return [...sortableFields];
+    return sortableFields.filter(config => dream[sortableCacheValuesName(config.positionField)] !== undefined);
+}
+/**
+ * Caches the values one sortable field's position work needs and applies the
+ * position sentinel to the instance, so that the driver write never commits a
+ * caller-supplied position the scope has not made room for.
+ */
+function prepareSortableFieldForSave(dream, { positionField, scope }) {
+    const cachedValuesName = sortableCacheValuesName(positionField);
+    const dreamAsAny = dream;
+    const changingScope = dream.isPersisted &&
+        scope.filter(scopeField => {
+            const association = dream['getAssociationMetadata'](scopeField);
+            return association
+                ? dream.willSaveChangeToAttribute(association.foreignKey())
+                : dream.willSaveChangeToAttribute(scopeField);
+        }).length > 0;
+    if (dream.willSaveChangeToAttribute(positionField) || changingScope) {
+        const position = dreamAsAny[positionField];
+        // store values to be used by the position work later in the save
+        const values = {
+            wasNewRecord: dream.isNewRecord,
+            changingScope,
+            position: positionIsInvalid(position) ? undefined : position,
+            previousPosition: dream.isPersisted && dream.willSaveChangeToAttribute(positionField)
+                ? dream.changes()[positionField]?.was
+                : changingScope
+                    ? position
+                    : undefined,
+        };
+        dreamAsAny[cachedValuesName] = values;
+    }
+    else {
+        // computed from the final state of the instance, so a cache from an earlier,
+        // now-stale state must not survive this decision
+        dreamAsAny[cachedValuesName] = undefined;
+    }
+    if (dream.isNewRecord || changingScope) {
+        // if the dream is not saved, or is being moved between scopes, set position to 0
+        // to prevent collisions with existing position values.
+        // the real position is computed and written under the scope lock later in the save.
+        dreamAsAny[positionField] = 0;
+    }
+    else if (dream.willSaveChangeToAttribute(positionField)) {
+        // if the dream is saved and the position is being changed, set the position field to
+        // undefined, which will cause the update cycle to ignore the position field. The
+        // position work later in the save writes the real value.
+        dreamAsAny[positionField] = undefined;
+    }
+}

package/dist/esm/src/decorators/field/sortable/helpers/resortAllRecords.js

@@ -1,35 +1,192 @@
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import isSortedCorrectly from './isSortedCorrectly.js';
-import scopeArray from './scopeArray.js';
+import { sql } from 'kysely';
+import Query from '../../../../dream/Query.js';
+import SortableRequiresAdvisoryTransactionLocks from '../../../../errors/SortableRequiresAdvisoryTransactionLocks.js';
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import sortableScopeColumns from './sortableScopeColumns.js';
+import sortableScopeLockKey from './sortableScopeLockKey.js';
+/**
+ * The alias and column names the renumbering UPDATE joins its `row_number()`
+ * subquery on. They are namespaced so that no real column of the table being
+ * resorted can collide with them.
+ */
+const RENUMBER_ALIAS = 'dream_resort_renumber';
+const RENUMBER_PRIMARY_KEY = 'dream_resort_primary_key';
+const RENUMBER_POSITION = 'dream_resort_position';
+/**
+ * The aliases the one-row summary of a sort scope's positions comes back under.
+ * They are namespaced for the same reason the renumbering aliases are, and are
+ * lowercase without underscores so that Kysely's CamelCasePlugin passes them
+ * through untouched and each value can be read straight off the result row (the
+ * same alias strategy `pluck` and the grouped aggregates use).
+ */
+const SUMMARY_ROW_COUNT = 'dreamresortrowcount';
+const SUMMARY_DISTINCT_POSITIONS = 'dreamresortdistinctpositions';
+const SUMMARY_MIN_POSITION = 'dreamresortminposition';
+const SUMMARY_MAX_POSITION = 'dreamresortmaxposition';
+/**
+ * @internal
+ *
+ * Renumbers every sort scope of a model so that each one runs 1..n with no gaps.
+ *
+ * Four things make this safe to run against a live table:
+ *
+ * - **A driver that cannot take the scope lock fails before the table is
+ *   read**, rather than succeeding for whichever scopes happen to be contiguous
+ *   and throwing on the first one that is not.
+ * - **The STI scope is stripped**, exactly as every sortable hook strips it. An
+ *   STI hierarchy shares one position space, so renumbering one child's rows in
+ *   isolation would hand them positions its siblings already hold.
+ * - **Groups are identified structurally**, by the scope columns' `[column,
+ *   value]` tuple rather than by joining the values into one string. Joining
+ *   merges scopes whose values differ only in where a delimiter falls, and
+ *   merges a null member with an empty-string one; a merged group is two
+ *   physical sort scopes renumbered as though they were one, and no single lock
+ *   key covers it.
+ * - **Every discovered scope is renumbered under its own scope lock, from a
+ *   read taken inside that lock.** The unlocked pass below only discovers
+ *   *which* sort scopes exist; it decides nothing about their contents, because
+ *   a concurrent create, destroy or raw update between the two reads is
+ *   precisely the case this exists to repair. Whether a scope needs renumbering
+ *   at all is decided under the lock.
+ *
+ * Each scope's transaction is this function's own: `resort` cannot join a
+ * transaction the caller owns, and must not be called from inside one. It would
+ * wait on a connection of its own for a scope lock the caller's transaction may
+ * already hold — a wait no deadlock detector can see, which ends in
+ * `SortableScopeLockWaitTimedOut` rather than in progress.
+ */
 export default async function resortAllRecords(dreamClass, positionField, scope) {
-    const dreams = await dreamClass.order({ [positionField]: 'asc' }).all();
-    const hash = {};
-    for (const dream of dreams) {
-        const foreignKeys = foreignKeysForScope(dream, scope);
-        hash[foreignKeys.join(':')] ||= [];
-        hash[foreignKeys.join(':')].push(dream);
-    }
-    for (const dreamArr of Object.values(hash)) {
-        const dreams = dreamArr;
-        if (isSortedCorrectly(dreams, positionField))
-            continue;
+    const queryDriverClass = Query.dbDriverClass(dreamClass.prototype.connectionName || 'default');
+    if (!queryDriverClass.supportsAdvisoryTransactionLocks)
+        throw new SortableRequiresAdvisoryTransactionLocks(queryDriverClass.name);
+    // every scope value, lock key and group identity below is derived from class
+    // level metadata — the table, the connection, the scope members' columns and
+    // their database types — so one bare instance stands in for every row
+    const derivationRecord = dreamClass.new();
+    for (const scopeValues of await discoverSortScopes(dreamClass, derivationRecord, scope)) {
         await dreamClass.transaction(async (txn) => {
-            let counter = 1;
-            for (const dream of dreams) {
-                await dreamClass
-                    .txn(txn)
-                    .where({ [dream['_primaryKey']]: dream.primaryKeyValue() })
-                    .toKysely('update')
-                    .set({
-                    [positionField]: counter++,
-                })
-                    .execute();
-            }
+            await acquireSortableScopeLocks(derivationRecord, txn, [
+                sortableScopeLockKey(derivationRecord, positionField, scopeValues),
+            ]);
+            if (await scopeIsAlreadyOrdered({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn }))
+                return;
+            await renumberScope({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn });
         });
     }
 }
-function foreignKeysForScope(dream, scope) {
-    return scopeArray(scope)
-        .map(singleScope => getColumnForSortableScope(dream, singleScope))
-        .map(fk => dream[fk]);
+/**
+ * Every physical sort scope the table currently holds, as the `[column, value]`
+ * tuples a lock key is derived from.
+ *
+ * One distinct read over the scope columns alone, which both bounds the cost —
+ * a single round trip returning one row per sort scope, however many rows the
+ * table holds — and makes the answer stable: a walk that windows the table can
+ * be shifted past rows by a concurrent delete, and a sort scope whose only rows
+ * fall in that gap would never be renumbered at all. Each discovered scope's
+ * rows are read again under its own lock before anything is written.
+ *
+ * A sortable field with no scope has exactly one sort scope, the whole table,
+ * so its answer needs no read.
+ */
+async function discoverSortScopes(dreamClass, derivationRecord, scope) {
+    const columns = sortableScopeColumns(derivationRecord, scope);
+    if (columns.length === 0)
+        return [[]];
+    const rows = (await stiUnscopedQuery(dreamClass)
+        .toKysely('select')
+        .clearSelect()
+        .distinct()
+        .select(columns)
+        .execute());
+    // the database's `distinct` is by raw value; two raw values the column's type
+    // treats as one (a citext scope column matching case-insensitively) are one
+    // sort scope under one lock key, and canonicalization is what says so
+    const sortScopes = new Map();
+    for (const row of rows) {
+        const scopeValues = columns.map((column) => [column, row[column]]);
+        const identity = scopeIdentity(derivationRecord, scopeValues);
+        if (!sortScopes.has(identity))
+            sortScopes.set(identity, scopeValues);
+    }
+    return [...sortScopes.values()];
+}
+/**
+ * Whether the sort scope already runs 1..n, decided inside the scope's lock by
+ * one aggregate row rather than by shipping every position in the scope to the
+ * client: a sort scope can hold as many rows as the table does, and this runs
+ * with the scope's lock held.
+ *
+ * A scope of `n` rows is already correct exactly when its positions are `n`
+ * distinct non-null values running from 1 to n. `count(distinct position)`
+ * drops both duplicates and nulls, so it agrees with `count(*)` only when every
+ * row holds a position of its own, and `min`/`max` pin that set to 1..n. An
+ * empty scope — one whose last row was destroyed between its discovery and this
+ * lock — has nothing to renumber.
+ */
+async function scopeIsAlreadyOrdered({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn, }) {
+    const summary = (await scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn })
+        .clearSelect()
+        .select([
+        sql `count(*)`.as(SUMMARY_ROW_COUNT),
+        sql `count(distinct ${sql.ref(positionField)})`.as(SUMMARY_DISTINCT_POSITIONS),
+        sql `min(${sql.ref(positionField)})`.as(SUMMARY_MIN_POSITION),
+        sql `max(${sql.ref(positionField)})`.as(SUMMARY_MAX_POSITION),
+    ])
+        .executeTakeFirstOrThrow());
+    // counts come back from some drivers as strings, since a count is a bigint
+    const rowCount = Number(summary[SUMMARY_ROW_COUNT]);
+    if (rowCount === 0)
+        return true;
+    return (Number(summary[SUMMARY_DISTINCT_POSITIONS]) === rowCount &&
+        Number(summary[SUMMARY_MIN_POSITION]) === 1 &&
+        Number(summary[SUMMARY_MAX_POSITION]) === rowCount);
+}
+/**
+ * Renumbers the whole sort scope in one statement, from a `row_number()` taken
+ * over the scope's rows ordered by position, nulls first, ties broken by
+ * primary key. A row already holding the position it is owed is left alone, so
+ * a scope with a single gap in it writes a single row rather than all of them.
+ */
+async function renumberScope({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn, }) {
+    const table = derivationRecord.table;
+    const primaryKey = derivationRecord['_primaryKey'];
+    const renumbered = scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn })
+        .clearSelect()
+        .select([
+        sql.ref(primaryKey).as(RENUMBER_PRIMARY_KEY),
+        sql `row_number() over (order by ${sql.ref(positionField)} asc nulls first, ${sql.ref(primaryKey)} asc)`.as(RENUMBER_POSITION),
+    ]);
+    await stiUnscopedQuery(dreamClass)
+        .txn(txn)
+        .toKysely('update')
+        .from(renumbered.as(RENUMBER_ALIAS))
+        .set({ [positionField]: sql.ref(`${RENUMBER_ALIAS}.${RENUMBER_POSITION}`) })
+        .whereRef(`${table}.${primaryKey}`, '=', `${RENUMBER_ALIAS}.${RENUMBER_PRIMARY_KEY}`)
+        .where(sql.ref(`${table}.${positionField}`), 'is distinct from', sql.ref(`${RENUMBER_ALIAS}.${RENUMBER_POSITION}`))
+        .execute();
+}
+/**
+ * A kysely select over the rows of one physical sort scope, carrying the
+ * model's default scopes (a soft-deleted row is not part of any sort scope) but
+ * not the STI scope, and matching a null scope member with `is null`.
+ */
+function scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn, }) {
+    const values = new Map(scopeValues);
+    return filterQueryToScopeValues(derivationRecord, stiUnscopedQuery(dreamClass).txn(txn).toKysely('select'), column => values.get(column) ?? null, scope);
+}
+function stiUnscopedQuery(dreamClass) {
+    return dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
+}
+/**
+ * A collision-free identity for a physical sort scope. Values are canonicalized
+ * against the column's database type by the same function the advisory lock key
+ * uses (null distinct from every string, a pending value agreeing with its
+ * hydrated counterpart) and encoded structurally, so two distinct tuples can
+ * never share an identity and a scope can never disagree with its own lock.
+ */
+function scopeIdentity(derivationRecord, scopeValues) {
+    return JSON.stringify(scopeValues.map(([column, value]) => [column, canonicalScopeValue(derivationRecord, column, value)]));
 }

package/dist/esm/src/decorators/field/sortable/helpers/setPosition.js

@@ -1,62 +1,116 @@
-import DreamApp from '../../../../dream-app/index.js';
-import PostgresQueryDriver from '../../../../dream/QueryDriver/Postgres.js';
 import range from '../../../../helpers/range.js';
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import scopeArray from './scopeArray.js';
+import ops from '../../../../ops/index.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import sortableScopeColumns from './sortableScopeColumns.js';
+import { sortableScopeLockKeyForCurrentScope } from './sortableScopeLockKeys.js';
+import { invalidateSortableRowCache } from './sortableRowCache.js';
+import { snapshotScopeValue } from './sortableSnapshot.js';
 import validPosition from './validPosition.js';
 export default async function setPosition(obj) {
     const { dream, txn } = obj;
-    if (txn) {
-        await applyUpdates({ ...obj, txn });
-        await dream.txn(txn).reload();
-    }
-    else {
-        await dream.constructor.transaction(async (txn) => {
-            await applyUpdates({ ...obj, txn });
-            await dream.txn(txn).reload();
-        });
-    }
+    await applyUpdates(obj);
+    await dream.txn(txn).reload();
 }
 async function applyUpdates(obj) {
-    const position = await validPosition(obj);
-    await updateConflictingRecords({ ...obj, position });
-    await updatePositionForRecord({ ...obj, position });
+    const { dream, positionField, scope, txn } = obj;
+    // Serialize every writer of this sort scope for the rest of the transaction,
+    // before the first position read. The operation-level phase has already
+    // acquired this key in its one sorted pass over every sortable field's keys
+    // (performSortablePositionWork on create; saveDream, before the driver
+    // write, on update), so this asks for a key the transaction holds and issues
+    // no statement at all.
+    await acquireSortableScopeLocks(dream, txn, [
+        sortableScopeLockKeyForCurrentScope(dream, positionField, scope),
+    ]);
+    // A pending scope change that lands on the scope the row already physically
+    // occupies moves the record between no scopes at all, and the rest of the
+    // write has to see it that way: the scope being vacated *is* the destination,
+    // so one source computes a new position from a max the other is about to
+    // shift out from under it. The record still counts toward the destination's
+    // extent — its row is in the scope, holding the position sentinel in place of
+    // the position the snapshot read — so the position write carries that
+    // position through to the clamp, and a record that was already last in the
+    // scope stays last rather than swapping with the record below it.
+    const write = alreadyInDestinationScope(obj)
+        ? { ...obj, changingScope: false, positionUnderSentinel: obj.previousPosition }
+        : obj;
+    const position = await validPosition(write);
+    await updateConflictingRecords({ ...write, position });
+    await updatePositionForRecord({ ...write, position });
+    // the shift above moved rows this transaction may be holding preflight reads
+    // of — every position a locked batch's later records were read with is now a
+    // position they no longer have
+    invalidateSortableRowCache(txn);
+}
+/**
+ * Whether a save that means to change sort scope is really a move within one
+ * scope: the snapshot read under the lock says the row already sits in the
+ * scope the instance is being written into, so nothing joins the destination
+ * and nothing is left behind.
+ *
+ * Values are compared through `canonicalScopeValue`, the same normalization the
+ * advisory lock key is derived from, so two shapes of one physical value — the
+ * pending `'1.00'` and the hydrated `1` — are one scope here exactly as they
+ * are when the key is taken.
+ *
+ * A row whose snapshot position is null holds no position in that scope, so it
+ * is joining the destination's position space and remains a scope change.
+ */
+function alreadyInDestinationScope({ changingScope, dream, previousPosition, scope, snapshot, }) {
+    if (!changingScope || snapshot === undefined)
+        return false;
+    if (previousPosition === undefined || previousPosition === null)
+        return false;
+    const columns = sortableScopeColumns(dream, scope);
+    if (!columns.length)
+        return false;
+    return columns.every(column => snapshot.scopeValues.has(column) &&
+        canonicalScopeValue(dream, column, snapshot.scopeValues.get(column)) ===
+            canonicalScopeValue(dream, column, dream[column]));
 }
 async function updateConflictingRecords(obj) {
-    const { wasNewRecord, position, previousPosition, dream, positionField, query, scope, txn, changingScope } = obj;
+    const { wasNewRecord, position, previousPosition, dream, positionField, query, scope, txn, changingScope, snapshot, } = obj;
+    // A scope move spans two unrelated position spaces: `previousPosition` is a
+    // position in the scope being left, `position` one in the scope being
+    // entered. Only the scope being left is compacted here, and it compacts all
+    // the way up — bounding it by a position from the other space closes nothing
+    // at all whenever the destination is the smaller of the two, leaving a
+    // permanent hole. The destination needs no room made: a scope-changing save
+    // always lands at the end of it, because `afterSortableUpdate` passes no
+    // position and `validPosition` then returns the destination's max + 1.
+    //
+    // A record with no position to vacate — a soft-deleted row, whose position
+    // column is NULL — leaves the scope it is moving out of untouched.
+    if (changingScope && (previousPosition === undefined || previousPosition === null))
+        return;
     const increasing = changingScope ||
         position === undefined ||
         (previousPosition !== undefined && previousPosition !== null && previousPosition < position);
+    const conflictingPositions = changingScope
+        ? ops.greaterThanOrEqualTo(previousPosition)
+        : increasing
+            ? range(previousPosition, position)
+            : range(position, previousPosition);
     let kyselyQuery = query
         .txn(txn)
         .whereNot({ [dream['_primaryKey']]: dream.primaryKeyValue() })
         .where({
-        [positionField]: increasing ? range(previousPosition, position) : range(position, previousPosition),
+        [positionField]: conflictingPositions,
     })
         .toKysely('update')
         .set((eb) => ({
         [positionField]: eb(positionField, increasing ? '-' : '+', 1),
     }));
-    kyselyQuery = applySortableScopesToQuery(dream, kyselyQuery, column => !wasNewRecord && dream.savedChangeToAttribute(column)
+    // the range being compacted belongs to the scope the record is *leaving*, so
+    // the filter has to name that scope's real column values — the snapshot read
+    // under the lock before the write, not what the instance remembers
+    kyselyQuery = filterQueryToScopeValues(dream, kyselyQuery, column => snapshotScopeValue(snapshot, column, () => !wasNewRecord && dream.savedChangeToAttribute(column)
         ? (dream.changes()[column]?.was ?? dream[column])
-        : dream[column], scope);
+        : dream[column]), scope);
     await kyselyQuery.execute();
 }
-export function applySortableScopesToQuery(dream, kyselyQuery, whereValueCB, scope) {
-    for (const singleScope of scopeArray(scope)) {
-        const column = getColumnForSortableScope(dream, singleScope);
-        if (column) {
-            const columnValue = whereValueCB(column);
-            if (columnValue === null) {
-                kyselyQuery = kyselyQuery.where(column, 'is', null);
-            }
-            else {
-                kyselyQuery = kyselyQuery.where(column, '=', columnValue);
-            }
-        }
-    }
-    return kyselyQuery;
-}
 async function updatePositionForRecord(obj) {
     const { txn, dream, positionField, position } = obj;
     await txn.kyselyTransaction
@@ -67,13 +121,3 @@ async function updatePositionForRecord(obj) {
     })
         .execute();
 }
-export function getPostgresQueryDriver(connectionName) {
-    const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(connectionName);
-    if (!(queryDriverClass === PostgresQueryDriver)) {
-        throw new Error(`
-      ${queryDriverClass.name} is not an instance of PostgresQueryDriver.
-      You must be using the PostgresQueryDriver when leveraging the Sortable decorator
-      `);
-    }
-    return queryDriverClass;
-}

package/dist/esm/src/decorators/field/sortable/helpers/sortableRowCache.js

@@ -0,0 +1,73 @@
+// The cached rows of every live transaction, keyed by the `DreamTransaction`
+// object itself. Module-level state is safe here because the key is an object
+// identity: every transaction — including a nested one — is its own
+// `DreamTransaction` instance, so no lookup can ever see rows stashed by
+// another transaction, whatever request or async flow it belongs to. The keys
+// are held weakly, so an entry becomes collectible with its transaction and
+// nothing accumulates for the life of the process. (The lock ledger in
+// `heldSortableScopeLockKeys.ts` relies on the same properties.)
+const rowsByTransaction = new WeakMap();
+// a JSON tuple rather than a joined string, so that no table name and no
+// primary key value can combine into another pair's key
+function cacheKey(table, primaryKeyValue) {
+    return JSON.stringify([table, String(primaryKeyValue)]);
+}
+/**
+ * @internal
+ *
+ * Stashes rows a locked batch's preflight read under the batch's scope locks,
+ * so that the per-record position work that follows does not read them a second
+ * time. The preflight reads every candidate's position and sort scope columns
+ * to derive the key set; each record's own snapshot read then asks the same
+ * question of the same row, in the same transaction, under the same locks.
+ *
+ * Called once per preflight, with the rows of the pass that converged: an
+ * earlier pass read before some of the locks were held, and a preflight that
+ * raised holds no lock the rest of the transaction can rely on. The rows are
+ * consumed one at a time and the whole entry is dropped by the first position
+ * write of the batch, since a compaction moves rows this holds stale positions
+ * for — so what it saves is the snapshot reads of the records walked before
+ * that first write.
+ *
+ * @param txn - the batch's transaction
+ * @param table - the table the rows came from
+ * @param primaryKey - the column the rows are keyed by
+ * @param rows - the rows read, carrying at least the position and scope columns
+ */
+export function cacheSortableRowsReadUnderLock(txn, table, primaryKey, rows) {
+    rowsByTransaction.set(txn, new Map(rows.map(row => [cacheKey(table, row[primaryKey]), row])));
+}
+/**
+ * @internal
+ *
+ * The cached row for one record, removed from the cache as it is handed over.
+ *
+ * Consuming is destructive because the consumer is a position-mutating
+ * operation: it is about to compact or renumber the scope the row sits in, and
+ * a second read of the same cached row would see the position the row had
+ * before that. {@link invalidateSortableRowCache} covers the same hazard for
+ * the *other* records a compaction moves.
+ */
+export function takeCachedSortableRow(txn, table, primaryKeyValue) {
+    const rows = rowsByTransaction.get(txn);
+    if (!rows)
+        return undefined;
+    const key = cacheKey(table, primaryKeyValue);
+    const row = rows.get(key);
+    rows.delete(key);
+    return row;
+}
+/**
+ * @internal
+ *
+ * Discards everything cached for this transaction. Called for two reasons: a
+ * position write just moved rows the cache cannot identify — a compaction
+ * shifts every row in one sort scope above a position, and the cache holds no
+ * index by scope — and the batch the rows were read for has finished, after
+ * which they describe nothing the rest of a caller-owned transaction should
+ * trust. The records still to be walked read their own rows again, which is
+ * what they did before the cache existed.
+ */
+export function invalidateSortableRowCache(txn) {
+    rowsByTransaction.delete(txn);
+}

package/dist/esm/src/decorators/field/sortable/helpers/sortableScopeColumns.js

@@ -0,0 +1,42 @@
+import getColumnForSortableScope from './getColumnForSortableScope.js';
+import scopeArray from './scopeArray.js';
+/**
+ * @internal
+ *
+ * The scope members of a sortable field paired with the database columns they
+ * resolve to. A member names either the column itself or the BelongsTo
+ * association whose foreign key backs it, and a caller matching incoming
+ * attributes needs both spellings; a member that resolves to no column is
+ * dropped.
+ *
+ * Every sortable path resolves its scope columns through this one function, so
+ * that a lock key, a snapshot read, a group identity and a scope filter can
+ * never disagree about which columns a sort scope is made of.
+ */
+export function sortableScopeColumnPairs(dream, scope) {
+    return scopeArray(scope).reduce((acc, singleScope) => {
+        const column = getColumnForSortableScope(dream, singleScope);
+        if (column)
+            acc.push([singleScope, column]);
+        return acc;
+    }, []);
+}
+/**
+ * @internal
+ *
+ * The database columns a sortable field's scope resolves to.
+ */
+export default function sortableScopeColumns(dream, scope) {
+    return sortableScopeColumnPairs(dream, scope).map(([, column]) => column);
+}
+/**
+ * @internal
+ *
+ * The sort scope as `[column, value]` pairs — the shape a lock key is derived
+ * from and a group is identified by. The value for each column comes from the
+ * caller, which decides whether it is reading the in-memory instance or a
+ * snapshot of the row.
+ */
+export function sortableScopeValues(dream, scope, valueForColumn) {
+    return sortableScopeColumns(dream, scope).map(column => [column, valueForColumn(column)]);
+}