@rvoh/dream 2.5.0 → 2.5.1

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

@@ -80,6 +80,40 @@ type AssociationMetadataForTable<Schema, TableName extends keyof Schema> = Schem
 export type AssociationNamesForTable<Schema, TableName extends keyof Schema> = keyof AssociationMetadataForTable<Schema, TableName> | AliasedSchemaAssociation<Schema, TableName>;
 type MetadataForAssociation<Schema, TableName extends keyof Schema, AssociationName, AssociationMetadata = AssociationMetadataForTable<Schema, TableName>> = AssociationMetadata[AssociationName & keyof AssociationMetadata];
 export type AssociationTableName<Schema, TableName extends keyof Schema, AssociationName, AssociationData = MetadataForAssociation<Schema, TableName, AssociationName>> = (AssociationData['tables' & keyof AssociationData] & any[])[0] & keyof Schema;
+/**
+ * @internal
+ *
+ * Union of all table names for an association, accounting
+ * for polymorphic associations, which contain more than one
+ * table.
+ *
+ * ```ts
+ * AssociationTableNamesForAssociation<Schema, 'ratings', 'rateable'>
+ * // 'compositions' | 'posts'
+ * ```
+ */
+export type AssociationTableNamesForAssociation<Schema, TableName extends keyof Schema, AssociationName, AssociationData = MetadataForAssociation<Schema, TableName, AssociationName>> = (AssociationData['tables' & keyof AssociationData] & readonly (keyof Schema)[])[number];
+/**
+ * @internal
+ *
+ * Union of all association names for an association, accounting
+ * for polymorphic associations. In a polymorphic scenario, an association
+ * like `Rating#rateable` will point to multiple models, in this case
+ * either Composition or Post. Both of these models have some shared associations
+ * (i.e. `user`), but also some differing associations. This type helper
+ * will union all of these possibilities together, enabling us to preload
+ * inner associations safely at the type layer, since it is already
+ * supported at the implementation layer.
+ *
+ * In the example below, `compositionAssets` will come from the Composition model,
+ * while `comments` will come from the Post model.
+ *
+ * ```ts
+ * AssociationNamesForAssociation<Schema, 'ratings', 'rateable'>
+ * // 'compositionAssets' | 'comments' ...
+ * ```
+ */
+export type AssociationNamesForAssociation<Schema, TableName extends keyof Schema, AssociationName, TableNamesUnion = AssociationTableNamesForAssociation<Schema, TableName, AssociationName>> = TableNamesUnion extends keyof Schema ? AssociationNamesForTable<Schema, TableNamesUnion> : never;
 export type DreamClassAssociationAndStatement<DreamClass extends typeof Dream, AssociationName, DreamInstance extends InstanceType<DreamClass> = InstanceType<DreamClass>, DB extends DreamInstance['DB'] = DreamInstance['DB'], Schema extends DreamInstance['schema'] = DreamInstance['schema'], TableName extends DreamInstance['table'] = DreamInstance['table'], AssocTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB = AssociationTableName<Schema, TableName, AssociationName>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName> = RequiredOnClauseKeys<Schema, TableName, AssociationName>, Statements extends JoinAndStatements<DreamInstance, DB, Schema, AssocTableName, RequiredOnClauseKeysForThisAssociation> = JoinAndStatements<DreamInstance, DB, Schema, AssocTableName, RequiredOnClauseKeysForThisAssociation>> = Statements;
 export type JoinAndStatements<I extends Dream, DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation> = RequiredOnClauseKeysForThisAssociation extends null ? {
     and?: InternalWhereStatement<I, DB, Schema, TableName>;

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

@@ -375,6 +375,52 @@ export type AssociationTableName<
   AssociationData = MetadataForAssociation<Schema, TableName, AssociationName>,
 > = (AssociationData['tables' & keyof AssociationData] & any[])[0] & keyof Schema
 
+/**
+ * @internal
+ *
+ * Union of all table names for an association, accounting
+ * for polymorphic associations, which contain more than one
+ * table.
+ *
+ * ```ts
+ * AssociationTableNamesForAssociation<Schema, 'ratings', 'rateable'>
+ * // 'compositions' | 'posts'
+ * ```
+ */
+export type AssociationTableNamesForAssociation<
+  Schema,
+  TableName extends keyof Schema,
+  AssociationName,
+  AssociationData = MetadataForAssociation<Schema, TableName, AssociationName>,
+> = (AssociationData['tables' & keyof AssociationData] & readonly (keyof Schema)[])[number]
+
+/**
+ * @internal
+ *
+ * Union of all association names for an association, accounting
+ * for polymorphic associations. In a polymorphic scenario, an association
+ * like `Rating#rateable` will point to multiple models, in this case
+ * either Composition or Post. Both of these models have some shared associations
+ * (i.e. `user`), but also some differing associations. This type helper
+ * will union all of these possibilities together, enabling us to preload
+ * inner associations safely at the type layer, since it is already
+ * supported at the implementation layer.
+ *
+ * In the example below, `compositionAssets` will come from the Composition model,
+ * while `comments` will come from the Post model.
+ *
+ * ```ts
+ * AssociationNamesForAssociation<Schema, 'ratings', 'rateable'>
+ * // 'compositionAssets' | 'comments' ...
+ * ```
+ */
+export type AssociationNamesForAssociation<
+  Schema,
+  TableName extends keyof Schema,
+  AssociationName,
+  TableNamesUnion = AssociationTableNamesForAssociation<Schema, TableName, AssociationName>,
+> = TableNamesUnion extends keyof Schema ? AssociationNamesForTable<Schema, TableNamesUnion> : never
+
 export type DreamClassAssociationAndStatement<
   DreamClass extends typeof Dream,
   AssociationName,

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

@@ -1,23 +1,32 @@
 import Dream from '../Dream.js';
 import { Camelized } from '../helpers/stringCasing.js';
 import { AssociationTableNames } from './db.js';
-import { AssociationNamesForTable, AssociationTableName, DreamAssociationNameToAssociatedModel, JoinAndStatements, MAX_VARIADIC_DEPTH, RequiredOnClauseKeys } from './dream.js';
+import { AssociationNamesForAssociation, AssociationNamesForTable, AssociationTableName, AssociationTableNamesForAssociation, DreamAssociationNameToAssociatedModel, JoinAndStatements, MAX_VARIADIC_DEPTH, RequiredOnClauseKeys } from './dream.js';
 import { Inc, ReadonlyTail } from './utils.js';
 type VALID = 'valid';
 type INVALID = 'invalid';
 type IS_ASSOCIATION_ALIAS = 'association_alias';
 type IS_ASSOCIATION_NAME = 'association_name';
 type IS_NOT_ASSOCIATION_NAME = 'not_association_name';
+type IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME = 'cross_polymorphic_association_name';
 type RecursionTypes = 'load' | 'leftJoinLoad' | 'join';
+/**
+ * Given a union of table names and an association name, returns the
+ * specific table(s) from the union that have that association defined.
+ * Used when traversing through a polymorphic association to a descendant
+ * that only exists on one of the polymorphic targets.
+ */
+type TableContainingAssociationInUnion<Schema, TableNamesUnion, AssociationName> = TableNamesUnion extends keyof Schema ? AssociationName extends keyof Schema[TableNamesUnion]['associations' & keyof Schema[TableNamesUnion]] ? TableNamesUnion : never : never;
 export type VariadicLoadArgs<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], AllowedNextArgValues = (keyof SchemaAssociations & string) | AliasedSchemaAssociation<Schema, ConcreteTableName>> = VariadicCheckThenRecurse<I, DB, Schema, ConcreteTableName, ConcreteArgs, 'load', ConcreteTableName, 0, null, never, AllowedNextArgValues | Readonly<AllowedNextArgValues[]>>;
 export type VariadicLeftJoinLoadArgs<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], AllowedNextArgValues = (keyof SchemaAssociations & string) | AliasedSchemaAssociation<Schema, ConcreteTableName>> = VariadicCheckThenRecurse<I, DB, Schema, ConcreteTableName, ConcreteArgs, 'leftJoinLoad', Camelized<ConcreteTableName>, 0, null, never, AllowedNextArgValues | Readonly<AllowedNextArgValues[]>>;
 export type VariadicJoinsArgs<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], AllowedNextArgValues = (keyof SchemaAssociations & string) | AliasedSchemaAssociation<Schema, ConcreteTableName>> = VariadicCheckThenRecurse<I, DB, Schema, ConcreteTableName, ConcreteArgs, 'join', Camelized<ConcreteTableName>, 0, null, never, AllowedNextArgValues>;
