@rvoh/dream 2.3.0-alpha.6 → 2.3.0-alpha.8

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

@@ -9,7 +9,7 @@ import {
   AssociatedModelParam,
   AssociationStatement,
   OnStatementForAssociation,
-  WhereStatement,
+  InternalWhereStatement,
 } from './associations/shared.js'
 import { AssociationTableNames } from './db.js'
 import { FindEachOpts } from './query.js'
@@ -393,32 +393,34 @@ export type DreamClassAssociationAndStatement<
     AssociationName
   > = RequiredOnClauseKeys<Schema, TableName, AssociationName>,
   Statements extends JoinAndStatements<
+    DreamInstance,
     DB,
     Schema,
     AssocTableName,
     RequiredOnClauseKeysForThisAssociation
-  > = JoinAndStatements<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?: WhereStatement<DB, Schema, TableName>
-      andNot?: WhereStatement<DB, Schema, TableName>
+      and?: InternalWhereStatement<I, DB, Schema, TableName>
+      andNot?: InternalWhereStatement<I, DB, Schema, TableName>
       // andNot?: WhereStatementWithoutSimilarityClauses<DB, Schema, TableName>
-      andAny?: WhereStatement<DB, Schema, TableName>[]
+      andAny?: InternalWhereStatement<I, DB, Schema, TableName>[]
       // andAny?: WhereStatementWithoutSimilarityClauses<DB, Schema, TableName>[]
     }
   : RequiredOnClauseKeysForThisAssociation extends string[]
     ? {
-        and: OnStatementForAssociation<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
-        andNot?: WhereStatement<DB, Schema, TableName>
+        and: OnStatementForAssociation<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+        andNot?: InternalWhereStatement<I, DB, Schema, TableName>
         // andNot?: WhereStatementWithoutSimilarityClauses<DB, Schema, TableName>
-        andAny?: WhereStatement<DB, Schema, TableName>[]
+        andAny?: InternalWhereStatement<I, DB, Schema, TableName>[]
         // andAny?: WhereStatementWithoutSimilarityClauses<DB, Schema, TableName>[]
       }
     : never
@@ -515,6 +517,30 @@ export type ViewModel = {
 }
 export type ViewModelClass = abstract new (...args: any) => ViewModel
 
+/**
+ * given a Dream model and an association name, this
+ * type will return the actual type set for that association,
+ * excluding null or arrays.
+ *
+ * ```ts
+ * DreamAssociationNameToAssociatedModel<User, 'compositions'>
+ * // Composition
+ *
+ * DreamAssociationNameToAssociatedModel<User, 'featuredPost'>
+ * // Post
+ * ```
+ */
+export type DreamAssociationNameToAssociatedModel<
+  I extends Dream,
+  AssociationName extends keyof I,
+> = I[AssociationName] extends (infer U extends Dream)[]
+  ? U
+  : I[AssociationName] extends Dream
+    ? I[AssociationName]
+    : I[AssociationName] extends Dream | null
+      ? Required<I[AssociationName]> & Dream
+      : I
+
 // preload
 export type DreamModelAssociationNames<
   Schema,
@@ -555,22 +581,22 @@ export type RelaxedJoinStatement<Depth extends number = 0> = Depth extends 7
   ? object
   : Record<string, RelaxedJoinStatement<Inc<Depth>>>
 
-export type RelaxedPreloadOnStatement<DB, Schema, Depth extends number = 0> = Depth extends 7
+export type RelaxedPreloadOnStatement<I extends Dream, DB, Schema, Depth extends number = 0> = Depth extends 7
   ? object
   : {
       [key: string]:
-        | RelaxedPreloadOnStatement<DB, Schema, Inc<Depth>>
-        | JoinAndStatements<any, any, any, any>
+        | RelaxedPreloadOnStatement<I, DB, Schema, Inc<Depth>>
+        | JoinAndStatements<I, any, any, any, any>
         | FakeOnClauseValue
         | object
     }
 
-export type RelaxedJoinAndStatement<DB, Schema, Depth extends number = 0> = Depth extends 7
+export type RelaxedJoinAndStatement<I extends Dream, DB, Schema, Depth extends number = 0> = Depth extends 7
   ? object
   : {
       [key: string]:
-        | RelaxedJoinAndStatement<DB, Schema, Inc<Depth>>
-        | JoinAndStatements<any, any, any, any>
+        | RelaxedJoinAndStatement<I, DB, Schema, Inc<Depth>>
+        | JoinAndStatements<I, any, any, any, any>
         | FakeOnClauseValue
         | object
     }

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

