metal-orm 1.0.15 → 1.0.17

package/src/orm/relations/has-many.ts

@@ -1,32 +1,33 @@
 import { HasManyCollection } from '../../schema/types.js';
-import { OrmContext, RelationKey } from '../orm-context.js';
+import { EntityContext } from '../entity-context.js';
+import { RelationKey } from '../runtime-types.js';
 import { HasManyRelation } from '../../schema/relation.js';
 import { TableDef } from '../../schema/table.js';
 import { EntityMeta, getHydrationRows } from '../entity-meta.js';
 
-type Rows = Record<string, any>[];
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-const hideInternal = (obj: any, keys: string[]): void => {
-  for (const key of keys) {
-    Object.defineProperty(obj, key, {
-      value: obj[key],
-      writable: false,
-      configurable: false,
-      enumerable: false
-    });
-  }
-};
-
-export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
-  private loaded = false;
-  private items: TChild[] = [];
-  private readonly added = new Set<TChild>();
-  private readonly removed = new Set<TChild>();
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
+  private loaded = false;
+  private items: TChild[] = [];
+  private readonly added = new Set<TChild>();
+  private readonly removed = new Set<TChild>();
 
   constructor(
-    private readonly ctx: OrmContext,
+    private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<any>,
     private readonly root: any,
     private readonly relationName: string,
@@ -34,14 +35,14 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
     private readonly createEntity: (row: Record<string, any>) => TChild,
-    private readonly localKey: string
-  ) {
-    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
-    this.hydrateFromCache();
-  }
-
-  async load(): Promise<TChild[]> {
-    if (this.loaded) return this.items;
+    private readonly localKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TChild[]> {
+    if (this.loaded) return this.items;
     const map = await this.loader();
     const key = toKey(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
@@ -112,16 +113,16 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return `${this.rootTable.name}.${this.relationName}`;
   }
 
-  private hydrateFromCache(): void {
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) return;
-    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
-    if (!rows?.length) return;
-    this.items = rows.map(row => this.createEntity(row));
-    this.loaded = true;
-  }
-
-  toJSON(): TChild[] {
-    return this.items;
-  }
-}
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
+    this.items = rows.map(row => this.createEntity(row));
+    this.loaded = true;
+  }
+
+  toJSON(): TChild[] {
+    return this.items;
+  }
+}

package/src/orm/relations/has-one.ts

