@rvoh/dream 2.40.2 → 2.42.0

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

@@ -264,6 +264,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns A Map from each present group value to the average of the aggregated column in that group
      */
     avgBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
+    exists(): Promise<boolean>;
     /**
      * Retrieves the number of records in the database
      *
@@ -367,6 +368,14 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * every `RETURNING *` / `select *` in this driver.
      */
     static saveDream(dream: Dream, txn?: DreamTransaction<Dream> | null): Promise<any>;
+    /**
+     * @internal
+     *
+     * Runs a read statement (a select, aggregate, pluck or preload), raising the
+     * driver's Dream error for a value the database rejects in place of the
+     * database's own error (see `dataIncompatibleWithDatabaseFieldError`).
+     */
+    private executeReadQuery;
     dbConnectionType(sqlCommandType: SqlCommandType): DbConnectionType;
     private isReplicaSafe;
     /**

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

@@ -1,6 +1,10 @@
 import { type SelectQueryBuilder } from 'kysely';
+import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
+import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
+import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
+import NotNullViolation from '../../errors/db/NotNullViolation.js';
 import Dream from '../../Dream.js';
-import { IntrospectedDatabase } from '../../types/db.js';
+import { DbConnectionType, IntrospectedDatabase } from '../../types/db.js';
 import DreamTransaction from '../DreamTransaction.js';
 import KyselyQueryDriver from './Kysely.js';
 import type { TestDatabaseLockSession } from './Base.js';
@@ -57,7 +61,31 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
     applyRowLock(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     static supportsAdvisoryTransactionLocks: boolean;
     static isUniqueConstraintViolation(error: unknown): boolean;
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.violatedUniqueIndexColumns}.
+     * A unique violation names the index it hit in the error's `constraint`
+     * field (a unique constraint's index shares its name), and one catalog query
+     * reads that index's key columns. `INCLUDE` columns are not keys and are
+     * left out.
+     */
+    static violatedUniqueIndexColumns(connectionName: string, error: unknown, table: string): Promise<string[] | null>;
     static isDeadlock(error: unknown): boolean;
+    static dataIncompatibleWithDatabaseFieldError(error: unknown): CheckConstraintViolation | ColumnOverflow | DataTypeColumnTypeMismatch | NotNullViolation | null;
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.rejectsAnyValueForColumnType}.
+     * One statement casts every value to its type, so Postgres's own input
+     * function for each type is the judge: a cast it rejects raises `22P02` or
+     * `22003`. Callers never ask inside a transaction, which a rejected cast
+     * would abort.
+     */
+    static rejectsAnyValueForColumnType(connectionName: string, dbConnectionType: DbConnectionType, values: {
+        value: unknown;
+        dbType: string;
+    }[]): Promise<boolean>;
     /**
      * @internal
      *

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

@@ -1,2 +1,3 @@
-export default function executeDatabaseQuery<Command extends DbQueryCommand, ReturnType extends Command extends 'execute' ? any[] : Command extends 'executeTakeFirst' ? any : Command extends 'executeTakeFirstOrThrow' ? any : never>(kyselyQuery: any, command: Command): Promise<ReturnType>;
+export default function executeDatabaseQuery<Command extends DbQueryCommand, ReturnType extends ExecuteDatabaseQueryReturnType<Command>>(kyselyQuery: any, command: Command): Promise<ReturnType>;
 export type DbQueryCommand = 'execute' | 'executeTakeFirst' | 'executeTakeFirstOrThrow';
+export type ExecuteDatabaseQueryReturnType<Command extends DbQueryCommand> = Command extends 'execute' ? any[] : Command extends 'executeTakeFirst' ? any : Command extends 'executeTakeFirstOrThrow' ? any : never;

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

@@ -1,6 +1,45 @@
 import Dream from '../Dream.js';
+/**
+ * What `createOrFindBy` and `createOrUpdateBy` could tell about why the
+ * record that blocked their insert was not found:
+ *
+ * - `conflictingAttributes`: the violated unique index covers these
+ *   `createWith`/`with` attributes but not every find attribute, so one of
+ *   their values likely conflicts with a different record
+ * - `hiddenByDefaultScope`: the violated unique index covers only find
+ *   attributes, or every find attribute, and a record matching them exists
+ *   once these default scopes are removed, so that record is the one the
+ *   insert conflicted with
+ * - `undetermined`: neither could be established. `hidingDefaultScopes` lists
+ *   the default scopes hiding a record that matches the find attributes, if
+ *   there is one, and `extraAttributesMayConflict` is true when a
+ *   `createWith`/`with` value may be what conflicted
+ */
+export type CreateOrFindFailureCause = {
+    kind: 'conflictingAttributes';
+    attributes: string[];
+} | {
+    kind: 'hiddenByDefaultScope';
+    defaultScopes: string[];
+} | {
+    kind: 'undetermined';
+    hidingDefaultScopes: string[];
+    extraAttributesMayConflict: boolean;
+};
+export declare const UNDETERMINED_CREATE_OR_FIND_FAILURE: CreateOrFindFailureCause;
 export default class CreateOrFindByFailedToCreateAndFind extends Error {
     private dreamClass;
-    constructor(dreamClass: typeof Dream);
+    private failureCause;
+    /**
+     * @param dreamClass - the model `createOrFindBy` was called on
+     * @param failureCause - what could be told about why the record that
+     * blocked the insert was not found
+     */
+    constructor(dreamClass: typeof Dream, failureCause?: CreateOrFindFailureCause);
     get message(): string;
 }
