metal-orm 1.0.89 → 1.0.91

package/src/orm/orm-session.ts

@@ -18,7 +18,7 @@ import { RelationChangeProcessor } from './relation-change-processor.js';
 import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
 import { ExecutionContext } from './execution-context.js';
 import type { HydrationContext } from './hydration-context.js';
-import type { EntityContext, PrimaryKey } from './entity-context.js';
+import type { EntityContext, PrimaryKey } from './entity-context.js';
 import {
   DomainEvent,
   OrmDomainEvent,
@@ -28,9 +28,9 @@ import {
   TrackedEntity
 } from './runtime-types.js';
 import { executeHydrated } from './execute.js';
-import { runInTransaction } from './transaction-runner.js';
-import { saveGraphInternal, SaveGraphOptions } from './save-graph.js';
-import type { SaveGraphInputPayload } from './save-graph-types.js';
+import { runInTransaction } from './transaction-runner.js';
+import { saveGraphInternal, SaveGraphOptions } from './save-graph.js';
+import type { SaveGraphInputPayload } from './save-graph-types.js';
 
 /**
  * Interface for ORM interceptors that allow hooking into the flush lifecycle.
@@ -53,7 +53,7 @@ export interface OrmInterceptor {
  * Options for creating an OrmSession instance.
  * @template E - The domain event type
  */
-export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
   /** The ORM instance */
   orm: Orm<E>;
   /** The database executor */
@@ -63,21 +63,21 @@ export interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
   /** Optional interceptors for flush lifecycle hooks */
   interceptors?: OrmInterceptor[];
   /** Optional domain event handlers */
-  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
-}
-
-export interface SaveGraphSessionOptions extends SaveGraphOptions {
-  /** Wrap the save operation in a transaction (default: true). */
-  transactional?: boolean;
-  /** Flush after saveGraph when not transactional (default: false). */
-  flush?: boolean;
-}
-
-/**
- * ORM Session that manages entity lifecycle, identity mapping, and database operations.
- * @template E - The domain event type
- */
-export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
+}
+
+export interface SaveGraphSessionOptions extends SaveGraphOptions {
+  /** Wrap the save operation in a transaction (default: true). */
+  transactional?: boolean;
+  /** Flush after saveGraph when not transactional (default: false). */
+  flush?: boolean;
+}
+
+/**
+ * ORM Session that manages entity lifecycle, identity mapping, and database operations.
+ * @template E - The domain event type
+ */
+export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
   /** The ORM instance */
   readonly orm: Orm<E>;
   /** The database executor */
@@ -88,11 +88,11 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
   readonly unitOfWork: UnitOfWork;
   /** The domain event bus */
   readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
-  /** The relation change processor */
-  readonly relationChanges: RelationChangeProcessor;
-
-  private readonly interceptors: OrmInterceptor[];
-  private saveGraphDefaults?: SaveGraphSessionOptions;
+  /** The relation change processor */
+  readonly relationChanges: RelationChangeProcessor;
+
+  private readonly interceptors: OrmInterceptor[];
+  private saveGraphDefaults?: SaveGraphSessionOptions;
 
   /**
    * Creates a new OrmSession instance.
@@ -150,9 +150,9 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param pk - The primary key value
    * @returns The entity or undefined if not found
    */
-  getEntity(table: TableDef, pk: PrimaryKey): object | undefined {
-    return this.unitOfWork.getEntity(table, pk);
-  }
+  getEntity(table: TableDef, pk: PrimaryKey): object | undefined {
+    return this.unitOfWork.getEntity(table, pk);
+  }
 
   /**
    * Sets an entity in the identity map.
@@ -160,9 +160,9 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param pk - The primary key value
    * @param entity - The entity instance
    */
-  setEntity(table: TableDef, pk: PrimaryKey, entity: object): void {
-    this.unitOfWork.setEntity(table, pk, entity);
-  }
+  setEntity(table: TableDef, pk: PrimaryKey, entity: object): void {
+    this.unitOfWork.setEntity(table, pk, entity);
+  }
 
   /**
    * Tracks a new entity.
@@ -170,9 +170,9 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param entity - The entity instance
    * @param pk - Optional primary key value
    */
-  trackNew(table: TableDef, entity: object, pk?: PrimaryKey): void {
-    this.unitOfWork.trackNew(table, entity, pk);
-  }
+  trackNew(table: TableDef, entity: object, pk?: PrimaryKey): void {
+    this.unitOfWork.trackNew(table, entity, pk);
+  }
 
   /**
    * Tracks a managed entity.
@@ -180,25 +180,25 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param pk - The primary key value
    * @param entity - The entity instance
    */
