metal-orm 1.0.72 → 1.0.74

package/dist/index.d.cts

@@ -2661,6 +2661,18 @@ interface SelectQueryBuilderEnvironment {
     readonly deps: SelectQueryBuilderDependencies;
 }
 
+type RelationIncludeInput<TTable extends TableDef> = {
+    [K in keyof RelationMap<TTable> & string]?: true | RelationIncludeNodeInput<TTable['relations'][K]>;
+};
+type RelationIncludeNodeInput<TRel extends RelationDef> = TypedRelationIncludeOptions<TRel> & {
+    include?: RelationIncludeInput<RelationTargetTable<TRel>>;
+};
+type NormalizedRelationIncludeNode = {
+    options?: RelationIncludeOptions;
+    include?: NormalizedRelationIncludeTree;
+};
+type NormalizedRelationIncludeTree = Record<string, NormalizedRelationIncludeNode>;
+
 type QueryResult = {
     columns: string[];
     values: unknown[][];
@@ -3795,6 +3807,7 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
     private readonly lazyRelations;
     private readonly lazyRelationOptions;
     private readonly entityConstructor?;
+    private readonly includeTree;
     /**
      * Creates a new SelectQueryBuilder instance
      * @param table - Table definition to query
@@ -3802,7 +3815,7 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * @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);
     /**
      * Creates a new SelectQueryBuilder instance with updated context and lazy relations
      * @param context - Updated query context
@@ -4057,8 +4070,11 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      *   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?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
+    include<K extends keyof TTable['relations'] & string>(relationName: K, options?: RelationIncludeNodeInput<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
+    include(relations: RelationIncludeInput<TTable>): SelectQueryBuilder<T, TTable>;
     /**
      * Includes a relation lazily in the query results
      * @param relationName - Name of the relation to include lazily
@@ -4098,6 +4114,10 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * @returns Map of relation names to include options
      */
     getLazyRelationOptions(): Map<string, RelationIncludeOptions>;
+    /**
+     * Gets normalized nested include information for runtime preloading.
+     */
+    getIncludeTree(): NormalizedRelationIncludeTree;
     /**
      * Gets the table definition for this query builder
      * @returns Table definition
@@ -6719,6 +6739,15 @@ declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
 declare const entityRef: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => TableRef$1<EntityTable<TEntity>>;
+type EntityRefsTuple<T extends readonly EntityConstructor<object>[]> = {
+    [K in keyof T]: T[K] extends EntityConstructor<infer TEntity> ? TableRef$1<EntityTable<TEntity & object>> : never;
+};
+/**
+ * Public API: variadic entity references.
+ * Usage:
+ *   const [u, p] = entityRefs(User, Post);
+ */
+declare const entityRefs: <T extends readonly EntityConstructor<object>[]>(...ctors: T) => EntityRefsTuple<T>;
 
 /**
  * Bag for storing decorator metadata during the decoration phase.
@@ -6983,4 +7012,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, entityRefs, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.d.ts

@@ -2661,6 +2661,18 @@ interface SelectQueryBuilderEnvironment {
     readonly deps: SelectQueryBuilderDependencies;
 }
 
+type RelationIncludeInput<TTable extends TableDef> = {
+    [K in keyof RelationMap<TTable> & string]?: true | RelationIncludeNodeInput<TTable['relations'][K]>;
+};
+type RelationIncludeNodeInput<TRel extends RelationDef> = TypedRelationIncludeOptions<TRel> & {
+    include?: RelationIncludeInput<RelationTargetTable<TRel>>;
+};
+type NormalizedRelationIncludeNode = {
+    options?: RelationIncludeOptions;
+    include?: NormalizedRelationIncludeTree;
+};
+type NormalizedRelationIncludeTree = Record<string, NormalizedRelationIncludeNode>;
+
 type QueryResult = {
     columns: string[];
     values: unknown[][];
@@ -3795,6 +3807,7 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
     private readonly lazyRelations;
     private readonly lazyRelationOptions;
     private readonly entityConstructor?;
+    private readonly includeTree;
     /**
      * Creates a new SelectQueryBuilder instance
      * @param table - Table definition to query
@@ -3802,7 +3815,7 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * @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);
     /**
      * Creates a new SelectQueryBuilder instance with updated context and lazy relations
      * @param context - Updated query context
@@ -4057,8 +4070,11 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      *   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?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
+    include<K extends keyof TTable['relations'] & string>(relationName: K, options?: RelationIncludeNodeInput<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
+    include(relations: RelationIncludeInput<TTable>): SelectQueryBuilder<T, TTable>;
     /**
      * Includes a relation lazily in the query results
      * @param relationName - Name of the relation to include lazily
@@ -4098,6 +4114,10 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * @returns Map of relation names to include options
      */
     getLazyRelationOptions(): Map<string, RelationIncludeOptions>;
+    /**
+     * Gets normalized nested include information for runtime preloading.
+     */
+    getIncludeTree(): NormalizedRelationIncludeTree;
     /**
      * Gets the table definition for this query builder
      * @returns Table definition
@@ -6719,6 +6739,15 @@ declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
 declare const entityRef: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => TableRef$1<EntityTable<TEntity>>;
+type EntityRefsTuple<T extends readonly EntityConstructor<object>[]> = {
+    [K in keyof T]: T[K] extends EntityConstructor<infer TEntity> ? TableRef$1<EntityTable<TEntity & object>> : never;
+};
+/**
+ * Public API: variadic entity references.
+ * Usage:
+ *   const [u, p] = entityRefs(User, Post);
+ */
+declare const entityRefs: <T extends readonly EntityConstructor<object>[]>(...ctors: T) => EntityRefsTuple<T>;
 
 /**
  * Bag for storing decorator metadata during the decoration phase.
@@ -6983,4 +7012,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, entityRefs, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.js

@@ -4618,6 +4618,58 @@ var resolveSelectQueryBuilderDependencies = (overrides = {}) => {
 };
 var defaultSelectQueryBuilderDependencies = resolveSelectQueryBuilderDependencies();
 
+// src/query-builder/relation-include-tree.ts
+var isObject = (value) => Boolean(value && typeof value === "object");
+var normalizeRelationIncludeNode = (value) => {
+  if (!value || value === true) {
+    return {};
+  }
+  if (!isObject(value)) {
+    return {};
+  }
+  const { include, ...rest } = value;
+  const options = Object.keys(rest).length ? rest : void 0;
+  const normalizedInclude = isObject(include) ? normalizeRelationInclude(include) : void 0;
+  if (normalizedInclude && Object.keys(normalizedInclude).length > 0) {
+    return { options, include: normalizedInclude };
+  }
+  return { options };
+};
+var normalizeRelationInclude = (input) => {
+  if (!input) return {};
+  const tree = {};
+  for (const [key, value] of Object.entries(input)) {
+    tree[key] = normalizeRelationIncludeNode(value);
+  }
+  return tree;
+};
+var mergeRelationIncludeTrees = (base, next) => {
+  const merged = { ...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;
+};
+var cloneRelationIncludeTree = (tree) => {
+  const cloned = {};
+  for (const [key, node] of Object.entries(tree)) {
+    cloned[key] = {
+      options: node.options,
+      ...node.include ? { include: cloneRelationIncludeTree(node.include) } : {}
+    };
+  }
+  return cloned;
+};
+
 // src/orm/hydration.ts
 var hydrateRows = (rows, plan) => {
   if (!plan || !rows.length) return rows;
@@ -5750,14 +5802,14 @@ var getRelationWrapper = (meta, relationName, owner, createEntity) => {
 };
 var instantiateWrapper = (meta, relationName, relation, owner, createEntity) => {
   const metaBase = meta;
-  const lazyOptions = meta.lazyRelationOptions.get(relationName);
   const loadCached = (factory) => relationLoaderCache(metaBase, relationName, factory);
+  const resolveOptions = () => meta.lazyRelationOptions.get(relationName);
   switch (relation.type) {
     case RelationKinds.HasOne: {
       const hasOne2 = relation;
       const localKey = hasOne2.localKey || findPrimaryKey(meta.table);
       const loader = () => loadCached(
-        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2, lazyOptions)
+        () => loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne2, resolveOptions())
       );
       return new DefaultHasOneReference(
         meta.ctx,
@@ -5775,7 +5827,7 @@ var instantiateWrapper = (meta, relationName, relation, owner, createEntity) =>
       const hasMany2 = relation;
       const localKey = hasMany2.localKey || findPrimaryKey(meta.table);
       const loader = () => loadCached(
-        () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2, lazyOptions)
+        () => loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany2, resolveOptions())
       );
       return new DefaultHasManyCollection(
         meta.ctx,
@@ -5793,7 +5845,7 @@ var instantiateWrapper = (meta, relationName, relation, owner, createEntity) =>
       const belongsTo2 = relation;
       const targetKey = belongsTo2.localKey || findPrimaryKey(belongsTo2.target);
       const loader = () => loadCached(
-        () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2, lazyOptions)
+        () => loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo2, resolveOptions())
       );
       return new DefaultBelongsToReference(
         meta.ctx,
@@ -5811,7 +5863,7 @@ var instantiateWrapper = (meta, relationName, relation, owner, createEntity) =>
       const many = relation;
       const localKey = many.localKey || findPrimaryKey(meta.table);
       const loader = () => loadCached(
-        () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
+        () => loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, resolveOptions())
       );
       return new DefaultManyToManyCollection(
         meta.ctx,
@@ -5918,6 +5970,58 @@ var createEntityFromRow = (ctx, table, row, lazyRelations = [], lazyRelationOpti
   return entity;
 };
 
+// src/orm/relation-preload.ts
+var collectEntities = (value) => {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    return value.filter((item) => item && typeof item === "object");
+  }
+  if (typeof value === "object") {
+    return [value];
+  }
+  return [];
+};
+var loadRelation = async (entity, relationName) => {
+  const wrapper = entity[relationName];
+  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);
+};
+var setLazyOptionsIfEmpty = (entity, relationName, options) => {
+  if (!options) return;
+  const meta = getEntityMeta(entity);
+  if (!meta || meta.lazyRelationOptions.has(relationName)) return;
+  meta.lazyRelationOptions.set(relationName, options);
+};
+var preloadRelationIncludes = async (entities, includeTree, depth = 0) => {
+  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);
+    }
+  }
+};
+
 // src/orm/execute.ts
 var flattenResults = (results) => {
   const rows = [];
@@ -5940,14 +6044,17 @@ var executeWithContexts = async (execCtx, entityCtx, qb) => {
   const rows = flattenResults(executed);
   const lazyRelations = qb.getLazyRelations();
   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, 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, includeTree);
   return entities;
 };
 var executePlainWithContexts = async (execCtx, qb) => {
@@ -6574,6 +6681,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   lazyRelations;
   lazyRelationOptions;
   entityConstructor;
+  includeTree;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6581,7 +6689,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor) {
+  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor, includeTree) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState) => deps.createQueryAstService(table, nextState);
@@ -6594,6 +6702,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     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);
@@ -6610,7 +6719,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  clone(context = this.context, lazyRelations = new Set(this.lazyRelations), lazyRelationOptions = new Map(this.lazyRelationOptions)) {
+  clone(context = this.context, lazyRelations = new Set(this.lazyRelations), lazyRelationOptions = new Map(this.lazyRelationOptions), includeTree = this.includeTree) {
     return new _SelectQueryBuilder(
       this.env.table,
       context.state,
@@ -6618,7 +6727,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       this.env.deps,
       lazyRelations,
       lazyRelationOptions,
-      this.entityConstructor
+      this.entityConstructor,
+      includeTree
     );
   }
   /**
@@ -6906,24 +7016,22 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const nextContext = this.relationFacet.joinRelation(this.context, relationName, joinKind, extraCondition);
     return this.clone(nextContext);
   }
-  /**
-   * Includes related data in the query results
-   * @param relationName - Name of the relationship to include
-   * @param options - Optional include options
-   * @returns New query builder instance with the relationship inclusion
-   * @example
-   * 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(relationName, options) {
-    const nextContext = this.relationFacet.include(this.context, relationName, options);
-    return this.clone(nextContext);
+  include(relationNameOrRelations, options) {
+    if (typeof relationNameOrRelations === "object" && relationNameOrRelations !== null) {
+      const normalized = normalizeRelationInclude(relationNameOrRelations);
+      let nextContext2 = this.context;
+      for (const [relationName2, node] of Object.entries(normalized)) {
+        nextContext2 = this.relationFacet.include(nextContext2, relationName2, node.options);
+      }
+      const nextTree2 = mergeRelationIncludeTrees(this.includeTree, normalized);
+      return this.clone(nextContext2, void 0, void 0, nextTree2);
+    }
+    const relationName = relationNameOrRelations;
+    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, void 0, void 0, nextTree);
   }
   /**
    * Includes a relation lazily in the query results
@@ -7007,6 +7115,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   getLazyRelationOptions() {
     return new Map(this.lazyRelationOptions);
   }
+  /**
+   * Gets normalized nested include information for runtime preloading.
+   */
+  getIncludeTree() {
+    return cloneRelationIncludeTree(this.includeTree);
+  }
   /**
    * Gets the table definition for this query builder
    * @returns Table definition
@@ -7543,6 +7657,9 @@ var entityRef = (ctor) => {
   }
   return tableRef(table);
 };
+var entityRefs = (...ctors) => {
+  return ctors.map((ctor) => entityRef(ctor));
+};
 
 // src/query-builder/select-helpers.ts
 function sel(table, ...cols) {
@@ -12969,6 +13086,7 @@ export {
   div,
   endOfMonth,
   entityRef,
+  entityRefs,
   eq,
   esel,
   executeHydrated,