@@ -1,6 +1,7 @@
+import Dream from '../Dream.js';
 import { Camelized } from '../helpers/stringCasing.js';
 import { AssociationTableNames } from './db.js';
-import { AssociationNamesForTable, AssociationTableName, JoinAndStatements, MAX_VARIADIC_DEPTH, RequiredOnClauseKeys } from './dream.js';
+import { AssociationNamesForTable, AssociationTableName, DreamAssociationNameToAssociatedModel, JoinAndStatements, MAX_VARIADIC_DEPTH, RequiredOnClauseKeys } from './dream.js';
 import { Inc, ReadonlyTail } from './utils.js';
 type VALID = 'valid';
 type INVALID = 'invalid';
@@ -8,15 +9,15 @@ type IS_ASSOCIATION_ALIAS = 'association_alias';
 type IS_ASSOCIATION_NAME = 'association_name';
 type IS_NOT_ASSOCIATION_NAME = 'not_association_name';
 type RecursionTypes = 'load' | 'leftJoinLoad' | 'join';
-export type VariadicLoadArgs<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<DB, Schema, ConcreteTableName, ConcreteArgs, 'load', ConcreteTableName, 0, null, never, AllowedNextArgValues | Readonly<AllowedNextArgValues[]>>;
-export type VariadicLeftJoinLoadArgs<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<DB, Schema, ConcreteTableName, ConcreteArgs, 'leftJoinLoad', Camelized<ConcreteTableName>, 0, null, never, AllowedNextArgValues | Readonly<AllowedNextArgValues[]>>;
-export type VariadicJoinsArgs<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<DB, Schema, ConcreteTableName, ConcreteArgs, 'join', Camelized<ConcreteTableName>, 0, null, never, AllowedNextArgValues>;
-type VariadicCheckThenRecurse<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, 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<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<DB, Schema, ConcreteTableName, ConcreteArgs, RecursionType, UsedNamespaces, Depth, PreviousConcreteTableName, ConcreteAssociationName>;
+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>;
 export type AliasedSchemaAssociation<Schema, ConcreteTableName extends keyof Schema, SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]]> = `${keyof SchemaAssociations & string} as ${string}`;
