metal-orm 1.0.64 → 1.0.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.64",
+  "version": "1.0.66",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/core/ast/aggregate-functions.ts

@@ -1,4 +1,4 @@
-import { ColumnNode, FunctionNode } from './expression-nodes.js';
+import { ColumnNode } from './expression-nodes.js';
 import { columnOperand, valueToOperand, ValueOperandInput } from './expression-builders.js';
 import { ColumnRef } from './types.js';
 import { OrderByNode } from './query.js';

package/src/core/ast/window-functions.ts

@@ -5,7 +5,7 @@ import { OrderByNode } from './query.js';
 import { ColumnRef } from './types.js';
 import { TypedExpression, asType } from './expression.js';
 
-const buildWindowFunction = <T = any>(
+const buildWindowFunction = <T = unknown>(
   name: string,
   args: (ColumnNode | LiteralNode | JsonPathNode)[] = [],
   partitionBy?: ColumnNode[],
@@ -66,7 +66,7 @@ export const ntile = (n: number): TypedExpression<number> =>
  * @param defaultValue - Optional default value.
  * @returns A `TypedExpression<T>` representing the `LAG` window function.
  */
-export const lag = <T = any>(
+export const lag = <T = unknown>(
   col: ColumnRef | ColumnNode,
   offset: number = 1,
   defaultValue?: LiteralNode['value']
@@ -89,7 +89,7 @@ export const lag = <T = any>(
  * @param defaultValue - Optional default value.
  * @returns A `TypedExpression<T>` representing the `LEAD` window function.
  */
-export const lead = <T = any>(
+export const lead = <T = unknown>(
   col: ColumnRef | ColumnNode,
   offset: number = 1,
   defaultValue?: LiteralNode['value']
@@ -110,7 +110,7 @@ export const lead = <T = any>(
  * @param col - Column or expression to get first value from.
  * @returns A `TypedExpression<T>` representing the `FIRST_VALUE` window function.
  */
-export const firstValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
+export const firstValue = <T = unknown>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
   buildWindowFunction<T>('FIRST_VALUE', [columnOperand(col)]);
 
 /**
@@ -119,7 +119,7 @@ export const firstValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpressio
  * @param col - Column or expression to get last value from.
  * @returns A `TypedExpression<T>` representing the `LAST_VALUE` window function.
  */
-export const lastValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
+export const lastValue = <T = unknown>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
   buildWindowFunction<T>('LAST_VALUE', [columnOperand(col)]);
 
 /**
@@ -131,7 +131,7 @@ export const lastValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpression
  * @param orderBy - Optional ORDER BY clauses.
  * @returns A `TypedExpression<T>` representing the window function.
  */
-export const windowFunction = <T = any>(
+export const windowFunction = <T = unknown>(
   name: string,
   args: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
   partitionBy?: (ColumnRef | ColumnNode)[],

package/src/core/functions/array.ts

@@ -22,14 +22,14 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
     args: args.map(toOperand)
 });
 
-const afn = <T = any[]>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+const afn = <T = unknown[]>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
 
 /**
  * Appends a value to the end of an array.
  * 
  * @param array - Array column or value.
  * @param value - Value to append.
- * @returns A `TypedExpression<any[]>` representing the `ARRAY_APPEND` SQL function.
+ * @returns A `TypedExpression<unknown[]>` representing the `ARRAY_APPEND` SQL function.
  */
-export const arrayAppend = (array: OperandInput, value: OperandInput): TypedExpression<any[]> =>
-    afn('ARRAY_APPEND', [array, value]);
+export const arrayAppend = (array: OperandInput, value: OperandInput): TypedExpression<unknown[]> =>
+    afn<unknown[]>('ARRAY_APPEND', [array, value]);

package/src/core/functions/control-flow.ts

@@ -22,7 +22,7 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
   args: args.map(toOperand)
 });
 
-const afn = <T = any>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+const afn = <T = unknown>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
 
 /**
  * Returns the first non-null value in a list.
@@ -33,7 +33,7 @@ const afn = <T = any>(key: string, args: OperandInput[]): TypedExpression<T> =>
  * @example
  * coalesce(users.nickname, users.firstName, 'Guest');
  */
-export const coalesce = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
+export const coalesce = <T = unknown>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('coalesce() expects at least 2 arguments');
   return afn<T>('COALESCE', args);
 };
@@ -45,7 +45,7 @@ export const coalesce = <T = any>(...args: OperandInput[]): TypedExpression<T> =
  * @param val2 - The second value to compare against.
  * @returns A `TypedExpression<T>` representing the `NULLIF` SQL function.
  */
-export const nullif = <T = any>(val1: OperandInput, val2: OperandInput): TypedExpression<T> => afn<T>('NULLIF', [val1, val2]);
+export const nullif = <T = unknown>(val1: OperandInput, val2: OperandInput): TypedExpression<T> => afn<T>('NULLIF', [val1, val2]);
 
 /**
  * Returns the largest value in a list.
@@ -53,7 +53,7 @@ export const nullif = <T = any>(val1: OperandInput, val2: OperandInput): TypedEx
  * @param args - The list of values or columns to compare.
  * @returns A `TypedExpression<T>` representing the `GREATEST` SQL function.
  */
-export const greatest = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
+export const greatest = <T = unknown>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('greatest() expects at least 2 arguments');
   return afn<T>('GREATEST', args);
 };
@@ -64,7 +64,7 @@ export const greatest = <T = any>(...args: OperandInput[]): TypedExpression<T> =
  * @param args - The list of values or columns to compare.
  * @returns A `TypedExpression<T>` representing the `LEAST` SQL function.
  */
-export const least = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
+export const least = <T = unknown>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('least() expects at least 2 arguments');
   return afn<T>('LEAST', args);
 };
@@ -76,4 +76,4 @@ export const least = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
  * @param defaultValue - The default value to return if val is null.
  * @returns A `TypedExpression<T>` representing the `COALESCE` SQL function.
  */
-export const ifNull = <T = any>(val: OperandInput, defaultValue: OperandInput): TypedExpression<T> => coalesce<T>(val, defaultValue);
+export const ifNull = <T = unknown>(val: OperandInput, defaultValue: OperandInput): TypedExpression<T> => coalesce<T>(val, defaultValue);

package/src/core/functions/json.ts

@@ -23,7 +23,7 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
 });
 
 const nfn = (key: string, args: OperandInput[]): TypedExpression<number> => asType<number>(fn(key, args));
-const afn = <T = any>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+const afn = <T = unknown>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
 
 /**
  * Returns the number of elements in a JSON array or object.
@@ -41,18 +41,18 @@ export const jsonLength = (target: OperandInput, path?: OperandInput): TypedExpr
  * @param target - JSON column or value.
  * @param path - JSON path to set.
  * @param value - Value to set.
- * @returns A `TypedExpression<any>` representing the `JSON_SET` SQL function.
+ * @returns A `TypedExpression<T>` representing the `JSON_SET` SQL function.
  */
-export const jsonSet = (target: OperandInput, path: OperandInput, value: OperandInput): TypedExpression<any> =>
-    afn('JSON_SET', [target, path, value]);
+export const jsonSet = <T = unknown>(target: OperandInput, path: OperandInput, value: OperandInput): TypedExpression<T> =>
+    afn<T>('JSON_SET', [target, path, value]);
 
 /**
  * Aggregates values into a JSON array.
  * 
  * @param value - Column or expression to aggregate.
- * @returns A `TypedExpression<any[]>` representing the `JSON_ARRAYAGG` SQL function.
+ * @returns A `TypedExpression<unknown[]>` representing the `JSON_ARRAYAGG` SQL function.
  */
-export const jsonArrayAgg = (value: OperandInput): TypedExpression<any[]> => afn<any[]>('JSON_ARRAYAGG', [value]);
+export const jsonArrayAgg = (value: OperandInput): TypedExpression<unknown[]> => afn<unknown[]>('JSON_ARRAYAGG', [value]);
 
 /**
  * Checks if a JSON document contains a specific piece of data.

package/src/index.ts

@@ -41,7 +41,8 @@ export * from './orm/relations/has-many.js';
 export * from './orm/relations/belongs-to.js';
 export * from './orm/relations/many-to-many.js';
 export * from './orm/execute.js';
-export * from './orm/entity-context.js';
+export type { EntityContext } from './orm/entity-context.js';
+export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
 export * from './orm/execution-context.js';
 export * from './orm/hydration-context.js';
 export * from './orm/domain-event-bus.js';

package/src/orm/entity-context.ts

@@ -2,7 +2,9 @@ import { Dialect } from '../core/dialect/abstract.js';
 import type { DbExecutor } from '../core/execution/db-executor.js';
 import { TableDef } from '../schema/table.js';
 import { RelationDef } from '../schema/relation.js';
-import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
+import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
+
+export type PrimaryKey = string | number;
 
 /**
  * Interface for entity context providing entity tracking and management.
@@ -19,7 +21,7 @@ export interface EntityContext {
      * @param pk - The primary key value
      * @returns The entity or undefined
      */
-    getEntity(table: TableDef, pk: unknown): unknown;
+    getEntity(table: TableDef, pk: PrimaryKey): object | undefined;
 
     /**
      * Sets an entity in the context.
@@ -27,7 +29,7 @@ export interface EntityContext {
      * @param pk - The primary key value
      * @param entity - The entity to set
      */
-    setEntity(table: TableDef, pk: unknown, entity: unknown): void;
+    setEntity(table: TableDef, pk: PrimaryKey, entity: object): void;
 
     /**
      * Tracks a new entity.
@@ -35,7 +37,7 @@ export interface EntityContext {
      * @param entity - The new entity
      * @param pk - Optional primary key
      */
-    trackNew(table: TableDef, entity: unknown, pk?: unknown): void;
+    trackNew(table: TableDef, entity: object, pk?: PrimaryKey): void;
 
     /**
      * Tracks a managed entity.
@@ -43,19 +45,19 @@ export interface EntityContext {
      * @param pk - The primary key
      * @param entity - The managed entity
      */
-    trackManaged(table: TableDef, pk: unknown, entity: unknown): void;
+    trackManaged(table: TableDef, pk: PrimaryKey, entity: object): void;
 
     /**
      * Marks an entity as dirty.
      * @param entity - The entity to mark
      */
-    markDirty(entity: unknown): void;
+    markDirty(entity: object): void;
 
     /**
      * Marks an entity as removed.
      * @param entity - The entity to mark
      */
-    markRemoved(entity: unknown): void;
+    markRemoved(entity: object): void;
 
     /**
      * Gets all tracked entities for a table.

package/src/orm/entity-relations.ts

@@ -1,207 +1,207 @@
-import { TableDef } from '../schema/table.js';
-import { EntityInstance, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
-import { EntityMeta, RelationKey } from './entity-meta.js';
-import { DefaultHasManyCollection } from './relations/has-many.js';
-import { DefaultHasOneReference } from './relations/has-one.js';
-import { DefaultBelongsToReference } from './relations/belongs-to.js';
-import { DefaultManyToManyCollection } from './relations/many-to-many.js';
-import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
-import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import { relationLoaderCache } from './entity-relation-cache.js';
-
-export type RelationEntityFactory = (
-  table: TableDef,
-  row: Record<string, unknown>
-) => EntityInstance<TableDef>;
-
-const proxifyRelationWrapper = <T extends object>(wrapper: T): T => {
-  return new Proxy(wrapper, {
-    get(target, prop, receiver) {
-      if (typeof prop === 'symbol') {
-        return Reflect.get(target, prop, receiver);
-      }
-
-      if (prop in target) {
-        return Reflect.get(target, prop, receiver);
-      }
-
-      const getItems = (target as { getItems?: () => unknown }).getItems;
-      if (typeof getItems === 'function') {
-        const items = getItems.call(target);
-        if (items && prop in (items as object)) {
-          const propName = prop as string;
-          const value = (items as Record<string, unknown>)[propName];
-          return typeof value === 'function' ? value.bind(items) : value;
-        }
-      }
-
-      const getRef = (target as { get?: () => unknown }).get;
-      if (typeof getRef === 'function') {
-        const current = getRef.call(target);
-        if (current && prop in (current as object)) {
-          const propName = prop as string;
-          const value = (current as Record<string, unknown>)[propName];
-          return typeof value === 'function' ? value.bind(current) : value;
-        }
-      }
-
-      return undefined;
-    },
-
-    set(target, prop, value, receiver) {
-      if (typeof prop === 'symbol') {
-        return Reflect.set(target, prop, value, receiver);
-      }
-
-      if (prop in target) {
-        return Reflect.set(target, prop, value, receiver);
-      }
-
-      const getRef = (target as { get?: () => unknown }).get;
-      if (typeof getRef === 'function') {
-        const current = getRef.call(target);
-        if (current && typeof current === 'object') {
-          return Reflect.set(current as object, prop, value);
-        }
-      }
-
-      const getItems = (target as { getItems?: () => unknown }).getItems;
-      if (typeof getItems === 'function') {
-        const items = getItems.call(target);
-        return Reflect.set(items as object, prop, value);
-      }
-
-      return Reflect.set(target, prop, value, receiver);
-    }
-  });
-};
-
-/**
- * Gets a relation wrapper for an entity.
- * @param meta - The entity metadata
- * @param relationName - The relation name
- * @param owner - The owner entity
- * @param createEntity - The entity factory for relation rows
- * @returns The relation wrapper or undefined
- */
-export const getRelationWrapper = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: RelationKey<TTable> | string,
-  owner: unknown,
-  createEntity: RelationEntityFactory
-): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
-  const relationKey = relationName as string;
-
-  if (meta.relationWrappers.has(relationKey)) {
-    return meta.relationWrappers.get(relationKey) as HasManyCollection<unknown>;
-  }
-
-  const relation = meta.table.relations[relationKey];
-  if (!relation) return undefined;
-
-  const wrapper = instantiateWrapper(meta, relationKey, relation, owner, createEntity);
-  if (!wrapper) return undefined;
-
-  const proxied = proxifyRelationWrapper(wrapper as object);
-  meta.relationWrappers.set(relationKey, proxied);
-  return proxied as HasManyCollection<unknown>;
-};
-
-/**
- * Instantiates the appropriate relation wrapper based on relation type.
- * @param meta - The entity metadata
- * @param relationName - The relation name
- * @param relation - The relation definition
- * @param owner - The owner entity
- * @param createEntity - The entity factory for relation rows
- * @returns The relation wrapper or undefined
- */
-const instantiateWrapper = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: string,
-  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
-  owner: unknown,
-  createEntity: RelationEntityFactory
-): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
-  const metaBase = meta as unknown as EntityMeta<TableDef>;
-  const lazyOptions = meta.lazyRelationOptions.get(relationName);
-  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
-    relationLoaderCache(metaBase, relationName, factory);
-  switch (relation.type) {
-    case RelationKinds.HasOne: {
-      const hasOne = relation as HasOneRelation;
-      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, lazyOptions)
-      );
-      return new DefaultHasOneReference(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        hasOne,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(hasOne.target, row),
-        localKey
-      );
-    }
-    case RelationKinds.HasMany: {
-      const hasMany = relation as HasManyRelation;
-      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, lazyOptions)
-      );
-      return new DefaultHasManyCollection(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        hasMany,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        localKey
-      );
-    }
-    case RelationKinds.BelongsTo: {
-      const belongsTo = relation as BelongsToRelation;
-      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
-      const loader = () => loadCached(() =>
-        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, lazyOptions)
-      );
-      return new DefaultBelongsToReference(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        belongsTo,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        targetKey
-      );
-    }
-    case RelationKinds.BelongsToMany: {
-      const many = relation as BelongsToManyRelation;
-      const localKey = many.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
-      );
-      return new DefaultManyToManyCollection(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        many,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        localKey
-      );
-    }
-    default:
-      return undefined;
-  }
-};
+import { TableDef } from '../schema/table.js';
+import { EntityInstance, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
+import { EntityMeta, RelationKey } from './entity-meta.js';
+import { DefaultHasManyCollection } from './relations/has-many.js';
+import { DefaultHasOneReference } from './relations/has-one.js';
+import { DefaultBelongsToReference } from './relations/belongs-to.js';
+import { DefaultManyToManyCollection } from './relations/many-to-many.js';
+import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
+import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import { relationLoaderCache } from './entity-relation-cache.js';
+
+export type RelationEntityFactory = (
+  table: TableDef,
+  row: Record<string, unknown>
+) => EntityInstance<TableDef>;
+
+const proxifyRelationWrapper = <T extends object>(wrapper: T): T => {
+  return new Proxy(wrapper, {
+    get(target, prop, receiver) {
+      if (typeof prop === 'symbol') {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+
+      const getItems = (target as { getItems?: () => unknown }).getItems;
+      if (typeof getItems === 'function') {
+        const items = getItems.call(target);
+        if (items && prop in (items as object)) {
+          const propName = prop as string;
+          const value = (items as Record<string, unknown>)[propName];
+          return typeof value === 'function' ? value.bind(items) : value;
+        }
+      }
+
+      const getRef = (target as { get?: () => unknown }).get;
+      if (typeof getRef === 'function') {
+        const current = getRef.call(target);
+        if (current && prop in (current as object)) {
+          const propName = prop as string;
+          const value = (current as Record<string, unknown>)[propName];
+          return typeof value === 'function' ? value.bind(current) : value;
+        }
+      }
+
+      return undefined;
+    },
+
+    set(target, prop, value, receiver) {
+      if (typeof prop === 'symbol') {
+        return Reflect.set(target, prop, value, receiver);
+      }
+
+      if (prop in target) {
+        return Reflect.set(target, prop, value, receiver);
+      }
+
+      const getRef = (target as { get?: () => unknown }).get;
+      if (typeof getRef === 'function') {
+        const current = getRef.call(target);
+        if (current && typeof current === 'object') {
+          return Reflect.set(current as object, prop, value);
+        }
+      }
+
+      const getItems = (target as { getItems?: () => unknown }).getItems;
+      if (typeof getItems === 'function') {
+        const items = getItems.call(target);
+        return Reflect.set(items as object, prop, value);
+      }
+
+      return Reflect.set(target, prop, value, receiver);
+    }
+  });
+};
+
+/**
+ * Gets a relation wrapper for an entity.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param owner - The owner entity
+ * @param createEntity - The entity factory for relation rows
+ * @returns The relation wrapper or undefined
+ */
+export const getRelationWrapper = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: RelationKey<TTable> | string,
+  owner: unknown,
+  createEntity: RelationEntityFactory
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
+  const relationKey = relationName as string;
+
+  if (meta.relationWrappers.has(relationKey)) {
+    return meta.relationWrappers.get(relationKey) as HasManyCollection<unknown>;
+  }
+
+  const relation = meta.table.relations[relationKey];
+  if (!relation) return undefined;
+
+  const wrapper = instantiateWrapper(meta, relationKey, relation, owner, createEntity);
+  if (!wrapper) return undefined;
+
+  const proxied = proxifyRelationWrapper(wrapper as object);
+  meta.relationWrappers.set(relationKey, proxied);
+  return proxied as HasManyCollection<unknown>;
+};
+
+/**
+ * Instantiates the appropriate relation wrapper based on relation type.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param relation - The relation definition
+ * @param owner - The owner entity
+ * @param createEntity - The entity factory for relation rows
+ * @returns The relation wrapper or undefined
+ */
+const instantiateWrapper = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
+  owner: unknown,
+  createEntity: RelationEntityFactory
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
+  const metaBase = meta as unknown as EntityMeta<TableDef>;
+  const lazyOptions = meta.lazyRelationOptions.get(relationName);
+  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
+    relationLoaderCache(metaBase, relationName, factory);
+  switch (relation.type) {
+    case RelationKinds.HasOne: {
+      const hasOne = relation as HasOneRelation;
+      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, lazyOptions)
+      );
+      return new DefaultHasOneReference(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        hasOne,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(hasOne.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.HasMany: {
+      const hasMany = relation as HasManyRelation;
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, lazyOptions)
+      );
+      return new DefaultHasManyCollection(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        hasMany,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.BelongsTo: {
+      const belongsTo = relation as BelongsToRelation;
+      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
+      const loader = () => loadCached(() =>
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, lazyOptions)
+      );
+      return new DefaultBelongsToReference(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        belongsTo,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        targetKey
+      );
+    }
+    case RelationKinds.BelongsToMany: {
+      const many = relation as BelongsToManyRelation;
+      const localKey = many.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
+      );
+      return new DefaultManyToManyCollection(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        many,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        localKey
+      );
+    }
+    default:
+      return undefined;
+  }
+};