+export declare function describeDefaultScopes(scopeNames: string[]): string;
+export declare function describeAttributes(attributes: string[]): string;
+export declare function describePossibleCauses(failureCause: Extract<CreateOrFindFailureCause, {
+    kind: 'undetermined';
+}>, extraAttributesOption: string): string;

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

@@ -1,6 +1,13 @@
 import Dream from '../Dream.js';
+import { CreateOrFindFailureCause } from './CreateOrFindByFailedToCreateAndFind.js';
 export default class CreateOrUpdateByFailedToCreateAndUpdate extends Error {
     private dreamClass;
-    constructor(dreamClass: typeof Dream);
+    private failureCause;
+    /**
+     * @param dreamClass - the model `createOrUpdateBy` was called on
+     * @param failureCause - what could be told about why the record that
+     * blocked the insert was not found
+     */
+    constructor(dreamClass: typeof Dream, failureCause?: CreateOrFindFailureCause);
     get message(): string;
 }

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

@@ -0,0 +1,18 @@
+export interface GeneratedFilesAlreadyExistFlags {
+    overwrite: string;
+    skip: string;
+}
+export default class GeneratedFilesAlreadyExist extends Error {
+    modelName: string;
+    existingFiles: string[];
+    existingMigrations: string[];
+    flags: GeneratedFilesAlreadyExistFlags | undefined;
+    /**
+     * @param modelName - the fully qualified model name the generator was invoked with
+     * @param existingFiles - project-relative paths of the model, spec, factory and serializer files that already exist
+     * @param existingMigrations - project-relative paths of existing migrations with the name the generator would give the model's migration
+     * @param flags - the caller's flags for overwriting and for skipping existing files; when omitted, the message names Dream's `--overwrite` and `--skip-existing` and the commands that accept them
+     */
+    constructor(modelName: string, existingFiles: string[], existingMigrations: string[], flags?: GeneratedFilesAlreadyExistFlags);
+    get message(): string;
+}

package/dist/types/src/errors/schema-builder/ColumnNamesDoNotRoundTrip.d.ts

@@ -0,0 +1,12 @@
+export interface ColumnNameThatDoesNotRoundTrip {
+    tableName: string;
+    columnName: string;
+    attributeName: string;
+    mappedColumnName: string;
+    modelName: string;
+}
+export default class ColumnNamesDoNotRoundTrip extends Error {
+    private columns;
+    constructor(columns: ColumnNameThatDoesNotRoundTrip[]);
+    get message(): string;
+}

package/dist/types/src/helpers/cli/ASTConnectionBuilder.d.ts

