metal-orm 1.1.21 → 1.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.1.21",
+  "version": "1.1.22",
   "type": "module",
   "repository": {
     "type": "git",

package/src/core/ddl/introspect/catalogs/mssql.ts

@@ -17,7 +17,6 @@ export const SysColumns = defineTable(
     user_type_id: col.int()
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -30,7 +29,6 @@ export const SysTables = defineTable(
     is_ms_shipped: col.boolean()
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -41,7 +39,6 @@ export const SysSchemas = defineTable(
     name: col.varchar(255)
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -52,7 +49,6 @@ export const SysTypes = defineTable(
     name: col.varchar(255)
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -69,7 +65,6 @@ export const SysIndexes = defineTable(
     is_hypothetical: col.boolean()
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -82,7 +77,6 @@ export const SysIndexColumns = defineTable(
     key_ordinal: col.int()
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -95,7 +89,6 @@ export const SysForeignKeys = defineTable(
     update_referential_action_desc: col.varchar(64)
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 
@@ -110,7 +103,6 @@ export const SysForeignKeyColumns = defineTable(
     constraint_column_id: col.int()
   },
   {},
-  undefined,
   { schema: 'sys' }
 );
 

package/src/core/ddl/introspect/catalogs/mysql.ts

@@ -12,7 +12,6 @@ export const InformationSchemaTables = defineTable(
     table_comment: col.varchar(1024)
   },
   {},
-  undefined,
   { schema: INFORMATION_SCHEMA }
 );
 
@@ -32,7 +31,6 @@ export const InformationSchemaColumns = defineTable(
     ordinal_position: col.int()
   },
   {},
-  undefined,
   { schema: INFORMATION_SCHEMA }
 );
 
@@ -51,7 +49,6 @@ export const InformationSchemaKeyColumnUsage = defineTable(
     referenced_column_name: col.varchar(255)
   },
   {},
-  undefined,
   { schema: INFORMATION_SCHEMA }
 );
 
@@ -65,7 +62,6 @@ export const InformationSchemaReferentialConstraints = defineTable(
     update_rule: col.varchar(255)
   },
   {},
-  undefined,
   { schema: INFORMATION_SCHEMA }
 );
 
@@ -81,7 +77,6 @@ export const InformationSchemaStatistics = defineTable(
     seq_in_index: col.int()
   },
   {},
-  undefined,
   { schema: INFORMATION_SCHEMA }
 );
 

package/src/core/ddl/introspect/catalogs/postgres.ts

@@ -14,7 +14,6 @@ export const PgInformationSchemaColumns = defineTable(
     ordinal_position: col.int()
   },
   {},
-  undefined,
   { schema: 'information_schema' }
 );
 
@@ -27,7 +26,6 @@ export const PgClass = defineTable(
     relkind: col.varchar(1)
   },
   {},
-  undefined,
   { schema: 'pg_catalog' }
 );
 
@@ -38,7 +36,6 @@ export const PgNamespace = defineTable(
     nspname: col.varchar(255)
   },
   {},
-  undefined,
   { schema: 'pg_catalog' }
 );
 
@@ -52,7 +49,6 @@ export const PgIndex = defineTable(
     indpred: col.varchar(1024)
   },
   {},
-  undefined,
   { schema: 'pg_catalog' }
 );
 
@@ -64,7 +60,6 @@ export const PgAttribute = defineTable(
     attnum: col.int()
   },
   {},
-  undefined,
   { schema: 'pg_catalog' }
 );
 
@@ -80,7 +75,6 @@ export const PgTableConstraints = defineTable(
     constraint_type: col.varchar(255)
   },
   {},
-  undefined,
   { schema: 'information_schema' }
 );
 
@@ -97,7 +91,6 @@ export const PgKeyColumnUsage = defineTable(
     ordinal_position: col.int()
   },
   {},
-  undefined,
   { schema: 'information_schema' }
 );
 
@@ -113,7 +106,6 @@ export const PgConstraintColumnUsage = defineTable(
     column_name: col.varchar(255)
   },
   {},
-  undefined,
   { schema: 'information_schema' }
 );
 
@@ -131,7 +123,6 @@ export const PgReferentialConstraints = defineTable(
     delete_rule: col.varchar(64)
   },
   {},
