metal-orm 1.0.43 → 1.0.44

package/src/orm/entity-context.ts

@@ -4,21 +4,75 @@ import { TableDef } from '../schema/table.js';
 import { RelationDef } from '../schema/relation.js';
 import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
 
+/**
+ * Interface for entity context providing entity tracking and management.
+ */
 export interface EntityContext {
+    /** The database dialect */
     dialect: Dialect;
+    /** The database executor */
     executor: DbExecutor;
 
+    /**
+     * Gets an entity by table and primary key.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @returns The entity or undefined
+     */
     getEntity(table: TableDef, pk: unknown): unknown;
+
+    /**
+     * Sets an entity in the context.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity to set
+     */
     setEntity(table: TableDef, pk: unknown, entity: unknown): void;
 
+    /**
+     * Tracks a new entity.
+     * @param table - The table definition
+     * @param entity - The new entity
+     * @param pk - Optional primary key
+     */
     trackNew(table: TableDef, entity: unknown, pk?: unknown): void;
+
+    /**
+     * Tracks a managed entity.
+     * @param table - The table definition
+     * @param pk - The primary key
+     * @param entity - The managed entity
+     */
     trackManaged(table: TableDef, pk: unknown, entity: unknown): void;
 
+    /**
+     * Marks an entity as dirty.
+     * @param entity - The entity to mark
+     */
     markDirty(entity: unknown): void;
+
+    /**
+     * Marks an entity as removed.
+     * @param entity - The entity to mark
+     */
     markRemoved(entity: unknown): void;
 
+    /**
+     * Gets all tracked entities for a table.
+     * @param table - The table definition
+     * @returns Array of tracked entities
+     */
     getEntitiesForTable(table: TableDef): TrackedEntity[];
 
+    /**
+     * Registers a relation change.
+     * @param root - The root entity
+     * @param relationKey - The relation key
+     * @param rootTable - The root table definition
+     * @param relationName - The relation name
+     * @param relation - The relation definition
+     * @param change - The relation change
+     */
     registerRelationChange(
         root: unknown,
         relationKey: RelationKey,

package/src/orm/entity-metadata.ts

@@ -2,13 +2,33 @@ import { ColumnDef } from '../schema/column.js';
 import { defineTable, TableDef, TableHooks } from '../schema/table.js';
 import { CascadeMode, RelationKinds } from '../schema/relation.js';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type EntityConstructor<T = object> = new (...args: any[]) => T;
+/**
+ * Constructor type for entities.
+ * Supports any constructor signature for maximum flexibility with decorator-based entities.
+ * @template T - The entity type
+ */
+export type EntityConstructor<T = object> = new (...args: never[]) => T;
+
+/**
+ * Target that can be an entity constructor or table definition.
+ */
 export type EntityOrTableTarget = EntityConstructor | TableDef;
+
+/**
+ * Resolver for entity or table target, can be direct or function.
+ */
 export type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
+/**
+ * Simplified column definition structure used during metadata registration.
+ * @template T - Concrete column definition type being extended
+ */
 export type ColumnDefLike<T extends ColumnDef = ColumnDef> = Omit<T, 'name' | 'table'>;
 
+/**
+ * Transforms simplified column metadata into full ColumnDef objects during table building.
+ * @template TColumns - Mapping of column names to simplified definitions
+ */
 type MaterializeColumns<TColumns extends Record<string, ColumnDefLike>> = {
   [K in keyof TColumns]: ColumnDef<TColumns[K]['type'], TColumns[K]['tsType']> & Omit<
     TColumns[K],
@@ -16,62 +36,119 @@ type MaterializeColumns<TColumns extends Record<string, ColumnDefLike>> = {
   > & { name: string; table: string };
 };
 
+/**
+ * Common properties shared by all relation metadata types.
+ */
 interface BaseRelationMetadata {
+  /** The property key for the relation */
   propertyKey: string;
+  /** The target entity or table */
   target: EntityOrTableTargetResolver;
+  /** Optional cascade mode */
   cascade?: CascadeMode;
 }
 
+/**
+ * Metadata for has many relations.
+ */
 export interface HasManyRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.HasMany;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for has one relations.
+ */
 export interface HasOneRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.HasOne;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for belongs to relations.
+ */
 export interface BelongsToRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.BelongsTo;
+  /** The foreign key */
   foreignKey: string;
+  /** Optional local key */
   localKey?: string;
 }
 
+/**
+ * Metadata for belongs to many relations.
+ */
 export interface BelongsToManyRelationMetadata extends BaseRelationMetadata {
+  /** The relation kind */
   kind: typeof RelationKinds.BelongsToMany;
+  /** The pivot table */
   pivotTable: EntityOrTableTargetResolver;
+  /** The pivot foreign key to root */
   pivotForeignKeyToRoot: string;
+  /** The pivot foreign key to target */
   pivotForeignKeyToTarget: string;
+  /** Optional local key */
   localKey?: string;
+  /** Optional target key */
   targetKey?: string;
+  /** Optional pivot primary key */
   pivotPrimaryKey?: string;
+  /** Optional default pivot columns */
   defaultPivotColumns?: string[];
 }
 
+/**
+ * Union type for all relation metadata.
+ */
 export type RelationMetadata =
   | HasManyRelationMetadata
   | HasOneRelationMetadata
   | BelongsToRelationMetadata
   | BelongsToManyRelationMetadata;
 
+/**
+ * Metadata for entities.
+ * @template TColumns - The columns type
+ */
 export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> = Record<string, ColumnDefLike>> {
+  /** The entity constructor */
   target: EntityConstructor;
+  /** The table name */
   tableName: string;
+  /** The columns */
   columns: TColumns;
+  /** The relations */
   relations: Record<string, RelationMetadata>;
+  /** Optional hooks */
   hooks?: TableHooks;
+  /** Optional table definition */
   table?: TableDef<MaterializeColumns<TColumns>>;
 }
 
 const metadataMap = new Map<EntityConstructor, EntityMetadata>();
 
+/**
+ * Registers entity metadata.
+ * @param meta - The entity metadata to register
+ */
 export const registerEntityMetadata = (meta: EntityMetadata): void => {
   metadataMap.set(meta.target, meta);
 };
 
+/**
+ * Ensures entity metadata exists for the target, creating it if necessary.
+ * @param target - The entity constructor
+ * @returns The entity metadata
+ */
 export const ensureEntityMetadata = (target: EntityConstructor): EntityMetadata => {
   let meta = metadataMap.get(target);
   if (!meta) {
@@ -86,18 +163,36 @@ export const ensureEntityMetadata = (target: EntityConstructor): EntityMetadata
   return meta;
 };
 
+/**
+ * Gets entity metadata for the target.
+ * @param target - The entity constructor
+ * @returns The entity metadata or undefined if not found
+ */
 export const getEntityMetadata = (target: EntityConstructor): EntityMetadata | undefined => {
   return metadataMap.get(target);
 };
 
+/**
+ * Gets all entity metadata.
+ * @returns Array of all entity metadata
+ */
 export const getAllEntityMetadata = (): EntityMetadata[] => {
   return Array.from(metadataMap.values());
 };
 
+/**
+ * Clears all entity metadata.
+ */
 export const clearEntityMetadata = (): void => {
   metadataMap.clear();
 };
 
+/**
+ * Adds column metadata to an entity.
+ * @param target - The entity constructor
+ * @param propertyKey - The property key
+ * @param column - The column definition
+ */
 export const addColumnMetadata = (
   target: EntityConstructor,
   propertyKey: string,
@@ -107,6 +202,12 @@ export const addColumnMetadata = (
   (meta.columns as Record<string, ColumnDefLike>)[propertyKey] = { ...column };
 };
 
+/**
+ * Adds relation metadata to an entity.
+ * @param target - The entity constructor
+ * @param propertyKey - The property key
+ * @param relation - The relation metadata
+ */
 export const addRelationMetadata = (
   target: EntityConstructor,
   propertyKey: string,
@@ -116,6 +217,12 @@ export const addRelationMetadata = (
   meta.relations[propertyKey] = relation;
 };
 
+/**
+ * Sets the table name and hooks for an entity.
+ * @param target - The entity constructor
+ * @param tableName - The table name
+ * @param hooks - Optional table hooks
+ */
 export const setEntityTableName = (
   target: EntityConstructor,
   tableName: string,
@@ -130,22 +237,28 @@ export const setEntityTableName = (
   }
 };
 
+/**
+ * Builds a table definition from entity metadata.
+ * @template TColumns - The columns type
+ * @param meta - The entity metadata
+ * @returns The table definition
+ */
 export const buildTableDef = <TColumns extends Record<string, ColumnDefLike>>(meta: EntityMetadata<TColumns>): TableDef<MaterializeColumns<TColumns>> => {
   if (meta.table) {
     return meta.table;
   }
 
-  const columns = Object.entries(meta.columns).reduce<MaterializeColumns<TColumns>>((acc, [key, def]) => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (acc as any)[key] = {
+  // Build columns using a simpler approach that avoids type assertion
+  const columns: Record<string, ColumnDef> = {};
+  for (const [key, def] of Object.entries(meta.columns)) {
+    columns[key] = {
       ...def,
       name: key,
       table: meta.tableName
-    };
-    return acc;
-  }, {} as MaterializeColumns<TColumns>);
+    } as ColumnDef;
+  }
 
-  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
+  const table = defineTable(meta.tableName, columns as MaterializeColumns<TColumns>, {}, meta.hooks);
   meta.table = table;
   return table;
 };

package/src/orm/execute.ts

@@ -42,6 +42,13 @@ const executeWithEntityContext = async <TTable extends TableDef>(
   return hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
 };
 
+/**
+ * Executes a hydrated query using the ORM session.
+ * @template TTable - The table type
+ * @param session - The ORM session
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of entity instances
+ */
 export async function executeHydrated<TTable extends TableDef>(
   session: OrmSession,
   qb: SelectQueryBuilder<unknown, TTable>
@@ -49,6 +56,14 @@ export async function executeHydrated<TTable extends TableDef>(
   return executeWithEntityContext(session, qb);
 }
 
+/**
+ * Executes a hydrated query using execution and hydration contexts.
+ * @template TTable - The table type
+ * @param _execCtx - The execution context (unused)
+ * @param hydCtx - The hydration context
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of entity instances
+ */
 export async function executeHydratedWithContexts<TTable extends TableDef>(
   _execCtx: ExecutionContext,
   hydCtx: HydrationContext,

package/src/orm/lazy-batch.ts

@@ -9,6 +9,8 @@ import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 
 type Rows = Record<string, unknown>[];
 
+type EntityTracker = ReturnType<EntityContext['getEntitiesForTable']>[number];
+
 const selectAllColumns = (table: TableDef): Record<string, ColumnDef> =>
   Object.entries(table.columns).reduce((acc, [name, def]) => {
     acc[name] = def;
@@ -38,6 +40,57 @@ const executeQuery = async (ctx: EntityContext, qb: SelectQueryBuilder<unknown,
 
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
+const collectKeysFromRoots = (roots: EntityTracker[], key: string): Set<unknown> => {
+  const collected = new Set<unknown>();
+  for (const tracked of roots) {
+    const value = tracked.entity[key];
+    if (value !== null && value !== undefined) {
+      collected.add(value);
+    }
+  }
+  return collected;
+};
+
+const buildInListValues = (keys: Set<unknown>): (string | number | LiteralNode)[] =>
+  Array.from(keys) as (string | number | LiteralNode)[];
+
+const fetchRowsForKeys = async (
+  ctx: EntityContext,
+  table: TableDef,
+  column: ColumnDef,
+  keys: Set<unknown>
+): Promise<Rows> => {
+  const qb = new SelectQueryBuilder(table).select(selectAllColumns(table));
+  qb.where(inList(column, buildInListValues(keys)));
+  return executeQuery(ctx, qb);
+};
+
+const groupRowsByMany = (rows: Rows, keyColumn: string): Map<string, Rows> => {
+  const grouped = new Map<string, Rows>();
+  for (const row of rows) {
+    const value = row[keyColumn];
+    if (value === null || value === undefined) continue;
+    const key = toKey(value);
+    const bucket = grouped.get(key) ?? [];
+    bucket.push(row);
+    grouped.set(key, bucket);
+  }
+  return grouped;
+};
+
+const groupRowsByUnique = (rows: Rows, keyColumn: string): Map<string, Record<string, unknown>> => {
+  const lookup = new Map<string, Record<string, unknown>>();
+  for (const row of rows) {
+    const value = row[keyColumn];
+    if (value === null || value === undefined) continue;
+    const key = toKey(value);
+    if (!lookup.has(key)) {
+      lookup.set(key, row);
+    }
+  }
+  return lookup;
+};
+
 export const loadHasManyRelation = async (
   ctx: EntityContext,
   rootTable: TableDef,
@@ -46,39 +99,17 @@ export const loadHasManyRelation = async (
 ): Promise<Map<string, Rows>> => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[localKey];
-    if (value !== null && value !== undefined) {
-      keys.add(value);
-    }
-  }
+  const keys = collectKeysFromRoots(roots, localKey);
 
   if (!keys.size) {
     return new Map();
   }
 
-  const selectMap = selectAllColumns(relation.target);
-  const fb = new SelectQueryBuilder(relation.target).select(selectMap);
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return new Map();
 
-  fb.where(inList(fkColumn, Array.from(keys) as (string | number | LiteralNode)[]));
-
-  const rows = await executeQuery(ctx, fb);
-  const grouped = new Map<string, Rows>();
-
-  for (const row of rows) {
-    const fkValue = row[relation.foreignKey];
-    if (fkValue === null || fkValue === undefined) continue;
-    const key = toKey(fkValue);
-    const bucket = grouped.get(key) ?? [];
-    bucket.push(row);
-    grouped.set(key, bucket);
-  }
-
-  return grouped;
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
+  return groupRowsByMany(rows, relation.foreignKey);
 };
 
 export const loadHasOneRelation = async (
@@ -89,39 +120,17 @@ export const loadHasOneRelation = async (
 ): Promise<Map<string, Record<string, unknown>>> => {
   const localKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[localKey];
-    if (value !== null && value !== undefined) {
-      keys.add(value);
-    }
-  }
+  const keys = collectKeysFromRoots(roots, localKey);
 
   if (!keys.size) {
     return new Map();
   }
 
-  const selectMap = selectAllColumns(relation.target);
-  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return new Map();
 
-  qb.where(inList(fkColumn, Array.from(keys) as (string | number | LiteralNode)[]));
-
-  const rows = await executeQuery(ctx, qb);
-  const lookup = new Map<string, Record<string, unknown>>();
-
-  for (const row of rows) {
-    const fkValue = row[relation.foreignKey];
-    if (fkValue === null || fkValue === undefined) continue;
-    const key = toKey(fkValue);
-    if (!lookup.has(key)) {
-      lookup.set(key, row);
-    }
-  }
-
-  return lookup;
+  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
+  return groupRowsByUnique(rows, relation.foreignKey);
 };
 
 export const loadBelongsToRelation = async (
@@ -131,36 +140,18 @@ export const loadBelongsToRelation = async (
   relation: BelongsToRelation
 ): Promise<Map<string, Record<string, unknown>>> => {
   const roots = ctx.getEntitiesForTable(rootTable);
-  const foreignKeys = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[relation.foreignKey];
-    if (value !== null && value !== undefined) {
-      foreignKeys.add(value);
-    }
-  }
+  const foreignKeys = collectKeysFromRoots(roots, relation.foreignKey);
 
   if (!foreignKeys.size) {
     return new Map();
   }
 
-  const selectMap = selectAllColumns(relation.target);
-  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
   const targetKey = relation.localKey || findPrimaryKey(relation.target);
   const pkColumn = relation.target.columns[targetKey];
   if (!pkColumn) return new Map();
 
-  qb.where(inList(pkColumn, Array.from(foreignKeys) as (string | number | LiteralNode)[]));
-  const rows = await executeQuery(ctx, qb);
-  const map = new Map<string, Record<string, unknown>>();
-
-  for (const row of rows) {
-    const keyValue = row[targetKey];
-    if (keyValue === null || keyValue === undefined) continue;
-    map.set(toKey(keyValue), row);
-  }
-
-  return map;
+  const rows = await fetchRowsForKeys(ctx, relation.target, pkColumn, foreignKeys);
+  return groupRowsByUnique(rows, targetKey);
 };
 
 export const loadBelongsToManyRelation = async (
@@ -171,27 +162,16 @@ export const loadBelongsToManyRelation = async (
 ): Promise<Map<string, Rows>> => {
   const rootKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
-  const rootIds = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[rootKey];
-    if (value !== null && value !== undefined) {
-      rootIds.add(value);
-    }
-  }
+  const rootIds = collectKeysFromRoots(roots, rootKey);
 
   if (!rootIds.size) {
     return new Map();
   }
 
-  const pivotSelect = selectAllColumns(relation.pivotTable);
-  const pivotQb = new SelectQueryBuilder(relation.pivotTable).select(pivotSelect);
-  const pivotFkCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
-  if (!pivotFkCol) return new Map();
-
-  pivotQb.where(inList(pivotFkCol, Array.from(rootIds) as (string | number | LiteralNode)[]));
-  const pivotRows = await executeQuery(ctx, pivotQb);
+  const pivotColumn = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
+  if (!pivotColumn) return new Map();
 
+  const pivotRows = await fetchRowsForKeys(ctx, relation.pivotTable, pivotColumn, rootIds);
   const rootLookup = new Map<string, { targetId: unknown; pivot: Record<string, unknown> }[]>();
   const targetIds = new Set<unknown>();
 
@@ -214,22 +194,12 @@ export const loadBelongsToManyRelation = async (
     return new Map();
   }
 
-  const targetSelect = selectAllColumns(relation.target);
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const targetPkColumn = relation.target.columns[targetKey];
   if (!targetPkColumn) return new Map();
 
-  const targetQb = new SelectQueryBuilder(relation.target).select(targetSelect);
-  targetQb.where(inList(targetPkColumn, Array.from(targetIds) as (string | number | LiteralNode)[]));
-  const targetRows = await executeQuery(ctx, targetQb);
-  const targetMap = new Map<string, Record<string, unknown>>();
-
-  for (const row of targetRows) {
-    const pkValue = row[targetKey];
-    if (pkValue === null || pkValue === undefined) continue;
-    targetMap.set(toKey(pkValue), row);
-  }
-
+  const targetRows = await fetchRowsForKeys(ctx, relation.target, targetPkColumn, targetIds);
+  const targetMap = groupRowsByUnique(targetRows, targetKey);
   const result = new Map<string, Rows>();
 
   for (const [rootId, entries] of rootLookup.entries()) {