@@ -1,139 +1,140 @@
-import { HasOneReference } from '../../schema/types.js';
-import { OrmContext, RelationKey } from '../orm-context.js';
-import { HasOneRelation } from '../../schema/relation.js';
-import { TableDef } from '../../schema/table.js';
-import { EntityMeta, getHydrationRecord, hasEntityMeta } from '../entity-meta.js';
-
-type Row = Record<string, any>;
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-const hideInternal = (obj: any, keys: string[]): void => {
-  for (const key of keys) {
-    Object.defineProperty(obj, key, {
-      value: obj[key],
-      writable: false,
-      configurable: false,
-      enumerable: false
-    });
-  }
-};
-
-export class DefaultHasOneReference<TChild> implements HasOneReference<TChild> {
-  private loaded = false;
-  private current: TChild | null = null;
-
-  constructor(
-    private readonly ctx: OrmContext,
-    private readonly meta: EntityMeta<any>,
-    private readonly root: any,
-    private readonly relationName: string,
-    private readonly relation: HasOneRelation,
-    private readonly rootTable: TableDef,
-    private readonly loader: () => Promise<Map<string, Row>>,
-    private readonly createEntity: (row: Row) => TChild,
-    private readonly localKey: string
-  ) {
-    hideInternal(this, [
-      'ctx',
-      'meta',
-      'root',
-      'relationName',
-      'relation',
-      'rootTable',
-      'loader',
-      'createEntity',
-      'localKey'
-    ]);
-    this.populateFromHydrationCache();
-  }
-
-  async load(): Promise<TChild | null> {
-    if (this.loaded) return this.current;
-    const map = await this.loader();
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) {
-      this.loaded = true;
-      return this.current;
-    }
-    const row = map.get(toKey(keyValue));
-    this.current = row ? this.createEntity(row) : null;
-    this.loaded = true;
-    return this.current;
-  }
-
-  get(): TChild | null {
-    return this.current;
-  }
-
-  set(data: Partial<TChild> | TChild | null): TChild | null {
-    if (data === null) {
-      return this.detachCurrent();
-    }
-
-    const entity = hasEntityMeta(data) ? (data as TChild) : this.createEntity(data as Row);
-    if (this.current && this.current !== entity) {
-      this.ctx.registerRelationChange(
-        this.root,
-        this.relationKey,
-        this.rootTable,
-        this.relationName,
-        this.relation,
-        { kind: 'remove', entity: this.current }
-      );
-    }
-
-    this.assignForeignKey(entity);
-    this.current = entity;
-    this.loaded = true;
-
-    this.ctx.registerRelationChange(
-      this.root,
-      this.relationKey,
-      this.rootTable,
-      this.relationName,
-      this.relation,
-      { kind: 'attach', entity }
-    );
-
-    return entity;
-  }
-
-  toJSON(): TChild | null {
-    return this.current;
-  }
-
-  private detachCurrent(): TChild | null {
-    const previous = this.current;
-    if (!previous) return null;
-    this.current = null;
-    this.loaded = true;
-    this.ctx.registerRelationChange(
-      this.root,
-      this.relationKey,
-      this.rootTable,
-      this.relationName,
-      this.relation,
-      { kind: 'remove', entity: previous }
-    );
-    return null;
-  }
-
-  private assignForeignKey(entity: TChild): void {
-    const keyValue = this.root[this.localKey];
-    (entity as Row)[this.relation.foreignKey] = keyValue;
-  }
-
-  private get relationKey(): RelationKey {
-    return `${this.rootTable.name}.${this.relationName}`;
-  }
-
-  private populateFromHydrationCache(): void {
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) return;
-    const row = getHydrationRecord(this.meta, this.relationName, keyValue);
-    if (!row) return;
-    this.current = this.createEntity(row);
-    this.loaded = true;
-  }
-}
+import { HasOneReference } from '../../schema/types.js';
+import { EntityContext } from '../entity-context.js';
+import { RelationKey } from '../runtime-types.js';
+import { HasOneRelation } from '../../schema/relation.js';
+import { TableDef } from '../../schema/table.js';
+import { EntityMeta, getHydrationRecord, hasEntityMeta } from '../entity-meta.js';
+
+type Row = Record<string, any>;
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultHasOneReference<TChild> implements HasOneReference<TChild> {
+  private loaded = false;
+  private current: TChild | null = null;
+
+  constructor(
+    private readonly ctx: EntityContext,
+    private readonly meta: EntityMeta<any>,
+    private readonly root: any,
+    private readonly relationName: string,
+    private readonly relation: HasOneRelation,
+    private readonly rootTable: TableDef,
+    private readonly loader: () => Promise<Map<string, Row>>,
+    private readonly createEntity: (row: Row) => TChild,
+    private readonly localKey: string
+  ) {
+    hideInternal(this, [
+      'ctx',
+      'meta',
+      'root',
+      'relationName',
+      'relation',
+      'rootTable',
+      'loader',
+      'createEntity',
+      'localKey'
+    ]);
+    this.populateFromHydrationCache();
+  }
+
+  async load(): Promise<TChild | null> {
+    if (this.loaded) return this.current;
+    const map = await this.loader();
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) {
+      this.loaded = true;
+      return this.current;
+    }
+    const row = map.get(toKey(keyValue));
+    this.current = row ? this.createEntity(row) : null;
+    this.loaded = true;
+    return this.current;
+  }
+
+  get(): TChild | null {
+    return this.current;
+  }
+
+  set(data: Partial<TChild> | TChild | null): TChild | null {
+    if (data === null) {
+      return this.detachCurrent();
+    }
+
+    const entity = hasEntityMeta(data) ? (data as TChild) : this.createEntity(data as Row);
+    if (this.current && this.current !== entity) {
+      this.ctx.registerRelationChange(
+        this.root,
+        this.relationKey,
+        this.rootTable,
+        this.relationName,
+        this.relation,
+        { kind: 'remove', entity: this.current }
+      );
+    }
+
+    this.assignForeignKey(entity);
+    this.current = entity;
+    this.loaded = true;
+
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'attach', entity }
+    );
+
+    return entity;
+  }
+
+  toJSON(): TChild | null {
+    return this.current;
+  }
+
+  private detachCurrent(): TChild | null {
+    const previous = this.current;
+    if (!previous) return null;
+    this.current = null;
+    this.loaded = true;
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'remove', entity: previous }
+    );
+    return null;
+  }
+
+  private assignForeignKey(entity: TChild): void {
+    const keyValue = this.root[this.localKey];
+    (entity as Row)[this.relation.foreignKey] = keyValue;
+  }
+
+  private get relationKey(): RelationKey {
+    return `${this.rootTable.name}.${this.relationName}`;
+  }
+
+  private populateFromHydrationCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const row = getHydrationRecord(this.meta, this.relationName, keyValue);
+    if (!row) return;
+    this.current = this.createEntity(row);
+    this.loaded = true;
+  }
+}