-type VariadicCheckThenRecurse<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], RecursionType extends RecursionTypes, UsedNamespaces, Depth extends number, PreviousConcreteTableName, ConcreteAssociationName, AssociationNamesOrOnClause, LastDream extends Dream = I, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], NthArgument extends VALID | INVALID = ConcreteArgs['length'] extends 0 ? VALID : ConcreteArgs[0] extends keyof SchemaAssociations & string ? VALID : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? VALID : ConcreteArgs[0] extends JoinAndStatements<LastDream, DB, Schema, ConcreteTableName, RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>> ? VALID : INVALID> = NthArgument extends INVALID ? `invalid where clause in argument ${Inc<Depth>}` : ConcreteArgs['length'] extends 0 ? AssociationNamesOrOnClause : VariadicRecurse<I, DB, Schema, ConcreteTableName, ConcreteArgs, RecursionType, UsedNamespaces, Depth, PreviousConcreteTableName, ConcreteAssociationName, LastDream>;
+type VariadicCheckThenRecurse<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], RecursionType extends RecursionTypes, UsedNamespaces, Depth extends number, PreviousConcreteTableName, ConcreteAssociationName, AssociationNamesOrOnClause, LastDream extends Dream = I, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], AllowedNamesForArrayArg = PreviousConcreteTableName extends keyof Schema ? AssociationNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName> : keyof SchemaAssociations & string, NthArgument extends VALID | INVALID = ConcreteArgs['length'] extends 0 ? VALID : ConcreteArgs[0] extends keyof SchemaAssociations & string ? VALID : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? VALID : ConcreteArgs[0] extends JoinAndStatements<LastDream, DB, Schema, ConcreteTableName, RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>> ? VALID : ConcreteArgs[0] extends readonly AllowedNamesForArrayArg[] ? VALID : ConcreteArgs[0] extends JoinAndStatements<LastDream, DB, Schema, ConcreteTableName, RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>> ? VALID : ConcreteArgs[0] extends AllowedNamesForArrayArg ? VALID : INVALID> = NthArgument extends INVALID ? `invalid where clause in argument ${Inc<Depth>}` : ConcreteArgs['length'] extends 0 ? AssociationNamesOrOnClause : VariadicRecurse<I, DB, Schema, ConcreteTableName, ConcreteArgs, RecursionType, UsedNamespaces, Depth, PreviousConcreteTableName, ConcreteAssociationName, LastDream>;
 export type AliasedSchemaAssociation<Schema, ConcreteTableName extends keyof Schema, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]]> = `${keyof SchemaAssociations & string} as ${string}`;
