@rvoh/dream 2.20.0 → 2.22.0

package/dist/esm/src/dream/QueryDriver/Base.js

@@ -256,6 +256,32 @@ export default class QueryDriverBase {
     options = {}) {
         throw new Error('implement takeAll in child class');
     }
+    /**
+     * @internal
+     *
+     * Adapter seam for exclusive row locking. Given the select statement about to
+     * be executed, return a statement that additionally acquires an exclusive
+     * lock on each row it returns, held until the enclosing transaction commits
+     * or rolls back (Postgres: `SELECT ... FOR UPDATE OF <table>`).
+     *
+     * This is only ever reached when a caller opts into a locked read (today,
+     * `Query#destroy({ lock: true })`), and only from inside a transaction. The
+     * base implementation throws so that an adapter which has not implemented row
+     * locking fails loud rather than silently performing an unlocked read and
+     * quietly dropping the compare-and-set guarantee the caller asked for.
+     *
+     * @param kyselyQuery - the select statement to lock
+     * @param tableAlias - the alias of the Query's base table; only rows of that
+     * table are locked, so a joined query does not lock unrelated rows and does
+     * not fail on the nullable side of an outer join
+     */
+    applyRowLock(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    kyselyQuery, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    tableAlias) {
+        throw new Error('implement applyRowLock in child class');
+    }
     /**
      * Retrieves the max value of the specified column
      * for this Query

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -29,6 +29,9 @@ import MissingThroughAssociationSource from '../../errors/associations/MissingTh
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
 import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import ArrayEqualityRequiresArrayColumn from '../../errors/ops/ArrayEqualityRequiresArrayColumn.js';
+import RowLockIncompatibleWithDistinct from '../../errors/RowLockIncompatibleWithDistinct.js';
+import RowLockIncompatibleWithJoinLoad from '../../errors/RowLockIncompatibleWithJoinLoad.js';
 import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
 import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
 import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
@@ -39,6 +42,7 @@ import ASTSchemaBuilder from '../../helpers/cli/ASTSchemaBuilder.js';
 import generateMigration from '../../helpers/cli/generateMigration.js';
 import compact from '../../helpers/compact.js';
 import { normalizeDataForDb } from '../../helpers/db/normalizeDataForDb.js';
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import groupBy from '../../helpers/groupBy.js';
 import isEmpty from '../../helpers/isEmpty.js';
@@ -412,9 +416,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * @returns an array of dreams
      */
     async takeAll(options = {}) {
-        if (this.query['joinLoadActivated'])
+        if (this.query['joinLoadActivated']) {
+            // executeJoinLoad builds its own select and has nowhere to put a row
+            // lock, so a locked read here has to fail rather than quietly return
+            // unlocked rows and drop the guarantee the caller asked for
+            if (options.lock)
+                throw new RowLockIncompatibleWithJoinLoad();
             return await this.executeJoinLoad(options);
-        const kyselyQuery = this.buildSelect(options);
+        }
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database, so
+        // fail loudly here instead of emitting SQL that cannot run
+        if (options.lock && this.query['distinctColumn'])
+            throw new RowLockIncompatibleWithDistinct();
+        let kyselyQuery = this.buildSelect(options);
+        // row locking is adapter-specific, so it goes through the query driver seam
+        if (options.lock)
+            kyselyQuery = this.applyRowLock(kyselyQuery, this.query['baseSqlAlias']);
         const results = await executeDatabaseQuery(kyselyQuery, 'execute');
         const theAll = results.map(r => this.dbResultToDreamInstance(r, this.dreamClass));
         await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], theAll);
@@ -1484,8 +1501,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             b = '=';
             c = val;
         }
-        c = this.normalizedWhereValue(dreamClass, attr, c);
-        c2 = this.normalizedWhereValue(dreamClass, attr, c2);
+        c = maybeBindArrayAsSingleValue(dreamClass, a, b, this.normalizedWhereValue(dreamClass, attr, c));
+        c2 = maybeBindArrayAsSingleValue(dreamClass, a2, b2, this.normalizedWhereValue(dreamClass, attr, c2));
         if (a && c === undefined)
             throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, a);
         if (a2 && c2 === undefined)
