metal-orm 1.0.72 → 1.0.74

package/README.md

@@ -549,16 +549,16 @@ const [user] = await selectFromEntity(User)
   .where(eq(U.id, 1))
   .execute(session); // user is an actual instance of the User class!
 
-// Use executePlain() if you want raw POJOs instead of class instances
-const [rawUser] = await selectFromEntity(User).executePlain(session);
-
-user.posts.add({ title: 'From decorators' });
-await session.commit();
-```
-
-Note: relation helpers like `add`/`attach` are only available on tracked entities returned by `execute(session)`. `executePlain()` returns POJOs without relation wrappers. Make sure the primary key (e.g. `id`) is selected so relation adds can link correctly.
-
-Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over. By default, `selectFromEntity` selects all columns if you don't specify any.
+// Use executePlain() if you want raw POJOs instead of class instances
+const [rawUser] = await selectFromEntity(User).executePlain(session);
+
+user.posts.add({ title: 'From decorators' });
+await session.commit();
+```
+
+Note: relation helpers like `add`/`attach` are only available on tracked entities returned by `execute(session)`. `executePlain()` returns POJOs without relation wrappers. Make sure the primary key (e.g. `id`) is selected so relation adds can link correctly.
+
+Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over. By default, `selectFromEntity` selects all columns if you don't specify any.
 
 
 This level is nice when:

package/dist/index.cjs

@@ -144,6 +144,7 @@ __export(index_exports, {
   div: () => div,
   endOfMonth: () => endOfMonth,
   entityRef: () => entityRef,
+  entityRefs: () => entityRefs,
   eq: () => eq,
   esel: () => esel,
   executeHydrated: () => executeHydrated,
@@ -4893,6 +4894,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;
@@ -6025,14 +6078,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,
@@ -6050,7 +6103,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,
@@ -6068,7 +6121,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,
@@ -6086,7 +6139,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,
@@ -6193,6 +6246,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 = [];
@@ -6215,14 +6320,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) => {
@@ -6849,6 +6957,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   lazyRelations;
   lazyRelationOptions;
   entityConstructor;
+  includeTree;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6856,7 +6965,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);
@@ -6869,6 +6978,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);
@@ -6885,7 +6995,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,
@@ -6893,7 +7003,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       this.env.deps,
       lazyRelations,
       lazyRelationOptions,
-      this.entityConstructor
+      this.entityConstructor,
+      includeTree
     );
   }
   /**
@@ -7181,24 +7292,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
@@ -7282,6 +7391,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
@@ -7818,6 +7933,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) {
@@ -13245,6 +13363,7 @@ function createPooledExecutorFactory(opts) {
   div,
   endOfMonth,
   entityRef,
+  entityRefs,
   eq,
   esel,
   executeHydrated,