-type VariadicRecurse<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], RecursionType extends RecursionTypes, UsedNamespaces, Depth extends number, PreviousConcreteTableName, ConcreteAssociationName, LastDream extends Dream, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], ConcreteNthArg extends (keyof SchemaAssociations & string) | AliasedSchemaAssociation<Schema, ConcreteTableName> | null = ConcreteArgs[0] extends undefined ? null : ConcreteArgs[0] extends null ? null : ConcreteArgs[0] extends keyof SchemaAssociations & string ? ConcreteArgs[0] & keyof SchemaAssociations & string : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? ConcreteArgs[0] & AliasedSchemaAssociation<Schema, ConcreteTableName> : null, NextUsedNamespaces = ConcreteArgs[0] extends undefined ? never : ConcreteArgs[0] extends null ? never : ConcreteArgs[0] extends keyof SchemaAssociations & string ? UsedNamespaces | ConcreteNthArg : UsedNamespaces, CurrentArgumentType extends IS_ASSOCIATION_NAME | IS_ASSOCIATION_ALIAS | IS_NOT_ASSOCIATION_NAME = ConcreteNthArg extends null ? IS_NOT_ASSOCIATION_NAME : ConcreteNthArg extends keyof SchemaAssociations & string ? IS_ASSOCIATION_NAME : ConcreteNthArg extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? IS_ASSOCIATION_ALIAS : IS_NOT_ASSOCIATION_NAME, NextPreviousConcreteTableName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteTableName : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteTableName : PreviousConcreteTableName, NextUnaliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteNthArg : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteNthArg extends `${infer AssocName extends string} as ${string}` ? AssocName & keyof SchemaAssociations & string : never : never, NextAliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteNthArg : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteNthArg extends `${string} as ${infer AssocAlias extends string}` ? AssocAlias & string : ConcreteAssociationName : ConcreteAssociationName, NextTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB = CurrentArgumentType extends IS_ASSOCIATION_NAME ? AssociationTableName<Schema, ConcreteTableName, NextUnaliasedAssociationName> : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? AssociationTableName<Schema, ConcreteTableName, NextUnaliasedAssociationName> : ConcreteTableName & AssociationTableNames<DB, Schema> & keyof DB, AllowedNextArgValues = RecursionType extends 'load' ? AllowedNextArgValuesForLoad<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>> : RecursionType extends 'leftJoinLoad' ? AllowedNextArgValuesForLeftJoinLoad<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>, NextUsedNamespaces> : RecursionType extends 'join' ? AllowedNextArgValuesForJoin<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>, NextUsedNamespaces> : never> = Depth extends MAX_VARIADIC_DEPTH ? never : VariadicCheckThenRecurse<I, DB, Schema, NextTableName, ReadonlyTail<ConcreteArgs>, RecursionType, NextUsedNamespaces, Inc<Depth>, NextPreviousConcreteTableName, NextAliasedAssociationName, AllowedNextArgValues, DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream> extends Dream ? DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream> : LastDream>;
-type AllowedNextArgValuesForLoad<I extends Dream, DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation> = AssociationNamesForTable<Schema, TableName> | AssociationNamesForTable<Schema, TableName>[] | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>;
-type AllowedNextArgValuesForLeftJoinLoad<I extends Dream, DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces> | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>[] | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>;
-type AllowedNextArgValuesForJoin<I extends Dream, DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces> | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>;
+type VariadicRecurse<I extends Dream, DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], RecursionType extends RecursionTypes, UsedNamespaces, Depth extends number, PreviousConcreteTableName, ConcreteAssociationName, LastDream extends Dream, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]], PolymorphicTableNamesUnion = PreviousConcreteTableName extends keyof Schema ? AssociationTableNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName> : ConcreteTableName, CrossPolymorphicTableForCurrentArg = ConcreteArgs[0] extends string ? TableContainingAssociationInUnion<Schema, PolymorphicTableNamesUnion, ConcreteArgs[0]> : never, EffectiveConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB = ConcreteArgs[0] extends keyof SchemaAssociations & string ? ConcreteTableName : [CrossPolymorphicTableForCurrentArg] extends [never] ? ConcreteTableName : CrossPolymorphicTableForCurrentArg extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB ? CrossPolymorphicTableForCurrentArg : ConcreteTableName, EffectiveSchemaAssociations = Schema[EffectiveConcreteTableName]['associations' & keyof Schema[EffectiveConcreteTableName]], ConcreteNthArg extends (keyof SchemaAssociations & string) | (keyof EffectiveSchemaAssociations & string) | AliasedSchemaAssociation<Schema, ConcreteTableName> | null = ConcreteArgs[0] extends undefined ? null : ConcreteArgs[0] extends null ? null : ConcreteArgs[0] extends keyof SchemaAssociations & string ? ConcreteArgs[0] & keyof SchemaAssociations & string : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? ConcreteArgs[0] & AliasedSchemaAssociation<Schema, ConcreteTableName> : ConcreteArgs[0] extends keyof EffectiveSchemaAssociations & string ? ConcreteArgs[0] & keyof EffectiveSchemaAssociations & string : null, NextUsedNamespaces = ConcreteArgs[0] extends undefined ? never : ConcreteArgs[0] extends null ? never : ConcreteNthArg extends null ? UsedNamespaces : UsedNamespaces | ConcreteNthArg, CurrentArgumentType extends IS_ASSOCIATION_NAME | IS_ASSOCIATION_ALIAS | IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME | IS_NOT_ASSOCIATION_NAME = ConcreteNthArg extends null ? IS_NOT_ASSOCIATION_NAME : ConcreteNthArg extends keyof SchemaAssociations & string ? IS_ASSOCIATION_NAME : ConcreteNthArg extends AliasedSchemaAssociation<Schema, ConcreteTableName> ? IS_ASSOCIATION_ALIAS : ConcreteNthArg extends keyof EffectiveSchemaAssociations & string ? IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME : IS_NOT_ASSOCIATION_NAME, NextPreviousConcreteTableName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteTableName : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteTableName : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME ? EffectiveConcreteTableName : PreviousConcreteTableName, NextUnaliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteNthArg : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteNthArg extends `${infer AssocName extends string} as ${string}` ? AssocName & keyof SchemaAssociations & string : never : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME ? ConcreteNthArg : never, NextAliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME ? ConcreteNthArg : CurrentArgumentType extends IS_ASSOCIATION_ALIAS ? ConcreteNthArg extends `${string} as ${infer AssocAlias extends string}` ? AssocAlias & string : ConcreteAssociationName : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME ? ConcreteNthArg : ConcreteAssociationName, IsAssociationNameOrAlias extends boolean = CurrentArgumentType extends IS_ASSOCIATION_NAME | IS_ASSOCIATION_ALIAS | IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME ? true : false, NextTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB = IsAssociationNameOrAlias extends true ? AssociationTableName<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName> : ConcreteTableName & AssociationTableNames<DB, Schema> & keyof DB, AllowedAssociationNames = IsAssociationNameOrAlias extends true ? AssociationNamesForAssociation<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName> : PreviousConcreteTableName extends keyof Schema ? AssociationNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName> : AssociationNamesForTable<Schema, ConcreteTableName>, // fall back to association names for table for root only
+AssociationTableOrConcreteTable extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB = IsAssociationNameOrAlias extends true ? AssociationTableName<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName> : ConcreteTableName, CurrentRequiredOnClauseKeys = IsAssociationNameOrAlias extends true ? RequiredOnClauseKeys<Schema, EffectiveConcreteTableName, NextAliasedAssociationName> : RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>, AllowedNextArgValues = RecursionType extends 'load' ? AllowedNextArgValuesForLoad<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, AllowedAssociationNames, AssociationTableOrConcreteTable, CurrentRequiredOnClauseKeys> : RecursionType extends 'leftJoinLoad' ? AllowedNextArgValuesForLeftJoinLoad<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, AllowedAssociationNames, AssociationTableOrConcreteTable, CurrentRequiredOnClauseKeys, NextUsedNamespaces> : RecursionType extends 'join' ? AllowedNextArgValuesForJoin<DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>, DB, Schema, AllowedAssociationNames, AssociationTableOrConcreteTable, CurrentRequiredOnClauseKeys, NextUsedNamespaces> : never> = Depth extends MAX_VARIADIC_DEPTH ? never : VariadicCheckThenRecurse<I, DB, Schema, NextTableName, ReadonlyTail<ConcreteArgs>, RecursionType, NextUsedNamespaces, Inc<Depth>, NextPreviousConcreteTableName, NextAliasedAssociationName, AllowedNextArgValues, DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream> extends Dream ? DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream> : LastDream>;
+type AllowedNextArgValuesForLoad<I extends Dream, DB, Schema, AllowedNames, TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation> = AllowedNames | AllowedNames[] | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>;
+type AllowedNextArgValuesForLeftJoinLoad<I extends Dream, DB, Schema, AllowedNames, TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AllowedNames, UsedNamespaces> | Exclude<AllowedNames, UsedNamespaces>[] | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>;
+type AllowedNextArgValuesForJoin<I extends Dream, DB, Schema, AllowedNames, TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AllowedNames, UsedNamespaces> | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>;
 export interface JoinedAssociation {
     table: string;
     alias: string;

package/dist/types/src/types/variadic.ts

@@ -2,8 +2,10 @@ import Dream from '../Dream.js'
 import { Camelized } from '../helpers/stringCasing.js'
 import { AssociationTableNames } from './db.js'
 import {
+  AssociationNamesForAssociation,
   AssociationNamesForTable,
   AssociationTableName,
+  AssociationTableNamesForAssociation,
   DreamAssociationNameToAssociatedModel,
   JoinAndStatements,
   MAX_VARIADIC_DEPTH,
@@ -16,7 +18,21 @@ type INVALID = 'invalid'
 type IS_ASSOCIATION_ALIAS = 'association_alias'
 type IS_ASSOCIATION_NAME = 'association_name'
 type IS_NOT_ASSOCIATION_NAME = 'not_association_name'
+type IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME = 'cross_polymorphic_association_name'
 type RecursionTypes = 'load' | 'leftJoinLoad' | 'join'
+
+/**
+ * Given a union of table names and an association name, returns the
+ * specific table(s) from the union that have that association defined.
+ * Used when traversing through a polymorphic association to a descendant
+ * that only exists on one of the polymorphic targets.
+ */
+type TableContainingAssociationInUnion<Schema, TableNamesUnion, AssociationName> =
+  TableNamesUnion extends keyof Schema
+    ? AssociationName extends keyof Schema[TableNamesUnion]['associations' & keyof Schema[TableNamesUnion]]
+      ? TableNamesUnion
+      : never
+    : never
 ///////////////////////////////
 // VARIADIC LOAD
 ///////////////////////////////
@@ -137,6 +153,9 @@ type VariadicCheckThenRecurse<
   LastDream extends Dream = I,
   //
   SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]],