@@ -32,9 +32,31 @@ export default class ASTConnectionBuilder extends ASTBuilder {
      * the connection's tables, sorted by their key in the DB interface, and its
      * enums, read through the query driver once, by this builder or by the one
      * it takes its introspection from. The tables that `tableIncludePattern`
-     * leaves out, or `tableExcludePattern` names, are left out.
+     * leaves out, or `tableExcludePattern` names, are left out. Fails, before
+     * either type file is written, when a column of a model's table does not
+     * round-trip through its attribute name (see guardColumnNamesRoundTrip).
      */
     protected introspectedDatabase(): Promise<IntrospectedDatabase>;
+    /**
+     * @internal
+     *
+     * fails the sync when a column of a table that one of the connection's
+     * models is backed by is not the column its attribute maps back to: Dream
+     * names the attribute by camelizing the column name, and each query naming
+     * the attribute targets the column the connection's CamelCasePlugin derives
+     * from it, so `address_line_1` (attribute `addressLine1`, which maps back to
+     * `address_line1`) could only be written, filtered on or join-loaded as a
+     * column that does not exist. A column the table's models ignore is
+     * skipped, since nothing queries it. A table no model is backed by is left
+     * to tableData, which fails the sync on it.
+     */
+    private guardColumnNamesRoundTrip;
+    /**
+     * @internal
+     *
+     * the models on the builder's connection
+     */
+    private connectionModels;
     /**
      * @internal
      *

package/dist/types/src/helpers/cli/generateDream.d.ts

@@ -1,3 +1,17 @@
+import { type GeneratedFilesAlreadyExistFlags } from '../../errors/GeneratedFilesAlreadyExist.js';
+/**
+ * What the model generators do when a file they would write already exists:
+ * - `'refuse'`: write nothing and throw an error listing the existing files
+ * - `'overwrite'`: replace the model, spec, factory and serializer files
+ * - `'skip'`: keep every existing file and write only the missing ones
+ *
+ * An existing migration with the name the generator would give the model's
+ * migration is never rewritten or duplicated, since it may already have run.
+ * Under `'skip'`, no migration is written at all when the model file already
+ * exists, since its table may have been created by a migration with another
+ * name.
+ */
+export type GenerateDreamExistingFiles = 'refuse' | 'overwrite' | 'skip';
 export interface GenerateDreamOptions {
     connectionName: string;
     serializer: boolean;
@@ -14,6 +28,17 @@ export interface GenerateDreamOptions {
      * allows opt-out via `--no-soft-delete`.
      */
     softDelete?: boolean;
+    /**
+     * What to do when a file the generator would write already exists.
+     * Defaults to `'refuse'`. See {@link GenerateDreamExistingFiles}.
+     */
+    existingFiles?: GenerateDreamExistingFiles | undefined;
+    /**
+     * The caller's flags that select `existingFiles: 'overwrite'` and
+     * `existingFiles: 'skip'`, which the refusal names. Defaults to Dream's
+     * `--overwrite` and `--skip-existing`.
+     */
+    existingFilesFlags?: GeneratedFilesAlreadyExistFlags | undefined;
 }
 export default function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }: {
     fullyQualifiedModelName: string;

package/dist/types/src/helpers/cli/generateMigration.d.ts

@@ -1,4 +1,21 @@
-export default function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete, }: {
+export interface GeneratedMigration {
+    /** The project-relative migrations folder the file goes in */
+    basePath: string;
+    /** `<version>-<fileStem>.ts` */
+    fileName: string;
+    /**
+     * The file name without its version prefix and extension, e.g.
+     * `create-room-bedroom` for the migration name `CreateRoom/Bedroom`
+     */
+    fileStem: string;
+    content: string;
+}
+export type GenerateMigrationArgs = Parameters<typeof buildMigration>[0];
+/**
+ * Builds and validates a migration without writing it, so a caller writing
+ * several files can build them all before writing any.
+ */
+export declare function buildMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete, }: {
     migrationName: string;
     columnsWithTypes: string[];
     connectionName: string;
@@ -17,4 +34,5 @@ export default function generateMigration({ migrationName, columnsWithTypes, con
      * `created_at` / `updated_at` timestamps.
      */
     softDelete?: boolean;
-}): Promise<void>;
+}): GeneratedMigration;
+export default function generateMigration(args: GenerateMigrationArgs): Promise<void>;

package/dist/types/src/helpers/cli/syncWithFailureContext.d.ts