-  trackManaged(table: TableDef, pk: PrimaryKey, entity: object): void {
-    this.unitOfWork.trackManaged(table, pk, entity);
-  }
+  trackManaged(table: TableDef, pk: PrimaryKey, entity: object): void {
+    this.unitOfWork.trackManaged(table, pk, entity);
+  }
 
   /**
    * Marks an entity as dirty (modified).
    * @param entity - The entity to mark as dirty
    */
-  markDirty(entity: object): void {
-    this.unitOfWork.markDirty(entity);
-  }
+  markDirty(entity: object): void {
+    this.unitOfWork.markDirty(entity);
+  }
 
   /**
    * Marks an entity as removed.
    * @param entity - The entity to mark as removed
    */
-  markRemoved(entity: object): void {
-    this.unitOfWork.markRemoved(entity);
-  }
+  markRemoved(entity: object): void {
+    this.unitOfWork.markRemoved(entity);
+  }
 
   /**
    * Registers a relation change.
@@ -244,22 +244,22 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param type - The event type
    * @param handler - The event handler
    */
-  registerDomainEventHandler<TType extends E['type']>(
-    type: TType,
-    handler: DomainEventHandler<Extract<E, { type: TType }>, OrmSession<E>>
-  ): void {
-    this.domainEvents.on(type, handler);
-  }
-
-  /**
-   * Sets default options applied to all saveGraph calls for this session.
-   * Per-call options override these defaults.
-   * @param defaults - Default saveGraph options for the session
-   */
-  withSaveGraphDefaults(defaults: SaveGraphSessionOptions): this {
-    this.saveGraphDefaults = { ...defaults };
-    return this;
-  }
+  registerDomainEventHandler<TType extends E['type']>(
+    type: TType,
+    handler: DomainEventHandler<Extract<E, { type: TType }>, OrmSession<E>>
+  ): void {
+    this.domainEvents.on(type, handler);
+  }
+
+  /**
+   * Sets default options applied to all saveGraph calls for this session.
+   * Per-call options override these defaults.
+   * @param defaults - Default saveGraph options for the session
+   */
+  withSaveGraphDefaults(defaults: SaveGraphSessionOptions): this {
+    this.saveGraphDefaults = { ...defaults };
+    return this;
+  }
 
   /**
    * Finds an entity by its primary key.
@@ -323,85 +323,85 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @param options - Graph save options
    * @returns The root entity instance
    */