package/src/orm/relations/many-to-many.ts

@@ -1,46 +1,47 @@
 import { ManyToManyCollection } from '../../schema/types.js';
-import { OrmContext, RelationKey } from '../orm-context.js';
+import { EntityContext } from '../entity-context.js';
+import { RelationKey } from '../runtime-types.js';
 import { BelongsToManyRelation } from '../../schema/relation.js';
 import { TableDef } from '../../schema/table.js';
 import { findPrimaryKey } from '../../query-builder/hydration-planner.js';
 import { EntityMeta, getHydrationRows } from '../entity-meta.js';
 
-type Rows = Record<string, any>[];
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-const hideInternal = (obj: any, keys: string[]): void => {
-  for (const key of keys) {
-    Object.defineProperty(obj, key, {
-      value: obj[key],
-      writable: false,
-      configurable: false,
-      enumerable: false
-    });
-  }
-};
-
-export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
-  private loaded = false;
-  private items: TTarget[] = [];
-
-  constructor(
-    private readonly ctx: OrmContext,
+type Rows = Record<string, any>[];
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: any, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
+  private loaded = false;
+  private items: TTarget[] = [];
+
+  constructor(
+    private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<any>,
     private readonly root: any,
     private readonly relationName: string,
     private readonly relation: BelongsToManyRelation,
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
-    private readonly createEntity: (row: Record<string, any>) => TTarget,
-    private readonly localKey: string
-  ) {
-    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
-    this.hydrateFromCache();
-  }
-
-  async load(): Promise<TTarget[]> {
-    if (this.loaded) return this.items;
+    private readonly createEntity: (row: Record<string, any>) => TTarget,
+    private readonly localKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'localKey']);
+    this.hydrateFromCache();
+  }
+
+  async load(): Promise<TTarget[]> {
+    if (this.loaded) return this.items;
     const map = await this.loader();
     const key = toKey(this.root[this.localKey]);
     const rows = map.get(key) ?? [];
@@ -144,22 +145,22 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     return this.relation.targetKey || findPrimaryKey(this.relation.target);
   }
 
-  private hydrateFromCache(): void {
-    const keyValue = this.root[this.localKey];
-    if (keyValue === undefined || keyValue === null) return;
-    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
-    if (!rows?.length) return;
+  private hydrateFromCache(): void {
+    const keyValue = this.root[this.localKey];
+    if (keyValue === undefined || keyValue === null) return;
+    const rows = getHydrationRows(this.meta, this.relationName, keyValue);
+    if (!rows?.length) return;
     this.items = rows.map(row => {
       const entity = this.createEntity(row);
       if ((row as any)._pivot) {
         (entity as any)._pivot = (row as any)._pivot;
       }
-      return entity;
-    });
-    this.loaded = true;
-  }
-
-  toJSON(): TTarget[] {
-    return this.items;
-  }
-}
+      return entity;
+    });
+    this.loaded = true;
+  }
+
+  toJSON(): TTarget[] {
+    return this.items;
+  }
+}

package/src/orm/runtime-types.ts

@@ -1,39 +1,97 @@
 import { RelationDef } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
 
