metal-orm 1.0.64 → 1.0.66

package/src/query-builder/select.ts

@@ -2,19 +2,19 @@ import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column-types.js';
 import { OrderingTerm, SelectQueryNode, SetOperationKind } from '../core/ast/query.js';
 import { HydrationPlan } from '../core/hydration/types.js';
-import {
-  ColumnNode,
-  ExpressionNode,
-  FunctionNode,
-  BinaryExpressionNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
-  and,
-  exists,
-  notExists,
-  OperandNode
-} from '../core/ast/expression.js';
-import type { TypedExpression } from '../core/ast/expression.js';
+import {
+  ColumnNode,
+  ExpressionNode,
+  FunctionNode,
+  BinaryExpressionNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  and,
+  exists,
+  notExists,
+  OperandNode
+} from '../core/ast/expression.js';
+import type { TypedExpression } from '../core/ast/expression.js';
 import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 
@@ -32,12 +32,12 @@ import { ColumnSelector } from './column-selector.js';
 import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
 import { RelationKinds } from '../schema/relation.js';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
-import { EntityInstance, RelationMap } from '../schema/types.js';
-import type { ColumnToTs, InferRow } from '../schema/types.js';
+import { EntityInstance, RelationMap } from '../schema/types.js';
+import type { ColumnToTs, InferRow } from '../schema/types.js';
 import { OrmSession } from '../orm/orm-session.ts';
 import { ExecutionContext } from '../orm/execution-context.js';
 import { HydrationContext } from '../orm/hydration-context.js';
-import { executeHydrated, executeHydratedPlain, executeHydratedWithContexts } from '../orm/execute.js';
+import { executeHydrated, executeHydratedPlain, executeHydratedWithContexts } from '../orm/execute.js';
 import { EntityConstructor } from '../orm/entity-metadata.js';
 import { materializeAs } from '../orm/entity-materializer.js';
 import { resolveSelectQuery } from './query-resolution.js';
@@ -57,27 +57,27 @@ import { SelectCTEFacet } from './select/cte-facet.js';
 import { SelectSetOpFacet } from './select/setop-facet.js';
 import { SelectRelationFacet } from './select/relation-facet.js';
 
-type ColumnSelectionValue =
-  | ColumnDef
-  | FunctionNode
-  | CaseExpressionNode
-  | WindowFunctionNode
-  | TypedExpression<unknown>;
-
-type SelectionValueType<TValue> =
-  TValue extends TypedExpression<infer TRuntime> ? TRuntime :
-  TValue extends ColumnDef ? ColumnToTs<TValue> :
-  unknown;
-
-type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
-  [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
-};
-
-type SelectionFromKeys<
-  TTable extends TableDef,
-  K extends keyof TTable['columns'] & string
-> = Pick<InferRow<TTable>, K>;
-
+type ColumnSelectionValue =
+  | ColumnDef
+  | FunctionNode
+  | CaseExpressionNode
+  | WindowFunctionNode
+  | TypedExpression<unknown>;
+
+type SelectionValueType<TValue> =
+  TValue extends TypedExpression<infer TRuntime> ? TRuntime :
+  TValue extends ColumnDef ? ColumnToTs<TValue> :
+  unknown;
+
+type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
+  [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
+};
+
+type SelectionFromKeys<
+  TTable extends TableDef,
+  K extends keyof TTable['columns'] & string
+> = Pick<InferRow<TTable>, K>;
+
 type DeepSelectEntry<TTable extends TableDef> = {
   type: 'root';
   columns: (keyof TTable['columns'] & string)[];
@@ -94,7 +94,7 @@ type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
  * @typeParam T - Result type for projections (unused)
  * @typeParam TTable - Table definition being queried
  */
-export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends TableDef = TableDef> {
+export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends TableDef = TableDef> {
   private readonly env: SelectQueryBuilderEnvironment;
   private readonly context: SelectQueryBuilderContext;
   private readonly columnSelector: ColumnSelector;
@@ -107,7 +107,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   private readonly relationFacet: SelectRelationFacet;
   private readonly lazyRelations: Set<string>;
   private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
-  private readonly entityConstructor?: EntityConstructor;
+  private readonly entityConstructor?: EntityConstructor;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -123,7 +123,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     dependencies?: Partial<SelectQueryBuilderDependencies>,
     lazyRelations?: Set<string>,
     lazyRelationOptions?: Map<string, RelationIncludeOptions>,
-    entityConstructor?: EntityConstructor
+    entityConstructor?: EntityConstructor
   ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
@@ -154,21 +154,21 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  private clone<TNext = T>(
-    context: SelectQueryBuilderContext = this.context,
-    lazyRelations = new Set(this.lazyRelations),
-    lazyRelationOptions = new Map(this.lazyRelationOptions)
-  ): SelectQueryBuilder<TNext, TTable> {
-    return new SelectQueryBuilder(
-      this.env.table as TTable,
-      context.state,
-      context.hydration,
-      this.env.deps,
-      lazyRelations,
-      lazyRelationOptions,
-      this.entityConstructor
-    ) as SelectQueryBuilder<TNext, TTable>;
-  }
+  private clone<TNext = T>(
+    context: SelectQueryBuilderContext = this.context,
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions)
+  ): SelectQueryBuilder<TNext, TTable> {
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions,
+      this.entityConstructor
+    ) as SelectQueryBuilder<TNext, TTable>;
+  }
 
   /**
    * Applies an alias to the root FROM table.
@@ -213,7 +213,8 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    */
   private applySetOperation<TSub extends TableDef>(
     operator: SetOperationKind,
-    query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+    query: SelectQueryBuilder<T, TSub> | SelectQueryNode
+
   ): SelectQueryBuilderContext {
     const subAst = resolveSelectQuery(query);
     return this.setOpFacet.applySetOperation(this.context, operator, subAst);
@@ -234,41 +235,41 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
    * });
    */