-  async saveGraph<TCtor extends EntityConstructor<object>>(
-    entityClass: TCtor,
-    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
-    options?: SaveGraphSessionOptions
-  ): Promise<InstanceType<TCtor>>;
-  async saveGraph<TCtor extends EntityConstructor<object>>(
-    entityClass: TCtor,
-    payload: Record<string, unknown>,
-    options?: SaveGraphSessionOptions
-  ): Promise<InstanceType<TCtor>> {
-    const resolved = this.resolveSaveGraphOptions(options);
-    const { transactional = true, flush = false, ...graphOptions } = resolved;
-    const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
-    if (!transactional) {
-      const result = await execute();
-      if (flush) {
-        await this.flush();
-      }
-      return result;
-    }
-    return this.transaction(() => execute());
-  }
-
-  /**
-   * Saves an entity graph and flushes immediately (defaults to transactional: false).
-   * @param entityClass - Root entity constructor
-   * @param payload - DTO payload containing column values and nested relations
-   * @param options - Graph save options
-   * @returns The root entity instance
-   */
-  async saveGraphAndFlush<TCtor extends EntityConstructor<object>>(
-    entityClass: TCtor,
-    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
-    options?: SaveGraphSessionOptions
-  ): Promise<InstanceType<TCtor>> {
-    const merged = { ...(options ?? {}), flush: true, transactional: options?.transactional ?? false };
-    return this.saveGraph(entityClass, payload, merged);
-  }
-
-  /**
-   * Updates an existing entity graph (requires a primary key in the payload).
-   * @param entityClass - Root entity constructor
-   * @param payload - DTO payload containing column values and nested relations
-   * @param options - Graph save options
-   * @returns The root entity instance or null if not found
-   */
-  async updateGraph<TCtor extends EntityConstructor<object>>(
-    entityClass: TCtor,
-    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
-    options?: SaveGraphSessionOptions
-  ): Promise<InstanceType<TCtor> | null> {
-    const table = getTableDefFromEntity(entityClass);
-    if (!table) {
-      throw new Error('Entity metadata has not been bootstrapped');
-    }
-    const primaryKey = findPrimaryKey(table);
-    const pkValue = (payload as Record<string, unknown>)[primaryKey];
-    if (pkValue === undefined || pkValue === null) {
-      throw new Error(`updateGraph requires a primary key value for "${primaryKey}"`);
-    }
-
-    const resolved = this.resolveSaveGraphOptions(options);
-    const { transactional = true, flush = false, ...graphOptions } = resolved;
-    const execute = async (): Promise<InstanceType<TCtor> | null> => {
-      const tracked = this.getEntity(table, pkValue as PrimaryKey) as InstanceType<TCtor> | undefined;
-      const existing = tracked ?? await this.find(entityClass, pkValue);
-      if (!existing) return null;
-      return saveGraphInternal(this, entityClass, payload, graphOptions);
-    };
-
-    if (!transactional) {
-      const result = await execute();
-      if (result && flush) {
-        await this.flush();
-      }
-      return result;
-    }
-    return this.transaction(() => execute());
-  }
+  async saveGraph<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
+    options?: SaveGraphSessionOptions
+  ): Promise<InstanceType<TCtor>>;
+  async saveGraph<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: Record<string, unknown>,
+    options?: SaveGraphSessionOptions
+  ): Promise<InstanceType<TCtor>> {
+    const resolved = this.resolveSaveGraphOptions(options);
+    const { transactional = true, flush = false, ...graphOptions } = resolved;
+    const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
+    if (!transactional) {
+      const result = await execute();
+      if (flush) {
+        await this.flush();
+      }
+      return result;
+    }
+    return this.transaction(() => execute());
+  }
+
+  /**
+   * Saves an entity graph and flushes immediately (defaults to transactional: false).
+   * @param entityClass - Root entity constructor
+   * @param payload - DTO payload containing column values and nested relations
+   * @param options - Graph save options
+   * @returns The root entity instance
+   */
+  async saveGraphAndFlush<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
+    options?: SaveGraphSessionOptions
+  ): Promise<InstanceType<TCtor>> {
+    const merged = { ...(options ?? {}), flush: true, transactional: options?.transactional ?? false };
+    return this.saveGraph(entityClass, payload, merged);
+  }
+
+  /**
+   * Updates an existing entity graph (requires a primary key in the payload).
+   * @param entityClass - Root entity constructor
+   * @param payload - DTO payload containing column values and nested relations
+   * @param options - Graph save options
+   * @returns The root entity instance or null if not found
+   */
+  async updateGraph<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
+    options?: SaveGraphSessionOptions
+  ): Promise<InstanceType<TCtor> | null> {
+    const table = getTableDefFromEntity(entityClass);
+    if (!table) {
+      throw new Error('Entity metadata has not been bootstrapped');
+    }
+    const primaryKey = findPrimaryKey(table);
+    const pkValue = (payload as Record<string, unknown>)[primaryKey];
+    if (pkValue === undefined || pkValue === null) {
+      throw new Error(`updateGraph requires a primary key value for "${primaryKey}"`);
+    }
+
+    const resolved = this.resolveSaveGraphOptions(options);
+    const { transactional = true, flush = false, ...graphOptions } = resolved;
+    const execute = async (): Promise<InstanceType<TCtor> | null> => {
+      const tracked = this.getEntity(table, pkValue as PrimaryKey) as InstanceType<TCtor> | undefined;
+      const existing = tracked ?? await this.find(entityClass, pkValue);
+      if (!existing) return null;
+      return saveGraphInternal(this, entityClass, payload, graphOptions);
+    };
+
+    if (!transactional) {
+      const result = await execute();
+      if (result && flush) {
+        await this.flush();
+      }
+      return result;
+    }
+    return this.transaction(() => execute());
+  }
 
   /**
    * Persists an entity (either inserts or updates).
@@ -420,7 +420,7 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     const primaryKey = findPrimaryKey(table);
     const pkValue = (entity as Record<string, unknown>)[primaryKey];
     if (pkValue !== undefined && pkValue !== null) {
-      this.trackManaged(table, pkValue as PrimaryKey, entity);
+      this.trackManaged(table, pkValue as PrimaryKey, entity);
     } else {
       this.trackNew(table, entity);
     }
@@ -476,7 +476,7 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * @returns The result of the function
    * @throws If the transaction fails
    */
