@rvoh/dream 2.26.0 → 2.28.0

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/esm/src/Dream.js

@@ -1787,23 +1787,6 @@ export default class Dream {
     static async pluck(...columnNames) {
         return (await this.query().pluck(...columnNames));
     }
-    /**
-     * Plucks the specified fields from the given dream class table
-     * in batches, passing each found columns into the
-     * provided callback function
-     *
-     * ```ts
-     * await User.order('id').pluckEach('id', (id) => {
-     *   console.log(id)
-     * })
-     * // 1
-     * // 2
-     * // 3
-     * ```
-     *
-     * @param args - a list of fields to pluck, followed by a callback function to call for each set of found fields
-     * @returns void
-     */
     static async pluckEach(...args) {
         return await this.query().pluckEach(...args);
     }
@@ -1820,6 +1803,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']})
@@ -3759,6 +3761,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/esm/src/db/errors.js

@@ -12,6 +12,7 @@ export const FOREIGN_KEY_VIOLATION = 'FOREIGN_KEY_VIOLATION';
 export const INTEGRITY_CONSTRAINT_VIOLATION = 'INTEGRITY_CONSTRAINT_VIOLATION';
 export const INVALID_INPUT_SYNTAX = 'INVALID_INPUT_SYNTAX';
 export const COLUMN_OVERFLOW = 'COLUMN_OVERFLOW';
+export const LOCK_NOT_AVAILABLE = 'LOCK_NOT_AVAILABLE';
 export const NOT_NULL_VIOLATION = 'NOT_NULL_VIOLATION';
 export const RESTRICT_VIOLATION = 'RESTRICT_VIOLATION';
 export const UNIQUE_VIOLATION = 'UNIQUE_VIOLATION';
@@ -26,6 +27,9 @@ export const PG_ERRORS = {
     '23000': INTEGRITY_CONSTRAINT_VIOLATION,
     '23001': RESTRICT_VIOLATION,
     '23503': FOREIGN_KEY_VIOLATION,
+    // a statement Postgres cancelled because its `lock_timeout` elapsed while it
+    // waited for a lock — the bound Dream puts on the sortable scope-lock wait
+    '55P03': LOCK_NOT_AVAILABLE,
 };
 function pgErrorFromCode(code) {
     return PG_ERRORS[code] || null;

package/dist/esm/src/decorators/field/sortable/Sortable.js

@@ -1,17 +1,37 @@
-import pascalize from '../../../helpers/pascalize.js';
-import { STI_SCOPE_NAME } from '../../class/STI.js';
-import { afterCreateImplementation } from '../lifecycle/AfterCreate.js';
-import { afterCreateCommitImplementation } from '../lifecycle/AfterCreateCommit.js';
-import { afterDestroyImplementation } from '../lifecycle/AfterDestroy.js';
-import { afterDestroyCommitImplementation } from '../lifecycle/AfterDestroyCommit.js';
-import { afterUpdateImplementation } from '../lifecycle/AfterUpdate.js';
-import { afterUpdateCommitImplementation } from '../lifecycle/AfterUpdateCommit.js';
-import { beforeSaveImplementation } from '../lifecycle/BeforeSave.js';
 import scopeArray from './helpers/scopeArray.js';
-import afterSortableCreate from './hooks/afterSortableCreate.js';
-import afterSortableDestroy from './hooks/afterSortableDestroy.js';
-import afterUpdateSortable from './hooks/afterSortableUpdate.js';
-import beforeSortableSave from './hooks/beforeSortableSave.js';
+/**
+ * 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 = {}) {
     return function (_, context) {
         const key = context.name;
@@ -27,116 +47,21 @@ export default function Sortable(opts = {}) {
                 // already declared on the base STI class.
                 dreamClass['sortableFields'] = [...dreamClass['sortableFields']];
             }
+            // the decorator registers nothing but this metadata: none of a sortable
+            // field's runtime work runs as hooks. A save's preparation and position
+            // write run as phases in `saveDream` (`prepareSortableFieldsForSave`,
+            // `performSortablePositionWork`), a destroy's lock acquisition, snapshot
+            // read and compaction as phases in `destroyDream`
+            // (`prepareSortableFieldsForDestroy`, `performSortableDestroyWork`), and
+            // an undestroy's restore inline in `undestroyDream` — each seated
+            // relative to the user's hooks by the caller, so no user hook code can
+            // interleave with the position work and every after-hook observes
+            // computed positions and compacted scopes
             ;
             dreamClass['sortableFields'].push({
                 scope: scopeArray(opts.scope),
                 positionField: key,
             });
-            const positionField = key;
-            const beforeSaveMethodName = `_cacheValueFor${pascalize(key)}`;
-            const afterCreateMethodName = `_setNewValueFor${pascalize(key)}AfterCreate`;
-            const afterCreateCommitMethodName = `_setNewValueFor${pascalize(key)}AfterCreateCommit`;
-            const afterUpdateMethodName = `_updateValueFor${pascalize(key)}AfterUpdate`;
-            const afterUpdateCommitMethodName = `_updateValueFor${pascalize(key)}AfteUpdateCommit`;
-            const afterDestroyMethodName = `_setValuesAfterDestructionFor${pascalize(key)}AfterDestroy`;
-            const afterDestroyCommitMethodName = `_setValuesAfterDestructionFor${pascalize(key)}AfterDestroyCommit`;
-            const dreamPrototype = Object.getPrototypeOf(dream);
-            // before saving, we remember the new value for position, but clear it from our
-            // supervised attributes to prevent position from saving
-            dreamPrototype[beforeSaveMethodName] = function () {
-                beforeSortableSave({
-                    dream: this,
-                    positionField,
-                    scope: opts.scope,
-                });
-            };
-            // once saved, we can now safely update position in isolation
-            dreamPrototype[afterUpdateMethodName] = async function (txn) {
-                // if no transaction is provided, leverage update commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterUpdateSortable({
-                    dream: this,
-                    positionField,
-                    query,
-                    txn,
-                    scope: opts.scope,
-                });
-            };
-            dreamPrototype[afterUpdateCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage update hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterUpdateSortable({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            // after create, we always want to ensure the position is set, so if they provide one,
-            // we need to split existing records on position and update, but otherwise we simply set the new position
-            // to be the length of all existing records + 1
-            dreamPrototype[afterCreateMethodName] = async function (txn) {
-                // if no transaction is provided, leverage create commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterSortableCreate({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                    txn,
-                });
-            };
-            dreamPrototype[afterCreateCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage create hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterSortableCreate({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            // after destroy, auto-adjust positions of all related records with a greater position
-            // than this one to maintain incrementing order,
-            dreamPrototype[afterDestroyMethodName] = async function (txn) {
-                // if no transaction is provided, leverage destroy commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterSortableDestroy({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            dreamPrototype[afterDestroyCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage destroy hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterSortableDestroy({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            beforeSaveImplementation(dream, beforeSaveMethodName);
-            afterCreateImplementation(dream, afterCreateMethodName);
-            afterCreateCommitImplementation(dream, afterCreateCommitMethodName);
-            afterUpdateImplementation(dream, afterUpdateMethodName);
-            afterUpdateCommitImplementation(dream, afterUpdateCommitMethodName);
-            afterDestroyImplementation(dream, afterDestroyMethodName);
-            afterDestroyCommitImplementation(dream, afterDestroyCommitMethodName);
         });
     };
 }

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

@@ -0,0 +1,38 @@
+import Query from '../../../../dream/Query.js';
+import SortableRequiresAdvisoryTransactionLocks from '../../../../errors/SortableRequiresAdvisoryTransactionLocks.js';
+import heldSortableScopeLockKeys from './heldSortableScopeLockKeys.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 async function acquireSortableScopeLocks(dream, txn, keys) {
+    if (!keys.length)
+        return;
+    const queryDriverClass = Query.dbDriverClass(dream.connectionName || 'default');
+    if (!queryDriverClass.supportsAdvisoryTransactionLocks)
+        throw new SortableRequiresAdvisoryTransactionLocks(queryDriverClass.name);
+    const heldKeys = heldSortableScopeLockKeys(txn);
+    const keysToAcquire = keys.filter(key => !heldKeys.has(key));
+    if (!keysToAcquire.length)
+        return;
+    await queryDriverClass.acquireAdvisoryTransactionLocks(txn, keysToAcquire);
+    keysToAcquire.forEach(key => heldKeys.add(key));
+}