-  select<K extends keyof TTable['columns'] & string>(
-    ...args: K[]
-  ): SelectQueryBuilder<T & SelectionFromKeys<TTable, K>, TTable>;
-  select<TSelection extends Record<string, ColumnSelectionValue>>(
-    columns: TSelection
-  ): SelectQueryBuilder<T & SelectionResult<TSelection>, TTable>;
-  select<
-    K extends keyof TTable['columns'] & string,
-    TSelection extends Record<string, ColumnSelectionValue>
-  >(
-    ...args: K[] | [TSelection]
-  ): SelectQueryBuilder<T, TTable> {
+  select<K extends keyof TTable['columns'] & string>(
+    ...args: K[]
+  ): SelectQueryBuilder<T & SelectionFromKeys<TTable, K>, TTable>;
+  select<TSelection extends Record<string, ColumnSelectionValue>>(
+    columns: TSelection
+  ): SelectQueryBuilder<T & SelectionResult<TSelection>, TTable>;
+  select<
+    K extends keyof TTable['columns'] & string,
+    TSelection extends Record<string, ColumnSelectionValue>
+  >(
+    ...args: K[] | [TSelection]
+  ): SelectQueryBuilder<T, TTable> {
     // If first arg is an object (not a string), treat as projection map
     if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null && typeof args[0] !== 'string') {
-      const columns = args[0] as TSelection;
-      return this.clone<T & SelectionResult<TSelection>>(
-        this.projectionFacet.select(this.context, columns)
-      );
-    }
+      const columns = args[0] as TSelection;
+      return this.clone<T & SelectionResult<TSelection>>(
+        this.projectionFacet.select(this.context, columns)
+      );
+    }
 
     // Otherwise, treat as column names
     const cols = args as K[];
     const selection: Record<string, ColumnDef> = {};
-    for (const key of cols) {
-      const col = this.env.table.columns[key];
-      if (!col) {
-        throw new Error(`Column '${key}' not found on table '${this.env.table.name}'`);
-      }
-      selection[key] = col;
-    }
-
-    return this.clone<T & SelectionFromKeys<TTable, K>>(
-      this.projectionFacet.select(this.context, selection)
-    );
-  }
+    for (const key of cols) {
+      const col = this.env.table.columns[key];
+      if (!col) {
+        throw new Error(`Column '${key}' not found on table '${this.env.table.name}'`);
+      }
+      selection[key] = col;
+    }
+
+    return this.clone<T & SelectionFromKeys<TTable, K>>(
+      this.projectionFacet.select(this.context, selection)
+    );
+  }
 
   /**
    * Selects raw column expressions
@@ -384,15 +385,15 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * qb.select('id', 'name')
    *   .selectSubquery('postCount', postCount);
    */
