metal-orm 1.0.72 → 1.0.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.72",
+  "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/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;
+};

package/src/query-builder/select.ts

@@ -29,8 +29,17 @@ import {
   SelectQueryBuilderEnvironment
 } from './select-query-builder-deps.js';
 import { ColumnSelector } from './column-selector.js';
-import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
-import { RelationKinds } from '../schema/relation.js';
+import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
+import { RelationKinds } from '../schema/relation.js';
+import {
+  RelationIncludeInput,
+  RelationIncludeNodeInput,
+  NormalizedRelationIncludeTree,
+  cloneRelationIncludeTree,
+  mergeRelationIncludeTrees,
+  normalizeRelationInclude,
+  normalizeRelationIncludeNode
+} from './relation-include-tree.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';
@@ -104,10 +113,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   private readonly predicateFacet: SelectPredicateFacet;
   private readonly cteFacet: SelectCTEFacet;
   private readonly setOpFacet: SelectSetOpFacet;
-  private readonly relationFacet: SelectRelationFacet;
-  private readonly lazyRelations: Set<string>;
-  private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
-  private readonly entityConstructor?: EntityConstructor;
+  private readonly relationFacet: SelectRelationFacet;
+  private readonly lazyRelations: Set<string>;
+  private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
+  private readonly entityConstructor?: EntityConstructor;
+  private readonly includeTree: NormalizedRelationIncludeTree;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -116,15 +126,16 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(
-    table: TTable,
-    state?: SelectQueryState,
-    hydration?: HydrationManager,
-    dependencies?: Partial<SelectQueryBuilderDependencies>,
-    lazyRelations?: Set<string>,
-    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
-    entityConstructor?: EntityConstructor
-  ) {
+  constructor(
+    table: TTable,
+    state?: SelectQueryState,
+    hydration?: HydrationManager,
+    dependencies?: Partial<SelectQueryBuilderDependencies>,
+    lazyRelations?: Set<string>,
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
+    entityConstructor?: EntityConstructor,
+    includeTree?: NormalizedRelationIncludeTree
+  ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState: SelectQueryState) => deps.createQueryAstService(table, nextState);
@@ -134,10 +145,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
       state: initialState,
       hydration: initialHydration
     };
-    this.lazyRelations = new Set(lazyRelations ?? []);
-    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
-    this.entityConstructor = entityConstructor;
-    this.columnSelector = deps.createColumnSelector(this.env);
+    this.lazyRelations = new Set(lazyRelations ?? []);
+    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
+    this.entityConstructor = entityConstructor;
+    this.includeTree = includeTree ?? {};
+    this.columnSelector = deps.createColumnSelector(this.env);
     const relationManager = deps.createRelationManager(this.env);
     this.fromFacet = new SelectFromFacet(this.env, createAstService);
     this.joinFacet = new SelectJoinFacet(this.env, createAstService);
