metal-orm 1.0.40 → 1.0.42

package/src/orm/domain-event-bus.ts

@@ -1,18 +1,44 @@
 import type { DomainEvent, HasDomainEvents, TrackedEntity } from './runtime-types.js';
 
+/**
+ * Extracts domain events of a specific type.
+ * @template E - The domain event type
+ * @template TType - The specific event type
+ */
 type EventOfType<E extends DomainEvent, TType extends E['type']> =
   Extract<E, { type: TType }>;
 
+/**
+ * Domain event handler function.
+ * @template E - The domain event type
+ * @template Context - The context type
+ * @param event - The domain event
+ * @param ctx - The context
+ */
 export type DomainEventHandler<E extends DomainEvent, Context> =
   (event: E, ctx: Context) => Promise<void> | void;
 
+/**
+ * Initial handlers for domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 export type InitialHandlers<E extends DomainEvent, Context> = {
   [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
 };
 
+/**
+ * Domain event bus for managing and dispatching domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 export class DomainEventBus<E extends DomainEvent, Context> {
   private readonly handlers = new Map<E['type'], DomainEventHandler<E, Context>[]>();
 
+  /**
+   * Creates a new DomainEventBus instance.
+   * @param initialHandlers - Optional initial event handlers
+   */
   constructor(initialHandlers?: InitialHandlers<E, Context>) {
     if (initialHandlers) {
       for (const key in initialHandlers) {
@@ -23,6 +49,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     }
   }
 
+  /**
+   * Registers an event handler for a specific event type.
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   on<TType extends E['type']>(
     type: TType,
     handler: DomainEventHandler<EventOfType<E, TType>, Context>
@@ -33,6 +65,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     this.handlers.set(key, existing);
   }
 
+  /**
+   * Registers an event handler for a specific event type (alias for on).
+   * @template TType - The event type
+   * @param type - The event type
+   * @param handler - The event handler
+   */
   register<TType extends E['type']>(
     type: TType,
     handler: DomainEventHandler<EventOfType<E, TType>, Context>
@@ -40,6 +78,11 @@ export class DomainEventBus<E extends DomainEvent, Context> {
     this.on(type, handler);
   }
 
+  /**
+   * Dispatches domain events for tracked entities.
+   * @param trackedEntities - Iterable of tracked entities
+   * @param ctx - The context to pass to handlers
+   */
   async dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void> {
     for (const tracked of trackedEntities) {
       const entity = tracked.entity as HasDomainEvents<E>;
@@ -59,6 +102,12 @@ export class DomainEventBus<E extends DomainEvent, Context> {
   }
 }
 
+/**
+ * Adds a domain event to an entity.
+ * @template E - The domain event type
+ * @param entity - The entity to add the event to
+ * @param event - The domain event to add
+ */
 export const addDomainEvent = <E extends DomainEvent>(
   entity: HasDomainEvents<E>,
   event: E

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,