metal-orm 1.0.57 → 1.0.58

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "metal-orm",
-  "version": "1.0.57",
-  "type": "module",
-  "types": "./dist/index.d.ts",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "bin": {
-    "metal-orm-gen": "./scripts/generate-entities.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "global.d.ts",
-    "scripts"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "check": "tsc --noEmit",
-    "gen:entities": "node scripts/generate-entities.mjs",
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "show-sql": "node scripts/show-sql.mjs",
-    "lint": "node scripts/run-eslint.mjs",
-    "lint:fix": "node scripts/run-eslint.mjs --fix"
-  },
-  "peerDependencies": {
-    "mysql2": "^3.9.0",
-    "pg": "^8.0.0",
-    "sqlite3": "^5.1.6",
-    "tedious": "^16.0.0"
-  },
-  "peerDependenciesMeta": {
-    "mysql2": {
-      "optional": true
-    },
-    "pg": {
-      "optional": true
-    },
-    "sqlite3": {
-      "optional": true
-    },
-    "tedious": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@vitest/ui": "^4.0.14",
-    "@typescript-eslint/eslint-plugin": "^8.20.0",
-    "@typescript-eslint/parser": "^8.20.0",
-    "eslint": "^8.57.0",
-    "eslint-plugin-deprecation": "^3.0.0",
-    "mysql2": "^3.15.3",
-    "pg": "^8.16.3",
-    "sqlite3": "^5.1.7",
-    "tedious": "^19.1.3",
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^4.0.14"
-  }
-}
+{
+  "name": "metal-orm",
+  "version": "1.0.58",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "metal-orm-gen": "./scripts/generate-entities.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "global.d.ts",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit",
+    "gen:entities": "node scripts/generate-entities.mjs",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "show-sql": "node scripts/show-sql.mjs",
+    "lint": "node scripts/run-eslint.mjs",
+    "lint:fix": "node scripts/run-eslint.mjs --fix"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.9.0",
+    "pg": "^8.0.0",
+    "sqlite3": "^5.1.6",
+    "tedious": "^16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    },
+    "tedious": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.0.14",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-deprecation": "^3.0.0",
+    "mysql2": "^3.15.3",
+    "pg": "^8.16.3",
+    "sqlite3": "^5.1.7",
+    "tedious": "^19.1.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.14"
+  }
+}

package/src/decorators/bootstrap.ts

@@ -5,6 +5,10 @@ import {
   belongsTo,
   belongsToMany,
   RelationKinds,
+  type HasManyRelation,
+  type HasOneRelation,
+  type BelongsToRelation,
+  type BelongsToManyRelation,
   type RelationDef
 } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
@@ -20,7 +24,14 @@ import {
 } from '../orm/entity-metadata.js';
 
 import { tableRef, type TableRef } from '../schema/table.js';
-import { SelectableKeys, ColumnDef } from '../schema/types.js';
+import {
+  SelectableKeys,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  BelongsToReference,
+  ManyToManyCollection
+} from '../schema/types.js';
 
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -144,14 +155,39 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
  * @param ctor - The entity constructor.
  * @returns A select query builder for the entity.
  */
+type NonFunctionKeys<T> = {
+  [K in keyof T]-?: T[K] extends (...args: unknown[]) => unknown ? never : K
+}[keyof T];
+
+type RelationKeys<TEntity extends object> =
+  Exclude<NonFunctionKeys<TEntity>, SelectableKeys<TEntity>> & string;
+
+type EntityTable<TEntity extends object> =
+  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
+    relations: {
+      [K in RelationKeys<TEntity>]:
+        NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
+          ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
+          : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget>
+            ? BelongsToManyRelation<EntityTable<NonNullable<TTarget> & object>>
+            : NonNullable<TEntity[K]> extends HasOneReference<infer TChild>
+              ? HasOneRelation<EntityTable<NonNullable<TChild> & object>>
+              : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent>
+                ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>>
+                : NonNullable<TEntity[K]> extends object
+                  ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
+                  : never;
+    };
+  };
+
 export const selectFromEntity = <TEntity extends object>(
   ctor: EntityConstructor<TEntity>
-): SelectQueryBuilder<unknown, TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>> => {
+): SelectQueryBuilder<unknown, EntityTable<TEntity>> => {
   const table = getTableDefFromEntity(ctor);
   if (!table) {
     throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
-  return new SelectQueryBuilder(table as unknown as TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>);
+  return new SelectQueryBuilder(table as unknown as EntityTable<TEntity>);
 };
 
 /**

package/src/orm/entity-meta.ts

@@ -1,4 +1,5 @@
-import { TableDef } from '../schema/table.js';
+import { TableDef } from '../schema/table.js';
+import { RelationIncludeOptions } from '../query-builder/relation-types.js';
 import { EntityContext } from './entity-context.js';
 import { RelationMap } from '../schema/types.js';
 
@@ -18,8 +19,10 @@ export interface EntityMeta<TTable extends TableDef> {
   ctx: EntityContext;
   /** Table definition */
   table: TTable;
-  /** Relations that should be loaded lazily */
-  lazyRelations: (keyof RelationMap<TTable>)[];
+  /** Relations that should be loaded lazily */
+  lazyRelations: (keyof RelationMap<TTable>)[];
+  /** Include options for lazy relations */
+  lazyRelationOptions: Map<string, RelationIncludeOptions>;
   /** Cache for relation promises */
   relationCache: Map<string, Promise<unknown>>;
   /** Hydration data for relations */

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;
+    }
+  }
+};