@rvoh/dream 2.26.0 → 2.28.0

package/dist/esm/src/dream/internal/undestroyDream.js

@@ -1,4 +1,6 @@
-import { applySortableScopesToQuery } from '../../decorators/field/sortable/helpers/setPosition.js';
+import acquireStabilizedSortableScopeLocks from '../../decorators/field/sortable/helpers/acquireStabilizedSortableScopeLocks.js';
+import filterQueryToScopeValues from '../../decorators/field/sortable/helpers/filterQueryToScopeValues.js';
+import { snapshotScopeValue } from '../../decorators/field/sortable/helpers/sortableSnapshot.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -31,11 +33,23 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
     if (!skipHooks) {
         await runHooksFor('beforeUpdate', dream, true, null, txn);
     }
-    await doUndestroyDream(dream, txn);
+    // The cascade runs ahead of the restore, matching `destroyDream`: this
+    // record's own scope lock is taken inside `doUndestroyDream`, so a cascade
+    // seated after it would hold that lock across every descendant's undestroy,
+    // and a parent and its children would take their advisory keys in the
+    // opposite order to the one the destroy side takes them in. The nested select
+    // the cascade builds bypasses the soft-delete scope on this record's own
+    // class (`undestroyOptions`), so it reaches the children while this record is
+    // still deleted.
     if (cascade) {
         await undestroyAssociatedRecords(dream, txn, options);
     }
