@rvoh/dream 2.18.1 → 2.20.0

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

@@ -157,6 +157,20 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      *
      */
     max(columnName: string): Promise<any>;
+    /**
+     * Retrieves the max value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().maxBy('name', 'score')
+     * // Map(2) { 'primary' => 9, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the max of within each group
+     * @returns A Map from each present group value to the max of the aggregated column in that group
+     */
+    maxBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -170,6 +184,20 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns the min value of the specified column for this Query
      */
     min(columnName: string): Promise<any>;
+    /**
+     * Retrieves the min value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().minBy('name', 'score')
+     * // Map(2) { 'primary' => 1, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the min of within each group
+     * @returns A Map from each present group value to the min of the aggregated column in that group
+     */
+    minBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -183,6 +211,20 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns the sum of the values of the specified column for this Query
      */
     sum(columnName: string): Promise<any>;
+    /**
+     * Retrieves the sum of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().sumBy('name', 'score')
+     * // Map(2) { 'primary' => 10, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to sum within each group
+     * @returns A Map from each present group value to the sum of the aggregated column in that group
+     */
+    sumBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -196,6 +238,20 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns the average of the values of the specified column for this Query
      */
     avg(columnName: string): Promise<any>;
+    /**
+     * Retrieves the average of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().avgBy('name', 'score')
+     * // Map(2) { 'primary' => 5, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to average within each group
+     * @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>>;
     /**
      * Retrieves the number of records in the database
      *
@@ -206,6 +262,38 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns The number of records in the database
      */
     count(): Promise<number>;
+    /**
+     * Retrieves the number of records in each group, keyed by the
+     * value of the provided group column.
+     *
+     * ```ts
+     * await User.query().countBy('name')
+     * // Map(2) { 'fred' => 2, 'zed' => 1 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @returns A Map from each present group value to the number of records in that group
+     */
+    countBy(groupColumn: string): Promise<Map<any, number>>;
+    /**
+     * @internal
+     *
+     * Shared plumbing for grouped aggregates (`countBy` and the value-aggregate
+     * siblings `minBy` / `maxBy` / `sumBy` / `avgBy`). Selects the group column
+     * alongside a single aggregate expression, groups by the group column, executes,
+     * and folds the resulting rows into a Map keyed by the group value.
+     *
+     * The group column and the aggregate are selected under stable, underscore-free
+     * aliases so they can be read back off each row without being affected by
+     * Kysely's CamelCasePlugin (which would otherwise mangle a namespaced alias),
+     * mirroring the short-alias strategy used by `pluck`.
+     *
+     * @param groupColumn - the column to GROUP BY (base or joined-association-namespaced)
+     * @param aggregateExpression - the Kysely aggregate expression to select per group (e.g. `count(pk)`)
+     * @param coerceValue - maps each raw aggregate value to the value stored in the returned Map
+     * @returns A Map from each present group value to its coerced aggregate value
+     */
+    private groupedAggregate;
     /**
      * @internal
      *
@@ -244,6 +332,27 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * is provided as a second argument, it will use that transaction
      * to encapsulate the persisting of the dream, as well as any
      * subsequent model hooks that are fired.
+     *
+     * `RETURNING *` (rather than enumerating the compiled column list) keeps
+     * writes working under schema/image skew: during a rolling deploy, a
+     * container built before a drop-column migration would otherwise name the
+     * dropped column in `RETURNING` and fail with `42703 column does not
+     * exist` on every write, even writes that never touch that column. The
+     * `SET`/`VALUES` half still names only dirty attributes, so a write that
+     * actually sets a dropped column still fails loudly. The returned row is
+     * filtered to the compiled column list before hydration (see
+     * internal/saveDream.ts), so a column the image doesn't know about never
+     * reaches `setAttributes`.
+     *
+     * KNOWN CONSTRAINT: star-selects are only safe because nothing in this
+     * stack uses named prepared statements — node-postgres prepares a
+     * statement only when given an explicit `name`, and Kysely never names
+     * them, so every query is re-planned. With named prepared statements, a
+     * concurrent `ADD COLUMN` changes a cached plan's result shape and
+     * Postgres raises `cached plan must not change result type` (the reason
+     * Rails added `enumerate_columns_in_select_statements`). If a future
+     * driver or pooling layer enables named prepared statements, revisit
+     * every `RETURNING *` / `select *` in this driver.
      */
     static saveDream(dream: Dream, txn?: DreamTransaction<Dream> | null): Promise<any>;
     dbConnectionType(sqlCommandType: SqlCommandType): DbConnectionType;
