metal-orm 1.0.71 → 1.0.73

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