-type VariadicRecurse<DB, Schema, ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, ConcreteArgs extends readonly unknown[], RecursionType extends RecursionTypes, UsedNamespaces, Depth extends number, PreviousConcreteTableName, ConcreteAssociationName, 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<DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>> : RecursionType extends 'leftJoinLoad' ? AllowedNextArgValuesForLeftJoinLoad<DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>, NextUsedNamespaces> : RecursionType extends 'join' ? AllowedNextArgValuesForJoin<DB, Schema, NextTableName, RequiredOnClauseKeys<Schema, ConcreteTableName, NextAliasedAssociationName>, NextUsedNamespaces> : never> = Depth extends MAX_VARIADIC_DEPTH ? never : VariadicCheckThenRecurse<DB, Schema, NextTableName, ReadonlyTail<ConcreteArgs>, RecursionType, NextUsedNamespaces, Inc<Depth>, NextPreviousConcreteTableName, NextAliasedAssociationName, AllowedNextArgValues>;
-type AllowedNextArgValuesForLoad<DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation> = AssociationNamesForTable<Schema, TableName> | AssociationNamesForTable<Schema, TableName>[] | JoinAndStatements<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>;
-type AllowedNextArgValuesForLeftJoinLoad<DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces> | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>[] | JoinAndStatements<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>;
-type AllowedNextArgValuesForJoin<DB, Schema, TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB, RequiredOnClauseKeysForThisAssociation, UsedNamespaces> = Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces> | JoinAndStatements<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]], 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>;
 export interface JoinedAssociation {
     table: string;
     alias: string;

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

@@ -1,8 +1,10 @@
+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,
@@ -20,6 +22,7 @@ type RecursionTypes = 'load' | 'leftJoinLoad' | 'join'
 ///////////////////////////////
 
 export type VariadicLoadArgs<
+  I extends Dream,
   DB,
   Schema,
   ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -30,6 +33,7 @@ export type VariadicLoadArgs<
     | (keyof SchemaAssociations & string)
     | AliasedSchemaAssociation<Schema, ConcreteTableName>,
 > = VariadicCheckThenRecurse<
+  I,
   DB,
   Schema,
   ConcreteTableName,
@@ -48,6 +52,7 @@ export type VariadicLoadArgs<
 // VARIADIC LEFT JOIN LOAD
 ///////////////////////////////
 export type VariadicLeftJoinLoadArgs<
+  I extends Dream,
   DB,
   Schema,
   ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -58,6 +63,7 @@ export type VariadicLeftJoinLoadArgs<
     | (keyof SchemaAssociations & string)
     | AliasedSchemaAssociation<Schema, ConcreteTableName>,
 > = VariadicCheckThenRecurse<
+  I,
   DB,
   Schema,
   ConcreteTableName,
@@ -81,6 +87,7 @@ export type VariadicLeftJoinLoadArgs<
 // VARIADIC JOINS
 ///////////////////////////////
 export type VariadicJoinsArgs<
+  I extends Dream,
   DB,
   Schema,
   ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -91,6 +98,7 @@ export type VariadicJoinsArgs<
     | (keyof SchemaAssociations & string)
     | AliasedSchemaAssociation<Schema, ConcreteTableName>,
 > = VariadicCheckThenRecurse<
+  I,
   DB,
   Schema,
   ConcreteTableName,
@@ -113,6 +121,7 @@ export type VariadicJoinsArgs<
 ///////////////////////////////
 
 type VariadicCheckThenRecurse<
+  I extends Dream,
   DB,
   Schema,
   ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -125,6 +134,7 @@ type VariadicCheckThenRecurse<
   ConcreteAssociationName,
   //
   AssociationNamesOrOnClause,
+  LastDream extends Dream = I,
   //
   SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]],
   NthArgument extends VALID | INVALID = ConcreteArgs['length'] extends 0
@@ -134,6 +144,7 @@ type VariadicCheckThenRecurse<
       : ConcreteArgs[0] extends AliasedSchemaAssociation<Schema, ConcreteTableName>
         ? VALID
         : ConcreteArgs[0] extends JoinAndStatements<
+              LastDream,
               DB,
               Schema,
               ConcreteTableName,
@@ -146,6 +157,7 @@ type VariadicCheckThenRecurse<
   : ConcreteArgs['length'] extends 0
     ? AssociationNamesOrOnClause
     : VariadicRecurse<
+        I,
         DB,
         Schema,
         ConcreteTableName,
@@ -154,7 +166,8 @@ type VariadicCheckThenRecurse<
         UsedNamespaces,
         Depth,
         PreviousConcreteTableName,
-        ConcreteAssociationName
+        ConcreteAssociationName,
+        LastDream
       >
 
 export type AliasedSchemaAssociation<
@@ -164,6 +177,7 @@ export type AliasedSchemaAssociation<
 > = `${keyof SchemaAssociations & string} as ${string}`
 
 type VariadicRecurse<
+  I extends Dream,
   DB,
   Schema,
   ConcreteTableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -174,6 +188,7 @@ type VariadicRecurse<
   //
   PreviousConcreteTableName,
   ConcreteAssociationName,
+  LastDream extends Dream,
   //
   SchemaAssociations = Schema[ConcreteTableName]['associations' & keyof Schema[ConcreteTableName]],
   ConcreteNthArg extends
@@ -239,6 +254,7 @@ type VariadicRecurse<
   //
   AllowedNextArgValues = RecursionType extends 'load'
     ? AllowedNextArgValuesForLoad<
+        DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
         DB,
         Schema,
         NextTableName,
@@ -246,6 +262,7 @@ type VariadicRecurse<
       >
     : RecursionType extends 'leftJoinLoad'
       ? AllowedNextArgValuesForLeftJoinLoad<
+          DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
           DB,
           Schema,
           NextTableName,
@@ -254,6 +271,7 @@ type VariadicRecurse<
         >
       : RecursionType extends 'join'
         ? AllowedNextArgValuesForJoin<
+            DreamAssociationNameToAssociatedModel<LastDream, ConcreteArgs[0] & keyof LastDream>,
             DB,
             Schema,
             NextTableName,