-  undefined,
   { schema: 'information_schema' }
 );
 

package/src/core/ddl/introspect/catalogs/sqlite.ts

@@ -14,7 +14,6 @@ export const SqliteMaster = defineTable(
     sql: col.varchar(4096)       // Original DDL
   },
   {},
-  undefined,
   { schema: undefined }
 );
 
@@ -26,7 +25,6 @@ export const SqliteSequence = defineTable(
     seq: col.int()           // Last autoincrement value
   },
   {},
-  undefined,
   { schema: undefined }
 );
 
@@ -39,7 +37,6 @@ export const SqliteStat1 = defineTable(
     stat: col.varchar(255)   // Statistics string
   },
   {},
-  undefined,
   { schema: undefined }
 );
 

package/src/decorators/entity.ts

@@ -1,4 +1,3 @@
-import { TableHooks } from '../schema/table.js';
 import { RelationKinds } from '../schema/relation.js';
 import {
   addColumnMetadata,
@@ -15,7 +14,6 @@ import { syncTreeEntityMetadata } from '../tree/tree-decorator.js';
  */
 export interface EntityOptions {
   tableName?: string;
-  hooks?: TableHooks;
   /** Entity type: 'table' (default) or 'view'. Views are read-only. */
   type?: 'table' | 'view';
 }
@@ -42,6 +40,7 @@ const deriveTableNameFromConstructor = (ctor: EntityConstructor<unknown>): strin
 
 /**
  * Class decorator to mark a class as an entity and configure its table mapping.
+ * Runtime lifecycle hooks are registered on OrmSession, not entity metadata.
  * @param options - Configuration options for the entity.
  * @returns A class decorator that registers the entity metadata.
  */
@@ -52,7 +51,7 @@ export function Entity(options: EntityOptions = {}) {
   ): T {
     const ctor = value;
     const tableName = options.tableName ?? deriveTableNameFromConstructor(ctor);
-    setEntityTableName(ctor, tableName, options.hooks, options.type);
+    setEntityTableName(ctor, tableName, options.type);
 
     const bag = context ? readMetadataBag(context) : readMetadataBagFromConstructor(ctor);
     if (bag) {

package/src/index.ts

@@ -38,6 +38,7 @@ export * from './orm/hydration.js';
 export * from './codegen/typescript.js';
 export * from './orm/orm-session.js';
 export * from './orm/orm.js';
+export * from './orm/lifecycle.js';
 export * from './orm/column-introspection.js';
 export * from './orm/entity.js';
 export * from './orm/lazy-batch.js';
@@ -84,4 +85,4 @@ export * from './tree/index.js';
 export * from './cache/index.js';
 
 // Bulk operations module
-export * from './bulk/index.js';
+export * from './bulk/index.js';

package/src/orm/entity-metadata.ts

@@ -1,5 +1,5 @@
 import { ColumnDef } from '../schema/column-types.js';
-import { defineTable, TableDef, TableHooks } from '../schema/table.js';
+import { defineTable, TableDef } from '../schema/table.js';
 import { CascadeMode, RelationKinds } from '../schema/relation.js';
 import type { TransformerMetadata } from '../decorators/transformers/transformer-metadata.js';
 
@@ -153,7 +153,7 @@ export interface MorphManyRelationMetadata {
 }
 
 /**
- * Union type for all relation metadata.
+ * Union type for all relation metadata types.
  */
 export type RelationMetadata =
   | HasManyRelationMetadata
@@ -169,6 +169,7 @@ export type EntityType = 'table' | 'view';
 
 /**
  * Metadata for entities.
+ * Runtime lifecycle hooks intentionally live on OrmSession rather than here.
  * @template TColumns - The columns type
  */
 export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> = Record<string, ColumnDefLike>> {
@@ -184,8 +185,6 @@ export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> =
   relations: Record<string, RelationMetadata>;
   /** The transformers */
   transformers: Record<string, TransformerMetadata>;
-  /** Optional hooks */
-  hooks?: TableHooks;
   /** Optional table definition */
   table?: TableDef<MaterializeColumns<TColumns>>;
 }
@@ -295,25 +294,21 @@ export const addTransformerMetadata = (
 };
 
 /**
- * Sets the table name, hooks, and type for an entity.
+ * Sets the table name and type for an entity.
+ * Lifecycle policy is session-bound and is not persisted in metadata.
  * @param target - The entity constructor
  * @param tableName - The table name
- * @param hooks - Optional table hooks
  * @param type - Entity type: 'table' or 'view'
  */
 export const setEntityTableName = (
   target: EntityConstructor,
   tableName: string,
-  hooks?: TableHooks,
   type?: EntityType
 ): void => {
   const meta = ensureEntityMetadata(target);
   if (tableName && tableName.length > 0) {
     meta.tableName = tableName;
   }
-  if (hooks) {
-    meta.hooks = hooks;
-  }
   if (type) {
     meta.type = type;
   }
@@ -340,7 +335,7 @@ export const buildTableDef = <TColumns extends Record<string, ColumnDefLike>>(me
     } as ColumnDef;
   }
 
-  const table = defineTable(meta.tableName, columns as MaterializeColumns<TColumns>, {}, meta.hooks);
+  const table = defineTable(meta.tableName, columns as MaterializeColumns<TColumns>);
   meta.table = table;
   return table;
 };

package/src/orm/lifecycle.ts

@@ -0,0 +1,20 @@
+import type { TableDef } from '../schema/table.js';
+
+/**
+ * Entity lifecycle hooks executed by the Unit of Work.
+ *
+ * Hooks are runtime/session configuration. They are intentionally not stored on
+ * TableDef so the same mapping can be used by independent sessions with
+ * different lifecycle policies.
+ */
+export interface TableHooks<TEntity = unknown, TContext = unknown> {
+  beforeInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
+}
+
+/** @internal */
+export type TableHookResolver = (table: TableDef) => TableHooks | undefined;

package/src/orm/orm-session.ts

@@ -13,6 +13,7 @@ import type { EntityConstructor } from './entity-metadata.js';
 import { Orm } from './orm.js';
 import { IdentityMap } from './identity-map.js';
 import { UnitOfWork } from './unit-of-work.js';
+import type { TableHooks } from './lifecycle.js';
 import { DomainEventBus, DomainEventHandler, InitialHandlers } from './domain-event-bus.js';
 import { RelationChangeProcessor } from './relation-change-processor.js';
 import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
@@ -38,6 +39,12 @@ const NESTED_TRANSACTIONS_REQUIRE_SAVEPOINTS =
 const ROLLBACK_ONLY_TRANSACTION =
   'Cannot commit transaction because an inner transaction failed';
 
+type LifecycleHookTarget = TableDef | EntityConstructor<object>;
+type LifecycleHookEntity<TTarget extends LifecycleHookTarget> =
+  TTarget extends TableDef ? EntityInstance<TTarget> :
+  TTarget extends EntityConstructor<object> ? InstanceType<TTarget> :
+  never;
+
 /**
  * Interface for ORM interceptors that allow hooking into the flush lifecycle.
  */
@@ -106,6 +113,7 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
   readonly tenantId?: string | number;
 
   private readonly interceptors: OrmInterceptor[];
+  private readonly tableHooks = new WeakMap<TableDef, TableHooks>();
   private saveGraphDefaults?: SaveGraphSessionOptions;
   private transactionDepth = 0;
   private savepointCounter = 0;
@@ -121,7 +129,13 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     this.interceptors = [...(opts.interceptors ?? [])];
 
     this.identityMap = new IdentityMap();
-    this.unitOfWork = new UnitOfWork(this.orm.dialect, this.executor, this.identityMap, () => this);
+    this.unitOfWork = new UnitOfWork(
+      this.orm.dialect,
+      this.executor,
+      this.identityMap,
+      () => this,
+      table => this.tableHooks.get(table)
+    );
     this.relationChanges = new RelationChangeProcessor(this.unitOfWork, this.orm.dialect, this.executor);
     this.domainEvents = new DomainEventBus<E, OrmSession<E>>(opts.domainEventHandlers);
     this.cacheManager = opts.cacheManager;
@@ -250,6 +264,24 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     return this.unitOfWork.getEntitiesForTable(table);
   }
 
+  /**
+   * Registers INSERT/UPDATE/DELETE lifecycle hooks for this Session only.
+   * The target can be a TableDef or a decorated entity constructor.
+   * Registering again for the same table replaces the previous hook set.
+   */
+  registerTableHooks<TTarget extends LifecycleHookTarget>(
+    target: TTarget,
+    hooks: TableHooks<LifecycleHookEntity<TTarget>, OrmSession<E>>
+  ): void {
+    const table = typeof target === 'function'
+      ? getTableDefFromEntity(target as EntityConstructor<object>)
+      : target;
+    if (!table) {
+      throw new Error('Entity metadata has not been bootstrapped');
+    }
+    this.tableHooks.set(table as TableDef, hooks as unknown as TableHooks);
+  }
+
   /**
    * Registers an interceptor for flush lifecycle hooks.
    * @param interceptor - The interceptor to register
@@ -261,7 +293,7 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
   /**
    * Registers a domain event handler.
    * @param type - The event type
-   * @param handler - The event handler
+   * @param handler - The domain event handler
    */
   registerDomainEventHandler<TType extends E['type']>(
     type: TType,
@@ -500,7 +532,9 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
   }
 
   /**
-   * Flushes pending changes to the database without session hooks, relation processing, or domain events.
+   * Flushes pending changes to the database without session interceptors,
+   * relation processing, or domain events. Table lifecycle hooks still run
+   * because they are part of the Unit of Work.
    */
   async flush(): Promise<void> {
     await this.unitOfWork.flush();

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

@@ -5,13 +5,14 @@ import { InsertQueryBuilder } from '../query-builder/insert.js';
 import { UpdateQueryBuilder } from '../query-builder/update.js';
 import { DeleteQueryBuilder } from '../query-builder/delete.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import type { TableDef, TableHooks } from '../schema/table.js';
+import type { TableDef } from '../schema/table.js';
 import { payloadResultSets } from '../core/execution/db-executor.js';
 import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
 import { IdentityMap } from './identity-map.js';
 import { EntityStatus } from './runtime-types.js';
 import type { TrackedEntity } from './runtime-types.js';
 import type { PrimaryKey } from './entity-context.js';
+import type { TableHookResolver, TableHooks } from './lifecycle.js';
 
 /**
  * Unit of Work pattern implementation for tracking entity changes.
@@ -25,12 +26,14 @@ export class UnitOfWork {
    * @param executor - The database executor
    * @param identityMap - The identity map
    * @param hookContext - Function to get the hook context
+   * @param resolveTableHooks - Session/runtime lifecycle hook resolver
    */
   constructor(
     private readonly dialect: Dialect,
     private readonly executor: DbExecutor,
     private readonly identityMap: IdentityMap,
-    private readonly hookContext: () => unknown
+    private readonly hookContext: () => unknown,
+    private readonly resolveTableHooks: TableHookResolver = () => undefined
   ) { }
 
   /**
@@ -195,7 +198,8 @@ export class UnitOfWork {
    * @param tracked - The tracked entity to insert
    */
   private async flushInsert(tracked: TrackedEntity): Promise<void> {
-    await this.runHook(tracked.table.hooks?.beforeInsert, tracked);
+    const hooks = this.resolveTableHooks(tracked.table);
+    await this.runHook(hooks?.beforeInsert, tracked);
 
     const payload = this.extractColumns(tracked.table, tracked.entity as Record<string, unknown>);
     let builder = new InsertQueryBuilder(tracked.table).values(payload as Record<string, ValueOperandInput>);
@@ -212,7 +216,7 @@ export class UnitOfWork {
     tracked.pk = this.getPrimaryKeyValue(tracked);
     this.registerIdentity(tracked);
 
-    await this.runHook(tracked.table.hooks?.afterInsert, tracked);
+    await this.runHook(hooks?.afterInsert, tracked);
   }
 
   /**
@@ -227,7 +231,8 @@ export class UnitOfWork {
       return;
     }
 
-    await this.runHook(tracked.table.hooks?.beforeUpdate, tracked);
+    const hooks = this.resolveTableHooks(tracked.table);
+    await this.runHook(hooks?.beforeUpdate, tracked);
 
     const pkColumn = tracked.table.columns[findPrimaryKey(tracked.table)];
     if (!pkColumn) return;
@@ -248,7 +253,7 @@ export class UnitOfWork {
     tracked.original = this.createSnapshot(tracked.table, tracked.entity as Record<string, unknown>);
     this.registerIdentity(tracked);
 
-    await this.runHook(tracked.table.hooks?.afterUpdate, tracked);
+    await this.runHook(hooks?.afterUpdate, tracked);
   }
 
   /**
@@ -257,7 +262,8 @@ export class UnitOfWork {
    */
   private async flushDelete(tracked: TrackedEntity): Promise<void> {
     if (tracked.pk == null) return;
-    await this.runHook(tracked.table.hooks?.beforeDelete, tracked);
+    const hooks = this.resolveTableHooks(tracked.table);
+    await this.runHook(hooks?.beforeDelete, tracked);
 
     const pkColumn = tracked.table.columns[findPrimaryKey(tracked.table)];
     if (!pkColumn) return;
@@ -270,11 +276,11 @@ export class UnitOfWork {
     this.trackedEntities.delete(tracked.entity);
     this.identityMap.remove(tracked);
 
-    await this.runHook(tracked.table.hooks?.afterDelete, tracked);
+    await this.runHook(hooks?.afterDelete, tracked);
   }
 
   /**
-   * Runs a table hook if defined.
+   * Runs a lifecycle hook if defined.
    * @param hook - The hook function
    * @param tracked - The tracked entity
    */

package/src/schema/table.ts

@@ -36,23 +36,15 @@ export interface TableOptions {
   collation?: string;
 }
 
-export interface TableHooks<TEntity = unknown, TContext = unknown> {
-  beforeInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  beforeUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  beforeDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
-}
-
 /**
- * Definition of a database table with its columns and relationships
+ * Definition of a database table with its columns and relationships.
+ *
+ * Runtime lifecycle policy intentionally does not live here. TableDef is
+ * mapping/schema metadata and can be shared by multiple OrmSession instances.
  * @typeParam T - Type of the columns record
  */
 export interface TableDef<
-  T extends Record<string, ColumnDef> = Record<string, ColumnDef>,
-  TEntity = unknown,
-  TContext = unknown
+  T extends Record<string, ColumnDef> = Record<string, ColumnDef>
 > {
   /** Name of the table */
   name: string;
@@ -62,8 +54,6 @@ export interface TableDef<
   columns: T;
   /** Record of relationship definitions keyed by relation name */
   relations: Record<string, RelationDef>;
-  /** Optional lifecycle hooks */
-  hooks?: TableHooks<TEntity, TContext>;
   /** Composite primary key definition (falls back to column.primary flags) */
   primaryKey?: string[];
   /** Secondary indexes */
@@ -79,11 +69,12 @@ export interface TableDef<
 }
 
 /**
- * Creates a table definition with columns and relationships
+ * Creates a table definition with columns and relationships.
  * @typeParam T - Type of the columns record
  * @param name - Name of the table
- * @param columns - Record of column definitions
+ * @param columns - Record of column definitions keyed by property name
  * @param relations - Record of relationship definitions (optional)
+ * @param options - Schema/table options (optional)
  * @returns Complete table definition with runtime-filled column metadata
  *
  * @example
@@ -95,17 +86,12 @@ export interface TableDef<
  * });
  * ```
  */
-export const defineTable = <
-  T extends Record<string, ColumnDef>,
-  TEntity = unknown,
-  TContext = unknown
->(
+export const defineTable = <T extends Record<string, ColumnDef>>(
   name: string,
   columns: T,
   relations: Record<string, RelationDef> = {},
-  hooks?: TableHooks<TEntity, TContext>,
   options: TableOptions = {}
-): TableDef<T, TEntity, TContext> => {
+): TableDef<T> => {
   // Runtime mutability to assign names to column definitions for convenience
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
     const colDef = { ...def, name: key, table: name };
@@ -118,7 +104,6 @@ export const defineTable = <
     schema: options.schema,
     columns: colsWithNames,
     relations,
-    hooks,
     primaryKey: options.primaryKey,
     indexes: options.indexes,
     checks: options.checks,