metal-orm 1.0.43 → 1.0.45

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,