+  AllowedNamesForArrayArg = PreviousConcreteTableName extends keyof Schema
+    ? AssociationNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName>
+    : keyof SchemaAssociations & string,
   NthArgument extends VALID | INVALID = ConcreteArgs['length'] extends 0
     ? VALID
     : ConcreteArgs[0] extends keyof SchemaAssociations & string
@@ -151,7 +170,19 @@ type VariadicCheckThenRecurse<
               RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>
             >
           ? VALID
-          : INVALID,
+          : ConcreteArgs[0] extends readonly AllowedNamesForArrayArg[]
+            ? VALID
+            : ConcreteArgs[0] extends JoinAndStatements<
+                  LastDream,
+                  DB,
+                  Schema,
+                  ConcreteTableName,
+                  RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>
+                >
+              ? VALID
+              : ConcreteArgs[0] extends AllowedNamesForArrayArg
+                ? VALID
+                : INVALID,
 > = NthArgument extends INVALID
   ? `invalid where clause in argument ${Inc<Depth>}`
   : ConcreteArgs['length'] extends 0
@@ -191,8 +222,37 @@ type VariadicRecurse<
   LastDream extends Dream,
   //
   SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]],
+  // Union of all table names reachable via the previous polymorphic association.
+  // When PreviousConcreteTableName is not a schema key (e.g. at depth 0), fall back to ConcreteTableName.
+  PolymorphicTableNamesUnion = PreviousConcreteTableName extends keyof Schema
+    ? AssociationTableNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName>
+    : ConcreteTableName,
+  // The specific table from the polymorphic union that owns the current arg as an association.
+  // Used when the arg is not directly on ConcreteTableName (i.e. cross-polymorphic traversal).
+  CrossPolymorphicTableForCurrentArg = ConcreteArgs[0] extends string
+    ? TableContainingAssociationInUnion<Schema, PolymorphicTableNamesUnion, ConcreteArgs[0]>
+    : never,
+  // The effective table for looking up the current arg's association:
+  // - ConcreteTableName when the arg is directly on it (normal case)
+  // - CrossPolymorphicTableForCurrentArg when the arg is on a different table in the polymorphic union
+  // Note: we use [T] extends [never] (non-distributive) to guard against CrossPolymorphicTableForCurrentArg
+  // being `never`, because `never extends X` is vacuously true and would cause EffectiveConcreteTableName
+  // to become `never` if we used a plain conditional.
+  EffectiveConcreteTableName extends keyof Schema &
+    AssociationTableNames<DB, Schema> &
+    keyof DB = ConcreteArgs[0] extends keyof SchemaAssociations & string
+    ? ConcreteTableName
+    : [CrossPolymorphicTableForCurrentArg] extends [never]
+      ? ConcreteTableName
+      : CrossPolymorphicTableForCurrentArg extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB
+        ? CrossPolymorphicTableForCurrentArg
+        : ConcreteTableName,
+  // Schema associations on the effective table (may differ from SchemaAssociations when cross-polymorphic).
+  EffectiveSchemaAssociations = Schema[EffectiveConcreteTableName]['associations' &
+    keyof Schema[EffectiveConcreteTableName]],
   ConcreteNthArg extends
     | (keyof SchemaAssociations & string)
