@rvoh/dream 2.40.1 → 2.41.0

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

@@ -0,0 +1,14 @@
+import Dream from '../../Dream.js';
+import { WhereStatement } from '../../types/associations/shared.js';
+import { UpdateablePropertiesForClass } from '../../types/dream.js';
+/**
+ * Builds the `findBy` statement that findOrCreateBy, createOrFindBy,
+ * updateOrCreateBy and createOrUpdateBy use to look up an existing record.
+ * Their attributes are both the lookup and the values to persist, so an array
+ * given for an array column is the whole array to store: the lookup compares
+ * it with `ops.equal`, matching only a record whose array equals it
+ * element-for-element, in order, instead of the `IN` a plain list means in a
+ * where clause. PostgreSQL defines no equality operator for `json`, so on a
+ * `json[]` column this lookup raises at the database, as `ops.equal` does.
+ */
+export default function findOrCreateLookupStatement<T extends typeof Dream>(dreamClass: T, attributes: UpdateablePropertiesForClass<T>): WhereStatement<InstanceType<T>>;

package/dist/types/src/dream-app/index.d.ts

@@ -159,25 +159,32 @@ export default class DreamApp {
     private _packageManager;
     get packageManager(): "pnpm" | "yarn" | "npm" | "bun" | "deno";
     private _importExtension;
+    /**
+     * The import suffix the CLI generators write: `.js`, `.ts` or `none`.
+     *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importExtension', …)`. Psychic forwards it here, and a different
+     * value set in conf/dream.ts throws at boot. In a Dream-only app, set it in
+     * conf/dream.ts with `dreamApp.set('importExtension', …)`.
+     *
+     * Defaults to `.js`.
+     */
     get importExtension(): ".js" | ".ts" | "none";
     private _importAliasPrefix;
     /**
      * The prefix of the import aliases the CLI generators write: the `@` in
      * `@models/User.js`, `@serializers/UserSerializer.js` and
-     * `@spec/factories/UserFactory.js`. Set with
-     * `dreamApp.set('importAliasPrefix', '#')` to have them write
+     * `@spec/factories/UserFactory.js`. Set it to `#` to have them write
      * `#models/User.js` and so on, which Node resolves as subpath imports
      * declared under `imports` in the app's package.json.
      *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importAliasPrefix', '#')`. Psychic forwards it here, and a
+     * different value set in conf/dream.ts throws at boot. In a Dream-only app,
+     * set it in conf/dream.ts with `dreamApp.set('importAliasPrefix', '#')`.
+     *
      * Defaults to `@`. The default becomes `#` in Dream 3; an app that wants
-     * to keep `@` should set it explicitly with
-     * `dreamApp.set('importAliasPrefix', '@')`.
-     *
-     * Psychic's resource controller-spec generator still writes its
-     * `@spec/unit/helpers/authentication.js` import with a literal `@` until
-     * Psychic reads this setting (planned for 3.17.0), so a Psychic app should
-     * keep its `@spec` alias, or wait for that release, before switching to
-     * `#` only.
+     * to keep `@` should set it to `@` explicitly.
      */
     get importAliasPrefix(): "@" | "#";
     /**

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

@@ -114,9 +114,13 @@ declare const ops: {
      *
      * **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-for-element, in order. The plain value form of a where clause
+     * targets regular (scalar) columns, so comparing an array column against an
+     * array value goes through `ops`: a flat list against an array column
+     * (`Post.where({ tags: ['a', 'b'] })`) is a compile error. A list of whole
+     * arrays (`Post.where({ tags: [['a', 'b'], ['c']] })`) means `IN`, matching
+     * rows whose column equals any one of them, and `ops.any` 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.
      *

package/dist/types/src/serializer/DreamSerializer.d.ts

@@ -9,18 +9,24 @@ import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
  *   DreamSerializer(User, user).attribute('email').rendersMany('posts')
  * ```
  *
- * A serializer must not read its data while being built: what it declares may not
- * depend on its data. Dream and Psychic build it without data to read its shape (the
- * OpenAPI schema, and the keys a flattened association or `customAttribute` that uses
- * it renders as `null` where its value does not supply them), so a serializer that
- * reads its data while being built throws when a flattened association or
- * `customAttribute` that uses it is rendered. Read the data inside a `customAttribute`
- * callback, which runs only when the serializer renders, not while it is built.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param dreamClass - The Dream model class the serializer renders
  * @param data - The Dream instance to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function DreamSerializer<DreamClass extends typeof Dream, DataType extends Dream | null, PassthroughDataType extends object | undefined = undefined>(dreamClass: DreamClass, data: DataType, passthroughData?: PassthroughDataType): DreamSerializerBuilder<DreamClass, DataType, PassthroughDataType, Exclude<DataType, null>>;

package/dist/types/src/serializer/ObjectSerializer.d.ts

@@ -8,17 +8,23 @@ import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
  *   ObjectSerializer(address).attribute('city', { openapi: 'string' })
  * ```
  *
- * A serializer must not read its data while being built: what it declares may not
- * depend on its data. Dream and Psychic build it without data to read its shape (the
- * OpenAPI schema, and the keys a flattened association or `customAttribute` that uses
- * it renders as `null` where its value does not supply them), so a serializer that
- * reads its data while being built throws when a flattened association or
- * `customAttribute` that uses it is rendered. Read the data inside a `customAttribute`
- * callback, which runs only when the serializer renders, not while it is built.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param data - The object to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function ObjectSerializer<DataType extends object | null, PassthroughDataType extends object | undefined = undefined>(data: DataType, passthroughData?: PassthroughDataType): ObjectSerializerBuilder<DataType, PassthroughDataType, Exclude<DataType, null>>;

package/dist/types/src/serializer/helpers/nullFlattenedSerializerKeys.d.ts

@@ -2,7 +2,6 @@ import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '../.
 import { DreamModelSerializerType, SerializerCasing, SimpleObjectSerializerType } from '../../types/serializer.js';
 export interface NullFlattenedSerializerKeysOptions {
     casing?: SerializerCasing;
-    passthroughData?: object;
 }
 /**
  * The keys a flattened `rendersOne` always adds to the parent's payload, returned as an object
@@ -32,8 +31,9 @@ export interface NullFlattenedSerializerKeysOptions {
  * flattens itself, adds nothing, so the walk always terminates; one reached again along another
  * path is walked again, so each path adds its keys and their requirements.
  *
- * `passthroughData` is handed to each serializer as it is built, as when rendering; outside a
- * render it may be left out.
+ * Each serializer is built with empty passthrough data, as Psychic's OpenAPI generation builds it,
+ * so the keys are the same whatever passthrough data a render carries: what a serializer declares
+ * must not depend on its passthrough data.
  */
 export declare function nullFlattenedSerializerKeys(serializers: (DreamModelSerializerType | SimpleObjectSerializerType)[], options?: NullFlattenedSerializerKeysOptions): Record<string, null>;
 /**

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

@@ -25,23 +25,25 @@ 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>, 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>;
+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 ? 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>}`;
 export type ColumnNamesAccountingForJoinedAssociations<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, RootTableName extends keyof DB, RootTableAlias extends string> = JoinedAssociations['length'] extends 0 ? TableColumnNames<DB, RootTableName> : TableColumnNames<DB, RootTableName> | JoinedAssociationColumnNames<JoinedAssociations, DB, AssociationNameToDotReferencedColumns<DB, RootTableName & keyof DB, RootTableAlias>>;
 type JoinedAssociationColumnNames<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, AllColumnNames, Depth extends number = 0, CurrentJoinedAssociation = Readonly<JoinedAssociations[0]>, NextTableName = CurrentJoinedAssociation extends Readonly<JoinedAssociation> ? CurrentJoinedAssociation['table'] : never, NextAssociationName = CurrentJoinedAssociation extends Readonly<JoinedAssociation> ? CurrentJoinedAssociation['alias'] : never> = JoinedAssociations['length'] extends 0 ? AllColumnNames : Depth extends MAX_JOINED_TABLES_DEPTH ? AllColumnNames : JoinedAssociationColumnNames<ReadonlyTail<JoinedAssociations>, DB, AllColumnNames | AssociationNameToDotReferencedColumns<DB, NextTableName & keyof DB, NextAssociationName>, Inc<Depth>>;
-type Whereable<R> = {
-    [K in keyof Selectable<R>]?: Selectable<R>[K] | Selectable<R>[K][];
+type Whereable<DB, Schema, TableName extends keyof DB, R = DB[TableName]> = {
+    [K in keyof Selectable<R>]?: TableColumnIsArray<Schema, TableName, K> extends true ? Extract<Selectable<R>[K], null> | Selectable<R>[K][] : Selectable<R>[K] | Selectable<R>[K][];
 };
 type WhereableAssociatedModelParam<I extends Dream> = {
     [K in keyof AssociatedModelParam<I>]: AssociatedModelParam<I>[K] | NonNullable<AssociatedModelParam<I>[K]>[];
 };
 export type WhereStatement<I extends Dream> = InternalWhereStatement<I, I['DB'], I['schema'], I['table']>;
-export type InternalWhereStatement<I extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<MergeUnionOfRecordTypes<Whereable<DB[TableName]> | DreamSelectable<DB, Schema, TableName> | WhereableAssociatedModelParam<I>>>;
+export type InternalWhereStatement<I extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<MergeUnionOfRecordTypes<Whereable<DB, Schema, TableName> | DreamSelectable<DB, Schema, TableName> | WhereableAssociatedModelParam<I>>>;
 export type OnStatementForAssociation<I extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, OnStatement extends InternalWhereStatement<I, DB, Schema, TableName> = InternalWhereStatement<I, DB, Schema, TableName>> = RequiredOnClauseKeysForThisAssociation extends null ? InternalWhereStatement<I, DB, Schema, TableName> : RequiredOnClauseKeysForThisAssociation extends string[] ? Required<Pick<OnStatement, RequiredOnClauseKeysForThisAssociation[number] & keyof OnStatement>> & Partial<Omit<OnStatement, RequiredOnClauseKeysForThisAssociation[number] & keyof OnStatement>> : never;
 export type OnStatementForSpecificColumns<I extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB, Columns extends string[], OnStatement extends InternalWhereStatement<I, DB, Schema, TableName> = InternalWhereStatement<I, DB, Schema, TableName>> = Pick<OnStatement, Columns[number] & keyof OnStatement>;
-type OnStatementForAssociationDefinition<DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<MergeUnionOfRecordTypes<Partial<Selectable<DB[TableName]>> | Partial<{
+type OnStatementForAssociationDefinition<DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<MergeUnionOfRecordTypes<Partial<{
+    [K in keyof Selectable<DB[TableName]>]: TableColumnIsArray<Schema, TableName, K> extends true ? Extract<Selectable<DB[TableName]>[K], null> | readonly [] : Selectable<DB[TableName]>[K];
+}> | Partial<{
     [ColumnName in keyof DB[TableName]]: NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, ColumnName> | typeof DreamConst.passthrough | typeof DreamConst.required;
 }>>>;
 export type SelfOnStatement<BaseInstance extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<Record<keyof DB[TableName], DreamColumnNames<BaseInstance>>>;

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

@@ -134,7 +134,6 @@ type NonKyselySupportedSupplementalWhereClauseValues<
   // a database error.
   PartialTypes = IsArrayColumn extends true
     ?
-        | (EnumTypeArray extends string[] ? EnumTypeArray : never)
         | OpsStatement<'=' | '!=' | '<>', ArrayOpsValType, any>
         | OpsStatement<KyselyComparisonOperatorExpression, PermanentOpsValTypes | RawBuilder<unknown>, any>
     : EnumTypeArray extends null
@@ -248,8 +247,22 @@ type JoinedAssociationColumnNames<
         Inc<Depth>
       >
 
-type Whereable<R> = {
-  [K in keyof Selectable<R>]?: Selectable<R>[K] | Selectable<R>[K][]
+// The plain value form of a where clause targets regular (scalar) columns: a
+// value means `=`, a list of values means `IN`, and `null` means `IS NULL`.
+// Comparing an array column against an array value goes through `ops`, e.g.
+// `Post.where({ tags: ops.equal(['a', 'b']) })`. An array column's plain value
+// is therefore limited to `null` and a list whose entries are each a whole
+// array or `null` (an `IN` of whole arrays, where `[]` matches nothing). A flat
+// list of elements against an array column, e.g.
+// `Post.where({ tags: ['a', 'b'] })`, is a compile error, since it is rendered
+// as the value list `IN ('a', 'b')`, which PostgreSQL rejects for an array
+// column unless every element is itself an array literal such as `'{a}'`.
+// Array-ness comes from the schema (`TableColumnIsArray`), not from the
+// Kysely column type, which also admits arrays for jsonb columns.
+type Whereable<DB, Schema, TableName extends keyof DB, R = DB[TableName]> = {
+  [K in keyof Selectable<R>]?: TableColumnIsArray<Schema, TableName, K> extends true
+    ? Extract<Selectable<R>[K], null> | Selectable<R>[K][]
+    : Selectable<R>[K] | Selectable<R>[K][]
 }
 
 // For filtering by BelongsTo model instance(s) in a where/and statement, e.g.
@@ -270,7 +283,9 @@ export type InternalWhereStatement<
   TableName extends AssociationTableNames<DB, Schema> & keyof DB,
 > = Partial<
   MergeUnionOfRecordTypes<
-    Whereable<DB[TableName]> | DreamSelectable<DB, Schema, TableName> | WhereableAssociatedModelParam<I>
+    | Whereable<DB, Schema, TableName>
+    | DreamSelectable<DB, Schema, TableName>
+    | WhereableAssociatedModelParam<I>
   >
 >
 
@@ -314,7 +329,14 @@ type OnStatementForAssociationDefinition<
   TableName extends AssociationTableNames<DB, Schema> & keyof DB,
 > = Partial<
   MergeUnionOfRecordTypes<
-    | Partial<Selectable<DB[TableName]>>
+    // As in `Whereable`, the plain value form targets regular (scalar) columns.
+    // An array column accepts only `null` and `[]` as a plain value here;
+    // every other comparison against it goes through `ops`.
+    | Partial<{
+        [K in keyof Selectable<DB[TableName]>]: TableColumnIsArray<Schema, TableName, K> extends true
+          ? Extract<Selectable<DB[TableName]>[K], null> | readonly []
+          : Selectable<DB[TableName]>[K]
+      }>
     | Partial<{
         [ColumnName in keyof DB[TableName]]:
           | NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, ColumnName>