metal-orm 1.0.39 → 1.0.41

package/src/orm/entity-metadata.ts

@@ -2,8 +2,8 @@ import { ColumnType, ColumnDef } from '../schema/column.js';
 import { defineTable, TableDef, TableHooks } from '../schema/table.js';
 import { CascadeMode, RelationKinds } from '../schema/relation.js';
 
-export type EntityConstructor = new (...args: any[]) => any;
-export type EntityOrTableTarget = EntityConstructor | TableDef;
+export type EntityConstructor<T = object> = new (...args: any[]) => T;
+export type EntityOrTableTarget = EntityConstructor<any> | TableDef;
 export type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
 export type ColumnDefLike<T extends ColumnDef = ColumnDef> = Omit<T, 'name' | 'table'>;
@@ -57,7 +57,7 @@ export type RelationMetadata =
   | BelongsToManyRelationMetadata;
 
 export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> = Record<string, ColumnDefLike>> {
-  target: EntityConstructor;
+  target: EntityConstructor<any>;
   tableName: string;
   columns: TColumns;
   relations: Record<string, RelationMetadata>;
@@ -65,13 +65,13 @@ export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> =
   table?: TableDef<MaterializeColumns<TColumns>>;
 }
 
-const metadataMap = new Map<EntityConstructor, EntityMetadata>();
+const metadataMap = new Map<EntityConstructor<any>, EntityMetadata>();
 
 export const registerEntityMetadata = (meta: EntityMetadata): void => {
   metadataMap.set(meta.target, meta);
 };
 
-export const ensureEntityMetadata = (target: EntityConstructor): EntityMetadata => {
+export const ensureEntityMetadata = (target: EntityConstructor<any>): EntityMetadata => {
   let meta = metadataMap.get(target);
   if (!meta) {
     meta = {
@@ -85,7 +85,7 @@ export const ensureEntityMetadata = (target: EntityConstructor): EntityMetadata
   return meta;
 };
 
-export const getEntityMetadata = (target: EntityConstructor): EntityMetadata | undefined => {
+export const getEntityMetadata = (target: EntityConstructor<any>): EntityMetadata | undefined => {
   return metadataMap.get(target);
 };
 
@@ -98,7 +98,7 @@ export const clearEntityMetadata = (): void => {
 };
 
 export const addColumnMetadata = (
-  target: EntityConstructor,
+  target: EntityConstructor<any>,
   propertyKey: string,
   column: ColumnDefLike
 ): void => {
@@ -107,7 +107,7 @@ export const addColumnMetadata = (
 };
 
 export const addRelationMetadata = (
-  target: EntityConstructor,
+  target: EntityConstructor<any>,
   propertyKey: string,
   relation: RelationMetadata
 ): void => {
@@ -116,7 +116,7 @@ export const addRelationMetadata = (
 };
 
 export const setEntityTableName = (
-  target: EntityConstructor,
+  target: EntityConstructor<any>,
   tableName: string,
   hooks?: TableHooks
 ): void => {

package/src/orm/entity.ts

@@ -10,8 +10,19 @@ import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelati
 import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 
+/**
+ * Type representing an array of database rows.
+ */
 type Rows = Record<string, any>[];
 
+/**
+ * Caches relation loader results across entities of the same type.
+ * @template T - The cache type
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param factory - The factory function to create the cache
+ * @returns Promise with the cached relation data
+ */
 const relationLoaderCache = <T extends Map<string, any>>(
   meta: EntityMeta<any>,
   relationName: string,
@@ -41,6 +52,16 @@ const relationLoaderCache = <T extends Map<string, any>>(
   return promise;
 };
 
+/**
+ * Creates an entity proxy with lazy loading capabilities.
+ * @template TTable - The table type
+ * @template TLazy - The lazy relation keys
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
 export const createEntityProxy = <
   TTable extends TableDef,
   TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>
@@ -104,6 +125,16 @@ export const createEntityProxy = <
   return proxy;
 };
 
+/**
+ * Creates an entity instance from a database row.
+ * @template TTable - The table type
+ * @template TResult - The result type
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
 export const createEntityFromRow = <
   TTable extends TableDef,
   TResult extends EntityInstance<TTable> = EntityInstance<TTable>
@@ -130,8 +161,20 @@ export const createEntityFromRow = <
   return entity as TResult;
 };
 
+/**
+ * Converts a value to a string key.
+ * @param value - The value to convert
+ * @returns String representation of the value
+ */
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
+/**
+ * Populates the hydration cache with relation data from the database row.
+ * @template TTable - The table type
+ * @param entity - The entity instance
+ * @param row - The database row
+ * @param meta - The entity metadata
+ */
 const populateHydrationCache = <TTable extends TableDef>(
   entity: any,
   row: Record<string, any>,
@@ -181,6 +224,13 @@ const populateHydrationCache = <TTable extends TableDef>(
   }
 };
 
+/**
+ * Gets a relation wrapper for an entity.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param owner - The owner entity
+ * @returns The relation wrapper or undefined
+ */
 const getRelationWrapper = (
   meta: EntityMeta<any>,
   relationName: string,
@@ -201,6 +251,14 @@ const getRelationWrapper = (
   return wrapper;
 };
 
+/**
+ * Instantiates the appropriate relation wrapper based on relation type.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param relation - The relation definition
+ * @param owner - The owner entity
+ * @returns The relation wrapper or undefined
+ */
 const instantiateWrapper = (
   meta: EntityMeta<any>,
   relationName: string,