@@ -2525,6 +2542,31 @@ export function resolvePostgresSsl(connectionConf) {
         return { rejectUnauthorized: false };
     return false;
 }
+const EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE = ['=', '!=', '<>'];
+/**
+ * Kysely renders a raw Javascript array passed as the right-hand side of a
+ * comparison as a value list (`($1, $2)`), which is what `in` / `not in` need,
+ * but which Postgres rejects for `=` against an array column
+ * (`operator does not exist: text[] = record`). For the equality operators,
+ * bind the array as a single parameter so that `ops.equal([...])` against an
+ * array column means literal array equality (`"col" = $1`).
+ *
+ * The rewrite is gated on the column actually being a database array column.
+ * An array reaching an equality operator against a *scalar* column is a
+ * mistake, and binding it as a single value would turn that mistake into a
+ * clause that matches nothing (`"name" = '{}'`) instead of one that raises, so
+ * it throws instead.
+ */
+function maybeBindArrayAsSingleValue(dreamClass, column, operator, val) {
+    if (!Array.isArray(val))
+        return val;
+    if (!EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE.includes(operator))
+        return val;
+    const isolatedColumn = maybeNamespacedColumnNameToColumnName(column ?? '');
+    if (!isDatabaseArrayColumn(dreamClass, isolatedColumn))
+        throw new ArrayEqualityRequiresArrayColumn(dreamClass, isolatedColumn, operator);
+    return sql.val(val);
+}
 function shouldSoftDelete(dream, reallyDestroy) {
     const dreamClass = dream.constructor;
     return dreamClass['softDelete'] && !reallyDestroy;

package/dist/esm/src/dream/QueryDriver/Postgres.js

@@ -198,6 +198,27 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
         await client.end();
         DreamCLI.logger.logEndProgress();
     }