-  selectSubquery<TValue = unknown, K extends string = string, TSub extends TableDef = TableDef>(
-    alias: K,
-    sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
-  ): SelectQueryBuilder<T & Record<K, TValue>, TTable> {
-    const query = resolveSelectQuery(sub);
-    return this.clone<T & Record<K, TValue>>(
-      this.projectionFacet.selectSubquery(this.context, alias, query)
-    );
-  }
+  selectSubquery<TValue = unknown, K extends string = string, TSub extends TableDef = TableDef>(
+    alias: K,
+    sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+  ): SelectQueryBuilder<T & Record<K, TValue>, TTable> {
+    const query = resolveSelectQuery(sub);
+    return this.clone<T & Record<K, TValue>>(
+      this.projectionFacet.selectSubquery(this.context, alias, query)
+    );
+  }
 
   /**
    * Adds a JOIN against a derived table (subquery with alias)
@@ -668,14 +669,14 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   /**
    * Ensures that if no columns are selected, all columns from the table are selected by default.
    */
-  private ensureDefaultSelection(): SelectQueryBuilder<T, TTable> {
-    const columns = this.context.state.ast.columns;
-    if (!columns || columns.length === 0) {
-      const columnKeys = Object.keys(this.env.table.columns) as (keyof TTable['columns'] & string)[];
-      return this.select(...columnKeys);
-    }
-    return this;
-  }
+  private ensureDefaultSelection(): SelectQueryBuilder<T, TTable> {
+    const columns = this.context.state.ast.columns;
+    if (!columns || columns.length === 0) {
+      const columnKeys = Object.keys(this.env.table.columns) as (keyof TTable['columns'] & string)[];
+      return this.select(...columnKeys);
+    }
+    return this;
+  }
 
   /**
    * Executes the query and returns hydrated results.
@@ -708,11 +709,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * // rows is EntityInstance<UserTable>[] (plain objects)
    * rows[0] instanceof User; // false
    */
-  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    const builder = this.ensureDefaultSelection();
-    const rows = await executeHydratedPlain(ctx, builder);
-    return rows as EntityInstance<TTable>[];
-  }
+  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
+    const builder = this.ensureDefaultSelection();
+    const rows = await executeHydratedPlain(ctx, builder);
+    return rows as EntityInstance<TTable>[];
+  }
 
   /**
    * Executes the query and returns results as real class instances.
@@ -894,7 +895,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   .where(eq(userTable.columns.active, false));
    * qb.union(activeUsers).union(inactiveUsers);
    */
-  union<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
+  union<TSub extends TableDef>(query: SelectQueryBuilder<T, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('UNION', query));
   }
 
@@ -907,7 +908,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * const q2 = new SelectQueryBuilder(userTable).where(lt(userTable.columns.score, 20));
    * qb.unionAll(q1).unionAll(q2);
    */
-  unionAll<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
+  unionAll<TSub extends TableDef>(query: SelectQueryBuilder<T, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('UNION ALL', query));
   }
 
@@ -922,7 +923,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   .where(eq(userTable.columns.premium, true));
    * qb.intersect(activeUsers).intersect(premiumUsers);
    */
-  intersect<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
+  intersect<TSub extends TableDef>(query: SelectQueryBuilder<T, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('INTERSECT', query));
   }
 
@@ -936,7 +937,7 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   .where(eq(userTable.columns.active, false));
    * qb.except(allUsers).except(inactiveUsers); // Only active users
    */
-  except<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
+  except<TSub extends TableDef>(query: SelectQueryBuilder<T, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
     return this.clone(this.applySetOperation('EXCEPT', query));
   }
 

package/src/schema/column-types.ts

