@rvoh/dream 2.21.1 → 2.23.0

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

@@ -0,0 +1,69 @@
+import Dream from '../../Dream.js';
+import { SerializerType } from '../../types/serializer.js';
+import { ResolvedSerializerAssociationEdge } from './resolveSerializerAssociationEdges.js';
+/**
+ * One contributing serializer's view of a merged target: the serializer that renders the target
+ * through this association, together with how it renders it. The edge type and the serializer-side
+ * association name belong here rather than on the target because they vary per contributing
+ * serializer — two children of an STI base can reach the same target class through the same
+ * association under different names or different edge types.
+ */
+export interface MergedSerializerAssociationTargetSerializer {
+    serializer: SerializerType;
+    type: ResolvedSerializerAssociationEdge['type'];
+    serializerAssociationName: string;
+}
+export interface MergedSerializerAssociationTarget {
+    dreamClass: typeof Dream;
+    /**
+     * Every serializer that renders this target through this association, deduped by serializer
+     * identity. More than one when the target is itself an STI base (one serializer per child).
+     */
+    serializers: MergedSerializerAssociationTargetSerializer[];
+}
+export interface MergedSerializerAssociationEdge {
+    associationAs: string;
+    /**
+     * true when at least one contributing serializer terminates this association — a
+     * delegatedAttribute (which always carries `targets: []`), or a rendersOne/rendersMany resolving
+     * to no serializer.
+     *
+     * Independent of `targets`: an association one child terminates and another descends into (as
+     * Balloon's `stiUnion` key does with `balloonLine`) is both terminating and targeted. The preload
+     * walk emits a leaf path for the terminating side; the display walk ignores it, since a
+     * terminated association prints nothing of its own.
+     */
+    terminates: boolean;
+    targets: MergedSerializerAssociationTarget[];
+}
+/**
+ * @internal
+ *
+ * Resolves the association edges of *every* serializer that can render `dreamClass` at this point
+ * in a serialization walk and merges them into one set, so that a walk rooted at an STI base sees
+ * the union across its children's serializers rather than one child's view of the class.
+ *
+ * The merge is keyed on (association, target class), so:
+ *
+ * - an association several children render identically (all three `stiUnion` serializers render
+ *   `sandbags`) collapses to a single edge with a single target, rather than repeating per child;
+ * - a polymorphic association keeps one target per target class
+ *   (`Polymorphic/Task#taskable` → `Chore` and `Workout`), which is a real distinction, not a
+ *   duplicate;
+ * - an association only some children render (`heartRatings`, rendered only by Latex's `stiUnion`
+ *   serializer) is present exactly once.
+ *
+ * Grouping the serializers *under* the target rather than emitting one target per serializer is
+ * what lets a caller recurse once per target class with the full set, so nested trees from
+ * different children of the same target merge instead of clobbering one another.
+ *
+ * Insertion-ordered throughout, so edges come back in the order the serializers declare them.
+ *
+ * This is the single union both serializer walks run on: `buildSerializerPreloadPaths` turns these
+ * edges into preload paths (taking `terminates` and the target classes, ignoring the per-serializer
+ * edge type and serializer-side name), and `Dream.recursiveSerializationMap` prints them (taking the
+ * per-serializer edge type and name, ignoring `terminates`). Keeping the two walks on one merge is the point: the bug
+ * this exists to prevent is `psy i:serialization` and `preloadFor` disagreeing about which
+ * associations a serializer key reaches, which a second hand-maintained merge invites back.
+ */
+export default function mergeSerializerAssociationEdges(dreamClass: typeof Dream, serializers: SerializerType[]): MergedSerializerAssociationEdge[];

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

