metal-orm 1.0.71 → 1.0.73

package/package.json

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

package/src/orm/entity-relations.ts

@@ -125,16 +125,16 @@ const instantiateWrapper = <TTable extends TableDef>(
   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);
+  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
+    relationLoaderCache(metaBase, relationName, factory);
+  const resolveOptions = () => meta.lazyRelationOptions.get(relationName);
   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)
-      );
+      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, resolveOptions())
+      );
       return new DefaultHasOneReference(
         meta.ctx,
         metaBase,
@@ -149,10 +149,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     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)
-      );
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, resolveOptions())
+      );
       return new DefaultHasManyCollection(
         meta.ctx,
         metaBase,
@@ -167,10 +167,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     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)
-      );
+      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
+      const loader = () => loadCached(() =>
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, resolveOptions())
+      );
       return new DefaultBelongsToReference(
         meta.ctx,
         metaBase,
@@ -185,10 +185,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     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)
-      );
+      const localKey = many.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, resolveOptions())
+      );
       return new DefaultManyToManyCollection(
         meta.ctx,
         metaBase,

package/src/orm/entity.ts

@@ -7,13 +7,20 @@ import { RelationIncludeOptions } from '../query-builder/relation-types.js';
 import { populateHydrationCache } from './entity-hydration.js';
 import { getRelationWrapper, RelationEntityFactory } from './entity-relations.js';
 
-export { relationLoaderCache } from './entity-relation-cache.js';
-
-/**
- * Creates an entity proxy with lazy loading capabilities.
- * @template TTable - The table type
- * @template TLazy - The lazy relation keys
- * @param ctx - The entity context
+export { relationLoaderCache } from './entity-relation-cache.js';
+
+const isRelationWrapperLoaded = (value: unknown): boolean => {
+  if (!value || typeof value !== 'object') return false;
+  return Boolean((value as { loaded?: boolean }).loaded);
+};
+
+type JsonSource<TTable extends TableDef> = EntityInstance<TTable> & Record<string, unknown>;
+
+/**
+ * Creates an entity proxy with lazy loading capabilities.
+ * @template TTable - The table type
+ * @template TLazy - The lazy relation keys
+ * @param ctx - The entity context
  * @param table - The table definition
  * @param row - The database row
  * @param lazyRelations - Optional lazy relations
@@ -28,26 +35,39 @@ export const createEntityProxy = <
   row: Record<string, unknown>,
   lazyRelations: TLazy[] = [] as TLazy[],
   lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
-): EntityInstance<TTable> => {
-  const target: Record<string, unknown> = { ...row };
-  const meta: EntityMeta<TTable> = {
-    ctx,
-    table,
+): 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()
-  };
-
-  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
-    createEntityFromRow(meta.ctx, relationTable, relationRow);
-
-  Object.defineProperty(target, ENTITY_META, {
-    value: meta,
-    enumerable: false,
-    writable: false
-  });
+    relationHydration: new Map(),
+    relationWrappers: new Map()
+  };
+  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
+    createEntityFromRow(meta.ctx, relationTable, relationRow);
+
+  const buildJson = (self: JsonSource<TTable>): Record<string, unknown> => {
+    const json: Record<string, unknown> = {};
+    for (const key of Object.keys(target)) {
+      json[key] = self[key];
+    }
+    for (const [relationName, wrapper] of meta.relationWrappers) {
+      if (Object.prototype.hasOwnProperty.call(json, relationName)) continue;
+      if (isRelationWrapperLoaded(wrapper)) {
+        json[relationName] = wrapper;
+      }
+    }
+    return json;
+  };
+
+  Object.defineProperty(target, ENTITY_META, {
+    value: meta,
+    enumerable: false,
+    writable: false
+  });
 
   const handler: ProxyHandler<object> = {
     get(targetObj, prop, receiver) {
@@ -55,21 +75,28 @@ export const createEntityProxy = <
         return meta;
       }
 
-      if (prop === '$load') {
-        return async (relationName: RelationKey<TTable>) => {
-          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
-          if (wrapper && typeof wrapper.load === 'function') {
-            return wrapper.load();
-          }
-          return undefined;
-        };
-      }
-
-      if (typeof prop === 'string' && table.relations[prop]) {
-        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
-      }
-
-      return Reflect.get(targetObj, prop, receiver);
+      if (prop === '$load') {
+        return async (relationName: RelationKey<TTable>) => {
+          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
+          if (wrapper && typeof wrapper.load === 'function') {
+            return wrapper.load();
+          }
+          return undefined;
+        };
+      }
+
+      if (prop === 'toJSON') {
+        if (prop in targetObj) {
+          return Reflect.get(targetObj, prop, receiver);
+        }
+        return () => buildJson(receiver as JsonSource<TTable>);
+      }
+
+      if (typeof prop === 'string' && table.relations[prop]) {
+        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
+      }
+
+      return Reflect.get(targetObj, prop, receiver);
     },
 
     set(targetObj, prop, value, receiver) {
@@ -77,14 +104,14 @@ export const createEntityProxy = <
       if (typeof prop === 'string' && table.columns[prop]) {
         ctx.markDirty(receiver);
       }
-      return result;
-    }
-  };
-
-  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
-  populateHydrationCache(proxy, row, meta);
-  return proxy;
-};
+      return result;
+    }
+  };
+
+  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
+  populateHydrationCache(proxy, row, meta);
+  return proxy;
+};
 
 /**
  * Creates an entity instance from a database row.

package/src/orm/execute.ts

@@ -12,8 +12,9 @@ import {
 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, RelationKey } from './entity-meta.js';
+import { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { getEntityMeta, RelationKey } from './entity-meta.js';
+import { preloadRelationIncludes } from './relation-preload.js';
 import {
   loadHasManyRelation,
   loadHasOneRelation,
@@ -44,23 +45,26 @@ const executeWithContexts = async <TTable extends TableDef>(
   qb: SelectQueryBuilder<unknown, TTable>
 ): Promise<EntityInstance<TTable>[]> => {
   const ast = qb.getAST();
-  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() as RelationKey<TTable>[];
-  const lazyRelationOptions = qb.getLazyRelationOptions();
-
-  if (ast.setOps && ast.setOps.length > 0) {
-    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());
-  const entities = hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
-  await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
-  return entities;
-};
+  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() as RelationKey<TTable>[];
+  const lazyRelationOptions = qb.getLazyRelationOptions();
+  const includeTree = qb.getIncludeTree();
+
+  if (ast.setOps && ast.setOps.length > 0) {
+    const proxies = rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+    await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+    await preloadRelationIncludes(proxies as Record<string, unknown>[], includeTree);
+    return proxies;
+  }
+
+  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);
+  await preloadRelationIncludes(entities as Record<string, unknown>[], includeTree);
+  return entities;
+};
 
 const executePlainWithContexts = async <TTable extends TableDef>(
   execCtx: ExecutionContext,

package/src/orm/relation-preload.ts

@@ -0,0 +1,82 @@
+import type { NormalizedRelationIncludeTree } from '../query-builder/relation-include-tree.js';
+import type { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { getEntityMeta } from './entity-meta.js';
+
+type LoadableRelation = {
+  load?: () => Promise<unknown>;
+  getItems?: () => unknown;
+  get?: () => unknown;
+};
+
+const collectEntities = (value: unknown): Record<string, unknown>[] => {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    return value.filter(item => item && typeof item === 'object') as Record<string, unknown>[];
+  }
+  if (typeof value === 'object') {
+    return [value as Record<string, unknown>];
+  }
+  return [];
+};
+
+const loadRelation = async (
+  entity: Record<string, unknown>,
+  relationName: string
+): Promise<Record<string, unknown>[]> => {
+  const wrapper = entity[relationName] as LoadableRelation | undefined;
+  if (!wrapper) return [];
+
+  if (typeof wrapper.load === 'function') {
+    const loaded = await wrapper.load();
+    return collectEntities(loaded);
+  }
+
+  if (typeof wrapper.getItems === 'function') {
+    return collectEntities(wrapper.getItems());
+  }
+
+  if (typeof wrapper.get === 'function') {
+    return collectEntities(wrapper.get());
+  }
+
+  return collectEntities(wrapper);
+};
+
+const setLazyOptionsIfEmpty = (
+  entity: Record<string, unknown>,
+  relationName: string,
+  options?: RelationIncludeOptions
+): void => {
+  if (!options) return;
+  const meta = getEntityMeta(entity);
+  if (!meta || meta.lazyRelationOptions.has(relationName)) return;
+  meta.lazyRelationOptions.set(relationName, options);
+};
+
+export const preloadRelationIncludes = async (
+  entities: Record<string, unknown>[],
+  includeTree: NormalizedRelationIncludeTree,
+  depth = 0
+): Promise<void> => {
+  if (!entities.length) return;
+  const entries = Object.entries(includeTree);
+  if (!entries.length) return;
+
+  for (const [relationName, node] of entries) {
+    const shouldLoad = depth > 0 || Boolean(node.include);
+    if (!shouldLoad) continue;
+
+    for (const entity of entities) {
+      setLazyOptionsIfEmpty(entity, relationName, node.options);
+    }
+
+    const loaded = await Promise.all(
+      entities.map(entity => loadRelation(entity, relationName))
+    );
+    const relatedEntities = loaded.flat();
+
+    if (node.include && relatedEntities.length) {
+      await preloadRelationIncludes(relatedEntities, node.include, depth + 1);
+    }
+  }
+};

package/src/query-builder/relation-include-tree.ts

@@ -0,0 +1,98 @@
+import type { TableDef } from '../schema/table.js';
+import type { RelationDef } from '../schema/relation.js';
+import type { RelationMap, RelationTargetTable } from '../schema/types.js';
+import type { RelationIncludeOptions, TypedRelationIncludeOptions } from './relation-types.js';
+
+export type RelationIncludeInput<TTable extends TableDef> = {
+  [K in keyof RelationMap<TTable> & string]?: true | RelationIncludeNodeInput<TTable['relations'][K]>;
+};
+
+export type RelationIncludeNodeInput<TRel extends RelationDef> =
+  TypedRelationIncludeOptions<TRel> & {
+    include?: RelationIncludeInput<RelationTargetTable<TRel>>;
+  };
+
+export type NormalizedRelationIncludeNode = {
+  options?: RelationIncludeOptions;
+  include?: NormalizedRelationIncludeTree;
+};
+
+export type NormalizedRelationIncludeTree = Record<string, NormalizedRelationIncludeNode>;
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object');
+
+export const normalizeRelationIncludeNode = <TRel extends RelationDef>(
+  value?: true | RelationIncludeNodeInput<TRel>
+): NormalizedRelationIncludeNode => {
+  if (!value || value === true) {
+    return {};
+  }
+
+  if (!isObject(value)) {
+    return {};
+  }
+
+  const { include, ...rest } = value as Record<string, unknown>;
+  const options = Object.keys(rest).length ? (rest as RelationIncludeOptions) : undefined;
+  const normalizedInclude = isObject(include)
+    ? normalizeRelationInclude(include as RelationIncludeInput<TableDef>)
+    : undefined;
+
+  if (normalizedInclude && Object.keys(normalizedInclude).length > 0) {
+    return { options, include: normalizedInclude };
+  }
+
+  return { options };
+};
+
+export const normalizeRelationInclude = (
+  input?: RelationIncludeInput<TableDef>
+): NormalizedRelationIncludeTree => {
+  if (!input) return {};
+
+  const tree: NormalizedRelationIncludeTree = {};
+  for (const [key, value] of Object.entries(input)) {
+    tree[key] = normalizeRelationIncludeNode(value as RelationIncludeNodeInput<RelationDef> | true);
+  }
+  return tree;
+};
+
+export const mergeRelationIncludeTrees = (
+  base: NormalizedRelationIncludeTree,
+  next: NormalizedRelationIncludeTree
+): NormalizedRelationIncludeTree => {
+  const merged: NormalizedRelationIncludeTree = { ...base };
+
+  for (const [key, node] of Object.entries(next)) {
+    const existing = merged[key];
+    if (!existing) {
+      merged[key] = node;
+      continue;
+    }
+
+    const include = existing.include && node.include
+      ? mergeRelationIncludeTrees(existing.include, node.include)
+      : (node.include ?? existing.include);
+
+    merged[key] = {
+      options: node.options ?? existing.options,
+      ...(include ? { include } : {})
+    };
+  }
+
+  return merged;
+};
+
+export const cloneRelationIncludeTree = (
+  tree: NormalizedRelationIncludeTree
+): NormalizedRelationIncludeTree => {
+  const cloned: NormalizedRelationIncludeTree = {};
+  for (const [key, node] of Object.entries(tree)) {
+    cloned[key] = {
+      options: node.options,
+      ...(node.include ? { include: cloneRelationIncludeTree(node.include) } : {})
+    };
+  }
+  return cloned;
+};