@@ -264,6 +282,7 @@ type VariadicRecurse<
 > = Depth extends MAX_VARIADIC_DEPTH
   ? never
   : VariadicCheckThenRecurse<
+      I,
       DB,
       Schema,
       NextTableName,
@@ -273,10 +292,14 @@ type VariadicRecurse<
       Inc<Depth>,
       NextPreviousConcreteTableName,
       NextAliasedAssociationName,
-      AllowedNextArgValues
+      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,
@@ -284,9 +307,10 @@ type AllowedNextArgValuesForLoad<
 > =
   | AssociationNamesForTable<Schema, TableName>
   | AssociationNamesForTable<Schema, TableName>[]
-  | JoinAndStatements<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
 
 type AllowedNextArgValuesForLeftJoinLoad<
+  I extends Dream,
   DB,
   Schema,
   TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -295,9 +319,10 @@ type AllowedNextArgValuesForLeftJoinLoad<
 > =
   | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>
   | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>[]
-  | JoinAndStatements<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
 
 type AllowedNextArgValuesForJoin<
+  I extends Dream,
   DB,
   Schema,
   TableName extends keyof Schema & AssociationTableNames<DB, Schema> & keyof DB,
@@ -305,7 +330,7 @@ type AllowedNextArgValuesForJoin<
   UsedNamespaces,
 > =
   | Exclude<AssociationNamesForTable<Schema, TableName>, UsedNamespaces>