@@ -154,21 +166,23 @@ 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),
+    includeTree = this.includeTree
+  ): SelectQueryBuilder<TNext, TTable> {
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions,
+      this.entityConstructor,
+      includeTree
+    ) as SelectQueryBuilder<TNext, TTable>;
+  }
 
   /**
    * Applies an alias to the root FROM table.
@@ -548,19 +562,42 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * qb.include('posts');
    * @example
    * qb.include('posts', { columns: ['id', 'title', 'published'] });
-   * @example
-   * qb.include('posts', {
-   *   columns: ['id', 'title'],
-   *   where: eq(postTable.columns.published, true)
-   * });
-   */
-  include<K extends keyof TTable['relations'] & string>(
-    relationName: K,
-    options?: TypedRelationIncludeOptions<TTable['relations'][K]>
-  ): SelectQueryBuilder<T, TTable> {
-    const nextContext = this.relationFacet.include(this.context, relationName, options);
-    return this.clone(nextContext);
-  }
+   * @example
+   * qb.include('posts', {
+   *   columns: ['id', 'title'],
+   *   where: eq(postTable.columns.published, true)
+   * });
+   * @example
+   * qb.include({ posts: { include: { author: true } } });
+   */
+  include<K extends keyof TTable['relations'] & string>(
+    relationName: K,
+    options?: RelationIncludeNodeInput<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable>;
+  include(relations: RelationIncludeInput<TTable>): SelectQueryBuilder<T, TTable>;
+  include<K extends keyof TTable['relations'] & string>(
+    relationNameOrRelations: K | RelationIncludeInput<TTable>,
+    options?: RelationIncludeNodeInput<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable> {
+    if (typeof relationNameOrRelations === 'object' && relationNameOrRelations !== null) {
+      const normalized = normalizeRelationInclude(relationNameOrRelations as RelationIncludeInput<TableDef>);
+      let nextContext = this.context;
+      for (const [relationName, node] of Object.entries(normalized)) {
+        nextContext = this.relationFacet.include(nextContext, relationName, node.options);
+      }
+      const nextTree = mergeRelationIncludeTrees(this.includeTree, normalized);
+      return this.clone(nextContext, undefined, undefined, nextTree);
+    }
+
+    const relationName = relationNameOrRelations as string;
+    const normalizedNode = normalizeRelationIncludeNode(options);
+    const nextContext = this.relationFacet.include(this.context, relationName, normalizedNode.options);
+    const shouldStore = Boolean(normalizedNode.include || normalizedNode.options);
+    const nextTree = shouldStore
+      ? mergeRelationIncludeTrees(this.includeTree, { [relationName]: normalizedNode })
+      : this.includeTree;
+    return this.clone(nextContext, undefined, undefined, nextTree);
+  }
 
   /**
    * Includes a relation lazily in the query results
@@ -608,13 +645,13 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @example
    * qb.includePick('posts', ['id', 'title', 'createdAt']);
    */
-  includePick<
-    K extends keyof TTable['relations'] & string,
-    C extends RelationTargetColumns<TTable['relations'][K]>
-  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
-    const options = { columns: cols as readonly C[] } as unknown as TypedRelationIncludeOptions<TTable['relations'][K]>;
-    return this.include(relationName, options);
-  }
+  includePick<
+    K extends keyof TTable['relations'] & string,
+    C extends RelationTargetColumns<TTable['relations'][K]>
+  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
+    const options = { columns: cols as readonly C[] } as unknown as RelationIncludeNodeInput<TTable['relations'][K]>;
+    return this.include(relationName, options);
+  }
 
   /**
    * Selects columns for the root table and relations from an array of entries
@@ -631,13 +668,13 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     let currBuilder: SelectQueryBuilder<T, TTable> = this;
 
     for (const entry of config) {
-      if (entry.type === 'root') {
-        currBuilder = currBuilder.select(...entry.columns);
-      } else {
-        const options = { columns: entry.columns } as unknown as TypedRelationIncludeOptions<TTable['relations'][typeof entry.relationName]>;
-        currBuilder = currBuilder.include(entry.relationName, options);
-      }
-    }
+      if (entry.type === 'root') {
+        currBuilder = currBuilder.select(...entry.columns);
+      } else {
+        const options = { columns: entry.columns } as unknown as RelationIncludeNodeInput<TTable['relations'][typeof entry.relationName]>;
+        currBuilder = currBuilder.include(entry.relationName, options);
+      }
+    }
 
     return currBuilder;
   }
@@ -654,9 +691,16 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * Gets lazy relation include options
    * @returns Map of relation names to include options
    */
-  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
-    return new Map(this.lazyRelationOptions);
-  }
+  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
+    return new Map(this.lazyRelationOptions);
+  }
+
+  /**
+   * Gets normalized nested include information for runtime preloading.
+   */
+  getIncludeTree(): NormalizedRelationIncludeTree {
+    return cloneRelationIncludeTree(this.includeTree);
+  }
 
   /**
    * Gets the table definition for this query builder