@@ -1,7 +1,25 @@
-import { DreamModelSerializerType, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, SimpleObjectSerializerType } from '../../types/serializer.js';
-export default function printSerializerHierarchyLevel({ serializerAssociationType, serializerAssociationName, associationSerializer, forDisplayDepth, }: {
-    serializerAssociationType: (InternalAnyTypedSerializerRendersMany<any> | InternalAnyTypedSerializerRendersOne<any> | InternalAnyTypedSerializerDelegatedAttribute)['type'];
-    serializerAssociationName: string;
-    associationSerializer: DreamModelSerializerType | SimpleObjectSerializerType;
+import { MergedSerializerAssociationTargetSerializer } from './mergeSerializerAssociationEdges.js';
+/**
+ * @internal
+ *
+ * Prints one level of `psy i:serialization`'s tree: the heading for an association, then the name
+ * of every serializer that renders the target of that association at this point in the walk. That
+ * is more than one serializer when the target is an STI base, since each child may register a
+ * different serializer under the same key.
+ *
+ * Those serializers are printed under a *single* heading rather than one heading each, because the
+ * caller prints the union of their association trees below, indented one level in from the
+ * heading. Repeating the heading per serializer would leave that union sitting directly beneath
+ * whichever child's serializer happened to print last, reading as though every sibling's
+ * associations belonged to that one child. Grouped, the shape matches what `displaySerialization`
+ * prints at the root of the tree — one name, then every serializer that can render it, then one
+ * merged tree.
+ *
+ * A target reached under more than one edge type or serializer-side name (two children of an STI
+ * base rendering the same class through `rendersOne` and `rendersMany`, say) gets one heading per
+ * distinct (type, name), since those are genuinely different lines rather than repetitions of one.
+ */
+export default function printSerializerHierarchyLevel({ targetSerializers, forDisplayDepth, }: {
+    targetSerializers: MergedSerializerAssociationTargetSerializer[];
     forDisplayDepth: number;
 }): void;

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

@@ -2,7 +2,6 @@ import Dream from '../../Dream.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
 export interface ResolvedSerializerAssociationEdge {
     associationAs: string;
-    sourceDreamClass: typeof Dream;
     type: 'rendersOne' | 'rendersMany' | 'delegatedAttribute';
     serializerAssociationName: string;
     targets: {
@@ -10,4 +9,31 @@ export interface ResolvedSerializerAssociationEdge {
         serializer: DreamModelSerializerType | SimpleObjectSerializerType;
     }[];
 }
+/**
+ * @internal
+ *
+ * Drops every memoized edge set. Only needed when a class object that stays in the process has its
+ * `serializers` getter replaced, which the memo cannot detect — specs that install or remove one
+ * around an example. Replacing the model classes themselves needs no call, since the memo keys on
+ * the class and serializer objects and entries resolved against the previous ones become
+ * unreachable.
+ */
+export declare function clearResolvedSerializerAssociationEdgesCache(): void;
+/**
+ * @internal
+ *
+ * Resolves the rendersOne/rendersMany/delegatedAttribute attributes of `serializer` to the
+ * associations of `dreamClass` they preload, along with the classes and serializers each one
+ * targets.
+ *
+ * Memoized on its two arguments, because every call rebuilds a throwaway serializer builder and
+ * re-infers the serializers of every association target, and the traversal in
+ * buildSerializerPreloadPaths revisits the same (class, serializer) pair many times.
+ *
+ * The two arguments are not the function's only inputs, though: resolving a target's serializers
+ * also reads that target's `serializers` getter, the STI children registered on it, and the
+ * DreamApp serializer registry. Loading a fresh set of classes replaces the keys along with that
+ * state, so the memo follows it. Mutating a `serializers` getter in place does not, and needs
+ * `clearResolvedSerializerAssociationEdgesCache` — see there.
+ */
 export default function resolveSerializerAssociationEdges(dreamClass: typeof Dream, serializer: DreamModelSerializerType | SimpleObjectSerializerType): ResolvedSerializerAssociationEdge[];

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/errors/serializers/NoSerializersResolvedForKey.d.ts

@@ -0,0 +1,18 @@
+import Dream from '../../Dream.js';
+import { ViewModelClass } from '../../types/dream.js';
+/**
+ * Raised when resolving a serializer key against a class yields an empty set of serializers.
+ *
+ * This is an internal-invariant failure, not a misconfiguration: an unresolvable serializer key
+ * raises `MissingSerializersDefinitionForKey` (and a class with no `serializers` getter at all
+ * raises `MissingSerializersDefinition`) while it is being resolved, and STI expansion always
+ * yields at least one class, so there is no supported application shape that reaches this. It is
+ * typed rather than a bare `Error` so that it can be asserted on, and so that the two callers that
+ * guard the invariant raise the same thing.
+ */
+export default class NoSerializersResolvedForKey extends Error {
+    private classDef;
+    private serializerKey;
+    constructor(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: 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/serializer/helpers/inferSerializerFromDreamOrViewModel.d.ts

@@ -4,3 +4,19 @@ import { DreamModelSerializerType, SerializerType, SimpleObjectSerializerType }
 export declare const DEFAULT_SERIALIZER_KEY = "default";
 export default function inferSerializerFromDreamOrViewModel<T extends Dream | ViewModel | null | undefined, ReturnType extends T extends null | undefined ? null : T extends Dream | ViewModel ? SerializerType : never>(obj: T, serializerKey?: string | undefined): ReturnType;
 export declare function inferSerializersFromDreamClassOrViewModelClass(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey?: string | undefined): (DreamModelSerializerType | SimpleObjectSerializerType)[];
+/**
+ * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
+ *
+ * The guard is unreachable today, and deliberately not phrased as "no serializer found for key": a
+ * serializer key that a class does not register throws `MissingSerializersDefinitionForKey` (and a
+ * class with no `serializers` getter at all throws `MissingSerializersDefinition`) from inside the
+ * inference above, and `expandStiClasses` always yields at least one class. It exists only so that
+ * a future change to any of those cannot turn an unresolvable serializer key into a silently empty
+ * serializer set — which, for the callers below, means a silently empty preload set and a
+ * `NonLoadedAssociation` at render rather than an error naming the real problem.
+ *
+ * Used by everything that walks a serializer graph rooted on a class rather than an instance —
+ * preload-path building and serialization display — so that they raise one typed error between
+ * them.
+ */
+export declare function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string): (DreamModelSerializerType | SimpleObjectSerializerType)[];

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];

package/dist/types/src/types/types/associations/shared.ts

@@ -22,6 +22,7 @@ import {
   ModelColumnType,
   OrderDir,
   TableColumnEnumTypeArray,
+  TableColumnIsArray,
   TableColumnNames,
   TableColumnType,
   TableNameForGlobalModelName,
@@ -88,75 +89,103 @@ type NonKyselySupportedSupplementalWhereClauseValues<
   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 [],
-  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,
+  // The element type of an array column, e.g. `string` for `text[]` and
+  // `BalloonColorsEnum` for `balloon_colors_enum[]`.
+  ArrayElementType = ModelPropertyType extends readonly (infer ElementType)[] ? ElementType : never,
+  // The whole-array value accepted by equality operators against an array
+  // column, e.g. `ops.equal(['a', 'b'])` against a `text[]` column. Readonly,
+  // because `ops.equal`'s `const` type parameter infers array literals as
+  // readonly tuples.
+  ArrayOpsValType = readonly ArrayElementType[] | PermanentOpsValTypes | RawBuilder<unknown>,
+  //
+  // NOTE: the array-ness branch MUST come before the enum branches: the schema
+  // sets `enumArrayType` for scalar enum columns AND for enum array columns, so
+  // an enum array column would otherwise take the scalar enum path.
+  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 = 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
+  // NOTE: as with `OpsValType` above, the array-ness branch MUST come first.
+  //
+  // A whole-array value is only accepted under the equality operators, which
+  // are the only ones the driver binds as a single array parameter
+  // (EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE in QueryDriver/Kysely.ts).
+  // Under any other operator an array value is rendered as a SQL value list,
+  // which PostgreSQL rejects, so it stays a compile error rather than becoming
+  // a database error.
+  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<ClockTime>
-            | Range<null, ClockTime>
-            | (() => Range<ClockTime>)
-            | (() => Range<null, ClockTime>)
+            | Range<DateTime | CalendarDate>
+            | Range<null, DateTime | CalendarDate>
+            | (() => Range<DateTime | CalendarDate>)
+            | (() => Range<null, DateTime | CalendarDate>)
             | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
-        : ModelPropertyType extends ClockTimeTz
+        : ModelPropertyType extends ClockTime
           ?
-              | Range<ClockTimeTz>
-              | Range<null, ClockTimeTz>
-              | (() => Range<ClockTimeTz>)
-              | (() => Range<null, ClockTimeTz>)
+              | Range<ClockTime>
+              | Range<null, ClockTime>
+              | (() => Range<ClockTime>)
+              | (() => Range<null, ClockTime>)
               | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
-          : ModelPropertyType extends CalendarDate
+          : ModelPropertyType extends ClockTimeTz
             ?
-                | Range<DateTime | CalendarDate>
-                | Range<null, DateTime | CalendarDate>
-                | (() => Range<DateTime | CalendarDate>)
-                | (() => Range<null, DateTime | CalendarDate>)
-                | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType>
-            : ColumnType extends 'bigint'
+                | Range<ClockTimeTz>
+                | Range<null, ClockTimeTz>
+                | (() => Range<ClockTimeTz>)
+                | (() => Range<null, ClockTimeTz>)
+                | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
+            : ModelPropertyType extends CalendarDate
               ?
-                  | Range<TypesAllowedForBigintAgainstTheDb>
-                  | Range<null, TypesAllowedForBigintAgainstTheDb>
-                  | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
-              : ModelPropertyType extends number
+                  | Range<DateTime | CalendarDate>
+                  | Range<null, DateTime | CalendarDate>
+                  | (() => Range<DateTime | CalendarDate>)
+                  | (() => Range<null, DateTime | CalendarDate>)
+                  | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType>
+              : ColumnType extends 'bigint'
                 ?
-                    | Range<ModelPropertyType>
-                    | Range<null, ModelPropertyType>
+                    | Range<TypesAllowedForBigintAgainstTheDb>
+                    | Range<null, TypesAllowedForBigintAgainstTheDb>
                     | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
-                : ModelPropertyType extends string
+                : ModelPropertyType extends number
                   ?
-                      | Range<string>
-                      | Range<null, string>
-                      | OpsStatement<KyselyComparisonOperatorExpression, string, any>
-                      | OpsStatement<TrigramOperator, ResolvedOpsValType, ExtraSimilarityArgs>
-                  : never
-    : EnumTypeArray extends string[]
-      ? EnumTypeArray | OpsStatement<KyselyComparisonOperatorExpression, ResolvedOpsValType, any>
-      : never,
+                      | 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>

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

@@ -441,6 +441,36 @@ export type TableColumnEnumTypeArray<
         : 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],
+  // NOTE: the leading `never` arm is load-bearing. A schema entry that omits
+  // `isArray` makes `IsArrayCandidate` resolve to `never`, and a bare
+  // `IsArrayCandidate extends true` distributes over that naked type parameter
+  // and yields `never` rather than the documented `false` — which then
+  // propagates into the array-ness branches of `OpsValType`/`PartialTypes`
+  // (also keyed off naked type parameters) and erases every `ops` and `Range`
+  // form from the column in `where()`. The tuple wrappers defuse distribution
+  // for that one check only: the second arm stays deliberately distributive so
+  // that an `any` schema still resolves to `boolean` and reaches both the
+  // array and the scalar branch, as internal callers with an untyped schema
+  // rely on.
+> = [IsArrayCandidate] extends [never] ? false : IsArrayCandidate extends true ? true : false
+
 ///////////////////////////
 // Association type helpers
 ///////////////////////////

package/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "eJyVksFOAjEQht9lzgW3SwpLj0JMjBE1MXogHMru4DZ0W9J2MRvCu5vKpSK65TTNZP75v87MAawx3gFfUjahhFK6ImBxo7D00mgH/ACU0hC0aBA4vLRou7mVe7S3wiEQ2EpdAad5QaC1CjiUSjiH7qZaD8+qh7VvFJBTBXDwrhoE+eCUIFDWUlUWNfBlXtDVkUBexO4PnUPVRV17/H/VX0NA82keEEKMGJ6N8x8WXTrFBUUPR3BlIxa5zmostzOjnbdCav8mjRJhRf9Zo7XGuuFf0hQGNooZjGob/bRHu1HmM8X5hyDFbxJvey68uNelaXbCy7XCd+nrkFsLh3cSVZWA0NvjqotgI0bCUAhl04zQcVZ8HwibZmfYr90OT78Pr0fpGuHLOpH3sjhhfOOsiDgWxi9apa45lXNJn+fx+AXCu279"
+window.hierarchyData = "eJyVksFuwjAMht/F58CaokRVjgNNmqaxTZq2A+IQWrNGpAlKUqYK8e5TxqUwRsPJkeXf/xfbe3DWBg9iQVnBCaV0ScDhWmMZlDUexB4opTEY2SAIeGvRdTOndujupUcgsFGmAkHzgkDrNAgotfQe/V21Gp9Vj+vQaCDHChAQfDWK8tExQaCsla4cGhCLvODLA4G84D33p86j7npdB/z/1N9CQCdZHhFi7DG8Wh++HPp0iguKAY7oyljWc53WWG6m1vjgpDLhQ1kt44quWaNz1vnxf9IUBl70GaxuG/OyQ7fW9jvF+USQ4ney7ZkM8tGUttnKoFYaP1WoY24lPT4o1FUCwmCPmy6CsYzEoRDKM0Yozye/B8Izdob93m3x+Pv4ela+kaGsE3kvixPGx/NJj2Nuw7zV+pZTOZcMeR4OP9YLbv0="