+    | (keyof EffectiveSchemaAssociations & string)
     | AliasedSchemaAssociation<Schema, ConcreteTableName>
     | null = ConcreteArgs[0] extends undefined
     ? null
@@ -202,31 +262,38 @@ type VariadicRecurse<
         ? ConcreteArgs[0] & keyof SchemaAssociations & string
         : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName>
           ? ConcreteArgs[0] & AliasedSchemaAssociation<Schema, ConcreteTableName>
-          : null,
+          : ConcreteArgs[0] extends keyof EffectiveSchemaAssociations & string
+            ? ConcreteArgs[0] & keyof EffectiveSchemaAssociations & string
+            : null,
   NextUsedNamespaces = ConcreteArgs[0] extends undefined
     ? never
     : ConcreteArgs[0] extends null
       ? never
-      : ConcreteArgs[0] extends keyof SchemaAssociations & string
-        ? UsedNamespaces | ConcreteNthArg
-        : UsedNamespaces,
+      : ConcreteNthArg extends null
+        ? UsedNamespaces
+        : UsedNamespaces | ConcreteNthArg,
   //
   CurrentArgumentType extends
     | IS_ASSOCIATION_NAME
     | IS_ASSOCIATION_ALIAS
+    | IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
     | IS_NOT_ASSOCIATION_NAME = ConcreteNthArg extends null
     ? IS_NOT_ASSOCIATION_NAME
     : ConcreteNthArg extends keyof SchemaAssociations & string
       ? IS_ASSOCIATION_NAME
       : ConcreteNthArg extends AliasedSchemaAssociation<Schema, ConcreteTableName>
         ? IS_ASSOCIATION_ALIAS