+    /**
+     * @internal
+     *
+     * Postgres implementation of the row-locking seam: appends
+     * `FOR UPDATE OF "<tableAlias>"` to the select, so every row the statement
+     * returns is exclusively locked until the enclosing transaction ends.
+     *
+     * Scoping the lock to the Query's own base table (rather than a bare
+     * `FOR UPDATE`) means a query that joins other tables neither locks rows the
+     * caller never asked about nor raises Postgres's "FOR UPDATE cannot be
+     * applied to the nullable side of an outer join".
+     *
+     * This is a waiting lock: neither `NOWAIT` nor `SKIP LOCKED` is applied, so a
+     * statement that collides with another transaction's lock blocks until that
+     * transaction ends. Callers that cannot afford an unbounded wait should set a
+     * `lock_timeout` on the connection; see the guarded-destroy notes on
+     * `Query#destroy`.
+     */
+    applyRowLock(kyselyQuery, tableAlias) {
+        return kyselyQuery.forUpdate(tableAlias);
+    }
     static supportsParallelTestDatabases = true;
     /**
      * @internal

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

@@ -1,20 +1,69 @@
+import loadDependentDestroyTree from './loadDependentDestroyTree.js';
+/**
+ * @internal
+ *
+ * Marks a Dream instance as one whose `dependent: 'destroy'` associations were
+ * hydrated by this cascade's own call to `loadDependentDestroyTree`, using the
+ * same destroy options the cascade is running under.
+ *
+ * Associations a caller happened to preload themselves (e.g.
+ * `Post.preload('comments')`) are deliberately NOT trusted: they may have been
+ * loaded under different default scopes than the destroy requires — most
+ * importantly, `reallyDestroy` strips the soft-delete scope, so a
+ * caller-preloaded association could be missing soft-deleted records that the
+ * cascade must destroy.
+ */
+const CASCADE_LOADED = Symbol.for('dream:dependentDestroyTreeLoaded');
 /**
  * @internal
  *
  * Destroys all HasOne/HasMany associations on this
  * dream that are marked as `dependent: 'destroy'`.
  *
- * Expects associations to be preloaded onto the dream instance
- * via `loadDependentDestroyTree`. Iterates loaded associations
- * directly instead of querying the database.
+ * The whole dependent-destroy tree is loaded ONCE, at the root of the destroy
+ * operation, by `loadDependentDestroyTree`. Descendants reached by recursing
+ * through this function consume those already-hydrated associations rather
+ * than re-querying their own subtrees.
+ *
+ * A load still happens here when an association is not hydrated. That covers
+ * two cases:
+ *
+ * 1. the root of the operation, whose associations have not been loaded yet
+ * 2. a node past `RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS` levels of
+ *    self-reference, which the root's preload could not reach
+ *
+ * The second case is why the check is per-association-hydration rather than a
+ * "descendants are already loaded" flag: such a flag would truncate cascades
+ * deeper than the preload horizon.
+ *
+ * NOTE: reusing a hydrated subtree is only sound because the same `options`
+ * are forwarded unchanged all the way down the cascade (see the recursive
+ * `destroy`/`reallyDestroy` calls below), so every node's associations were
+ * loaded under the scopes this node would have used. Nothing in the types
+ * enforces that; if `options` ever start varying by depth, this reuse has to
+ * be revisited.
  */
 export default async function destroyAssociatedRecords(dream, txn, options) {
     const dreamClass = dream.constructor;
     const { reallyDestroy } = options;
+    // `loadDependentDestroyTree` hydrates and returns a CLONE rather than
+    // mutating the receiver, so the result must be assigned back — otherwise
+    // each association in the loop below would trigger its own reload.
+    let dreamWithAssociations = dream;
+    let alreadyLoadedTree = false;
     for (const associationName of dreamClass['dependentDestroyAssociationNames']()) {
-        const loaded = dream[associationName];
+        if (!alreadyLoadedTree && !cascadeLoaded(dreamWithAssociations, associationName)) {
+            dreamWithAssociations = await loadDependentDestroyTree(dreamWithAssociations, txn, {
+                reallyDestroy,
+                bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
+                defaultScopesToBypass: options.defaultScopesToBypass ?? [],
+            });
+            alreadyLoadedTree = true;
+        }
+        const loaded = dreamWithAssociations[associationName];
         const records = Array.isArray(loaded) ? loaded : loaded ? [loaded] : [];
         for (const record of records) {
+            markCascadeLoaded(record);
             if (reallyDestroy) {
                 await record.txn(txn).reallyDestroy(options);
             }
@@ -24,3 +73,26 @@ export default async function destroyAssociatedRecords(dream, txn, options) {
         }
     }
 }
+/**
+ * @internal
+ *
+ * True when this dream was hydrated by this cascade's own preload AND the
+ * given association is hydrated on it.
+ */
+function cascadeLoaded(dream, associationName) {
+    if (!dream[CASCADE_LOADED])
+        return false;
+    return dream.loaded(associationName);
+}
+/**
+ * @internal
+ *
+ * A plain assignment rather than `Object.defineProperty`: the key is a symbol,
+ * so it is already excluded from `Object.keys`, `for...in` and
+ * `JSON.stringify` without an explicit descriptor, and this runs once per node
+ * of a potentially wide cascade tree.
+ */
+function markCascadeLoaded(dream) {
+    ;
+    dream[CASCADE_LOADED] = true;
+}

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

@@ -1,6 +1,5 @@
 import DreamApp from '../../dream-app/index.js';
 import destroyAssociatedRecords from './destroyAssociatedRecords.js';
-import loadDependentDestroyTree from './loadDependentDestroyTree.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -31,12 +30,12 @@ export default async function destroyDream(dream, txn = null, options) {
 async function destroyDreamWithTransaction(dream, txn, options) {
     const { cascade, reallyDestroy, skipHooks } = options;
     if (cascade) {
-        const dreamWithAssociations = await loadDependentDestroyTree(dream, txn, {
-            reallyDestroy,
-            bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
-            defaultScopesToBypass: options.defaultScopesToBypass ?? [],
-        });
-        await destroyAssociatedRecords(dreamWithAssociations, txn, options);
+        // NOTE: the dependent-destroy tree is loaded lazily, inside
+        // destroyAssociatedRecords, so that a cascaded descendant whose
+        // associations the root already preloaded does not re-query its own
+        // subtree. `dream` itself is intentionally never replaced by the loaded
+        // clone: the hooks and the delete below operate on the original.
+        await destroyAssociatedRecords(dream, txn, options);
     }
     if (!skipHooks) {
         await runHooksFor('beforeDestroy', dream, true, null, txn);

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

@@ -0,0 +1,19 @@
+export default class InvalidBatchSize extends Error {
+    batchSize;
+    constructor(batchSize) {
+        super();
+        this.batchSize = batchSize;
+    }
+    get message() {
+        return `
+Invalid batchSize provided.
+
+batchSize given:
+  ${String(this.batchSize)}
+
+batchSize must be a positive integer. A batchSize of 0 is especially dangerous,
+since a limit of 0 is treated as "no limit", which would collapse a batched
+operation into a single unbounded pass over the entire matched set.
+`;
+    }
+}

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

@@ -0,0 +1,17 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table;
+    alterDirection;
+    constructor(table, alterDirection) {
+        super();
+        this.table = table;
+        this.alterDirection = alterDirection;
+    }
+    get message() {
+        return `
+no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+
+Pass at least one column declaration with a resolvable type, e.g.:
+  name:string
+    `;
+    }
+}

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithDistinct extends Error {
+    get message() {
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database
+        // ("FOR UPDATE is not allowed with DISTINCT clause"), so fail here, with a
+        // message that names the two incompatible parts, rather than surfacing a
+        // raw driver error from inside a per-batch transaction.
+        return `
+An exclusive row lock was requested on a query that also calls \`distinct\`.
+
+A locked read cannot be combined with DISTINCT. Drop the \`distinct\` call, or
+drop the lock.
+`;
+    }
+}

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

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithJoinLoad extends Error {
+    get message() {
+        // A join load builds its own select statement (one row per joined
+        // association row, later collapsed in memory), which cannot carry the
+        // Query's row lock. Rather than silently performing an unlocked read and
+        // dropping the compare-and-set guarantee the caller asked for, refuse.
+        return `
+An exclusive row lock was requested on a query that also uses leftJoinPreload.
+
+A join-loaded query cannot be locked. Use \`preload\` instead of
+\`leftJoinPreload\`, or drop the lock.
+`;
+    }
+}

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

@@ -0,0 +1,16 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration;
+    constructor(declaration) {
+        super();
+        this.declaration = declaration;
+    }
+    get message() {
+        return `
+could not determine a column type for the following migration column declaration:
+  ${this.declaration}
+
+Make sure the column includes a type, e.g.:
+  ${this.declaration.split(':')[0]}:string
+    `;
+    }
+}

package/dist/esm/src/errors/ops/ArrayEqualityRequiresArrayColumn.js

@@ -0,0 +1,23 @@
+export default class ArrayEqualityRequiresArrayColumn extends Error {
+    dreamClass;
+    column;
+    operator;
+    constructor(dreamClass, column, operator) {
+        super();
+        this.dreamClass = dreamClass;
+        this.column = column;
+        this.operator = operator;
+    }
+    get message() {
+        return `
+Attempting to compare an array for equality against a column that is not an
+array in the database:
+
+  ${this.dreamClass.sanitizedName}#${this.column} (operator: ${this.operator})
+
+Whole-array equality (\`=\`, \`!=\`, \`<>\`) is only meaningful for array columns.
+If you meant "is this column one of these values", use \`ops.in([...])\`
+(or a bare array) instead.
+`;
+    }
+}

package/dist/esm/src/helpers/cli/generateMigration.js

@@ -1,6 +1,6 @@
 import * as path from 'node:path';
 import pluralize from 'pluralize-esm';
-import generateMigrationContent from '../cli/generateMigrationContent.js';
+import generateMigrationContent, { MIGRATION_TABLE_NAME_PLACEHOLDER, } from '../cli/generateMigrationContent.js';
 import primaryKeyType from '../db/primaryKeyType.js';
 import hyphenize from '../hyphenize.js';
 import migrationVersion from '../migrationVersion.js';
@@ -9,6 +9,18 @@ import dreamPath from '../path/dreamPath.js';
 import snakeify from '../snakeify.js';
 import generateStiMigrationContent from './generateStiMigrationContent.js';
 import writeGeneratedFile from './writeGeneratedFile.js';
+/**
+ * Equivalent to `migrationName.match(new RegExp(`${marker}(.+)$`))?.[1]`, but
+ * without a regex: CodeQL flags `.+` anchored to `$` as a polynomial-ReDoS
+ * shape, and a plain `indexOf`/`slice` does the same leftmost-match-to-end
+ * job with no backtracking risk.
+ */
+function tableNameFromSuffix(migrationName, marker) {
+    const markerIndex = migrationName.indexOf(marker);
+    if (markerIndex === -1)
+        return undefined;
+    return migrationName.slice(markerIndex + marker.length) || undefined;
+}
 export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
@@ -33,12 +45,17 @@ export default async function generateMigration({ migrationName, columnsWithType
         });
     }
     else {
-        const tableName = migrationName.match(/-to-(.+)$/)?.[1];
+        const toTableName = tableNameFromSuffix(migrationName, '-to-');
+        const fromTableName = toTableName
+            ? undefined
+            : tableNameFromSuffix(migrationName, '-from-');
+        const tableName = toTableName || fromTableName;
         content = generateMigrationContent({
-            table: tableName ? pluralize(snakeify(tableName)) : '<table-name>',
+            table: tableName ? pluralize(snakeify(tableName)) : MIGRATION_TABLE_NAME_PLACEHOLDER,
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             createOrAlter: 'alter',
+            alterDirection: fromTableName ? 'remove' : 'add',
         });
     }
     await writeGeneratedFile({

package/dist/esm/src/helpers/cli/generateMigrationContent.js

@@ -2,11 +2,19 @@ import pluralize from 'pluralize-esm';
 import lookupModelByGlobalName from '../../dream-app/helpers/lookupModelByGlobalName.js';
 import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
+import NoColumnsToAlterMigration from '../../errors/NoColumnsToAlterMigration.js';
+import UnparseableMigrationColumn from '../../errors/UnparseableMigrationColumn.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
+// Sentinel table name used by generateMigration.ts when a standalone
+// migration name matches neither a `-to-<table>` nor `-from-<table>` suffix.
+// That path intentionally produces a stub the user is expected to hand-edit
+// (e.g. an index-only migration with no column operations at all), so it's
+// exempt from the "no valid columns" check below.
+export const MIGRATION_TABLE_NAME_PLACEHOLDER = '<table-name>';
 const STI_TYPE_COLUMN_NAME = 'type';
 // deleted_at is deliberately NOT in this list: the SoftDelete default scope's
 // `WHERE deleted_at IS NULL` is unselective on healthy tables, Dream internals
@@ -15,8 +23,9 @@ const STI_TYPE_COLUMN_NAME = 'type';
 // default. See spec/unit/cli/generateMigrationContent.spec.ts
 // ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
+export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', alterDirection = 'add', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
+    const removingInUp = altering && alterDirection === 'remove';
     let requireCitextExtension = false;
     const checkConstraints = [];
     // When creating a new table, we automatically emit `created_at`,
@@ -65,7 +74,17 @@ export default function generateMigrationContent({ connectionName = 'default', t
         // when creating a migration for an STI child, we don't want to include notNull;
         // instead, we'll add a check constraint that uses the STI child class name
         const sqlAttributeType = getAttributeType(attributeType, descriptors);
-        if (attributeType === undefined || ['hasone', 'hasmany'].includes(processedAttrType))
+        if (attributeType === undefined) {
+            // In alter mode (both `-to-`/add and `-from-`/remove), a column whose
+            // type can't be resolved (e.g. a mistyped declaration with no `:type`
+            // segment) must not silently vanish from the generated migration —
+            // that's especially dangerous for `-from-` migrations, whose whole
+            // premise is describing removed columns so `down` can restore them.
+            if (altering)
+                throw new UnparseableMigrationColumn(attributeDeclaration);
+            return acc;
+        }
+        if (['hasone', 'hasmany'].includes(processedAttrType))
             return acc;
         if (attributeType === 'citext')
             requireCitextExtension = true;
@@ -169,6 +188,25 @@ export async function down(db: Kysely<any>): Promise<void> {
 }\
 `;
     }
+    // An alter migration (either `-to-`/add or `-from-`/remove) with no valid
+    // columns to add/drop would otherwise emit a bare `.alterTable(...).execute()`
+    // with no column operation at all, which Postgres rejects at migration-run
+    // time rather than generation time. Fail loudly here instead.
+    //
+    // This guard is scoped to the standalone `g:migration` `-to-`/`-from-` flow
+    // only (`stiChildClassName` is unset there). `g:sti-child` legitimately
+    // calls this function in alter mode with zero `columnsWithTypes` — a
+    // zero-attribute STI child is a documented use case (see `g:sti-child`'s
+    // help example in src/cli/index.ts), and `generateStiMigrationContent`
+    // handles the type-column/check-constraint machinery separately from the
+    // `columnDefs` this check inspects, so an empty `columnDefs` there is
+    // expected, not a sign of a mistyped/unparseable column list.
+    if (altering &&
+        columnDefs.length === 0 &&
+        table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
+        !stiChildClassName) {
+        throw new NoColumnsToAlterMigration(table, alterDirection);
+    }
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`
         : '';
@@ -179,7 +217,22 @@ export async function down(db: Kysely<any>): Promise<void> {
     const newlineIndent = '\n  ';
     const newlineDoubleIndent = '\n    ';
     const doubleNewlineIndent = '\n\n  ';
-    const columnDefLines = columnDefs.length ? newlineDoubleIndent + columnDefs.join(newlineDoubleIndent) : '';
+    // For a `-from-` migration (`alterDirection: 'remove'`), `down` re-adds the
+    // column(s) that `up` removed. The generator has no way to know the
+    // column's original default, so a non-optional (`.notNull()`) column with
+    // no default emitted here will fail at migration-run time against a table
+    // that already has rows. We can't fix that without a lot more heavy
+    // lifting (and the risk that comes with it), so flag it with a comment
+    // instead of silently generating a `down` that's likely to break.
+    const NO_KNOWN_DEFAULT_COMMENT = "// NOTE: the generator doesn't know this column's original default; this addColumn will fail against a table with existing rows unless you add a default by hand.";
+    const finalColumnDefs = removingInUp
+        ? columnDefs.map(def => def.includes('.notNull()') && !def.includes('.defaultTo(')
+            ? `${NO_KNOWN_DEFAULT_COMMENT}\n    ${def}`
+            : def)
+        : columnDefs;
+    const columnDefLines = finalColumnDefs.length
+        ? newlineDoubleIndent + finalColumnDefs.join(newlineDoubleIndent)
+        : '';
     const columnDropLines = columnDrops.length
         ? newlineDoubleIndent + columnDrops.join(newlineDoubleIndent) + newlineDoubleIndent
         : '';
@@ -190,21 +243,33 @@ export async function down(db: Kysely<any>): Promise<void> {
             newlineDoubleIndent +
             ".addColumn('updated_at', 'timestamp', col => col.notNull())" +
             (emitDeletedAtColumn ? newlineDoubleIndent + ".addColumn('deleted_at', 'timestamp')" : '');
+    // For `alterDirection: 'remove'` (a `-from-` migration), the enum *type*
+    // itself must never be created or dropped here, even when the column
+    // declaration includes inline enum values — enums are frequently reused
+    // across columns/tables, so `up` must drop only the column (no `dropType`)
+    // and `down` must re-add only the column (no `createType`), identical to
+    // referencing an existing enum by name with no values.
+    const enumCreateStatements = removingInUp ? '' : generateEnumStatements(columnsWithTypes);
+    const enumDropStatements = removingInUp ? '' : generateEnumDropStatements(columnsWithTypes);
+    const addColumnsBody = `${citextExtension}${enumCreateStatements}  await db.schema
+    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
+    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}`;
+    const removeColumnsBody = `  ${altering
+        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
+        : `await db.schema.dropTable('${table}').execute()`}${enumDropStatements}`;
+    const upBody = removingInUp ? removeColumnsBody : addColumnsBody;
+    const downBody = removingInUp ? addColumnsBody : removeColumnsBody;
     return `\
 ${dreamDbImports.length ? `import { ${dreamDbImports.join(', ')} } from '@rvoh/dream/db'\n` : ''}import { ${kyselyImports.join(', ')} } from 'kysely'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function up(db: Kysely<any>): Promise<void> {
-${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
-    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
-    .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}
+${upBody}
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function down(db: Kysely<any>): Promise<void> {
-  ${altering
-        ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
-        : `await db.schema.dropTable('${table}').execute()`}${generateEnumDropStatements(columnsWithTypes)}
+${downBody}
 }\
 `;
 }

package/dist/esm/src/ops/index.js

@@ -117,11 +117,27 @@ const ops = {
     /**
      * Creates an `OpsStatement` using the `=` operator for strict equality.
      *
+     * **Array columns:** passing an array means literal array equality — the
+     * whole array is bound as a single parameter, so the column must match
+     * element-for-element, in order. This is the opt-in counterpart to a bare
+     * array in a where clause (`Post.where({ tags: ['a', 'b'] })`), which means
+     * `IN`, and to `ops.any`, which tests for containment of a single element.
+     * Element types are constrained by the column, so an enum array column
+     * rejects a string that is not a member of its enum.
+     *
+     * Note that PostgreSQL defines no equality operator for `json` (as opposed
+     * to `jsonb`), so `ops.equal` against a `json[]` column raises at the
+     * database.
+     *
      * @param equal - The value the column must equal.
      * @returns An `OpsStatement` using the `=` operator.
      *
      * @example
      * User.where({ role: ops.equal('admin') })
+     *
+     * @example
+     * // matches only rows whose tags column is exactly ['a', 'b'], in that order
+     * Post.where({ tags: ops.equal(['a', 'b']) })
      */
     equal: (equal) => new OpsStatement('=', equal),
     /**
@@ -260,6 +276,9 @@ const ops = {
         /**
          * Creates an `OpsStatement` using the `!=` operator for inequality.
          *
+         * **Array columns:** as with `ops.equal`, passing an array compares against
+         * the whole array rather than against its elements.
+         *
          * @param equal - The value the column must not equal.
          * @returns An `OpsStatement` using the `!=` operator.
          *

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

@@ -1011,6 +1011,9 @@ export default class Dream {
      * // User{email: 'goodbye@world'}
      * ```
      *
+     * Records are always visited in ascending primary key order; any `order`
+     * applied to the query is discarded. See {@link Query.findEach} for why.
+     *
      * @param cb - The callback to call for each found record
      * @param opts - Optional parameters for batch processing
      * @param opts.batchSize - the batch size you wish to collect records in. If not provided, it will default to 1000

package/dist/types/src/cli/index.d.ts

@@ -14,7 +14,7 @@ export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
     args?: string[];
 };
 export declare const CLI_INDENT = "                  ";
-export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
+export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                      - boolean\n                      - boolean[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export declare const columnsWithTypesDescriptionForStiChild: string;
 export default class DreamCLI {
     /**