@rvoh/dream 2.27.0 → 2.28.0

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

@@ -0,0 +1,194 @@
+import cachedTypeForAttribute from '../../../../helpers/db/cachedTypeForAttribute.js';
+const UTF8 = new TextEncoder();
+/**
+ * @internal
+ *
+ * The canonical text form of one sort-scope value — the thing an advisory lock
+ * key and a resort group identity are actually built from.
+ *
+ * Two writers of the same physical sort scope have to derive the same key, and
+ * they do not always hold the value in the same JavaScript shape. A save that
+ * has not been written yet holds the *pending* value the caller supplied
+ * (`'1.00'`, an uppercase UUID, an object whose keys are in source order),
+ * while a snapshot read, a create's post-INSERT read and `resort`'s table read
+ * hold the value Postgres *hydrated* (`1`, a lowercase UUID, an object whose
+ * keys are in jsonb's own order). Postgres considers those pairs one value;
+ * `typeof`-only normalization considers them two, and two keys do not exclude
+ * each other.
+ *
+ * So canonicalization is keyed on the column's runtime `dbType`, and the
+ * canonical form of each type is **the form the hydrated value already takes**.
+ * That anchoring is what makes this safe to ship without a migration or a
+ * coordinated deploy: no key derived from a database-hydrated value moves, and
+ * the pending-side keys that do move are exactly the ones that disagree with
+ * every hydrated-path writer of the same scope today.
+ *
+ * The classes handled, and what the hydrated value looks like:
+ *
+ * - `uuid` — Postgres renders UUIDs lowercase, so the canonical form is
+ *   lowercase.
+ * - `numeric` / `real` / `double precision` — hydrated through
+ *   `parsePostgresDecimal`, i.e. `parseFloat`, so `'1.00'` and `1` both
+ *   canonicalize to `'1'`.
+ * - `jsonb` — hydrated by `JSON.parse` of jsonb's own output, whose object keys
+ *   are ordered by key length and then bytewise. Objects are re-emitted in that
+ *   order, recursively, so property insertion order stops mattering.
+ * - `boolean` — hydrated as a JavaScript boolean; Postgres's own input literals
+ *   (`'t'`, `'yes'`, `'0'`, …) canonicalize to `'true'`/`'false'`.
+ * - `date` and the four timestamp/time types — hydrated as `CalendarDate`,
+ *   `DateTime`, `ClockTime` or `ClockTimeTz`, whose JSON form is the quoted ISO
+ *   string. Strings are quoted the same way so a pending `'2026-02-07'` and a
+ *   hydrated `CalendarDate` agree.
+ *
+ * Everything else — `bigint` and `character varying`, which is to say the
+ * foreign keys and text columns nearly every sort scope is made of — is left on
+ * the untyped normalization below, unchanged.
+ *
+ * Two residuals are known and accepted rather than fixed:
+ *
+ * - **`citext`**: Postgres stores the case a row was written with while
+ *   comparing case-insensitively, so two rows of one physical scope hydrate to
+ *   values that differ in case and split the key on their own. Lowercasing
+ *   would fix the split but would *move* hydrated keys, which is the one thing
+ *   this design refuses to do.
+ * - **Temporal values that agree on the instant but not on the text**: a zone
+ *   offset or a fractional-second precision that differs from the hydrated
+ *   rendering still yields a different key. Only the string-vs-object quoting
+ *   mismatch is canonicalized.
+ *
+ * Both are over-serialization or a missed exclusion between two *pending*-side
+ * writers, never a corrupt position under a key two writers do share.
+ *
+ * @param dream - the record whose scope column is being canonicalized
+ * @param column - the physical database column
+ * @param value - the pending or hydrated value held for that column
+ * @returns the canonical text form, or `null` for an absent value
+ */
+export default function canonicalScopeValue(dream, column, value) {
+    if (value === null || value === undefined)
+        return null;
+    switch (cachedTypeForAttribute(dream.constructor, column)) {
+        case 'uuid':
+            return canonicalUuid(value);
+        case 'numeric':
+        case 'real':
+        case 'double precision':
+            return canonicalNumeric(value);
+        case 'jsonb':
+            return canonicalJsonb(value);
+        case 'boolean':
+            return canonicalBoolean(value);
+        case 'date':
+        case 'timestamp without time zone':
+        case 'timestamp with time zone':
+        case 'time without time zone':
+        case 'time with time zone':
+            return canonicalTemporal(value);
+        default:
+            return untypedScopeValue(value);
+    }
+}
+/**
+ * @internal
+ *
+ * The type-blind fallback, and the shape every unrecognized `dbType` keeps:
+ * the same foreign key can arrive as a string or a number depending on the path
+ * that loaded it, so values are rendered as text and null is kept distinct from
+ * every string, including the empty one.
+ */
+export function untypedScopeValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+            return value.toString();
+        default:
+            return JSON.stringify(value) ?? null;
+    }
+}
+function canonicalUuid(value) {
+    return typeof value === 'string' ? value.toLowerCase() : untypedScopeValue(value);
+}
+function canonicalNumeric(value) {
+    const parsed = typeof value === 'number' ? value : parseFloat(String(value));
+    return Number.isFinite(parsed) ? String(parsed) : untypedScopeValue(value);
+}
+/**
+ * @internal
+ *
+ * Postgres's own boolean input literals, lower-cased and trimmed, which a
+ * pending value may hold while the hydrated value is a JavaScript boolean.
+ * Exported so the spec drives its cases from the sets themselves rather than
+ * from a hand-copied list that can silently drift out of step with them.
+ */
+export const BOOLEAN_TRUE_LITERALS = new Set(['t', 'true', 'y', 'yes', 'on', '1']);
+export const BOOLEAN_FALSE_LITERALS = new Set(['f', 'false', 'n', 'no', 'off', '0']);
+function canonicalBoolean(value) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        const literal = value.trim().toLowerCase();
+        if (BOOLEAN_TRUE_LITERALS.has(literal))
+            return 'true';
+        if (BOOLEAN_FALSE_LITERALS.has(literal))
+            return 'false';
+    }
+    return untypedScopeValue(value);
+}
+/**
+ * Temporal columns hydrate as `CalendarDate`/`DateTime`/`ClockTime` instances
+ * whose `toJSON` is the ISO string, so JSON-encoding both shapes puts a pending
+ * ISO string and its hydrated counterpart on the same quoted text.
+ */
+function canonicalTemporal(value) {
+    return JSON.stringify(value) ?? null;
+}
+/**
+ * jsonb neither stores nor renders property insertion order: it orders object
+ * keys by length and then bytewise, and a hydrated value therefore always
+ * arrives in that order. Re-emitting in the same order makes a pending object
+ * literal agree with it, and leaves every hydrated value byte-identical.
+ */
+function canonicalJsonb(value) {
+    const parsed = typeof value === 'string' ? parseJson(value) : value;
+    return JSON.stringify(inJsonbKeyOrder(parsed)) ?? null;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function inJsonbKeyOrder(value) {
+    if (Array.isArray(value))
+        return value.map(inJsonbKeyOrder);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.keys(value)
+        .sort(compareJsonbKeys)
+        .reduce((acc, key) => {
+        acc[key] = inJsonbKeyOrder(value[key]);
+        return acc;
+    }, {});
+}
+/**
+ * jsonb's own key collation: shorter keys first, ties broken by comparing the
+ * UTF-8 bytes.
+ */
+function compareJsonbKeys(a, b) {
+    const bytesA = UTF8.encode(a);
+    const bytesB = UTF8.encode(b);
+    if (bytesA.length !== bytesB.length)
+        return bytesA.length - bytesB.length;
+    for (let i = 0; i < bytesA.length; i++) {
+        if (bytesA[i] !== bytesB[i])
+            return bytesA[i] - bytesB[i];
+    }
+    return 0;
+}

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

@@ -1,5 +1,23 @@
 import sortableCacheValuesName from './sortableCacheValuesName.js';
+import { clearSortableSnapshot } from './sortableSnapshot.js';
 export default function clearCachedSortableValues(dream, positionField) {
     const cachedValuesName = sortableCacheValuesName(positionField);
     dream[cachedValuesName] = undefined;
 }
+/**
+ * @internal
+ *
+ * Discards both halves of what a save's sortable phase stashes on the
+ * instance: the cached values the position work reads, and the snapshot of the
+ * row it would have computed its shift against. The position work clears them
+ * itself as it consumes them, so this is for the paths where it does not run —
+ * the row was already gone when the snapshot read found it, or the save's
+ * transaction rolled back — leaving a later save of the same instance to read
+ * the row for itself rather than inherit this save's reading of it.
+ */
+export function clearSortableSaveState(dream, configs) {
+    for (const { positionField } of configs) {
+        clearCachedSortableValues(dream, positionField);
+        clearSortableSnapshot(dream, positionField);
+    }
+}

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

@@ -1,7 +1,7 @@
 import ops from '../../../../ops/index.js';
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import scopeArray from './scopeArray.js';
-export default async function decrementPositionForScopedRecordsGreaterThanPosition(position, { dream, positionField, query, scope, }) {
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import { snapshotScopeValue } from './sortableSnapshot.js';
+export default async function decrementPositionForScopedRecordsGreaterThanPosition(position, { dream, positionField, query, scope, snapshot, }) {
     let kyselyQuery = query
         .whereNot({ [dream['_primaryKey']]: dream.primaryKeyValue() })
         .where({
@@ -13,11 +13,11 @@ export default async function decrementPositionForScopedRecordsGreaterThanPositi
             [positionField]: eb(positionField, '-', 1),
         };
     });
-    for (const singleScope of scopeArray(scope)) {
-        const column = getColumnForSortableScope(dream, singleScope);
-        if (column) {
-            kyselyQuery = kyselyQuery.where(column, '=', dream[column]);
-        }
-    }
+    // A null scope value has to be matched with `is null`: `column = NULL` is
+    // never true, so the compaction would silently shift nothing at all in a
+    // null-valued sort scope. `filterQueryToScopeValues` is the one place that
+    // branch lives, and it is the same filter every other position-mutating path
+    // builds.
+    kyselyQuery = filterQueryToScopeValues(dream, kyselyQuery, column => snapshotScopeValue(snapshot, column, () => dream[column]), scope);
     await kyselyQuery.execute();
 }

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

@@ -0,0 +1,20 @@
+import sortableScopeColumns from './sortableScopeColumns.js';
+/**
+ * @internal
+ *
+ * Narrows a Dream `Query` to one sort scope, **reading the scope values off the
+ * in-memory instance**. That is only the scope the row physically occupies when
+ * the instance is known to agree with the row — inside a transaction that has
+ * just written those values, or on a record read under the scope lock.
+ *
+ * Where the row may have been moved by another writer, the caller wants
+ * `filterQueryToScopeValues` instead, which takes each column's value from the
+ * caller (the snapshot read under the lock) rather than from the instance.
+ */
+export default function filterQueryToInstanceScope(query, dream, scope) {
+    for (const column of sortableScopeColumns(dream, scope)) {
+        const value = dream[column];
+        query = query.where({ [column]: value ?? null });
+    }
+    return query;
+}

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

@@ -0,0 +1,32 @@
+import sortableScopeColumns from './sortableScopeColumns.js';
+/**
+ * @internal
+ *
+ * Narrows a kysely query to one sort scope, taking each scope column's value
+ * **from the caller** rather than from the in-memory instance — the snapshot
+ * read under the scope lock on the paths that compact a scope a record is
+ * leaving, which is not necessarily the scope the instance was loaded from.
+ *
+ * This is also the one place the null branch lives: a null scope value has to
+ * be matched with `is null`, since `column = NULL` is never true and the filter
+ * would silently match nothing at all in a null-valued sort scope.
+ *
+ * The instance-reading sibling is `filterQueryToInstanceScope`.
+ *
+ * @param dream - the record whose class resolves the scope members to columns
+ * @param kyselyQuery - the query to narrow
+ * @param whereValueCB - the value to match each scope column against
+ * @param scope - the sortable field's scope
+ */
+export default function filterQueryToScopeValues(dream, kyselyQuery, whereValueCB, scope) {
+    for (const column of sortableScopeColumns(dream, scope)) {
+        const columnValue = whereValueCB(column);
+        if (columnValue === null) {
+            kyselyQuery = kyselyQuery.where(column, 'is', null);
+        }
+        else {
+            kyselyQuery = kyselyQuery.where(column, '=', columnValue);
+        }
+    }
+    return kyselyQuery;
+}

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

@@ -0,0 +1,34 @@
+const heldKeysByTransaction = new WeakMap();
+/**
+ * @internal
+ *
+ * The sortable scope-lock keys this transaction already holds.
+ *
+ * Advisory transaction locks are released only when the transaction ends, so a
+ * key taken once is held for the rest of it: every later acquisition of that
+ * key is a statement whose entire effect is to observe that the transaction
+ * already has what it is asking for. Tracking them turns those statements into
+ * nothing at all — the per-field acquisition inside the position write, and
+ * every per-record acquisition inside a locked batch whose preflight already
+ * took the batch's whole key set.
+ *
+ * Being the transaction's whole ledger is also what lets the locked-batch
+ * preflight count its bound cumulatively rather than per batch: how many scope
+ * locks one more batch would leave the transaction holding is this set's size
+ * plus whatever of the batch's keys is not already in it.
+ *
+ * Keyed by the transaction object rather than by the connection, which is what
+ * makes it correct rather than merely fast: a nested transaction gets its own
+ * `DreamTransaction` and therefore its own set, so keys taken inside a
+ * subtransaction that rolls back — releasing its locks with it — are never
+ * remembered as held by the transaction that outlives it. The entry is
+ * discarded with the transaction object.
+ */
+export default function heldSortableScopeLockKeys(txn) {
+    const held = heldKeysByTransaction.get(txn);
+    if (held)
+        return held;
+    const newHeld = new Set();
+    heldKeysByTransaction.set(txn, newHeld);
+    return newHeld;
+}

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

@@ -0,0 +1,21 @@
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import afterSortableDestroy from '../hooks/afterSortableDestroy.js';
+/**
+ * @internal
+ *
+ * The compaction of a sortable destroy: closes the vacancy each sortable
+ * field's sort scope is left with, computed from the snapshot the preparation
+ * phase (`prepareSortableFieldsForDestroy`) read before the delete. Called
+ * directly from `destroyDream` after the delete and before any user
+ * `afterDestroy` hook — never registered as a hook among them — so every
+ * after-destroy hook observes the compacted scope regardless of where it was
+ * declared, exactly as every after-save hook observes the computed position.
+ */
+export default async function performSortableDestroyWork(dream, txn) {
+    const dreamClass = dream.constructor;
+    const sortableFields = dreamClass['sortableFields'];
+    for (const { positionField, scope } of sortableFields) {
+        const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
+        await afterSortableDestroy({ dream, positionField, query, scope, txn });
+    }
+}

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

@@ -0,0 +1,36 @@
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import afterSortableCreate from '../hooks/afterSortableCreate.js';
+import afterUpdateSortable from '../hooks/afterSortableUpdate.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import { sortableCurrentScopeLockKeys } from './sortableScopeLockKeys.js';
+/**
+ * @internal
+ *
+ * The position work of a sortable save: computes each sortable field's real
+ * position under the scope lock and writes it. Called directly from
+ * `saveDream` after the driver write — never registered as an after-hook — so
+ * no user hook code can interleave with it while the scope lock is held, and
+ * on a self-opened save it is the last work before COMMIT releases the lock.
+ */
+export default async function performSortablePositionWork(dream, txn, sortableFieldConfigs, { alreadyPersisted }) {
+    const dreamClass = dream.constructor;
+    // A create acquires its whole advisory key set here — every sortable field,
+    // one sorted pass — before any field's position is computed, so a
+    // multi-field create takes its keys in the same global order as an update or
+    // a destroy and cannot deadlock against them. The per-field acquisition
+    // inside `setPosition` then re-acquires keys this transaction already holds,
+    // which is a no-op. (An update acquired its keys before the driver write, in
+    // `saveDream`.)
+    if (!alreadyPersisted) {
+        await acquireSortableScopeLocks(dream, txn, sortableCurrentScopeLockKeys(dream, sortableFieldConfigs));
+    }
+    for (const { positionField, scope } of sortableFieldConfigs) {
+        const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
+        if (alreadyPersisted) {
+            await afterUpdateSortable({ dream, positionField, query, txn, scope });
+        }
+        else {
+            await afterSortableCreate({ dream, positionField, query, txn, scope });
+        }
+    }
+}

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