-        : IS_NOT_ASSOCIATION_NAME,
+        : ConcreteNthArg extends keyof EffectiveSchemaAssociations & string
+          ? IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
+          : IS_NOT_ASSOCIATION_NAME,
   //
   NextPreviousConcreteTableName = CurrentArgumentType extends IS_ASSOCIATION_NAME
     ? ConcreteTableName
     : CurrentArgumentType extends IS_ASSOCIATION_ALIAS
       ? ConcreteTableName
-      : PreviousConcreteTableName,
+      : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
+        ? EffectiveConcreteTableName
+        : PreviousConcreteTableName,
   //
   NextUnaliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME
     ? ConcreteNthArg
@@ -234,7 +301,9 @@ type VariadicRecurse<
       ? ConcreteNthArg extends `${infer AssocName extends string} as ${string}`
         ? AssocName & keyof SchemaAssociations & string
         : never
-      : never,
+      : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
+        ? ConcreteNthArg
+        : never,
   //
   NextAliasedAssociationName = CurrentArgumentType extends IS_ASSOCIATION_NAME
     ? ConcreteNthArg
@@ -242,31 +311,56 @@ type VariadicRecurse<
       ? ConcreteNthArg extends `${string} as ${infer AssocAlias extends string}`
         ? AssocAlias & string
         : ConcreteAssociationName
