@rvoh/dream 2.21.1 → 2.22.0

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/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/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/dream/DreamClassTransactionBuilder.d.ts

@@ -384,6 +384,9 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * // 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 options.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void

package/dist/types/src/dream/Query.d.ts

@@ -16,6 +16,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      */
     static readonly BATCH_SIZES: {
         FIND_EACH: number;
+        LOCKED_DESTROY: number;
         PLUCK_EACH: number;
         PLUCK_EACH_THROUGH: number;
     };
@@ -282,13 +283,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * records matching the Query have been fetched.
      *
      * ```ts
-     * await User.order('id').findEach(user => {
+     * await User.where({ deletedAt: null }).findEach(user => {
      *   DreamApp.log(user)
      * })
      * // User{id: 1}
      * // User{id: 2}
      * ```
      *
+     * IMPORTANT: `findEach` always iterates in ascending primary key order.
+     * Any `order` applied to the Query is discarded; passing one has no effect
+     * on the order records are visited in.
+     *
+     * This is not a limitation that can be lifted. `findEach` guarantees that
+     * every matching record is visited exactly once, and it delivers that by
+     * paginating on a keyset: each batch selects the next `batchSize` records
+     * with a primary key greater than the last record of the previous batch.
+     * That guarantee only holds over a stable, unique key. Ordering by a
+     * mutable, non-unique column would mean a record whose sort value changed
+     * partway through the iteration could be skipped entirely or visited twice.
+     * ({@link Query.cursorPaginate} can honor an arbitrary order precisely
+     * because a paginated UI tolerates that anomaly; a full traversal cannot.)
+     *
+     * If you need records processed in a particular order, load them with a
+     * regular ordered query instead of `findEach`.
+     *
      * @param cb - The callback to call for each found record
      * @param __namedParameters - Options for batch processing
      * @param __namedParameters.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