-    if (!skipHooks) {
+    const restoredRowCount = await doUndestroyDream(dream, txn);
+    // A restore of a row that is not deleted — a second `undestroy()`, a job
+    // retry, or a record that was never destroyed, which `Query#undestroy` reaches
+    // routinely since it lifts the soft-delete scope and walks every match —
+    // matches no row, so there is nothing for the after-update hooks to react to.
+    if (!skipHooks && restoredRowCount > 0) {
         await runHooksFor('afterUpdate', dream, true, null, txn);
         await runHooksFor('afterUpdateCommit', dream, true, null, txn);
     }
@@ -45,22 +59,56 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
 /**
  * @internal
  *
- * Destroys the dream iff it was not blocked from
- * deleting by one of the beforeDestroy model hooks
+ * Clears the record's `deletedAt` and, for a sortable model, gives it a
+ * position at the end of the sort scope its row physically occupies.
+ *
+ * Restoring is conditional on the row still being deleted, and the count of
+ * rows the statement matched is what the caller reads that off. A row that is
+ * already back would otherwise be inside the `max(position)` its new position
+ * is computed from, and would move one past itself on every repeat — a
+ * permanent gap in the scope.
+ *
+ * @returns the number of rows restored: 1, or 0 when the row was not deleted
  */
 async function doUndestroyDream(dream, txn) {
     const updateStatement = txn.kyselyTransaction.updateTable(dream.table);
     let query = updateStatement
         .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
+        .where(dream['_deletedAtField'], 'is not', null)
         .set({ [dream['_deletedAtField']]: null });
     const dreamClass = dream.constructor;
-    dreamClass['sortableFields']?.forEach(sortableFieldMetadata => {
+    const sortableFields = (dreamClass['sortableFields'] ?? []);
+    // Undestroy has no sortable hook of its own — the position is recomputed
+    // inline, below, before `afterUpdate` ever runs — so the scope lock is taken
+    // here, around that recomputation. Without it the `max(position) + 1`
+    // subquery races every other writer of the scope the record is being restored
+    // into.
+    //
+    // The scope this record is being restored into is the one its row physically
+    // carries, not the one the instance was loaded with: another writer may have
+    // moved it between scopes while it was soft deleted, which is what the
+    // stabilized acquisition converges on.
+    const { snapshots } = await acquireStabilizedSortableScopeLocks(dream, txn, sortableFields);
+    sortableFields.forEach(sortableFieldMetadata => {
         const positionColumn = sortableFieldMetadata.positionField;
+        const snapshot = snapshots.get(positionColumn);
         query = query.set(eb => ({
-            [positionColumn]: eb(applySortableScopesToQuery(dream, txn.kyselyTransaction.selectFrom(dream.table), column => dream[column], sortableFieldMetadata.scope).select(eb => eb.fn.max(positionColumn).as(positionColumn + '_max')), '+', 1),
+            [positionColumn]: eb(filterQueryToScopeValues(dream, txn.kyselyTransaction.selectFrom(dream.table), column => snapshotScopeValue(snapshot, column, () => dream[column]), sortableFieldMetadata.scope).select(eb => 
+            // `max` over a scope with no positioned rows left — an empty
+            // scope, or one whose every remaining row is soft deleted and so
+            // carries a NULL position — is NULL, and NULL + 1 is NULL, which
+            // would restore the record with no position at all. Coalescing
+            // before the increment restores it at position 1.
+            eb.fn.coalesce(eb.fn.max(positionColumn), eb.lit(0)).as(positionColumn + '_max')), '+', 1),
         }));
     });
-    return await query.execute();
+    const [result] = await query.execute();
+    // No sortable row cache invalidation here: the restored record took a position
+    // at the end of the scope it was restored into and nothing else moved, so no
+    // other record's cached preflight row went stale, and this record's own cached
+    // row was consumed — destructively — by the snapshot read every sortable field
+    // above goes through.
+    return Number(result?.numUpdatedRows ?? 0);
 }
 /**
  * @internal

package/dist/esm/src/dream-app/index.js

@@ -212,6 +212,24 @@ export default class DreamApp {
     get paginationMaxPageSize() {
         return this._paginationMaxPageSize;
     }
+    /**
+     * How long, in milliseconds, a position-mutating operation on a
+     * `@deco.Sortable` model will wait for another transaction to release the
+     * sort scope it needs before giving up with
+     * `SortableScopeLockWaitTimedOut`. Applied to the lock acquisition statement
+     * alone — the transaction's other lock waits keep whatever `lock_timeout`
+     * the application has configured.
+     *
+     * `0` waits without bound, which is what Postgres's `lock_timeout` means by
+     * it, and holds even on a connection configured with a `lock_timeout` of its
+     * own: the acquisition disables the bound for the duration of the statement.
+     *
+     * Set it with `dreamApp.set('sortableScopeLockTimeout', milliseconds)`.
+     */
+    _sortableScopeLockTimeout = 5000;
+    get sortableScopeLockTimeout() {
+        return this._sortableScopeLockTimeout;
+    }
     _primaryKeyType = 'bigint';
     get primaryKeyType() {
         return this._primaryKeyType;
@@ -492,6 +510,9 @@ export default class DreamApp {
             case 'paginationMaxPageSize':
                 this._paginationMaxPageSize = options;
                 break;
+            case 'sortableScopeLockTimeout':
+                this._sortableScopeLockTimeout = options;
+                break;
             default: {
                 // protection so that if a new ApplyOpt is ever added, this will throw a type error at build time
                 const _never = applyOption;

package/dist/esm/src/errors/SortableBatchRequiresTooManyScopeLocks.js

@@ -0,0 +1,57 @@
+/**
+ * Raised when a batch of a locked `Query#destroy` or `Query#update` on a
+ * sortable model would carry its transaction past the number of advisory
+ * sort-scope locks Dream is willing to hold at once.
+ *
+ * The batched, row-locking query APIs take every advisory scope key the batch
+ * needs before they claim a single row — one key per sort scope the batch's
+ * candidate records occupy, per sortable field the model declares. Advisory
+ * locks live in Postgres's cluster-wide shared lock table, whose size is fixed
+ * at startup (`max_locks_per_transaction` × `max_connections`), and they are
+ * held until the transaction ends. A batch over a table whose sort scope has
+ * very high cardinality can therefore consume a meaningful fraction of a
+ * resource every other connection in the cluster shares, and exhausting it
+ * fails unrelated transactions rather than only this one.
+ *
+ * So the preflight counts first and refuses, before claiming any row. The count
+ * is the whole transaction's: the keys it already holds plus the keys the
+ * refused batch would add, since advisory locks are released only when the
+ * transaction ends. Inside a transaction Dream opens for the batch that is the
+ * batch's own key set and nothing has been locked when this is raised; inside a
+ * transaction you own, it also counts every key the run's earlier batches took,
+ * and those stay held.
+ *
+ * The fix is almost always a smaller `batchSize`: the keys one batch needs are
+ * bounded by how many distinct sort scopes its records span, so halving the
+ * batch size halves the worst case. If the run itself is what accumulates them
+ * — a long multi-batch run inside a transaction you opened — either let Dream
+ * open a transaction per batch (do not pass a transaction of your own) or
+ * commit between runs, which is what releases the locks as it goes.
+ */
+export default class SortableBatchRequiresTooManyScopeLocks extends Error {
+    dreamClassName;
+    keyCount;
+    maxKeyCount;
+    constructor(dreamClassName, keyCount, maxKeyCount) {
+        super();
+        this.dreamClassName = dreamClassName;
+        this.keyCount = keyCount;
+        this.maxKeyCount = maxKeyCount;
+    }
+    get message() {
+        return `\
+A locked batch over ${this.dreamClassName} would leave its transaction holding ${this.keyCount} sort scope locks, and the limit is ${this.maxKeyCount}.
+
+Sortable takes one advisory lock per sort scope a batch touches, per sortable field, before the
+batch claims any row, and holds them until the transaction ends. Advisory locks come out of a
+lock table the whole Postgres cluster shares, so a batch that would carry its transaction past
+this limit is refused rather than risking every other connection's transactions.
+
+Use a smaller batchSize. The keys one batch needs are bounded by the number of distinct sort
+scopes its records span, so a smaller batch takes proportionally fewer. If this operation runs
+inside a transaction you opened, note that the locks of earlier batches are still held while
+later batches preflight, and are counted here; letting Dream open a transaction per batch
+releases them as it goes.
+`;
+    }
+}

package/dist/esm/src/errors/SortableRequiresAdvisoryTransactionLocks.js

@@ -0,0 +1,26 @@
+/**
+ * Raised when a model declaring sortable fields is used on a query driver that
+ * cannot take transaction-scoped advisory locks.
+ *
+ * Sortable computes position values under a lock on the sort scope, without
+ * which concurrent writers collide on the same position. A driver that cannot
+ * provide that lock fails loudly here rather than racing silently.
+ */
+export default class SortableRequiresAdvisoryTransactionLocks extends Error {
+    queryDriverClassName;
+    constructor(queryDriverClassName) {
+        super();
+        this.queryDriverClassName = queryDriverClassName;
+    }
+    get message() {
+        return `\
+${this.queryDriverClassName} cannot be used with the Sortable decorator.
+
+Sortable computes position values under a transaction-scoped advisory lock on the sort
+scope, without which concurrent writers collide on the same position. Implement
+\`acquireAdvisoryTransactionLocks\` on ${this.queryDriverClassName} and set
+\`supportsAdvisoryTransactionLocks = true\`, or use the PostgresQueryDriver for models
+that declare sortable fields.
+`;
+    }
+}

package/dist/esm/src/errors/SortableScopeDidNotStabilize.js

@@ -0,0 +1,39 @@
+/**
+ * Raised when a position-mutating operation cannot settle on the sort scope its
+ * record actually occupies.
+ *
+ * A save, destroy, undestroy or locked batch operation locks the sort scopes it
+ * believes it is touching, then reads the rows to find out which scopes they
+ * physically occupy. When another writer has moved a row in between, the
+ * operation takes the additional scope's lock and reads again. A row that keeps
+ * moving exhausts that bound, and the operation raises rather than compacting a
+ * scope the row has already left.
+ *
+ * This is a retryable condition: retrying the operation is the intended
+ * response. One caveat for saves the caller did not wrap in a transaction: the
+ * model's before-hooks run before the transaction this error aborts, so any
+ * effects those hooks had outside the record's own row — writes to other
+ * tables, enqueued work — are not rolled back, and run again on retry.
+ */
+export default class SortableScopeDidNotStabilize extends Error {
+    dreamClassName;
+    rounds;
+    constructor(dreamClassName, rounds) {
+        super();
+        this.dreamClassName = dreamClassName;
+        this.rounds = rounds;
+    }
+    get message() {
+        return `\
+The sort scope of a ${this.dreamClassName} record kept changing while its position was being computed.
+
+Sortable locks the sort scopes an operation touches and then reads the record's actual scope
+under those locks, taking any additional lock the read reveals. After ${this.rounds} rounds the
+record had still been moved to another scope by a competing writer, so the operation was
+abandoned rather than compacting a scope the record no longer occupies. Retrying the operation
+is the intended response; note that on a save the caller did not wrap in a transaction, the
+model's before-hooks ran before the transaction this error aborted, so their effects outside
+the record's own row are not rolled back and run again on retry.
+`;
+    }
+}

package/dist/esm/src/errors/SortableScopeLockWaitTimedOut.js

@@ -0,0 +1,50 @@
+/**
+ * Raised when a position-mutating operation waited too long for another
+ * transaction to release a sort scope.
+ *
+ * Every position-mutating path — a save, a destroy, an undestroy, a locked
+ * batch, `Dream.resort` — computes its positions under an exclusive advisory
+ * lock on the sort scope, held until the transaction that took it ends. A
+ * writer that finds the scope already locked waits, and that wait is bounded:
+ * Dream applies a `lock_timeout` (5 seconds by default, set through the
+ * `sortableScopeLockTimeout` DreamApp option) to the acquisition statement
+ * alone, and restores whatever `lock_timeout` was in effect afterward, so the
+ * transaction's other lock waits — row locks taken by `lock: true`, foreign key
+ * checks — are left exactly as the application configured them.
+ *
+ * This is a retryable condition: the operation touched nothing, and the holder
+ * it was waiting for is a transaction that will end. What has to be retried
+ * depends on who owns the transaction. When Dream opened it — a plain
+ * `save()`, `destroy()`, `undestroy()` or `resort()` — only that call was rolled
+ * back, and retrying the call is the whole response. Inside a transaction the
+ * caller owns, the failed statement aborts **the entire transaction**: nothing
+ * further can run on it, and the caller has to retry the transaction as a whole
+ * rather than the sortable operation inside it.
+ *
+ * Hitting this bound routinely is a signal rather than a transient: it means one
+ * sort scope is being written by more concurrent writers than it can serialize,
+ * or that something slow is running inside a transaction that holds the scope —
+ * on a destroy or an undestroy, that includes your own `afterDestroy` and
+ * `afterUpdate` hooks, which run inside the lock window.
+ */
+export default class SortableScopeLockWaitTimedOut extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super();
+        this.timeoutMs = timeoutMs;
+    }
+    get message() {
+        return `\
+Timed out after ${this.timeoutMs}ms waiting for another transaction to release a sort scope.
+
+Sortable computes positions under an exclusive advisory lock on the sort scope, held until the
+transaction holding it ends. This operation waited the configured bound and gave up rather than
+waiting indefinitely; it changed nothing, and retrying it is the intended response — but if the
+transaction this ran in was one you opened yourself, the whole transaction is aborted and has to
+be retried as a whole.
+
+Change the bound with \`dreamApp.set('sortableScopeLockTimeout', milliseconds)\` in your Dream
+configuration, or set it to 0 to wait without bound.
+`;
+    }
+}

package/dist/esm/src/package-exports/errors.js

@@ -12,6 +12,9 @@ export { default as DecryptionParseError } from '../errors/encrypt/DecryptionPar
 export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
 export { default as MissingSerializersDefinition } from '../errors/serializers/MissingSerializersDefinition.js';
+export { default as SortableBatchRequiresTooManyScopeLocks } from '../errors/SortableBatchRequiresTooManyScopeLocks.js';
+export { default as SortableScopeDidNotStabilize } from '../errors/SortableScopeDidNotStabilize.js';
+export { default as SortableScopeLockWaitTimedOut } from '../errors/SortableScopeLockWaitTimedOut.js';
 export { default as ValidationError } from '../errors/ValidationError.js';
 export { InvalidCalendarDate } from '../utils/datetime/CalendarDate.js';
 export { InvalidClockTime } from '../utils/datetime/ClockTime.js';

package/dist/types/src/Dream.d.ts

@@ -8,7 +8,7 @@ import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
 import { OnStatementForSpecificColumns, PassthroughOnClause, WhereStatement } from './types/associations/shared.js';
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
-import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts, ValidatedPluckEachColumnNames } from './types/dream.js';
 import { BaseModelColumnTypes, CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, DefaultQueryTypeOptions, FindEachOpts, LoadForModifierFn, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from './types/serializer.js';
 import { ValidationType } from './types/validation.js';
@@ -1445,7 +1445,8 @@ export default class Dream {
      * @param args - a list of fields to pluck, followed by a callback function to call for each set of found fields
      * @returns void
      */
-    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, ColumnNames extends TableColumnNames<I['DB'], I['table']>[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, I>>(this: T, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
+    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, const ColumnNames extends unknown[]>(this: T, ...args: PluckEachArgs<ValidatedPluckEachColumnNames<ColumnNames, TableColumnNames<I['DB'], I['table']>>, BaseModelColumnTypes<ValidatedPluckEachColumnNames<ColumnNames, TableColumnNames<I['DB'], I['table']>>, I>>): Promise<void>;
+    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, const ColumnNames extends TableColumnNames<I['DB'], I['table']>[]>(this: T, ...args: PluckEachArgs<ColumnNames, BaseModelColumnTypes<ColumnNames, I>>): Promise<void>;
     /**
      * Used in conjunction with the Sortable decorator, `resort`
      * takes a list of sortable fields, and for each one, finds and
@@ -1459,6 +1460,25 @@ export default class Dream {
      * with no gaps, accounting for the scopes specified in the
      * corresponding Sortable decorator.
      *
+     * Each sort scope is renumbered in its own transaction, under the same
+     * advisory lock every other position-mutating path takes on that scope, from
+     * a read of the scope taken inside that lock — so a concurrent create or
+     * destroy cannot make the renumbering land on positions it never read.
+     *
+     * **Do not call `resort` from inside a transaction you own.** It opens those
+     * transactions itself, on connections of its own, so it can neither join
+     * yours nor roll back with it: its writes commit on their own. Worse, if your
+     * transaction already holds the scope lock for a scope being renumbered — any
+     * position-mutating write to that scope earlier in the transaction takes it —
+     * `resort` waits on that lock from the outside, where no deadlock detector
+     * can see the cycle, until the wait bound expires and it throws
+     * `SortableScopeLockWaitTimedOut`.
+     *
+     * On an STI hierarchy the position space is shared by every class in the
+     * hierarchy, exactly as it is for creates, updates and destroys. Calling
+     * `resort` on a child class therefore renumbers the hierarchy's rows, not
+     * only the receiver's.
+     *
      * ```ts
      * class Post extends ApplicationModel {
      *   @deco.Sortable({ scope: ['user']})
@@ -2973,6 +2993,19 @@ export default class Dream {
      * This is usually used for a soft-delete
      * pattern
      *
+     * The veto is fail-closed, and the record is left
+     * entirely untouched: on a soft-delete model the soft
+     * delete is skipped as well, no `afterDestroy` or
+     * `afterDestroyCommit` hooks run, since the record is
+     * still present, and the destroy returns before the
+     * `dependent: 'destroy'` cascade, so this record's
+     * dependent associations survive too.
+     *
+     * A veto only stops the subtree rooted at the record
+     * that called it. When a record is reached by another
+     * record's cascade, vetoing spares it and its own
+     * dependents; the destroy that reached it carries on.
+     *
      * ```ts
      * class User extends ApplicationModel {
      *   @deco.BeforeDestroy()

package/dist/types/src/db/errors.d.ts

@@ -3,6 +3,7 @@ export declare const FOREIGN_KEY_VIOLATION = "FOREIGN_KEY_VIOLATION";
 export declare const INTEGRITY_CONSTRAINT_VIOLATION = "INTEGRITY_CONSTRAINT_VIOLATION";
 export declare const INVALID_INPUT_SYNTAX = "INVALID_INPUT_SYNTAX";
 export declare const COLUMN_OVERFLOW = "COLUMN_OVERFLOW";
+export declare const LOCK_NOT_AVAILABLE = "LOCK_NOT_AVAILABLE";
 export declare const NOT_NULL_VIOLATION = "NOT_NULL_VIOLATION";
 export declare const RESTRICT_VIOLATION = "RESTRICT_VIOLATION";
 export declare const UNIQUE_VIOLATION = "UNIQUE_VIOLATION";
@@ -17,6 +18,7 @@ export declare const PG_ERRORS: {
     readonly '23000': "INTEGRITY_CONSTRAINT_VIOLATION";
     readonly '23001': "RESTRICT_VIOLATION";
     readonly '23503': "FOREIGN_KEY_VIOLATION";
+    readonly '55P03': "LOCK_NOT_AVAILABLE";
 };
 type PgErrorType = (typeof PG_ERRORS)[keyof typeof PG_ERRORS];
 export declare function pgErrorType(error: any): PgErrorType | null;

package/dist/types/src/decorators/field/sortable/Sortable.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Marks an integer column as a sortable position: Dream keeps the positions of
+ * every record in a sort scope contiguous, starting at 1, as records are
+ * created, moved, destroyed and undestroyed.
+ *
+ * ```ts
+ * class Post extends ApplicationModel {
+ *   @deco.Sortable({ scope: 'user' })
+ *   public position: number
+ * }
+ *
+ * await post.update({ position: 2 }) // the records at 2 and above shift up
+ * ```
+ *
+ * A position past the end of the scope is clamped to the end, and a position
+ * below 1 — or none at all — lands the record at the end.
+ *
+ * **A save that changes the sort scope ignores a position given alongside it.**
+ * The record lands at the end of the scope it moves into, whatever position the
+ * same `update` supplied:
+ *
+ * ```ts
+ * await post.update({ user: otherUser, position: 1 })
+ * // post is now the last record in otherUser's scope, not the first
+ * ```
+ *
+ * Move it in two saves to place it: `await post.update({ user: otherUser })`,
+ * then `await post.update({ position: 1 })`.
+ *
+ * Sortable requires a query driver that supports advisory transaction locks —
+ * the `PostgresQueryDriver` does — since every position write serializes the
+ * writers of its sort scope on one.
+ */
 export default function Sortable(opts?: SortableOpts): any;
 interface SortableOpts {
     /**

package/dist/types/src/decorators/field/sortable/helpers/acquireSortableScopeLocks.d.ts

@@ -0,0 +1,25 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * Serializes every writer of a set of sort scopes by taking those scopes'
+ * transaction-scoped advisory locks. They are released when the enclosing
+ * transaction ends, so there is nothing to release here.
+ *
+ * Keys this transaction already holds are dropped rather than re-acquired: the
+ * lock is held to the end of the transaction either way, so the statement would
+ * do nothing but cost a round trip inside the lock window. Whatever is left is
+ * taken in the order given — callers that need more than one sort them first,
+ * so that two operations touching the same pair of scopes cannot deadlock
+ * against each other — and in one statement, on drivers that can express it.
+ *
+ * Waiting for a key another transaction holds is bounded by the driver, which
+ * raises `SortableScopeLockWaitTimedOut` rather than waiting forever; see
+ * `QueryDriverBase.acquireAdvisoryTransactionLocks`.
+ *
+ * @param dream - the record whose connection provides the driver
+ * @param txn - the transaction the locks are scoped to
+ * @param keys - the scope keys to acquire, in acquisition order
+ */
+export default function acquireSortableScopeLocks(dream: Dream, txn: DreamTransaction<any>, keys: bigint[]): Promise<void>;

package/dist/types/src/decorators/field/sortable/helpers/acquireStabilizedSortableBatchLocks.d.ts

@@ -0,0 +1,91 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * The most advisory sort-scope locks a batch preflight will let one transaction
+ * hold.
+ *
+ * Advisory locks are entries in a cluster-wide shared lock table sized at
+ * startup (`max_locks_per_transaction` × `max_connections`, 6400 entries under
+ * the stock settings), and a transaction holds every key it takes until it
+ * ends. `batchSize` is the caller's to choose and nothing bounds the number of
+ * distinct sort scopes a batch's records span, so without a limit a wide enough
+ * batch over a high-cardinality scope can starve every other connection in the
+ * cluster of a resource they all draw on — a failure that lands on unrelated
+ * transactions rather than on the one that caused it.
+ *
+ * The count is **cumulative over the transaction**: each preflight round counts
+ * the keys the transaction already holds together with the keys that round
+ * would add. So the bound holds across the rounds of one stabilization loop
+ * (each of which can discover a different set of scopes), and across the
+ * batches of a multi-batch run inside a caller-owned transaction, where
+ * advisory locks are released only when the caller commits.
+ *
+ * The headroom this leaves: the locked-batch defaults are ten records per batch
+ * (`Query.BATCH_SIZES.LOCKED_DESTROY` / `LOCKED_UPDATE`), so reaching the bound
+ * takes a caller who raises `batchSize` by two orders of magnitude and whose
+ * records each occupy a sort scope of their own — or a long run of such batches
+ * inside one transaction. Two shapes consume the budget faster than one key per
+ * record: a model declaring more than one sortable field needs one key per
+ * field, and the attribute form of `update` needs up to two per record per
+ * field, since the record's current scope and its destination scope are
+ * different keys.
+ *
+ * Only the batch preflight enforces this. A per-record save, destroy or
+ * undestroy takes its keys without counting them, so what they take is counted
+ * by the next preflight in the same transaction but cannot itself raise.
+ */
+export declare const MAX_SORTABLE_BATCH_SCOPE_LOCKS = 1000;
+/**
+ * @internal
+ *
+ * The operation-level scope-lock preflight for the batched, row-locking query
+ * APIs — `Query#destroy({ lock: true })` and the attribute form of
+ * `Query#update(attributes, { lock: true })`.
+ *
+ * Why it exists: those operations take *row* locks (`takeAll({ lock: true })`)
+ * and then run per-record sortable work that takes *advisory* scope locks. Two
+ * transactions running in that order can each hold what the other is waiting
+ * for. Acquiring every advisory key the batch needs — across every sortable
+ * field and every candidate record — in one sorted pass, before a single row is
+ * claimed, removes the inversion: the advisory locks are always taken first, and
+ * always in the same order.
+ *
+ * The key set cannot simply be read once: `Query.lockedBatches` plucks only
+ * primary keys, so the candidates' scope columns have to be read separately, and
+ * that first read is not protected by any lock. So the read is stabilized the
+ * same way the per-record paths stabilize theirs, through the same
+ * `stabilizeSortableScopeLocks` protocol — acquire on what the unlocked read
+ * implies, re-read under those locks, take any additional key the re-read
+ * reveals — with the same bound, and the same `SortableScopeDidNotStabilize`
+ * when a batch of rows keeps moving between scopes faster than it can be read.
+ *
+ * A model with no sortable fields never reaches the driver seam, so this is
+ * inert — and free — for every other model.
+ *
+ * How many keys the transaction may hold is bounded — see
+ * {@link MAX_SORTABLE_BATCH_SCOPE_LOCKS} — and a batch that would carry it past
+ * the bound is refused before it claims any row. The first round refuses before
+ * anything at all is locked; a later round refuses after that loop's earlier
+ * rounds took their keys, which stay held until the transaction ends like every
+ * advisory lock this branch takes.
+ *
+ * What the preflight can and cannot see: `incomingScopeValue` recognizes an
+ * attribute that names a scope column directly or the BelongsTo association
+ * backing it. A destination scope produced any other way — by a custom setter,
+ * a virtual attribute, or a `beforeSave` hook that moves the record between
+ * scopes during the per-record save — is invisible here, and those shapes are
+ * preflight fallbacks like the callback form of `update` and a multi-batch run
+ * inside a caller-owned transaction: the missing key is taken as the
+ * per-record save reaches it, after this batch's row locks, and the residual
+ * failure is Postgres's `40P01` deadlock error — a visible, retryable failure
+ * rather than a silent wrong ordering.
+ *
+ * @param dreamInstance - a bare instance of the Query's model, used for the
+ *   table, the connection, and the scope column resolution
+ * @param txn - the batch's transaction; the locks live until it ends
+ * @param primaryKeyValues - the candidate records this batch will try to claim
+ * @param incomingAttributes - the attributes the operation will write, when they
+ *   are knowable before the claim (the attribute form of `update`); a scope
+ *   column among them means the batch also needs the destination scope's key
+ */
+export default function acquireStabilizedSortableBatchLocks(dreamInstance: Dream, txn: DreamTransaction<any>, primaryKeyValues: unknown[], incomingAttributes?: Record<string, unknown>): Promise<void>;

package/dist/types/src/decorators/field/sortable/helpers/acquireStabilizedSortableScopeLocks.d.ts

@@ -0,0 +1,31 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+import { SortableFieldConfig } from '../Sortable.js';
+import { SortableSnapshotRead } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * Takes the scope locks a per-record position-mutating operation needs, and
+ * returns the database snapshot read under them. Every per-record path goes
+ * through this: a position- or scope-changing save (from `saveDream`'s sortable
+ * phase), a destroy (from the sortable destroy phase), and an undestroy (from
+ * `doUndestroyDream`). A destroy and an undestroy have no incoming scope
+ * values, so their instance-derived key set is a single key per sortable field —
+ * the scope the instance believes the row occupies — and the snapshot is what
+ * corrects it.
+ *
+ * The first pass locks the key set the instance implies, since the snapshot
+ * cannot be read until something is locked; every later pass locks what the
+ * snapshot read under those locks reveals. `stabilizeSortableScopeLocks` owns
+ * that protocol, its bound, and its failure — including the guarantee that a
+ * second pass always runs, so the snapshot is read under the locks even when
+ * the transaction already held every key the instance implies (a record being
+ * walked inside a locked batch, whose preflight took the whole batch's keys).
+ *
+ * @param dream - the record whose scope is being locked
+ * @param txn - the transaction the operation's write runs in
+ * @param configs - the sortable fields this operation performs position work for
+ * @returns the snapshot read under the locks, alongside whether the row was
+ *   physically there to read — an empty snapshot map on its own cannot say
+ */
+export default function acquireStabilizedSortableScopeLocks(dream: Dream, txn: DreamTransaction<any>, configs: SortableFieldConfig[]): Promise<SortableSnapshotRead>;