metal-orm 1.0.71 → 1.0.73

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

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

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,
@@ -5831,6 +5883,10 @@ var instantiateWrapper = (meta, relationName, relation, owner, createEntity) =>
 };
 
 // src/orm/entity.ts
+var isRelationWrapperLoaded = (value) => {
+  if (!value || typeof value !== "object") return false;
+  return Boolean(value.loaded);
+};
 var createEntityProxy = (ctx, table, row, lazyRelations = [], lazyRelationOptions = /* @__PURE__ */ new Map()) => {
   const target = { ...row };
   const meta = {
@@ -5843,6 +5899,19 @@ var createEntityProxy = (ctx, table, row, lazyRelations = [], lazyRelationOption
     relationWrappers: /* @__PURE__ */ new Map()
   };
   const createRelationEntity = (relationTable, relationRow) => createEntityFromRow(meta.ctx, relationTable, relationRow);
+  const buildJson = (self) => {
+    const json = {};
+    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,
@@ -5862,6 +5931,12 @@ var createEntityProxy = (ctx, table, row, lazyRelations = [], lazyRelationOption
           return void 0;
         };
       }
+      if (prop === "toJSON") {
+        if (prop in targetObj) {
+          return Reflect.get(targetObj, prop, receiver);
+        }
+        return () => buildJson(receiver);
+      }
       if (typeof prop === "string" && table.relations[prop]) {
         return getRelationWrapper(meta, prop, receiver, createRelationEntity);
       }
@@ -5895,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 = [];
@@ -5917,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) => {
@@ -6551,6 +6681,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   lazyRelations;
   lazyRelationOptions;
   entityConstructor;
+  includeTree;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6558,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);
@@ -6571,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);
@@ -6587,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,
@@ -6595,7 +6727,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       this.env.deps,
       lazyRelations,
       lazyRelationOptions,
-      this.entityConstructor
+      this.entityConstructor,
+      includeTree
     );
   }
   /**
@@ -6883,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
@@ -6984,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