metal-orm 1.0.56 → 1.0.58

package/src/orm/entity.ts

@@ -9,6 +9,7 @@ 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 { RelationIncludeOptions } from '../query-builder/relation-types.js';
 
 /**
  * Type representing an array of database rows.
@@ -23,7 +24,7 @@ type Rows = Record<string, unknown>[];
  * @param factory - The factory function to create the cache
  * @returns Promise with the cached relation data
  */
-const relationLoaderCache = <T extends Map<string, unknown>>(
+export const relationLoaderCache = <T extends Map<string, unknown>>(
   meta: EntityMeta<TableDef>,
   relationName: string,
   factory: () => Promise<T>
@@ -69,13 +70,15 @@ export const createEntityProxy = <
   ctx: EntityContext,
   table: TTable,
   row: Record<string, unknown>,
-  lazyRelations: TLazy[] = [] as TLazy[]
+  lazyRelations: TLazy[] = [] as TLazy[],
+  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
 ): EntityInstance<TTable> => {
   const target: Record<string, unknown> = { ...row };
   const meta: EntityMeta<TTable> = {
     ctx,
     table,
     lazyRelations: [...lazyRelations],
+    lazyRelationOptions: new Map(lazyRelationOptions),
     relationCache: new Map(),
     relationHydration: new Map(),
     relationWrappers: new Map()
@@ -141,7 +144,8 @@ export const createEntityFromRow = <
   ctx: EntityContext,
   table: TTable,
   row: Record<string, unknown>,
-  lazyRelations: (keyof RelationMap<TTable>)[] = []
+  lazyRelations: (keyof RelationMap<TTable>)[] = [],
+  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
 ): TResult => {
   const pkName = findPrimaryKey(table);
   const pkValue = row[pkName];
@@ -150,7 +154,7 @@ export const createEntityFromRow = <
     if (tracked) return tracked as TResult;
   }
 
-  const entity = createEntityProxy(ctx, table, row, lazyRelations);
+  const entity = createEntityProxy(ctx, table, row, lazyRelations, lazyRelationOptions);
   if (pkValue !== undefined && pkValue !== null) {
     ctx.trackManaged(table, pkValue, entity);
   } else {
@@ -223,6 +227,68 @@ const populateHydrationCache = <TTable extends 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
@@ -234,7 +300,7 @@ const getRelationWrapper = (
   meta: EntityMeta<TableDef>,
   relationName: string,
   owner: unknown
-): HasManyCollection<unknown> | HasOneReference<unknown> | BelongsToReference<unknown> | ManyToManyCollection<unknown> | undefined => {
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
   if (meta.relationWrappers.has(relationName)) {
     return meta.relationWrappers.get(relationName) as HasManyCollection<unknown>;
   }
@@ -243,11 +309,11 @@ const getRelationWrapper = (
   if (!relation) return undefined;
 
   const wrapper = instantiateWrapper(meta, relationName, relation, owner);
-  if (wrapper) {
-    meta.relationWrappers.set(relationName, wrapper);
-  }
+  if (!wrapper) return undefined;
 
-  return wrapper;
+  const proxied = proxifyRelationWrapper(wrapper as object);
+  meta.relationWrappers.set(relationName, proxied);
+  return proxied as HasManyCollection<unknown>;
 };
 
 /**
@@ -263,13 +329,14 @@ const instantiateWrapper = (
   relationName: string,
   relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
   owner: unknown
-): HasManyCollection<unknown> | HasOneReference<unknown> | BelongsToReference<unknown> | ManyToManyCollection<unknown> | undefined => {
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
+  const lazyOptions = meta.lazyRelationOptions.get(relationName);
   switch (relation.type) {
     case RelationKinds.HasOne: {
       const hasOne = relation as HasOneRelation;
       const localKey = hasOne.localKey || findPrimaryKey(meta.table);
       const loader = () => relationLoaderCache(meta, relationName, () =>
-        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne)
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, lazyOptions)
       );
       return new DefaultHasOneReference(
         meta.ctx,
@@ -287,7 +354,7 @@ const instantiateWrapper = (
       const hasMany = relation as HasManyRelation;
       const localKey = hasMany.localKey || findPrimaryKey(meta.table);
       const loader = () => relationLoaderCache(meta, relationName, () =>
-        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany)
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, lazyOptions)
       );
       return new DefaultHasManyCollection(
         meta.ctx,
@@ -305,7 +372,7 @@ const instantiateWrapper = (
       const belongsTo = relation as BelongsToRelation;
       const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
       const loader = () => relationLoaderCache(meta, relationName, () =>
-        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo)
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, lazyOptions)
       );
       return new DefaultBelongsToReference(
         meta.ctx,
@@ -323,7 +390,7 @@ const instantiateWrapper = (
       const many = relation as BelongsToManyRelation;
       const localKey = many.localKey || findPrimaryKey(meta.table);
       const loader = () => relationLoaderCache(meta, relationName, () =>
-        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many)
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
       );
       return new DefaultManyToManyCollection(
         meta.ctx,

package/src/orm/execute.ts

@@ -1,16 +1,29 @@
-import { TableDef } from '../schema/table.js';
-import { EntityInstance } from '../schema/types.js';
-import { hydrateRows } from './hydration.js';
-import { OrmSession } from './orm-session.ts';
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import { createEntityProxy, createEntityFromRow } from './entity.js';
+import { TableDef } from '../schema/table.js';
+import { EntityInstance, RelationMap } from '../schema/types.js';
+import { RelationKinds } from '../schema/relation.js';
+import { hydrateRows } from './hydration.js';
+import { OrmSession } from './orm-session.ts';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import {
+  createEntityProxy,
+  createEntityFromRow,
+  relationLoaderCache
+} from './entity.js';
 import { EntityContext } from './entity-context.js';
 import { ExecutionContext } from './execution-context.js';
 import { HydrationContext } from './hydration-context.js';
+import { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { getEntityMeta } from './entity-meta.js';
+import {
+  loadHasManyRelation,
+  loadHasOneRelation,
+  loadBelongsToRelation,
+  loadBelongsToManyRelation
+} from './lazy-batch.js';
 
 type Row = Record<string, unknown>;
 
-const flattenResults = (results: { columns: string[]; values: unknown[][] }[]): Row[] => {
+const flattenResults = (results: { columns: string[]; values: unknown[][] }[]): Row[] => {
   const rows: Row[] = [];
   for (const result of results) {
     const { columns, values } = result;
@@ -23,8 +36,8 @@ const flattenResults = (results: { columns: string[]; values: unknown[][] }[]):
     }
   }
   return rows;
-};
-
+};
+
 const executeWithContexts = async <TTable extends TableDef>(
   execCtx: ExecutionContext,
   entityCtx: EntityContext,
@@ -34,14 +47,20 @@ const executeWithContexts = async <TTable extends TableDef>(
   const compiled = execCtx.dialect.compileSelect(ast);
   const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   const rows = flattenResults(executed);
+  const lazyRelations = qb.getLazyRelations();
+  const lazyRelationOptions = qb.getLazyRelationOptions();
 
   if (ast.setOps && ast.setOps.length > 0) {
-    return rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+    const proxies = rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+    await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+    return proxies;
   }
-
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
-};
+
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  const entities = hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+  await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+  return entities;
+};
 
 /**
  * Executes a hydrated query using the ORM session.
@@ -50,12 +69,12 @@ const executeWithContexts = async <TTable extends TableDef>(
  * @param qb - The select query builder
  * @returns Promise resolving to array of entity instances
  */
-export async function executeHydrated<TTable extends TableDef>(
-  session: OrmSession,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<EntityInstance<TTable>[]> {
-  return executeWithContexts(session.getExecutionContext(), session, qb);
-}
+export async function executeHydrated<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<unknown, TTable>
+): Promise<EntityInstance<TTable>[]> {
+  return executeWithContexts(session.getExecutionContext(), session, qb);
+}
 
 /**
  * Executes a hydrated query using execution and hydration contexts.
@@ -76,3 +95,51 @@ export async function executeHydratedWithContexts<TTable extends TableDef>(
   }
   return executeWithContexts(execCtx, entityCtx, qb);
 }
+
+const loadLazyRelationsForTable = async <TTable extends TableDef>(
+  ctx: EntityContext,
+  table: TTable,
+  lazyRelations: (keyof RelationMap<TTable>)[],
+  lazyRelationOptions: Map<string, RelationIncludeOptions>
+): Promise<void> => {
+  if (!lazyRelations.length) return;
+
+  const tracked = ctx.getEntitiesForTable(table);
+  if (!tracked.length) return;
+
+  const meta = getEntityMeta(tracked[0].entity);
+  if (!meta) return;
+
+  for (const relationName of lazyRelations) {
+    const relation = table.relations[relationName as string];
+    if (!relation) continue;
+    const key = relationName as string;
+    const options = lazyRelationOptions.get(key);
+    if (!options) {
+      continue;
+    }
+
+    switch (relation.type) {
+      case RelationKinds.HasOne:
+        await relationLoaderCache(meta, key, () =>
+          loadHasOneRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.HasMany:
+        await relationLoaderCache(meta, key, () =>
+          loadHasManyRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.BelongsTo:
+        await relationLoaderCache(meta, key, () =>
+          loadBelongsToRelation(ctx, table, key, relation, options)
+        );
+        break;
+      case RelationKinds.BelongsToMany:
+        await relationLoaderCache(meta, key, () =>
+          loadBelongsToManyRelation(ctx, table, key, relation, options)
+        );
+        break;
+    }
+  }
+};

package/src/orm/hydration-context.ts

@@ -6,11 +6,21 @@ import type { EntityContext } from './entity-context.js';
 import type { AnyDomainEvent, DomainEvent } from './runtime-types.js';
 import type { OrmSession } from './orm-session.js';
 
+/**
+ * Context used during the hydration of entities from database results.
+ * It carries necessary services and processors to handle identity management,
+ * unit of work registration, and relation changes.
+ */
 export interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
+  /** The identity map used to track and reuse entity instances. */
   identityMap: IdentityMap;
+  /** The unit of work used to track changes in hydrated entities. */
   unitOfWork: UnitOfWork;
+  /** The bus used to dispatch domain events during or after hydration. */
   domainEvents: DomainEventBus<E, OrmSession<E>>;
+  /** Processor for handling changes in entity relations during hydration. */
   relationChanges: RelationChangeProcessor;
+  /** Context providing access to entity-specific metadata and services. */
   entityContext: EntityContext;
   // maybe mapping registry, converters, etc.
 }

package/src/orm/identity-map.ts

@@ -1,6 +1,10 @@
 import type { TableDef } from '../schema/table.js';
 import type { TrackedEntity } from './runtime-types.js';
 
+/**
+ * Simple identity map for tracking entities within a session.
+ * Ensures that the same database record is represented by a single entity instance.
+ */
 export class IdentityMap {
   private readonly buckets = new Map<string, Map<string, TrackedEntity>>();
 
@@ -8,11 +12,21 @@ export class IdentityMap {
     return this.buckets;
   }
 
+  /**
+   * Retrieves an entity from the identity map if it exists.
+   * @param table The table definition of the entity.
+   * @param pk The primary key value.
+   * @returns The entity instance if found, undefined otherwise.
+   */
   getEntity(table: TableDef, pk: string | number): unknown | undefined {
     const bucket = this.buckets.get(table.name);
     return bucket?.get(this.toIdentityKey(pk))?.entity;
   }
 
+  /**
+   * Registers a tracked entity in the identity map.
+   * @param tracked The tracked entity metadata and instance.
+   */
   register(tracked: TrackedEntity): void {
     if (tracked.pk == null) return;
     const bucket = this.buckets.get(tracked.table.name) ?? new Map<string, TrackedEntity>();
@@ -26,6 +40,11 @@ export class IdentityMap {
     bucket?.delete(this.toIdentityKey(tracked.pk));
   }
 
+  /**
+   * Returns all tracked entities for a specific table.
+   * @param table The table definition.
+   * @returns Array of tracked entities.
+   */
   getEntitiesForTable(table: TableDef): TrackedEntity[] {
     const bucket = this.buckets.get(table.name);
     return bucket ? Array.from(bucket.values()) : [];

package/src/orm/interceptor-pipeline.ts

@@ -8,6 +8,10 @@ export interface QueryContext {
 
 export type QueryInterceptor = (ctx: QueryContext, next: () => Promise<QueryResult[]>) => Promise<QueryResult[]>;
 
+/**
+ * Pipeline for query interceptors.
+ * Interceptors can wrap query execution to add logging, tracing, caching, etc.
+ */
 export class InterceptorPipeline {
   private interceptors: QueryInterceptor[] = [];