+/**
+ * Entity status enum representing the lifecycle state of an entity
+ */
 export enum EntityStatus {
+  /** Entity is newly created and not yet persisted */
   New = 'new',
+  /** Entity is managed by the ORM and synchronized with the database */
   Managed = 'managed',
+  /** Entity has been modified but not yet persisted */
   Dirty = 'dirty',
+  /** Entity has been marked for removal */
   Removed = 'removed',
+  /** Entity is detached from the ORM context */
   Detached = 'detached'
 }
 
+/**
+ * Represents an entity being tracked by the ORM
+ */
 export interface TrackedEntity {
+  /** The table definition this entity belongs to */
   table: TableDef;
+  /** The actual entity instance */
   entity: any;
+  /** Primary key value of the entity */
   pk: string | number | null;
+  /** Current status of the entity */
   status: EntityStatus;
+  /** Original values of the entity when it was loaded */
   original: Record<string, any> | null;
 }
 
+/**
+ * Type representing a key for relation navigation
+ */
 export type RelationKey = string;
 
+/**
+ * Represents a change operation on a relation
+ * @typeParam T - Type of the related entity
+ */
 export type RelationChange<T> =
   | { kind: 'add'; entity: T }
   | { kind: 'attach'; entity: T }
   | { kind: 'remove'; entity: T }
   | { kind: 'detach'; entity: T };
 
+/**
+ * Represents a relation change entry in the unit of work
+ */
 export interface RelationChangeEntry {
+  /** Root entity that owns the relation */
   root: any;
+  /** Key of the relation being changed */
   relationKey: RelationKey;
+  /** Table definition of the root entity */
   rootTable: TableDef;
+  /** Name of the relation */
   relationName: string;
+  /** Relation definition */
   relation: RelationDef;
+  /** The change being applied */
   change: RelationChange<any>;
 }
 
-export interface HasDomainEvents {
-  domainEvents?: any[];
+/**
+ * Represents a domain event that can be emitted by entities
+ * @typeParam TType - Type of the event (string literal)
+ */
+export interface DomainEvent<TType extends string = string> {
+  /** Type identifier for the event */
+  readonly type: TType;
+  /** Timestamp when the event occurred */
+  readonly occurredAt?: Date;
+}
+
+/**
+ * Type representing any domain event
+ */
+export type AnyDomainEvent = DomainEvent<string>;
+
+/**
+ * Type representing ORM-specific domain events
+ */
+export type OrmDomainEvent = AnyDomainEvent;
+
+/**
+ * Interface for entities that can emit domain events
+ * @typeParam E - Type of domain events this entity can emit
+ */
+export interface HasDomainEvents<E extends DomainEvent = AnyDomainEvent> {
+  /** Array of domain events emitted by this entity */
+  domainEvents?: E[];
 }

package/src/orm/transaction-runner.ts

@@ -1,5 +1,12 @@
 import type { DbExecutor } from '../core/execution/db-executor.js';
 
+/**
+ * Executes a function within a database transaction
+ * @param executor - Database executor to use for transaction operations
+ * @param action - Function to execute within the transaction
+ * @returns Promise that resolves when the transaction is complete
+ * @throws Re-throws any errors that occur during the transaction (after rolling back)
+ */
 export const runInTransaction = async (executor: DbExecutor, action: () => Promise<void>): Promise<void> => {
   if (!executor.beginTransaction) {
     await action();

package/src/orm/unit-of-work.ts

@@ -18,7 +18,7 @@ export class UnitOfWork {
     private readonly executor: DbExecutor,
     private readonly identityMap: IdentityMap,
     private readonly hookContext: () => unknown
-  ) {}
+  ) { }
 
   get identityBuckets(): Map<string, Map<string, TrackedEntity>> {
     return this.identityMap.bucketsMap;
@@ -117,6 +117,11 @@ export class UnitOfWork {
     }
   }
 
+  reset(): void {
+    this.trackedEntities.clear();
+    this.identityMap.clear();
+  }
+
   private async flushInsert(tracked: TrackedEntity): Promise<void> {
     await this.runHook(tracked.table.hooks?.beforeInsert, tracked);
 
@@ -210,6 +215,7 @@ export class UnitOfWork {
   private extractColumns(table: TableDef, entity: any): Record<string, unknown> {
     const payload: Record<string, unknown> = {};
     for (const column of Object.keys(table.columns)) {
+      if (entity[column] === undefined) continue;
       payload[column] = entity[column];
     }
     return payload;