metal-orm 1.0.72 → 1.0.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.72",
+  "version": "1.0.74",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/decorators/bootstrap.ts

@@ -25,14 +25,14 @@ import {
 
 import { tableRef, type TableRef } from '../schema/table.js';
 import {
-  SelectableKeys,
-  ColumnDef,
-  HasManyCollection,
-  HasOneReference,
-  BelongsToReference,
-  ManyToManyCollection,
-  EntityInstance
-} from '../schema/types.js';
+  SelectableKeys,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  BelongsToReference,
+  ManyToManyCollection,
+  EntityInstance
+} from '../schema/types.js';
 
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -197,9 +197,9 @@ type NonFunctionKeys<T> = {
 type RelationKeys<TEntity extends object> =
   Exclude<NonFunctionKeys<TEntity>, SelectableKeys<TEntity>> & string;
 
-type EntityTable<TEntity extends object> =
-  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
-    relations: {
+type EntityTable<TEntity extends object> =
+  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
+    relations: {
       [K in RelationKeys<TEntity>]:
       NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
       ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
@@ -215,18 +215,18 @@ type EntityTable<TEntity extends object> =
       : NonNullable<TEntity[K]> extends object
       ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
       : never;
-    };
-  };
-
-export type DecoratedEntityInstance<TEntity extends object> =
-  TEntity & EntityInstance<EntityTable<TEntity>>;
-
-export const selectFromEntity = <TEntity extends object>(
-  ctor: EntityConstructor<TEntity>
-): SelectQueryBuilder<DecoratedEntityInstance<TEntity>, EntityTable<TEntity>> => {
-  const table = getTableDefFromEntity(ctor);
-  if (!table) {
-    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+    };
+  };
+
+export type DecoratedEntityInstance<TEntity extends object> =
+  TEntity & EntityInstance<EntityTable<TEntity>>;
+
+export const selectFromEntity = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): SelectQueryBuilder<DecoratedEntityInstance<TEntity>, EntityTable<TEntity>> => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
   return new SelectQueryBuilder(
     table as unknown as EntityTable<TEntity>,
@@ -245,12 +245,29 @@ export const selectFromEntity = <TEntity extends object>(
  * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
-export const entityRef = <TEntity extends object>(
-  ctor: EntityConstructor<TEntity>
-): TableRef<EntityTable<TEntity>> => {
-  const table = getTableDefFromEntity(ctor);
-  if (!table) {
-    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
-  }
-  return tableRef(table as EntityTable<TEntity>);
-};
+export const entityRef = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): TableRef<EntityTable<TEntity>> => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+  }
+  return tableRef(table as EntityTable<TEntity>);
+};
+
+type EntityRefsTuple<T extends readonly EntityConstructor<object>[]> = {
+  [K in keyof T]: T[K] extends EntityConstructor<infer TEntity>
+  ? TableRef<EntityTable<TEntity & object>>
+  : never;
+};
+
+/**
+ * Public API: variadic entity references.
+ * Usage:
+ *   const [u, p] = entityRefs(User, Post);
+ */
+export const entityRefs = <T extends readonly EntityConstructor<object>[]>(
+  ...ctors: T
+): EntityRefsTuple<T> => {
+  return ctors.map(ctor => entityRef(ctor)) as EntityRefsTuple<T>;
+};

package/src/decorators/index.ts

@@ -1,12 +1,12 @@
-/**
- * Decorators for defining entities, columns, and relations in Metal ORM.
- */
-export * from './entity.js';
-export * from './column-decorator.js';
-export * from './relations.js';
-export * from './bootstrap.js';
-export { getDecoratorMetadata } from './decorator-metadata.js';
-
-// Entity Materialization - convert query results to real class instances
-export { materializeAs, DefaultEntityMaterializer, PrototypeMaterializationStrategy, ConstructorMaterializationStrategy } from '../orm/entity-materializer.js';
-export type { EntityMaterializer, EntityMaterializationStrategy } from '../orm/entity-materializer.js';
+/**
+ * Decorators for defining entities, columns, and relations in Metal ORM.
+ */
+export * from './entity.js';
+export * from './column-decorator.js';
+export * from './relations.js';
+export * from './bootstrap.js';
+export { getDecoratorMetadata } from './decorator-metadata.js';
+
+// Entity Materialization - convert query results to real class instances
+export { materializeAs, DefaultEntityMaterializer, PrototypeMaterializationStrategy, ConstructorMaterializationStrategy } from '../orm/entity-materializer.js';
+export type { EntityMaterializer, EntityMaterializationStrategy } from '../orm/entity-materializer.js';

package/src/orm/entity-relations.ts

@@ -125,16 +125,16 @@ const instantiateWrapper = <TTable extends TableDef>(
   createEntity: RelationEntityFactory
 ): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
   const metaBase = meta as unknown as EntityMeta<TableDef>;