@@ -1209,17 +1227,131 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * // 12
      * ```
      *
+     * ## Guarded (compare-and-set) destroy
+     *
+     * By default, `destroy` reads the matching records and then destroys each of
+     * them, so a concurrent writer can change a record in between — the record is
+     * destroyed even though it no longer matches the Query that selected it.
+     * Passing `lock: true` closes that window, making `destroy` a compare-and-set
+     * the way `update(..., { skipHooks: true })` already is:
+     *
+     * ```ts
+     * const destroyed = await Order.where({ status: 'pending' }).destroy({ lock: true })
+     * // 0 — someone else moved every one of them out of 'pending' first
+     * ```
+     *
+     * With `lock: true`, records are processed in batches, and each batch runs in
+     * its own transaction which first re-selects that batch's records with an
+     * exclusive row lock and then destroys them before committing. Because the
+     * database re-checks the Query's conditions after acquiring each row lock,
+     * a record a concurrent transaction has already moved out of the Query drops
+     * out of the locked read and is never destroyed. The returned count is the
+     * number of records actually claimed, so a caller can detect that it lost a
+     * race by comparing the count against what it expected.
+     *
+     * Things to know before relying on it:
+     *
+     * - **The guarantee is per batch, not set-wide.** A run spanning more than one
+     *   batch can win a race in batch 1 and lose one in batch 2; nothing holds the
+     *   whole matched set still for the duration of the run. Sharing one
+     *   transaction across every batch — by threading a transaction onto the Query
+     *   itself, `Order.query().txn(txn).where({ ... }).destroy({ lock: true })` —
+     *   buys two things: the destroys become all-or-nothing (a rollback undoes the
+     *   whole run), and the row locks taken by every batch are held until you
+     *   commit. It does **not** extend the compare-and-set to the part of the set
+     *   the run has not reached yet: under READ COMMITTED each statement takes a
+     *   fresh snapshot, so a record moved out of the Query between batch 1 and
+     *   batch 2 still drops out of batch 2's locked read. A genuinely set-wide
+     *   guarantee needs REPEATABLE READ / SERIALIZABLE, or a single locking
+     *   statement over the whole set.
+     * - **Only a transaction carried by the Query is shared.** Merely wrapping the
+     *   call in `Model.transaction(...)` does not thread that transaction onto the
+     *   Query — `Dream.transaction` establishes no ambient transaction, it only
+     *   hands a `txn` to your callback — so each batch would open its own
+     *   transaction on a different pooled connection. Worse, if the surrounding
+     *   transaction has already written to any of the matched rows, each batch's
+     *   locked read blocks on locks the surrounding transaction holds while that
+     *   transaction awaits the destroy: a cycle across two connections, which
+     *   Postgres's deadlock detector cannot see, so it hangs rather than aborting.
+     *   Always pass the transaction with `.txn(txn)`.
+     * - **Behavior above READ COMMITTED differs.** The drop-out-of-the-result
+     *   behavior described above is READ COMMITTED (Postgres's default). Under
+     *   REPEATABLE READ or SERIALIZABLE, the same race raises a serialization
+     *   failure instead of silently returning a lower count. Both are safe; only
+     *   one of them is quiet.
+     * - **`batchSize` defaults to 10 here**, not `findEach`'s 1000, and the
+     *   default is deliberately small. Every row in a batch stays locked for the
+     *   whole batch, including the time spent running each record's hooks and
+     *   `dependent: 'destroy'` cascade, so an oversized batch blocks unrelated
+     *   writers touching those rows and surfaces as timeouts somewhere else in the
+     *   application, which is very hard to trace back to this destroy. Too small a
+     *   batch, by contrast, only slows down this call, which you can see and fix.
+     *   Lower it further for models with deep `dependent: 'destroy'` cascades or
+     *   expensive destroy hooks.
+     * - **A batch waits, without bound, for whoever holds the row.** The locked
+     *   read is a plain `FOR UPDATE`: if another transaction already holds a lock
+     *   on one of the batch's rows, this call blocks until that transaction ends,
+     *   holding its own transaction and its pooled connection open the whole
+     *   time. Dream sets no `lock_timeout` or `statement_timeout`, so a
+     *   long-running writer on the other side stalls the run indefinitely and, at
+     *   scale, ties up connections. If that is a risk in your application, set a
+     *   `lock_timeout` on the connection so a stuck batch fails instead of
+     *   hanging.
+     * - **If you are destroying a large set and do not need compare-and-set, do
+     *   not pass `lock`.** Plain `destroy()` (hooks and cascade, no locking) or
+     *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
+     *   are the right tools for bulk removal.
+     *
      * @param __namedParameters - Options for destroying the instance
      * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
+     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
      * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
      * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    destroy({ skipHooks, cascade, }?: {
+    destroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean | undefined;
         cascade?: boolean | undefined;
+        lock?: boolean | undefined;
+        batchSize?: number | undefined;
     }): Promise<number>;
+    /**
+     * @internal
+     *
+     * The compare-and-set implementation behind `destroy({ lock: true })`.
+     *
+     * Each batch is handled in two steps inside one transaction:
+     *
+     * 1. an unlocked pluck of the next `batchSize` primary keys, in ascending
+     *    primary key order, which establishes the batch's window (its keyset
+     *    cursor) and tells us how many records were *attempted*. Only the keys are
+     *    read: hydrating and preloading these records would duplicate the work
+     *    step 2 does over the same rows; then
+     * 2. a locked re-read restricted to exactly those primary keys, which
+     *    re-applies every condition on the Query while acquiring an exclusive row
+     *    lock on each row it returns. Records a concurrent transaction has moved
+     *    out of the Query since step 1 do not come back, and are the records this
+     *    run lost the race for.
+     *
+     * The count comes from step 2's result set, which is why it reports records
+     * actually claimed rather than records attempted. (One thing it does not
+     * account for, because it never has: a `beforeDestroy` hook that sets
+     * `_preventDeletion` leaves the record in place but still counts.)
+     *
+     * The two-step shape is what keeps iteration correct. If the locked read both
+     * claimed rows and advanced the cursor, a batch whose records all lost the
+     * race would come back empty and end the run early, silently skipping every
+     * record after it. Advancing the cursor from step 1 instead means losing a
+     * race skips only the records that were lost.
+     *
+     * When the Query already carries a transaction, that transaction is used for
+     * every batch rather than opening one per batch, so the caller's transaction
+     * boundary wins and the locks are held until the caller commits.
+     */
+    private lockedDestroy;
     /**
      * Destroys all records matching the Query,
      * ignoring the SoftDelete decorator and
@@ -1241,13 +1373,18 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @param __namedParameters - Options for destroying the instance
      * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
+     * @param __namedParameters.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
      * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
      * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
+     * @throws InvalidBatchSize if `batchSize` is not a positive integer
      */
-    reallyDestroy({ skipHooks, cascade, }?: {
+    reallyDestroy({ skipHooks, cascade, lock, batchSize, }?: {
         skipHooks?: boolean;
         cascade?: boolean;
+        lock?: boolean;
+        batchSize?: number;
     }): Promise<number>;
     /**
      * Undestroys a SoftDelete model, unsetting

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -190,7 +190,28 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      */
     takeAll(options?: {
         columns?: DreamColumnNames<DreamInstance>[];
+        lock?: boolean;
     }): Promise<DreamInstance[]>;
+    /**
+     * @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(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     /**
      * Retrieves the max value of the specified column
      * for this Query

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -142,6 +142,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      */
     takeAll(options?: {
         columns?: DreamColumnNames<DreamInstance>[];
+        lock?: boolean;
     }): Promise<DreamInstance[]>;
     /**
      * Retrieves the max value of the specified column

package/dist/types/src/dream/QueryDriver/Postgres.d.ts

@@ -1,3 +1,4 @@
+import { type SelectQueryBuilder } from 'kysely';
 import Dream from '../../Dream.js';
 import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
 import KyselyQueryDriver from './Kysely.js';
@@ -34,6 +35,25 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
         [key: string]: SchemaBuilderColumnData;
     }>;
     static duplicateDatabase(connectionName: string): Promise<void>;
+    /**
+     * @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: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     static supportsParallelTestDatabases: boolean;
     /**
      * @internal

package/dist/types/src/dream/internal/destroyAssociatedRecords.d.ts

@@ -7,8 +7,27 @@ import { ReallyDestroyOptions } from './destroyDream.js';
  * 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 function destroyAssociatedRecords<I extends Dream>(dream: I, txn: DreamTransaction<I>, options: ReallyDestroyOptions<I>): Promise<void>;

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

@@ -0,0 +1,5 @@
+export default class InvalidBatchSize extends Error {
+    private batchSize;
+    constructor(batchSize: unknown);
+    get message(): string;
+}

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

@@ -0,0 +1,3 @@
+export default class RowLockIncompatibleWithDistinct extends Error {
+    get message(): string;
+}

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

@@ -0,0 +1,3 @@
+export default class RowLockIncompatibleWithJoinLoad extends Error {
+    get message(): string;
+}

package/dist/types/src/errors/ops/ArrayEqualityRequiresArrayColumn.d.ts

@@ -0,0 +1,8 @@
+import Dream from '../../Dream.js';
+export default class ArrayEqualityRequiresArrayColumn extends Error {
+    dreamClass: typeof Dream;
+    column: string;
+    operator: string;
+    constructor(dreamClass: typeof Dream, column: string, operator: string);
+    get message(): string;
+}

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

@@ -112,11 +112,27 @@ declare 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: <const T>(equal: T) => OpsStatement<"=", T, undefined>;
     /**
@@ -269,6 +285,9 @@ declare 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/types/associations/shared.d.ts

@@ -8,7 +8,7 @@ import { ClockTime, ClockTimeTz } from '../../package-exports/index.js';
 import CalendarDate from '../../utils/datetime/CalendarDate.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
 import { AssociationTableNames } from '../db.js';
-import { DefaultScopeName, DefaultScopeNameForTable, DreamBelongsToAssociationMetadata, DreamColumnNames, GlobalModelNameTableMap, ModelColumnType, OrderDir, TableColumnEnumTypeArray, TableColumnNames, TableColumnType, TableNameForGlobalModelName, TrigramOperator } from '../dream.js';
+import { DefaultScopeName, DefaultScopeNameForTable, DreamBelongsToAssociationMetadata, DreamColumnNames, GlobalModelNameTableMap, ModelColumnType, OrderDir, TableColumnEnumTypeArray, TableColumnIsArray, TableColumnNames, TableColumnType, TableNameForGlobalModelName, TrigramOperator } from '../dream.js';
 import { Inc, MergeUnionOfRecordTypes, ReadonlyTail, UnionToIntersection } from '../utils.js';
 import { JoinedAssociation } from '../variadic.js';
 import { BelongsToStatement } from './belongsTo.js';
@@ -25,7 +25,7 @@ export type PassthroughOnClause<PassthroughColumns extends string[]> = Partial<R
 type DreamSelectable<DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<{
     [ColumnName in keyof DB[TableName]]: NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, ColumnName>;
 }>;
-type NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, Column, ModelPropertyType = ModelColumnType<Schema, TableName, Column>, ColumnType = TableColumnType<Schema, TableName, Column>, EnumTypeArray extends string[] | null = TableColumnEnumTypeArray<Schema, TableName, Column>, PermanentOpsValTypes = null | readonly [], OpsValType = EnumTypeArray extends null ? ColumnType extends 'bigint' ? TypesAllowedForBigintAgainstTheDb | PermanentOpsValTypes : ModelPropertyType extends DateTime | CalendarDate ? DateTime | CalendarDate | null : ModelPropertyType extends ClockTime ? ClockTime | null : ModelPropertyType extends ClockTimeTz ? ClockTimeTz | null : ModelPropertyType extends number | string ? ModelPropertyType | PermanentOpsValTypes : never : EnumTypeArray extends string[] ? EnumTypeArray[number] | PermanentOpsValTypes : never, ResolvedOpsValType = OpsValType | RawBuilder<unknown>, PartialTypes = EnumTypeArray extends null ? ModelPropertyType extends DateTime ? Range<DateTime | CalendarDate> | Range<null, DateTime | CalendarDate> | (() => Range<DateTime | CalendarDate>) | (() => Range<null, DateTime | CalendarDate>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends ClockTime ? Range<ClockTime> | Range<null, ClockTime> | (() => Range<ClockTime>) | (() => Range<null, ClockTime>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends ClockTimeTz ? Range<ClockTimeTz> | Range<null, ClockTimeTz> | (() => Range<ClockTimeTz>) | (() => Range<null, ClockTimeTz>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends CalendarDate ? Range<DateTime | CalendarDate> | Range<null, DateTime | CalendarDate> | (() => Range<DateTime | CalendarDate>) | (() => Range<null, DateTime | CalendarDate>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType> : ColumnType extends 'bigint' ? Range<TypesAllowedForBigintAgainstTheDb> | Range<null, TypesAllowedForBigintAgainstTheDb> | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends number ? Range<ModelPropertyType> | Range<null, ModelPropertyType> | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends string ? Range<string> | Range<null, string> | OpsStatement<KyselyComparisonOperatorExpression, string, any> | OpsStatement<TrigramOperator, ResolvedOpsValType, ExtraSimilarityArgs> : never : EnumTypeArray extends string[] ? EnumTypeArray | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : never> = PartialTypes extends never ? OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> | CurriedOpsStatement<any, any, any, ResolvedOpsValType> | SelectQueryBuilder<DB, keyof DB, any> : PartialTypes | CurriedOpsStatement<any, any, any, ResolvedOpsValType> | SelectQueryBuilder<DB, keyof DB, any>;
+type NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, Column, ModelPropertyType = ModelColumnType<Schema, TableName, Column>, ColumnType = TableColumnType<Schema, TableName, Column>, EnumTypeArray extends string[] | null = TableColumnEnumTypeArray<Schema, TableName, Column>, IsArrayColumn = TableColumnIsArray<Schema, TableName, Column>, PermanentOpsValTypes = null | readonly [], ArrayElementType = ModelPropertyType extends readonly (infer ElementType)[] ? ElementType : never, ArrayOpsValType = readonly ArrayElementType[] | PermanentOpsValTypes | RawBuilder<unknown>, OpsValType = IsArrayColumn extends true ? ArrayElementType | PermanentOpsValTypes : EnumTypeArray extends null ? ColumnType extends 'bigint' ? TypesAllowedForBigintAgainstTheDb | PermanentOpsValTypes : ModelPropertyType extends DateTime | CalendarDate ? DateTime | CalendarDate | null : ModelPropertyType extends ClockTime ? ClockTime | null : ModelPropertyType extends ClockTimeTz ? ClockTimeTz | null : ModelPropertyType extends number | string ? ModelPropertyType | PermanentOpsValTypes : never : EnumTypeArray extends string[] ? EnumTypeArray[number] | PermanentOpsValTypes : never, ResolvedOpsValType = OpsValType | RawBuilder<unknown>, PartialTypes = IsArrayColumn extends true ? (EnumTypeArray extends string[] ? EnumTypeArray : never) | OpsStatement<'=' | '!=' | '<>', ArrayOpsValType, any> | OpsStatement<KyselyComparisonOperatorExpression, PermanentOpsValTypes | RawBuilder<unknown>, any> : EnumTypeArray extends null ? ModelPropertyType extends DateTime ? Range<DateTime | CalendarDate> | Range<null, DateTime | CalendarDate> | (() => Range<DateTime | CalendarDate>) | (() => Range<null, DateTime | CalendarDate>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends ClockTime ? Range<ClockTime> | Range<null, ClockTime> | (() => Range<ClockTime>) | (() => Range<null, ClockTime>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends ClockTimeTz ? Range<ClockTimeTz> | Range<null, ClockTimeTz> | (() => Range<ClockTimeTz>) | (() => Range<null, ClockTimeTz>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends CalendarDate ? Range<DateTime | CalendarDate> | Range<null, DateTime | CalendarDate> | (() => Range<DateTime | CalendarDate>) | (() => Range<null, DateTime | CalendarDate>) | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType> : ColumnType extends 'bigint' ? Range<TypesAllowedForBigintAgainstTheDb> | Range<null, TypesAllowedForBigintAgainstTheDb> | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends number ? Range<ModelPropertyType> | Range<null, ModelPropertyType> | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : ModelPropertyType extends string ? Range<string> | Range<null, string> | OpsStatement<KyselyComparisonOperatorExpression, string, any> | OpsStatement<TrigramOperator, ResolvedOpsValType, ExtraSimilarityArgs> : never : EnumTypeArray extends string[] ? EnumTypeArray | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> : never> = PartialTypes extends never ? OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any> | CurriedOpsStatement<any, any, any, ResolvedOpsValType> | SelectQueryBuilder<DB, keyof DB, any> : PartialTypes | CurriedOpsStatement<any, any, any, ResolvedOpsValType> | SelectQueryBuilder<DB, keyof DB, any>;
 export type WhereStatementForDreamClass<DreamClass extends typeof Dream> = WhereStatement<InstanceType<DreamClass>>;
 export type WhereStatementForDream<DreamInstance extends Dream> = WhereStatement<DreamInstance>;
 type AssociationNameToDotReferencedColumns<DB, TableName extends keyof DB, AssociationName> = `${AssociationName & string}.${TableColumnNames<DB, TableName>}`;

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

@@ -103,6 +103,14 @@ export type DreamTableSchema<DreamInstance extends Dream> = Updateable<DreamInst
 export type ModelColumnType<Schema, TableName, Column, TableSchema extends Schema[TableName & keyof Schema] = Schema[TableName & keyof Schema], TableColumns extends TableSchema['columns' & keyof TableSchema] = TableSchema['columns' & keyof TableSchema], TableColumnMetadata extends TableColumns[Column & keyof TableColumns] = TableColumns[Column & keyof TableColumns], ColumnType extends TableColumnMetadata['coercedType' & keyof TableColumnMetadata] = TableColumnMetadata['coercedType' & keyof TableColumnMetadata]> = ColumnType;
 export type TableColumnType<Schema, TableName, Column, TableSchema extends Schema[TableName & keyof Schema] = Schema[TableName & keyof Schema], TableColumns extends TableSchema['columns' & keyof TableSchema] = TableSchema['columns' & keyof TableSchema], TableColumnMetadata extends TableColumns[Column & keyof TableColumns] = TableColumns[Column & keyof TableColumns], ColumnType extends TableColumnMetadata['dbType' & keyof TableColumnMetadata] = TableColumnMetadata['dbType' & keyof TableColumnMetadata]> = ColumnType;
 export type TableColumnEnumTypeArray<Schema, TableName, Column, TableSchema extends Schema[TableName & keyof Schema] = Schema[TableName & keyof Schema], TableColumns extends TableSchema['columns' & keyof TableSchema] = TableSchema['columns' & keyof TableSchema], TableColumnMetadata extends TableColumns[Column & keyof TableColumns] = TableColumns[Column & keyof TableColumns], EnumTypeCandidate = TableColumnMetadata['enumArrayType' & keyof TableColumnMetadata], EnumTypeArray extends string[] | null = EnumTypeCandidate extends null ? null : EnumTypeCandidate extends undefined ? null : EnumTypeCandidate extends string[] ? EnumTypeCandidate : never> = EnumTypeArray;
+/**
+ * Resolves to `true` when the schema marks the column as a database array
+ * column (e.g. `text[]`, `integer[]`, `balloon_colors_enum[]`), otherwise
+ * `false`. Enum array columns carry both `enumArrayType` and `isArray: true`,
+ * so any branch keyed off array-ness must be checked before branching on
+ * `TableColumnEnumTypeArray`, which is also set for scalar enum columns.
+ */
+export type TableColumnIsArray<Schema, TableName, Column, TableSchema extends Schema[TableName & keyof Schema] = Schema[TableName & keyof Schema], TableColumns extends TableSchema['columns' & keyof TableSchema] = TableSchema['columns' & keyof TableSchema], TableColumnMetadata extends TableColumns[Column & keyof TableColumns] = TableColumns[Column & keyof TableColumns], IsArrayCandidate = TableColumnMetadata['isArray' & keyof TableColumnMetadata]> = [IsArrayCandidate] extends [never] ? false : IsArrayCandidate extends true ? true : false;
 type AssociationMetadataForTable<Schema, TableName extends keyof Schema> = Schema[TableName]['associations' & keyof Schema[TableName]];
 export type AssociationNamesForTable<Schema, TableName extends keyof Schema> = keyof AssociationMetadataForTable<Schema, TableName> | AliasedSchemaAssociation<Schema, TableName>;
 type MetadataForAssociation<Schema, TableName extends keyof Schema, AssociationName, AssociationMetadata = AssociationMetadataForTable<Schema, TableName>> = AssociationMetadata[AssociationName & keyof AssociationMetadata];