@@ -319,6 +428,48 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     private inArrayWithNull_or_notInArrayWithoutNull_ExpressionBuilder;
     private inArrayWithoutNullExpressionBuilder;
     private notInArrayWithNullExpressionBuilder;
+    /**
+     * @internal
+     *
+     * A Dream instance (or array of Dream instances) as a where-clause value is
+     * resolved as an association of the dreamClass whose statement is being
+     * compiled, so a key namespaced to a different table (e.g.
+     * `where({ 'c.user': user })` after `innerJoin('composition as c')`) would
+     * silently resolve the association against the wrong class, emitting invalid
+     * SQL or SQL that filters the wrong table. Such keys are already rejected at
+     * the type level; this guard rejects them at runtime. Un-namespaced keys and
+     * keys namespaced to the alias the statement applies to are unaffected, as
+     * are callers that do not declare an expected alias.
+     */
+    private validateAssociationFilterAlias;
+    /**
+     * @internal
+     *
+     * An array under an association name can only be an array of Dream instances
+     * (association names are not columns). The every-element check simply avoids
+     * changing the handling of invalid runtime input (e.g. an array of ids under
+     * an association name), which the type system already rejects.
+     */
+    private isAssociationInstanceArray;
+    /**
+     * @internal
+     *
+     * Expands an array of Dream instances under a BelongsTo association name into
+     * foreign key filtering:
+     * - non-polymorphic: `foreignKey IN (...)`
+     * - polymorphic: instances are grouped by their reference type (STI children
+     *   collapse into their base class), each group becoming
+     *   `(foreignKey IN (...) AND foreignKeyTypeField = 'TheType')`, with multiple
+     *   groups ORed together
+     * - empty array: matches nothing (FALSE); when the caller negates, NOT(FALSE)
+     *   matches everything, mirroring empty `in`/`not in` array semantics
+     *
+     * When `negate` is set, IS NOT NULL conditions are included so that the
+     * caller's negation also matches records in which the foreign key (or type
+     * field) is null, consistent with negation of single Dream instances and of
+     * `in` arrays.
+     */
+    private associationInstanceArrayToExpressionWrapper;
     private dreamWhereStatementToExpressionBuilderParts;
     private normalizedWhereValue;
     private recursivelyJoin;