-      : ConcreteAssociationName,
+      : CurrentArgumentType extends IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
+        ? ConcreteNthArg
+        : ConcreteAssociationName,
+  //
+  IsAssociationNameOrAlias extends boolean = CurrentArgumentType extends
+    | IS_ASSOCIATION_NAME
+    | IS_ASSOCIATION_ALIAS
+    | IS_CROSS_POLYMORPHIC_ASSOCIATION_NAME
+    ? true
+    : false,
   //
   NextTableName extends keyof Schema &
     AssociationTableNames<DB, Schema> &
-    keyof DB = CurrentArgumentType extends IS_ASSOCIATION_NAME
-    ? AssociationTableName<Schema, ConcreteTableName, NextUnaliasedAssociationName>
-    : CurrentArgumentType extends IS_ASSOCIATION_ALIAS
-      ? AssociationTableName<Schema, ConcreteTableName, NextUnaliasedAssociationName>
-      : ConcreteTableName & AssociationTableNames<DB, Schema> & keyof DB,
+    keyof DB = IsAssociationNameOrAlias extends true
+    ? AssociationTableName<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName>
+    : ConcreteTableName & AssociationTableNames<DB, Schema> & keyof DB,
+  //
+  AllowedAssociationNames = IsAssociationNameOrAlias extends true
+    ? AssociationNamesForAssociation<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName>
+    : PreviousConcreteTableName extends keyof Schema
+      ? AssociationNamesForAssociation<Schema, PreviousConcreteTableName, ConcreteAssociationName>
+      : AssociationNamesForTable<Schema, ConcreteTableName>, // fall back to association names for table for root only
+  //
+  AssociationTableOrConcreteTable extends keyof Schema &
+    AssociationTableNames<DB, Schema> &
+    keyof DB = IsAssociationNameOrAlias extends true
+    ? AssociationTableName<Schema, EffectiveConcreteTableName, NextUnaliasedAssociationName>
+    : ConcreteTableName,
+  //
+  CurrentRequiredOnClauseKeys = IsAssociationNameOrAlias extends true
+    ? RequiredOnClauseKeys<Schema, EffectiveConcreteTableName, NextAliasedAssociationName>
+    : RequiredOnClauseKeys<Schema, PreviousConcreteTableName, ConcreteAssociationName>,
   //
   AllowedNextArgValues = RecursionType extends 'load'
     ? AllowedNextArgValuesForLoad<
         DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
         DB,
         Schema,