-  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
+  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
     // If the executor can't do transactions, just run and commit once.
     if (!this.executor.capabilities.transactions) {
       const result = await fn(this);
@@ -524,25 +524,25 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
    * Gets the hydration context.
    * @returns The hydration context
    */
-  getHydrationContext(): HydrationContext<E> {
-    return {
-      identityMap: this.identityMap,
-      unitOfWork: this.unitOfWork,
-      domainEvents: this.domainEvents,
-      relationChanges: this.relationChanges,
-      entityContext: this
-    };
-  }
-
-  /**
-   * Merges session defaults with per-call saveGraph options.
-   * @param options - Per-call saveGraph options
-   * @returns Combined options with per-call values taking precedence
-   */
-  private resolveSaveGraphOptions(options?: SaveGraphSessionOptions): SaveGraphSessionOptions {
-    return { ...(this.saveGraphDefaults ?? {}), ...(options ?? {}) };
-  }
-}
+  getHydrationContext(): HydrationContext<E> {
+    return {
+      identityMap: this.identityMap,
+      unitOfWork: this.unitOfWork,
+      domainEvents: this.domainEvents,
+      relationChanges: this.relationChanges,
+      entityContext: this
+    };
+  }
+
+  /**
+   * Merges session defaults with per-call saveGraph options.
+   * @param options - Per-call saveGraph options
+   * @returns Combined options with per-call values taking precedence
+   */
+  private resolveSaveGraphOptions(options?: SaveGraphSessionOptions): SaveGraphSessionOptions {
+    return { ...(this.saveGraphDefaults ?? {}), ...(options ?? {}) };
+  }
+}
 
 const buildRelationChangeEntry = (
   root: unknown,

package/src/orm/relation-change-processor.ts

@@ -78,7 +78,7 @@ export class RelationChangeProcessor {
     const target = entry.change.entity;
     if (!target) return;
 
-    const tracked = this.unitOfWork.findTracked(target as object);
+    const tracked = this.unitOfWork.findTracked(target as object);
     if (!tracked) return;
 
     const localKey = relation.localKey || findPrimaryKey(entry.rootTable);
@@ -105,7 +105,7 @@ export class RelationChangeProcessor {
     const target = entry.change.entity;
     if (!target) return;
 
-    const tracked = this.unitOfWork.findTracked(target as object);
+    const tracked = this.unitOfWork.findTracked(target as object);
     if (!tracked) return;
 
     const localKey = relation.localKey || findPrimaryKey(entry.rootTable);
@@ -154,7 +154,7 @@ export class RelationChangeProcessor {
       await this.deletePivotRow(relation, rootId, targetId);
 
       if (relation.cascade === 'all' || relation.cascade === 'remove') {
-        this.unitOfWork.markRemoved(entry.change.entity as object);
+        this.unitOfWork.markRemoved(entry.change.entity as object);
       }
     }
   }

package/src/orm/runtime-types.ts

@@ -20,11 +20,11 @@ export enum EntityStatus {
 /**
  * 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: object;
+export interface TrackedEntity {
+  /** The table definition this entity belongs to */
+  table: TableDef;
+  /** The actual entity instance */
+  entity: object;
   /** Primary key value of the entity */
   pk: string | number | null;
   /** Current status of the entity */

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

@@ -198,13 +198,12 @@ export class UnitOfWork {
 
     const payload = this.extractColumns(tracked.table, tracked.entity as Record<string, unknown>);
     let builder = new InsertQueryBuilder(tracked.table).values(payload as Record<string, ValueOperandInput>);
-    if (this.dialect.supportsReturning()) {
-      builder = builder.returning(...this.getReturningColumns(tracked.table));
-    }
-    const compiled = builder.compile(this.dialect);
-    const results = await this.executeCompiled(compiled);
-    this.applyReturningResults(tracked, results);
-    this.applyInsertId(tracked, results);
+    if (this.dialect.supportsReturning()) {
+      builder = builder.returning(...this.getReturningColumns(tracked.table));
+    }
+    const compiled = builder.compile(this.dialect);
+    const results = await this.executeCompiled(compiled);
+    this.applyReturningResults(tracked, results);
 
     tracked.status = EntityStatus.Managed;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity as Record<string, unknown>);
@@ -345,29 +344,18 @@ export class UnitOfWork {
    * @param tracked - The tracked entity
    * @param results - Query results
    */
-  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
-    if (!this.dialect.supportsReturning()) return;
-    const first = results[0];
-    if (!first || first.values.length === 0) return;
+  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
+    if (!this.dialect.supportsReturning()) return;
+    const first = results[0];
+    if (!first || first.values.length === 0) return;
 
     const row = first.values[0];
     for (let i = 0; i < first.columns.length; i++) {
       const columnName = this.normalizeColumnName(first.columns[i]);
       if (!(columnName in tracked.table.columns)) continue;
-      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
-    }
-  }
-
-  private applyInsertId(tracked: TrackedEntity, results: QueryResult[]): void {
-    if (this.dialect.supportsReturning()) return;
-    if (tracked.pk != null) return;
-    const pkName = findPrimaryKey(tracked.table);
-    const pkColumn = tracked.table.columns[pkName];
-    if (!pkColumn?.autoIncrement) return;
-    const insertId = results.find(result => typeof result.insertId === 'number')?.insertId;
-    if (insertId == null) return;
-    (tracked.entity as Record<string, unknown>)[pkName] = insertId;
-  }
+      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
+    }
+  }
 
   /**
    * Normalizes a column name by removing quotes and table prefixes.