@@ -29,8 +29,13 @@ export interface SyncFailureContext {
      * work is already committed by the time the sync runs, so re-running it rolls
      * back a *further* migration rather than retrying the step that failed.
      *
-     * Defaults to ``run `sync` on its own`` — the retry that is safe after any of
-     * these commands, since it repeats only the step that actually failed.
+     * Defaults to ``run `sync` on its own``, which is not safe after every
+     * command: a failed sync reverts the generated types to what they were
+     * before the command ran, and a Psychic app's `psy sync` boots with the
+     * integrity checks on, so it fails against those types whenever a model or
+     * serializer already uses a table or column the command just added. A
+     * command that adds schema passes advice that re-runs `db:migrate`, which
+     * boots with the checks bypassed and goes straight to the sync.
      */
     recoveryAdvice?: string | undefined;
 }

package/dist/types/src/helpers/cli/writeGeneratedFile.d.ts

@@ -10,9 +10,14 @@ export interface WriteGeneratedFileArgs {
     content: string;
     /** Label for CLI output (e.g. 'dream', 'serializer', 'factory', 'spec', 'migration') */
     logLabel: string;
+    /**
+     * When true, an existing file at the path is replaced. Otherwise the write
+     * fails if a file is already there.
+     */
+    overwrite?: boolean | undefined;
 }
 /**
  * Common file-writing helper used by all Dream generators.
  * Handles directory creation, file writing, logging, and error wrapping.
  */
-export default function writeGeneratedFile({ dreamPathKey, basePath, fileName, content, logLabel, }: WriteGeneratedFileArgs): Promise<void>;
+export default function writeGeneratedFile({ dreamPathKey, basePath, fileName, content, logLabel, overwrite, }: WriteGeneratedFileArgs): Promise<void>;

package/dist/types/src/helpers/db/normalizeDataForDb.d.ts

@@ -1,4 +1,11 @@
 import Dream from '../../Dream.js';
+/**
+ * Whether `error` is the `DataTypeColumnTypeMismatch` raised here for a date,
+ * datetime or time value Dream cannot convert for its column. Values are
+ * converted while a statement is built, so such an error means the statement
+ * was never sent to the database.
+ */
+export declare function isMismatchRaisedBeforeQuerying(error: unknown): boolean;
 export declare function normalizeDataForDb({ val, dreamClass, column, }: {
     val: unknown;
     dreamClass: typeof Dream;

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/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>

package/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "eJyVkkFvwjAMhf+Lz4EppQq0x4EmTdPYJk3bAXEIrVkj0gTFKVOF+O9TxqUwWMPJUeTn9+XFe3DWeoJ8wUU6ZpzzJQOHa42FV9YQ5HvgnIdiZI2Qw1uDrp05tUN3LwmBwUaZEnKeTBg0TkMOhZZESHflanjWPax8rYEdOyAHT+UgyAfHCwZFpXTp0EC+SLJseWCQZFnH/akl1G1nao//n/5bCPhoJAJCqB2GV0v+yyHFU1xQ9HAEV3GS+7TCYjO1hryTyvgPZbUMX/SfNTpnHQ2vSWMYkm76U6ub2rzs0K21/Y5xPhHE+KXjjt9MevloCltvpVcrjZ/KV+FuJQkfFOoyAqF3xk0bIThnIRTGhRCMi0n6uyBCiDPs93aLx9eH07OiWvqiiuS9LI6Jb5J2OObWzxutb1mVc0mf5+HwAx1tbyM="
+window.hierarchyData = "eJyVksFuAiEQht9lzmjFNcvKsZomTVPbJk17MB5wd+wSWTDA2myM795QL9TaLp6GkPn5PmAOYI3xDviSstGUUEpXBCxuFJZeGu2AH4BSGooWDQKHlxZtN7dyj/ZWOAQCW6kr4HRcEGitAg6lEs6hu6nWw7PuYe0bBeTUARy8qwYhPjhtEChrqSqLGvgyo2x1JJBRFtEfOoeqi07t4f/qv8aAZqwICqFGDs/G+Q+LLt3iQqLHI1BzlkXUWY3ldma081ZI7d+kUSJ80X9otNZYN/wrmuIwjf9+ZlTb6Kc92o0ynynkH4EEHhtNI95ceHGvS9PshJdrhe/S12FvLRzeSVRVgkLvGVdNRM4yEh6FUDYuCGWT/HtA2Lg4037tdni6fVg9StcIX9aJvpfDKc83ySOPhfGLVqlrRuU80sc8Hr8AEqNvJQ=="