-        NextTableName,
-        RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>
+        AllowedAssociationNames,
+        AssociationTableOrConcreteTable,
+        CurrentRequiredOnClauseKeys
       >
     : RecursionType extends 'leftJoinLoad'
       ? AllowedNextArgValuesForLeftJoinLoad<
           DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
           DB,
           Schema,
-          NextTableName,
-          RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>,
+          AllowedAssociationNames,
+          AssociationTableOrConcreteTable,
+          CurrentRequiredOnClauseKeys,
           NextUsedNamespaces
         >
       : RecursionType extends 'join'
@@ -274,8 +368,9 @@ type VariadicRecurse<
             DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
             DB,
             Schema,
-            NextTableName,
-            RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>,
+            AllowedAssociationNames,
+            AssociationTableOrConcreteTable,
+            CurrentRequiredOnClauseKeys,
             NextUsedNamespaces
           >
         : never,
@@ -302,35 +397,38 @@ type AllowedNextArgValuesForLoad<
   I extends Dream,
   DB,
   Schema,
-  TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
+  AllowedNames,
+  TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
   RequiredOnClauseKeysForThisAssociation,
 > =
-  | AssociationNamesForTable<Schema, TableName>
-  | AssociationNamesForTable<Schema, TableName>[]
-  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | AllowedNames
+  | AllowedNames[]
+  | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>
 
 type AllowedNextArgValuesForLeftJoinLoad<
   I extends Dream,
   DB,
   Schema,
-  TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
+  AllowedNames,
+  TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
   RequiredOnClauseKeysForThisAssociation,
   UsedNamespaces,
 > =
-  | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>
-  | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>[]
-  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | Exclude<AllowedNames, UsedNamespaces>
+  | Exclude<AllowedNames, UsedNamespaces>[]
+  | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>
 
 type AllowedNextArgValuesForJoin<
   I extends Dream,
   DB,
   Schema,
-  TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
+  AllowedNames,
+  TableForJoin extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
   RequiredOnClauseKeysForThisAssociation,
   UsedNamespaces,
 > =
-  | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>
-  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | Exclude<AllowedNames, UsedNamespaces>
+  | JoinAndStatements<I, DB, Schema, TableForJoin, RequiredOnClauseKeysForThisAssociation>
 
 export interface JoinedAssociation {
   table: string