@@ -134,20 +134,20 @@ export const col = {
 
   /**
    * Creates a variable character column definition
-   * @param length - Maximum length of the string
-   * @returns ColumnDef with VARCHAR type
-   */
-  varchar: (length: number): ColumnDef<'VARCHAR'> => ({ name: '', type: 'VARCHAR', args: [length] }),
-
-  /**
-   * Creates a text column definition
-   */
-  text: (): ColumnDef<'TEXT'> => ({ name: '', type: 'TEXT' }),
-
-  /**
-   * Creates a fixed precision decimal column definition
-   */
-  decimal: (precision: number, scale = 0): ColumnDef<'DECIMAL'> => ({
+   * @param length - Maximum length of the string
+   * @returns ColumnDef with VARCHAR type
+   */
+  varchar: (length: number): ColumnDef<'VARCHAR'> => ({ name: '', type: 'VARCHAR', args: [length] }),
+
+  /**
+   * Creates a text column definition
+   */
+  text: (): ColumnDef<'TEXT'> => ({ name: '', type: 'TEXT' }),
+
+  /**
+   * Creates a fixed precision decimal column definition
+   */
+  decimal: (precision: number, scale = 0): ColumnDef<'DECIMAL'> => ({
     name: '',
     type: 'DECIMAL',
     args: [precision, scale]

package/src/schema/table.ts

@@ -30,20 +30,24 @@ export interface TableOptions {
   collation?: string;
 }
 
-export interface TableHooks {
-  beforeInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
-  afterInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
-  beforeUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
-  afterUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
-  beforeDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
-  afterDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
+export interface TableHooks<TEntity = unknown, TContext = unknown> {
+  beforeInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
 }
 
 /**
  * Definition of a database table with its columns and relationships
  * @typeParam T - Type of the columns record
  */
-export interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
+export interface TableDef<
+  T extends Record<string, ColumnDef> = Record<string, ColumnDef>,
+  TEntity = unknown,
+  TContext = unknown
+> {
   /** Name of the table */
   name: string;
   /** Optional schema/catalog name */
@@ -53,7 +57,7 @@ export interface TableDef<T extends Record<string, ColumnDef> = Record<string, C
   /** Record of relationship definitions keyed by relation name */
   relations: Record<string, RelationDef>;
   /** Optional lifecycle hooks */
-  hooks?: TableHooks;
+  hooks?: TableHooks<TEntity, TContext>;
   /** Composite primary key definition (falls back to column.primary flags) */
   primaryKey?: string[];
   /** Secondary indexes */
@@ -85,13 +89,17 @@ export interface TableDef<T extends Record<string, ColumnDef> = Record<string, C
  * });
  * ```
  */
-export const defineTable = <T extends Record<string, ColumnDef>>(
-  name: string,
-  columns: T,
-  relations: Record<string, RelationDef> = {},
-  hooks?: TableHooks,
-  options: TableOptions = {}
-): TableDef<T> => {
+export const defineTable = <
+  T extends Record<string, ColumnDef>,
+  TEntity = unknown,
+  TContext = unknown
+>(
+  name: string,
+  columns: T,
+  relations: Record<string, RelationDef> = {},
+  hooks?: TableHooks<TEntity, TContext>,
+  options: TableOptions = {}
+): TableDef<T, TEntity, TContext> => {
   // Runtime mutability to assign names to column definitions for convenience
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
     const colDef = { ...def, name: key, table: name };
@@ -112,21 +120,21 @@ export const defineTable = <T extends Record<string, ColumnDef>>(
     engine: options.engine,
     charset: options.charset,
     collation: options.collation
-  };
-};
-
-/**
- * Assigns relations to a table definition while preserving literal typing.
- */
-export function setRelations<
-  TTable extends TableDef,
-  TRelations extends Record<string, RelationDef>
->(
-  table: TTable,
-  relations: TRelations
-): asserts table is TTable & { relations: TRelations } {
-  table.relations = relations;
-}
+  };
+};
+
+/**
+ * Assigns relations to a table definition while preserving literal typing.
+ */
+export function setRelations<
+  TTable extends TableDef,
+  TRelations extends Record<string, RelationDef>
+>(
+  table: TTable,
+  relations: TRelations
+): asserts table is TTable & { relations: TRelations } {
+  table.relations = relations;
+}
 
 type DirectColumnKeys<T extends TableDef> =
   Exclude<keyof T["columns"] & string, keyof T | "$">;

package/src/schema/types.ts

@@ -12,12 +12,12 @@ import {
 /**
  * Resolves a relation definition to its target table type.
  */
-export type RelationTargetTable<TRel extends RelationDef> =
-  TRel extends HasManyRelation<infer TTarget> ? TTarget :
-  TRel extends HasOneRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
-  never;
+export type RelationTargetTable<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget> ? TTarget :
+  TRel extends HasOneRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
+  never;
 
 type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
 
@@ -43,12 +43,12 @@ export type InferRow<TTable extends TableDef> = {
   [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
 };
 
-type RelationResult<T extends RelationDef> =
-  T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
-  T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToManyRelation<infer TTarget, TableDef> ? (InferRow<TTarget> & { _pivot?: Record<string, unknown> })[] :
-  never;
+type RelationResult<T extends RelationDef> =
+  T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
+  T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToManyRelation<infer TTarget, infer TPivot> ? (InferRow<TTarget> & { _pivot?: InferRow<TPivot> })[] :
+  never;
 
 /**
  * Maps relation names to the expected row results
@@ -57,26 +57,26 @@ export type RelationMap<TTable extends TableDef> = {
   [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
 };
 
-type RelationWrapper<TRel extends RelationDef> =
-  TRel extends HasManyRelation<infer TTarget>
-    ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
-    : TRel extends HasOneRelation<infer TTarget>
-      ? HasOneReference<EntityInstance<TTarget>>
-      : TRel extends BelongsToManyRelation<infer TTarget>
-    ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
-      & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
-    : TRel extends BelongsToRelation<infer TTarget>
-          ? BelongsToReference<EntityInstance<TTarget>>
-          : never;
-
-export interface HasManyCollection<TChild> {
-  length: number;
-  [Symbol.iterator](): Iterator<TChild>;
-  load(): Promise<TChild[]>;
-  getItems(): TChild[];
-  add(data: Partial<TChild>): TChild;
-  attach(entity: TChild): void;
-  remove(entity: TChild): void;
+type RelationWrapper<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget>
+  ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
+  : TRel extends HasOneRelation<infer TTarget>
+  ? HasOneReference<EntityInstance<TTarget>>
+  : TRel extends BelongsToManyRelation<infer TTarget, infer TPivot>
+  ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
+  & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
+  : TRel extends BelongsToRelation<infer TTarget>
+  ? BelongsToReference<EntityInstance<TTarget>>
+  : never;
+
+export interface HasManyCollection<TChild> {
+  length: number;
+  [Symbol.iterator](): Iterator<TChild>;
+  load(): Promise<TChild[]>;
+  getItems(): TChild[];
+  add(data: Partial<TChild>): TChild;
+  attach(entity: TChild): void;
+  remove(entity: TChild): void;
   clear(): void;
 }
 
@@ -96,17 +96,17 @@ export interface HasOneReferenceApi<TChild extends object = object> {
 
 export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
 
-export interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
-  length: number;
-  [Symbol.iterator](): Iterator<TTarget>;
-  load(): Promise<TTarget[]>;
-  getItems(): TTarget[];
-  attach(target: TTarget | number | string): void;
-  detach(target: TTarget | number | string): void;
-  syncByIds(ids: (number | string)[]): Promise<void>;
-  /** @internal Type-level marker for the related pivot entity */
-  readonly __pivotType?: TPivot;
-}
+export interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
+  length: number;
+  [Symbol.iterator](): Iterator<TTarget>;
+  load(): Promise<TTarget[]>;
+  getItems(): TTarget[];
+  attach(target: TTarget | number | string): void;
+  detach(target: TTarget | number | string): void;
+  syncByIds(ids: (number | string)[]): Promise<void>;
+  /** @internal Type-level marker for the related pivot entity */
+  readonly __pivotType?: TPivot;
+}
 
 export type EntityInstance<
   TTable extends TableDef,
@@ -117,14 +117,14 @@ export type EntityInstance<
   $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
 };
 
-export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
-
-type IsAny<T> = 0 extends (1 & T) ? true : false;
-
-export type SelectableKeys<T> = {
-  [K in keyof T]-?: IsAny<T[K]> extends true
-    ? never
-    : NonNullable<T[K]> extends Primitive
-      ? K
-      : never
-}[keyof T];
+export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
+
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+
+export type SelectableKeys<T> = {
+  [K in keyof T]-?: IsAny<T[K]> extends true
+  ? never
+  : NonNullable<T[K]> extends Primitive
+  ? K
+  : never
+}[keyof T];