-  const lazyOptions = meta.lazyRelationOptions.get(relationName);
-  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
-    relationLoaderCache(metaBase, relationName, factory);
+  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
+    relationLoaderCache(metaBase, relationName, factory);
+  const resolveOptions = () => meta.lazyRelationOptions.get(relationName);
   switch (relation.type) {
     case RelationKinds.HasOne: {
       const hasOne = relation as HasOneRelation;
-      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, lazyOptions)
-      );
+      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, resolveOptions())
+      );
       return new DefaultHasOneReference(
         meta.ctx,
         metaBase,
@@ -149,10 +149,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     case RelationKinds.HasMany: {
       const hasMany = relation as HasManyRelation;
-      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, lazyOptions)
-      );
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, resolveOptions())
+      );
       return new DefaultHasManyCollection(
         meta.ctx,
         metaBase,
@@ -167,10 +167,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     case RelationKinds.BelongsTo: {
       const belongsTo = relation as BelongsToRelation;
-      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
-      const loader = () => loadCached(() =>
-        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, lazyOptions)
-      );
+      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
+      const loader = () => loadCached(() =>
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, resolveOptions())
+      );
       return new DefaultBelongsToReference(
         meta.ctx,
         metaBase,
@@ -185,10 +185,10 @@ const instantiateWrapper = <TTable extends TableDef>(
     }
     case RelationKinds.BelongsToMany: {
       const many = relation as BelongsToManyRelation;
-      const localKey = many.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, lazyOptions)
-      );
+      const localKey = many.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, resolveOptions())
+      );
       return new DefaultManyToManyCollection(
         meta.ctx,
         metaBase,

package/src/orm/execute.ts

@@ -12,8 +12,9 @@ import {
 import { EntityContext } from './entity-context.js';
 import { ExecutionContext } from './execution-context.js';
 import { HydrationContext } from './hydration-context.js';
-import { RelationIncludeOptions } from '../query-builder/relation-types.js';
-import { getEntityMeta, RelationKey } from './entity-meta.js';
+import { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { getEntityMeta, RelationKey } from './entity-meta.js';
+import { preloadRelationIncludes } from './relation-preload.js';
 import {
   loadHasManyRelation,
   loadHasOneRelation,
@@ -44,23 +45,26 @@ const executeWithContexts = async <TTable extends TableDef>(
   qb: SelectQueryBuilder<unknown, TTable>
 ): Promise<EntityInstance<TTable>[]> => {
   const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
-  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const rows = flattenResults(executed);
-  const lazyRelations = qb.getLazyRelations() as RelationKey<TTable>[];
-  const lazyRelationOptions = qb.getLazyRelationOptions();
-
-  if (ast.setOps && ast.setOps.length > 0) {
-    const proxies = rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
-    await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
-    return proxies;
-  }
-
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  const entities = hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
-  await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
-  return entities;
-};
+  const compiled = execCtx.dialect.compileSelect(ast);
+  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const rows = flattenResults(executed);
+  const lazyRelations = qb.getLazyRelations() as RelationKey<TTable>[];
+  const lazyRelationOptions = qb.getLazyRelationOptions();
+  const includeTree = qb.getIncludeTree();
+
+  if (ast.setOps && ast.setOps.length > 0) {
+    const proxies = rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+    await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+    await preloadRelationIncludes(proxies as Record<string, unknown>[], includeTree);
+    return proxies;
+  }
+
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  const entities = hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, lazyRelations, lazyRelationOptions));
+  await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
+  await preloadRelationIncludes(entities as Record<string, unknown>[], includeTree);
+  return entities;
+};
 
 const executePlainWithContexts = async <TTable extends TableDef>(
   execCtx: ExecutionContext,

package/src/orm/relation-preload.ts

@@ -0,0 +1,82 @@
+import type { NormalizedRelationIncludeTree } from '../query-builder/relation-include-tree.js';
+import type { RelationIncludeOptions } from '../query-builder/relation-types.js';
+import { getEntityMeta } from './entity-meta.js';
+
+type LoadableRelation = {
+  load?: () => Promise<unknown>;
+  getItems?: () => unknown;
+  get?: () => unknown;
+};
+
+const collectEntities = (value: unknown): Record<string, unknown>[] => {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    return value.filter(item => item && typeof item === 'object') as Record<string, unknown>[];
+  }
+  if (typeof value === 'object') {
+    return [value as Record<string, unknown>];
+  }
+  return [];
+};
+
+const loadRelation = async (
+  entity: Record<string, unknown>,
+  relationName: string
+): Promise<Record<string, unknown>[]> => {
+  const wrapper = entity[relationName] as LoadableRelation | undefined;
+  if (!wrapper) return [];
+
+  if (typeof wrapper.load === 'function') {
+    const loaded = await wrapper.load();
+    return collectEntities(loaded);
+  }
+
+  if (typeof wrapper.getItems === 'function') {
+    return collectEntities(wrapper.getItems());
+  }
+
+  if (typeof wrapper.get === 'function') {
+    return collectEntities(wrapper.get());
+  }
+
+  return collectEntities(wrapper);
+};
+
+const setLazyOptionsIfEmpty = (
+  entity: Record<string, unknown>,
+  relationName: string,
+  options?: RelationIncludeOptions
+): void => {
+  if (!options) return;
+  const meta = getEntityMeta(entity);
+  if (!meta || meta.lazyRelationOptions.has(relationName)) return;
+  meta.lazyRelationOptions.set(relationName, options);
+};
+
+export const preloadRelationIncludes = async (
+  entities: Record<string, unknown>[],
+  includeTree: NormalizedRelationIncludeTree,
+  depth = 0
+): Promise<void> => {
+  if (!entities.length) return;
+  const entries = Object.entries(includeTree);
+  if (!entries.length) return;
+
+  for (const [relationName, node] of entries) {
+    const shouldLoad = depth > 0 || Boolean(node.include);
+    if (!shouldLoad) continue;
+
+    for (const entity of entities) {
+      setLazyOptionsIfEmpty(entity, relationName, node.options);
+    }
+
+    const loaded = await Promise.all(
+      entities.map(entity => loadRelation(entity, relationName))
+    );
+    const relatedEntities = loaded.flat();
+
+    if (node.include && relatedEntities.length) {
+      await preloadRelationIncludes(relatedEntities, node.include, depth + 1);
+    }
+  }
+};

package/src/query-builder/relation-include-tree.ts

@@ -0,0 +1,98 @@
+import type { TableDef } from '../schema/table.js';
+import type { RelationDef } from '../schema/relation.js';
+import type { RelationMap, RelationTargetTable } from '../schema/types.js';
+import type { RelationIncludeOptions, TypedRelationIncludeOptions } from './relation-types.js';
+
+export type RelationIncludeInput<TTable extends TableDef> = {
+  [K in keyof RelationMap<TTable> & string]?: true | RelationIncludeNodeInput<TTable['relations'][K]>;
+};
+
+export type RelationIncludeNodeInput<TRel extends RelationDef> =
+  TypedRelationIncludeOptions<TRel> & {
+    include?: RelationIncludeInput<RelationTargetTable<TRel>>;
+  };
+
+export type NormalizedRelationIncludeNode = {
+  options?: RelationIncludeOptions;
+  include?: NormalizedRelationIncludeTree;
+};
+
+export type NormalizedRelationIncludeTree = Record<string, NormalizedRelationIncludeNode>;
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object');
+
+export const normalizeRelationIncludeNode = <TRel extends RelationDef>(
+  value?: true | RelationIncludeNodeInput<TRel>
+): NormalizedRelationIncludeNode => {
+  if (!value || value === true) {
+    return {};
+  }
+
+  if (!isObject(value)) {
+    return {};
+  }
+
+  const { include, ...rest } = value as Record<string, unknown>;
+  const options = Object.keys(rest).length ? (rest as RelationIncludeOptions) : undefined;
+  const normalizedInclude = isObject(include)
+    ? normalizeRelationInclude(include as RelationIncludeInput<TableDef>)
+    : undefined;
+
+  if (normalizedInclude && Object.keys(normalizedInclude).length > 0) {
+    return { options, include: normalizedInclude };
+  }
+
+  return { options };
+};
+
+export const normalizeRelationInclude = (
+  input?: RelationIncludeInput<TableDef>
+): NormalizedRelationIncludeTree => {
+  if (!input) return {};
+
+  const tree: NormalizedRelationIncludeTree = {};
+  for (const [key, value] of Object.entries(input)) {
+    tree[key] = normalizeRelationIncludeNode(value as RelationIncludeNodeInput<RelationDef> | true);
+  }
+  return tree;
+};
+
+export const mergeRelationIncludeTrees = (
+  base: NormalizedRelationIncludeTree,
+  next: NormalizedRelationIncludeTree
+): NormalizedRelationIncludeTree => {
+  const merged: NormalizedRelationIncludeTree = { ...base };
+
+  for (const [key, node] of Object.entries(next)) {
+    const existing = merged[key];
+    if (!existing) {
+      merged[key] = node;
+      continue;
+    }
+
+    const include = existing.include && node.include
+      ? mergeRelationIncludeTrees(existing.include, node.include)
+      : (node.include ?? existing.include);
+
+    merged[key] = {
+      options: node.options ?? existing.options,
+      ...(include ? { include } : {})
+    };
+  }
+
+  return merged;
+};
+
+export const cloneRelationIncludeTree = (
+  tree: NormalizedRelationIncludeTree
+): NormalizedRelationIncludeTree => {
+  const cloned: NormalizedRelationIncludeTree = {};
+  for (const [key, node] of Object.entries(tree)) {
+    cloned[key] = {
+      options: node.options,
+      ...(node.include ? { include: cloneRelationIncludeTree(node.include) } : {})
+    };
+  }
+  return cloned;
+};