-  | JoinAndStatements<DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
+  | JoinAndStatements<I, DB, Schema, TableName, RequiredOnClauseKeysForThisAssociation>
 
 export interface JoinedAssociation {
   table: string

package/dist/types/src/utils/datetime/BaseClockTime.d.ts

@@ -0,0 +1,287 @@
+import { ClockTimeDiffResult, ClockTimeDurationLikeObject, ClockTimeDurationUnit, ClockTimeUnit, type ClockTimeObject } from '../../types/clocktime.js';
+import { type LocaleOptions } from '../../types/datetime.js';
+import { DateTime } from './DateTime.js';
+export default class BaseClockTime {
+    protected dateTime: DateTime;
+    protected _toSQL?: string;
+    /**
+     * @internal
+     */
+    constructor(source?: DateTime | null);
+    /**
+     * Create a ClockTimeTz from a DateTime instance.
+     * @param dateTime - A DateTime instance
+     * @returns A ClockTimeTz for the time portion of the DateTime
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromDateTime(DateTime.now())
+     * ```
+     */
+    static fromDateTime<T extends typeof BaseClockTime>(this: T, dateTime: DateTime): InstanceType<T>;
+    /**
+     * Returns true if this ClockTime equals another ClockTime.
+     * @param otherClockTime - ClockTime to compare
+     * @returns true if times are equal
+     * @example
+     * ```ts
+     * const t1 = ClockTime.fromObject({ hour: 14, minute: 30 })
+     * const t2 = ClockTime.fromObject({ hour: 14, minute: 30 })
+     * t1.equals(t2)  // true
+     * ```
+     */
+    equals<T extends BaseClockTime>(this: T, otherClockTime: T): boolean;
+    /**
+     * Returns a new ClockTime with the given time units set.
+     * @param values - Object with time units to set (hour, minute, second, millisecond, microsecond)
+     * @returns A new ClockTime
+     * @throws {InvalidClockTime} When the underlying DateTime operation fails
+     * @example
+     * ```ts
+     * ClockTime.fromObject({ hour: 10, minute: 30 }).set({ hour: 14, microsecond: 500 })
+     * // hour: 14, minute: 30, microsecond: 500
+     * ```
+     */
+    set<T extends BaseClockTime>(this: T, values: Partial<ClockTimeObject>): T;
+    /**
+     * Returns a new ClockTime at the start of the given period.
+     * @param period - Unit to truncate to ('hour', 'minute', or 'second')
+     * @returns A ClockTime at the start of the period
+     * @example
+     * ```ts
+     * ClockTime.fromObject({ hour: 14, minute: 30, second: 45 }).startOf('hour')
+     * // hour: 14, minute: 0, second: 0
+     * ```
+     */
+    startOf<T extends BaseClockTime>(this: T, period: ClockTimeUnit): T;
+    /**
+     * Returns a new ClockTime at the end of the given period.
+     * @param period - Unit to extend to end of ('hour', 'minute', or 'second')
+     * @returns A ClockTime at the end of the period
+     * @example
+     * ```ts
+     * ClockTime.fromObject({ hour: 14, minute: 30 }).endOf('hour')
+     * // hour: 14, minute: 59, second: 59, millisecond: 999
+     * ```
+     */
+    endOf<T extends BaseClockTime>(this: T, period: ClockTimeUnit): T;
+    /**
+     * Returns the time as an ISO time string (for valueOf() operations).
+     * @returns ISO time string
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.now().valueOf()
+     * ```
+     */
+    private _valueOf;
+    valueOf(): string;
+    toISO(opts?: {
+        suppressMilliseconds?: boolean;
+        suppressSeconds?: boolean;
+        format?: 'basic' | 'extended';
+    }): string;
+    toSQL(): string;
+    /**
+     * Returns the time as an ISO 8601 time string with timezone offset.
+     * Alias for `toISO()`.
+     *
+     * @param opts - Optional format options
+     * @param opts.suppressMilliseconds - If true, omits milliseconds/microseconds when they are zero
+     * @param opts.suppressSeconds - If true, omits seconds when they are zero
+     * @param opts.format - Format variant: 'basic' (compact) or 'extended' (default, with colons)
+     * @returns ISO time string with timezone offset (e.g., '14:30:45.123456-05:00')
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 }).toISOTime()  // '14:30:45.000000+00:00'
+     * ClockTime/ClockTimeTz.fromISO('14:30:45-05:00').toISOTime()  // '14:30:45.000000-05:00'
+     * ```
+     */
+    toISOTime(opts?: {
+        suppressMilliseconds?: boolean;
+        suppressSeconds?: boolean;
+        format?: 'basic' | 'extended';
+    }): string;
+    /**
+     * Returns the time as an ISO time string for JSON serialization.
+     * @returns ISO time string
+     * @example
+     * ```ts
+     * JSON.stringify({ time: ClockTime.now() })
+     * ```
+     */
+    toJSON(): string;
+    /**
+     * Alias of `toSQL`.
+     * Returns the SQL time string without timezone offset.
+     * Result is memoized for performance.
+     *
+     * @returns SQL time string without timezone offset (e.g., '14:30:45.123456')
+     */
+    toSQLTime(): string;
+    /**
+     * Returns a localized string representation of the time.
+     * @param formatOpts - Intl.DateTimeFormat options for formatting
+     * @param opts - Optional locale configuration
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
+     * @returns Localized time string
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.now().toLocaleString()
+     * ClockTime/ClockTimeTz.now().toLocaleString({ hour: 'numeric', minute: '2-digit' })
+     * ClockTime/ClockTimeTz.now().toLocaleString({ hour: '2-digit' }, { locale: 'fr-FR' })
+     * ```
+     */
+    toLocaleString(formatOpts?: Intl.DateTimeFormatOptions, opts?: LocaleOptions): string;
+    /**
+     * Returns the time as an ISO string (same as toISO).
+     * @returns ISO datetime string
+     * @example
+     * ```ts
+     * ClockTime.now().toString()
+     * ```
+     */
+    toString(): string;
+    /**
+     * Returns the underlying DateTime instance.
+     * @returns A DateTime representing this time with zone
+     * @example
+     * ```ts
+     * const dt = ClockTime/ClockTimeTz.now().toDateTime()
+     * ```
+     */
+    toDateTime(): DateTime;
+    /**
+     * Gets the hour (0-23).
+     * @returns The hour number
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).hour  // 14
+     * ```
+     */
+    get hour(): number;
+    /**
+     * Gets the minute (0-59).
+     * @returns The minute number
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).minute  // 30
+     * ```
+     */
+    get minute(): number;
+    /**
+     * Gets the second (0-59).
+     * @returns The second number
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 }).second  // 45
+     * ```
+     */
+    get second(): number;
+    /**
+     * Gets the millisecond (0-999).
+     * @returns The millisecond number
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, millisecond: 123 }).millisecond  // 123
+     * ```
+     */
+    get millisecond(): number;
+    /**
+     * Gets the microsecond (0-999).
+     * @returns The microsecond number
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromISO('14:30:45.123456').microsecond  // 456
+     * ```
+     */
+    get microsecond(): number;
+    /**
+     * Returns the earliest ClockTime/ClockTimeTz from the given arguments.
+     * @param clockTimes - ClockTime/ClockTimeTz instances to compare
+     * @returns The earliest ClockTime/ClockTimeTz
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.min(time1, time2, time3)
+     * ```
+     */
+    static min<T extends typeof BaseClockTime>(this: T, ...clockTimes: InstanceType<T>[]): InstanceType<T> | null;
+    /**
+     * Returns the latest ClockTime/ClockTimeTz from the given arguments.
+     * @param clockTimes - ClockTime/ClockTimeTz instances to compare
+     * @returns The latest ClockTime/ClockTimeTz
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.max(time1, time2, time3)
+     * ```
+     */
+    static max<T extends typeof BaseClockTime>(this: T, ...clockTimes: InstanceType<T>[]): InstanceType<T> | null;
+    /**
+     * Returns a new ClockTime/ClockTimeTz with the given duration added.
+     * @param duration - Duration to add (object with hours, minutes, seconds, etc.)
+     * @returns A new ClockTime/ClockTimeTz
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).plus({ hours: 2, minutes: 15 })
+     * // hour: 16, minute: 45
+     * ```
+     */
+    plus<T extends BaseClockTime>(this: T, duration: ClockTimeDurationLikeObject): T;
+    /**
+     * Returns a new ClockTime/ClockTimeTz with the given duration subtracted.
+     * @param duration - Duration to subtract (object with hours, minutes, seconds, etc.)
+     * @returns A new ClockTime/ClockTimeTz
+     * @example
+     * ```ts
+     * ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).minus({ hours: 2, minutes: 15 })
+     * // hour: 12, minute: 15
+     * ```
+     */
+    minus<T extends BaseClockTime>(this: T, duration: ClockTimeDurationLikeObject): T;
+    /**
+     * Returns true if this and other are in the same unit of time.
+     * @param otherClockTime - ClockTime to compare against
+     * @param period - Unit to check ('hour', 'minute', or 'second')
+     * @returns true if same period
+     * @example
+     * ```ts
+     * const t1 = ClockTime.fromObject({ hour: 14, minute: 30 })
+     * const t2 = ClockTime.fromObject({ hour: 14, minute: 45 })
+     * t1.hasSame(t2, 'hour')    // true
+     * t1.hasSame(t2, 'minute')  // false
+     * ```
+     */
+    hasSame<T extends BaseClockTime>(this: T, otherClockTime: T, period: ClockTimeUnit): boolean;
+    /**
+     * Returns the difference between this ClockTime and another in the specified unit.
+     * @param otherClockTime - ClockTime to compare against
+     * @param duration - Unit for the difference ('hours', 'minutes', 'seconds', etc.)
+     * @returns Numeric difference in the specified unit
+     * @example
+     * ```ts
+     * const t1 = ClockTime.fromObject({ hour: 14, minute: 30 })
+     * const t2 = ClockTime.fromObject({ hour: 10, minute: 15 })
+     * t1.diff(t2, 'hours')    // 4.25
+     * t1.diff(t2, 'minutes')  // 255
+     * ```
+     */
+    /**
+     * Returns the difference between this ClockTime and another in the specified unit(s).
+     * Supports microsecond precision when 'microseconds' is included in the unit parameter.
+     *
+     * @param other - ClockTime to compare against
+     * @param unit - Unit or units to return (hours, minutes, seconds, milliseconds, microseconds)
+     * @returns Object with only the specified units (or all units if not specified)
+     * @example
+     * ```ts
+     * const t1 = ClockTime.fromObject({ hour: 15, minute: 30 })
+     * const t2 = ClockTime.fromObject({ hour: 14, minute: 0 })
+     * t1.diff(t2, 'hours')  // { hours: 1 }
+     * t1.diff(t2, ['hours', 'minutes'])  // { hours: 1, minutes: 30 }
+     * t1.diff(t2)  // { hours: 1, minutes: 30, seconds: 0, milliseconds: 0, microseconds: 0 }
+     * ```
+     */
+    diff<T extends BaseClockTime, U extends ClockTimeDurationUnit | ClockTimeDurationUnit[] | undefined = undefined>(this: T, other: T, unit?: U): ClockTimeDiffResult<U>;
+    protected static wrapLuxonError<T>(fn: () => T): T;
+    protected wrapLuxonError<T>(fn: () => T): T;
+}