@@ -466,26 +617,54 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      *   public b
      * ```
      *
+     * Options declared on a through association (`and`/`andAny`/`andNot`/`selfAnd`/
+     * `selfAndNot`/`order`/`distinct`) are applied at the join of the table where the
+     * through association's target model materializes. When a source is itself a
+     * through association, that join is only reached after bridging further through
+     * associations, so each through association is pushed onto the
+     * `previousThroughAssociations` stack (along with the alias `selfAnd`/`selfAndNot`
+     * clauses reference) before the terminal `applyOneJoin` call, and the stack is
+     * threaded through every recursion until `addAssociationJoinStatementToQuery`
+     * reaches a concrete (non-through) association, where every stacked entry is
+     * applied to that join.
+     *
      * Then `MyModel.leftJoinPreload('myB')` is processed as follows:
      * - `applyOneJoin` is called with the `myB` association
      *   - `joinsBridgeThroughAssociations` is called with the `myB` association
      *     - `joinsBridgeThroughAssociations` is called with the `myA` association
      *       - `addAssociationJoinStatementToQuery` is called with the `otherModel` association
-     *       - `applyOneJoin` is called with the `a` association from OtherModel
-     *         - `joinsBridgeThroughAssociations` is called with the `a` association from OtherModel
-     *           // throw ThroughAssociationConditionsIncompatibleWithThroughAssociationSource if
-     *           // myA in MyModel defines conditions, distinct, or order
+     *       - `applyOneJoin` is called with the `a` association from OtherModel, with `myA` pushed
+     *         onto the previousThroughAssociations stack
+     *         - `joinsBridgeThroughAssociations` is called with the `a` association from OtherModel,
+     *           inheriting the stack
      *           - `addAssociationJoinStatementToQuery` is called with the `aToOtherModelJoinModel` association
-     *           - `applyOneJoin` is called with the `a` association from AToOtherModelJoinModel with conditions (if present) on `a` defined on OtherModel
-     *             - `addAssociationJoinStatementToQuery` is called with the `myA` association
-     *     - `applyOneJoin` is called with the `b` association from A with conditions (if present) from `myB` defined on MyModel
-     *       - `addAssociationJoinStatementToQuery` is called with the `myB` association
+     *           - `applyOneJoin` is called with the `a` association from AToOtherModelJoinModel, with the
+     *             `a` association from OtherModel pushed onto the stack
+     *             - `addAssociationJoinStatementToQuery` is called with the `a` association from
+     *               AToOtherModelJoinModel, applying the options (if present) of every stacked through
+     *               association (`myA` defined on MyModel, `a` defined on OtherModel) to the `through_as` join
+     *     - `applyOneJoin` is called with the `b` association from A, with `myB` pushed onto the stack
+     *       - `addAssociationJoinStatementToQuery` is called with the `b` association from A, applying
+     *         the options (if present) of `myB` defined on MyModel to the `through_bs` join
      */
     private joinsBridgeThroughAssociations;
     private applyOneJoin;
     private addAssociationJoinStatementToQuery;
     private applyOrderStatementForAssociation;
     private distinctColumnNameForAssociation;
+    /**
+     * Applies the and-family clauses (`and`/`andAny`/`andNot`/`selfAnd`/`selfAndNot`)
+     * of every pending through association to the terminal concrete join of a
+     * through association chain.
+     *
+     * The first entry in the stack is the association the developer named in the
+     * join/preload/associationQuery statement, so it is the association the
+     * developer-supplied joinAndStatement corresponds to (used to satisfy
+     * `DreamConst.required` clauses); `DreamConst.required` on any other stacked
+     * through association cannot be satisfied and will throw
+     * `MissingRequiredAssociationAndClause`.
+     */
+    private applyPreviousThroughAssociationAndStatementsToJoinStatement;
     private applyAssociationAndStatementsToJoinStatement;
     private throwUnlessAllRequiredWhereClausesProvided;
     private conditionallyApplyDefaultScopesDependentOnAssociation;

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

@@ -0,0 +1,30 @@
+/**
+ * @internal
+ *
+ * Returns an object containing only the keys of `row` that are columns
+ * the compiled schema knows about (per the provided column set).
+ *
+ * Under schema/image skew (e.g. a rolling deploy in which a migration adds
+ * a column while containers built against the previous schema are still
+ * draining, or application code is rolled back after an add-column
+ * migration), a `RETURNING *` / `select *` row can include columns this
+ * build has never heard of. Passing such keys to `setAttributes` would
+ * assign them as plain properties — invoking a same-named user-defined
+ * setter, or throwing on a getter-only property — so they must be dropped
+ * before hydration.
+ *
+ * Keys are intersected rather than enumerated from the column set so that
+ * a column missing from the row (the dropped-column direction of skew)
+ * simply does not appear, rather than appearing with an `undefined` value.
+ *
+ * Identity fast path: when every key of `row` is a known column (the
+ * no-skew steady state), `row` itself is returned unchanged, without
+ * allocating a copy; a filtered copy is built only when at least one
+ * unknown key is present.
+ *
+ * @param row - a raw database row
+ * @param columns - the compiled column set for the Dream class being hydrated
+ * @returns `row` itself when every key is a known column; otherwise a new
+ * object containing only the known-column entries of `row`
+ */
+export default function filterRowToKnownColumns(row: Record<string, any>, columns: Set<string>): Record<string, any>;

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

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

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

@@ -0,0 +1,12 @@
+import Dream from '../../Dream.js';
+import { AssociationStatement } from '../../types/associations/shared.js';
+export default class CannotIgnoreAssociationColumn extends Error {
+    private tableName;
+    private columnName;
+    private modelClass;
+    private association;
+    private columnRole;
+    constructor(tableName: string, columnName: string, modelClass: typeof Dream, association: AssociationStatement, columnRole: 'foreign key' | 'polymorphic type field' | 'primary key override');
+    get message(): string;
+    private get consequence();
+}

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

@@ -0,0 +1,7 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnoreEncryptedColumn extends Error {
+    private modelClass;
+    private columnName;
+    constructor(modelClass: typeof Dream, columnName: string);
+    get message(): string;
+}

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

@@ -0,0 +1,6 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnorePrimaryKey extends Error {
+    private modelClass;
+    constructor(modelClass: typeof Dream);
+    get message(): string;
+}

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

@@ -0,0 +1,7 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnoreSoftDeleteColumn extends Error {
+    private modelClass;
+    private columnName;
+    constructor(modelClass: typeof Dream, columnName: string);
+    get message(): string;
+}

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

@@ -0,0 +1,7 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnoreSortablePositionColumn extends Error {
+    private modelClass;
+    private columnName;
+    constructor(modelClass: typeof Dream, columnName: string);
+    get message(): string;
+}

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

@@ -0,0 +1,8 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnoreSortableScopeColumn extends Error {
+    private modelClass;
+    private columnName;
+    private positionField;
+    constructor(modelClass: typeof Dream, columnName: string, positionField: string);
+    get message(): string;
+}

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

@@ -0,0 +1,6 @@
+import Dream from '../../Dream.js';
+export default class CannotIgnoreStiTypeColumn extends Error {
+    private modelClass;
+    constructor(modelClass: typeof Dream);
+    get message(): string;
+}

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

@@ -0,0 +1,7 @@
+import Dream from '../../Dream.js';
+export default class ConflictingIgnoredColumns extends Error {
+    private tableName;
+    private modelClasses;
+    constructor(tableName: string, modelClasses: (typeof Dream)[]);
+    get message(): string;
+}

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

@@ -0,0 +1,7 @@
+import Dream from '../../Dream.js';
+export default class IgnoredColumnMustBeCamelCase extends Error {
+    private modelClass;
+    private columnName;
+    constructor(modelClass: typeof Dream, columnName: string);
+    get message(): string;
+}

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

@@ -94,6 +94,26 @@ export default class ASTConnectionBuilder extends ASTBuilder {
      * Can be used to build up types
      */
     private tableData;
+    /**
+     * @internal
+     *
+     * resolves the ignored columns declared by the models backed by the
+     * given table (validating the declarations; see resolveIgnoredColumns)
+     */
+    protected ignoredColumnsForTable(tableName: string): Set<string>;
+    /**
+     * @internal
+     *
+     * returns the provided column data without the columns that the table's
+     * models declare in ignoredColumns. This is what removes ignored columns
+     * from the generated dream schema file: `columns()` reads the generated
+     * schema at runtime, so every column enumeration built from `columns()`
+     * (preload and join-load select lists, save hydration, attribute
+     * definition) inherits this filtering. A column that is ignored but not
+     * present in the introspected table (e.g. after the drop migration has
+     * run but before the declaration is removed) is a no-op.
+     */
+    private withoutIgnoredColumns;
     /**
      * @internal
      *

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

@@ -70,6 +70,19 @@ export default class ASTKyselyCodegenEnhancer extends ASTConnectionBuilder {
      * (since the DB interface is indexed by table name, which must not be camelized)
      */
     private camelizeKeys;
+    /**
+     * @internal
+     *
+     * removes columns declared in model `ignoredColumns` getters from the
+     * table interfaces generated by kysely-codegen. This is what removes
+     * ignored columns from the generated db types file: every column-name
+     * level type (`DreamColumnNames`, `UpdateableProperties`, where-clause
+     * statements) derives from the Kysely `DB` interface, so filtering here
+     * turns any remaining code reference to an ignored column into a type
+     * error. Runs after camelizeKeys so that member names align with the
+     * camelCase column names models declare in ignoredColumns.
+     */
+    private removeIgnoredColumns;
     /**
      * @internal
      *

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

@@ -0,0 +1,41 @@
+import Dream from '../../Dream.js';
+/**
+ * @internal
+ *
+ * Resolves the set of ignored columns for a table from the `ignoredColumns`
+ * declarations of every model backed by that table, validating the
+ * declarations along the way. Called while `sync` builds the generated types
+ * files (the declarations have no runtime behavior; see the `ignoredColumns`
+ * getter on Dream), so each of these guards fails the sync command loudly
+ * rather than surfacing as broken behavior at runtime:
+ *
+ * - ignored columns must be declared in camelCase, since generated column
+ *   names are camelized, so any other shape can never match a generated
+ *   column and would be silently inert
+ * - a model may never ignore its primary key
+ * - an STI model may never ignore the STI "type" column
+ * - a model may never ignore an @Sortable position field or a plain-column
+ *   @Sortable scope, the backing column of an @Encrypted property, or (on a
+ *   SoftDelete model) its deletedAtField — the framework reads and writes
+ *   those columns by name
+ * - models sharing a table must agree on their ignored columns, since there
+ *   is only one generated schema per table (STI children inherit the base
+ *   model's getter, so agreement is automatic unless a child overrides it)
+ * - no association anywhere in the app may name an ignored column as the
+ *   foreign key (or polymorphic type field) it reads and writes on this
+ *   table — a BelongsTo on a model backed by this table names a foreign key
+ *   on this table, and so does a HasMany/HasOne on any other model that
+ *   points at a model backed by this table
+ * - no association anywhere in the app may name an ignored column as its
+ *   primaryKeyOverride — the column the association's foreign key points
+ *   at, which lives on the associated model's table for a BelongsTo and on
+ *   the declaring model's own table for a HasMany/HasOne
+ *
+ * @param models - every model backed by the table
+ * @param tableName - the table whose ignored columns are being resolved
+ * @param allModels - every model in the app (on the table's connection);
+ *   required because associations declared on other models can name foreign
+ *   keys on this table
+ * @returns the set of column names to omit from the table's generated types
+ */
+export default function resolveIgnoredColumns(models: (typeof Dream)[], tableName: string, allModels: (typeof Dream)[]): Set<string>;

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

@@ -34,8 +34,11 @@ type JoinedAssociationColumnNames<JoinedAssociations extends Readonly<JoinedAsso
 type Whereable<R> = {
     [K in keyof Selectable<R>]?: 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> | AssociatedModelParam<I>>>;
+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 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<{

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

@@ -51,6 +51,23 @@ export type PassthroughOnClauseKeys<Schema, TableName, AssociationName, Associat
  * must be forbidden at compile time for the hydrating load variants.
  */
 export type IsNonOptionalBelongsToAssociation<Schema, TableName, AssociationName, Associations = TableName extends null ? null : TableName extends keyof Schema & string ? Schema[TableName]['associations' & keyof Schema[TableName]] : null, Association = Associations extends null ? null : AssociationName extends keyof Associations ? Associations[AssociationName] : null> = Association extends null ? false : Association['type' & keyof Association] extends 'BelongsTo' ? Association['optional' & keyof Association] extends false ? true : false : false;
+/**
+ * Resolves to `true` when the named association on the given table is a
+ * polymorphic BelongsTo. Joining a polymorphic BelongsTo raises
+ * CannotJoinPolymorphicBelongsToError at runtime, so the variadic join types
+ * (innerJoin / leftJoin / leftJoinPreload / leftJoinLoad) reject these
+ * association names at compile time.
+ */
+export type IsPolymorphicBelongsToAssociation<Schema, TableName, AssociationName, Associations = TableName extends null ? null : TableName extends keyof Schema & string ? Schema[TableName]['associations' & keyof Schema[TableName]] : null, Association = Associations extends null ? null : AssociationName extends keyof Associations ? Associations[AssociationName] : null> = Association extends null ? false : Association['type' & keyof Association] extends 'BelongsTo' ? Association['foreignKeyTypeColumn' & keyof Association] extends string ? true : false : false;
+/**
+ * Union of the association names on the given table that are polymorphic
+ * BelongsTo associations. Used by the variadic join types to exclude these
+ * names from the allowed argument values, since joining a polymorphic
+ * BelongsTo raises CannotJoinPolymorphicBelongsToError at runtime.
+ */
+export type PolymorphicBelongsToAssociationNames<Schema, TableName extends keyof Schema, AssociationMetadata = AssociationMetadataForTable<Schema, TableName>> = IsAny<AssociationMetadata> extends true ? never : {
+    [K in keyof AssociationMetadata]: AssociationMetadata[K]['type' & keyof AssociationMetadata[K]] extends 'BelongsTo' ? AssociationMetadata[K]['foreignKeyTypeColumn' & keyof AssociationMetadata[K]] extends string ? K : never : never;
+}[keyof AssociationMetadata];
 export type DreamAssociationNames<DreamInstance extends Dream, SchemaAssociations = DreamAssociationMetadata<DreamInstance>> = keyof SchemaAssociations;
 export type DreamBelongsToAssociationNames<DreamInstance extends Dream> = keyof DreamBelongsToAssociationMetadata<DreamInstance>;
 export type DreamHasOneAssociationNames<DreamInstance extends Dream> = keyof DreamHasOneAssociationMetadata<DreamInstance>;

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

@@ -221,6 +221,15 @@ type Whereable<R> = {
   [K in keyof Selectable<R>]?: Selectable<R>[K] | Selectable<R>[K][]
 }
 
+// For filtering by BelongsTo model instance(s) in a where/and statement, e.g.
+// `await Room.where({ place: [place1, place2] }).all()`. Unlike
+// `AssociatedModelParam` (the create/update param type, where an array of
+// instances would be meaningless), each association also accepts an array
+// of associated model instances.
+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<
@@ -230,7 +239,7 @@ export type InternalWhereStatement<
   TableName extends AssociationTableNames<DB, Schema> & keyof DB,
 > = Partial<
   MergeUnionOfRecordTypes<
-    Whereable<DB[TableName]> | DreamSelectable<DB, Schema, TableName> | AssociatedModelParam<I>
+    Whereable<DB[TableName]> | DreamSelectable<DB, Schema, TableName> | WhereableAssociatedModelParam<I>
   >
 >
 

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

@@ -254,6 +254,59 @@ export type IsNonOptionalBelongsToAssociation<
       : false
     : false
 
+/**
+ * Resolves to `true` when the named association on the given table is a
+ * polymorphic BelongsTo. Joining a polymorphic BelongsTo raises
+ * CannotJoinPolymorphicBelongsToError at runtime, so the variadic join types
+ * (innerJoin / leftJoin / leftJoinPreload / leftJoinLoad) reject these
+ * association names at compile time.
+ */
+export type IsPolymorphicBelongsToAssociation<
+  Schema,
+  TableName,
+  AssociationName,
+  Associations = TableName extends null
+    ? null
+    : TableName extends keyof Schema & string
+      ? Schema[TableName]['associations' & keyof Schema[TableName]]
+      : null,
+  Association = Associations extends null
+    ? null
+    : AssociationName extends keyof Associations
+      ? Associations[AssociationName]
+      : null,
+> = Association extends null
+  ? false
+  : Association['type' & keyof Association] extends 'BelongsTo'
+    ? Association['foreignKeyTypeColumn' & keyof Association] extends string
+      ? true
+      : false
+    : false
+
+/**
+ * Union of the association names on the given table that are polymorphic
+ * BelongsTo associations. Used by the variadic join types to exclude these
+ * names from the allowed argument values, since joining a polymorphic
+ * BelongsTo raises CannotJoinPolymorphicBelongsToError at runtime.
+ */
+export type PolymorphicBelongsToAssociationNames<
+  Schema,
+  TableName extends keyof Schema,
+  AssociationMetadata = AssociationMetadataForTable<Schema, TableName>,
+> =
+  // when the schema is untyped (`any`), resolve to `never` so nothing is
+  // excluded from the allowed association names
+  IsAny<AssociationMetadata> extends true
+    ? never
+    : {
+        [K in keyof AssociationMetadata]: AssociationMetadata[K]['type' &
+          keyof AssociationMetadata[K]] extends 'BelongsTo'
+          ? AssociationMetadata[K]['foreignKeyTypeColumn' & keyof AssociationMetadata[K]] extends string
+            ? K
+            : never
+          : never
+      }[keyof AssociationMetadata]
+
 export type DreamAssociationNames<
   DreamInstance extends Dream,
   SchemaAssociations = DreamAssociationMetadata<DreamInstance>,