metal-orm 1.0.14 → 1.0.16

package/src/orm/orm-session.ts

@@ -0,0 +1,234 @@
+import { Dialect } from '../core/dialect/abstract.js';
+import { eq } from '../core/ast/expression.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import type { TableDef } from '../schema/table.js';
+import { Entity } from '../schema/types.js';
+import { RelationDef } from '../schema/relation.js';
+
+import { selectFromEntity, getTableDefFromEntity } from '../decorators/bootstrap.js';
+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 { DomainEventBus, DomainEventHandler } from './domain-event-bus.js';
+import { RelationChangeProcessor } from './relation-change-processor.js';
+import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
+import { ExecutionContext } from './execution-context.js';
+import { HydrationContext } from './hydration-context.js';
+import { EntityContext } from './entity-context.js';
+import {
+  RelationChange,
+  RelationChangeEntry,
+  RelationKey,
+  TrackedEntity
+} from './runtime-types.js';
+import { executeHydrated } from './execute.js';
+import { runInTransaction } from './transaction-runner.js';
+
+export interface OrmInterceptor {
+  beforeFlush?(ctx: EntityContext): Promise<void> | void;
+  afterFlush?(ctx: EntityContext): Promise<void> | void;
+}
+
+export interface OrmSessionOptions {
+  orm: Orm;
+  executor: DbExecutor;
+  queryLogger?: QueryLogger;
+  interceptors?: OrmInterceptor[];
+  domainEventHandlers?: Record<string, DomainEventHandler<OrmSession>[]>;
+}
+
+export class OrmSession implements EntityContext {
+  readonly orm: Orm;
+  readonly executor: DbExecutor;
+  readonly identityMap: IdentityMap;
+  readonly unitOfWork: UnitOfWork;
+  readonly domainEvents: DomainEventBus<OrmSession>;
+  readonly relationChanges: RelationChangeProcessor;
+
+  private readonly interceptors: OrmInterceptor[];
+
+  constructor(opts: OrmSessionOptions) {
+    this.orm = opts.orm;
+    this.executor = createQueryLoggingExecutor(opts.executor, opts.queryLogger);
+    this.interceptors = [...(opts.interceptors ?? [])];
+
+    this.identityMap = new IdentityMap();
+    this.unitOfWork = new UnitOfWork(this.orm.dialect, this.executor, this.identityMap, () => this);
+    this.relationChanges = new RelationChangeProcessor(this.unitOfWork, this.orm.dialect, this.executor);
+    this.domainEvents = new DomainEventBus<OrmSession>(opts.domainEventHandlers);
+  }
+
+  get dialect(): Dialect {
+    return this.orm.dialect;
+  }
+
+  get identityBuckets(): Map<string, Map<string, TrackedEntity>> {
+    return this.unitOfWork.identityBuckets;
+  }
+
+  get tracked(): TrackedEntity[] {
+    return this.unitOfWork.getTracked();
+  }
+
+  getEntity(table: TableDef, pk: any): any | undefined {
+    return this.unitOfWork.getEntity(table, pk);
+  }
+
+  setEntity(table: TableDef, pk: any, entity: any): void {
+    this.unitOfWork.setEntity(table, pk, entity);
+  }
+
+  trackNew(table: TableDef, entity: any, pk?: any): void {
+    this.unitOfWork.trackNew(table, entity, pk);
+  }
+
+  trackManaged(table: TableDef, pk: any, entity: any): void {
+    this.unitOfWork.trackManaged(table, pk, entity);
+  }
+
+  markDirty(entity: any): void {
+    this.unitOfWork.markDirty(entity);
+  }
+
+  markRemoved(entity: any): void {
+    this.unitOfWork.markRemoved(entity);
+  }
+
+  registerRelationChange = (
+    root: any,
+    relationKey: RelationKey,
+    rootTable: TableDef,
+    relationName: string,
+    relation: RelationDef,
+    change: RelationChange<any>
+  ): void => {
+    this.relationChanges.registerChange(
+      buildRelationChangeEntry(root, relationKey, rootTable, relationName, relation, change)
+    );
+  };
+
+  getEntitiesForTable(table: TableDef): TrackedEntity[] {
+    return this.unitOfWork.getEntitiesForTable(table);
+  }
+
+  registerInterceptor(interceptor: OrmInterceptor): void {
+    this.interceptors.push(interceptor);
+  }
+
+  registerDomainEventHandler(name: string, handler: DomainEventHandler<OrmSession>): void {
+    this.domainEvents.register(name, handler);
+  }
+
+  async find<TTable extends TableDef>(entityClass: EntityConstructor, id: any): Promise<Entity<TTable> | null> {
+    const table = getTableDefFromEntity(entityClass);
+    if (!table) {
+      throw new Error('Entity metadata has not been bootstrapped');
+    }
+    const primaryKey = findPrimaryKey(table);
+    const column = table.columns[primaryKey];
+    if (!column) {
+      throw new Error('Entity table does not expose a primary key');
+    }
+    const qb = selectFromEntity<TTable>(entityClass)
+      .where(eq(column, id))
+      .limit(1);
+    const rows = await executeHydrated(this, qb);
+    return rows[0] ?? null;
+  }
+
+  async findOne<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable> | null> {
+    const limited = qb.limit(1);
+    const rows = await executeHydrated(this, limited);
+    return rows[0] ?? null;
+  }
+
+  async findMany<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable>[]> {
+    return executeHydrated(this, qb);
+  }
+
+  async persist(entity: object): Promise<void> {
+    if (this.unitOfWork.findTracked(entity)) {
+      return;
+    }
+    const table = getTableDefFromEntity((entity as any).constructor as EntityConstructor);
+    if (!table) {
+      throw new Error('Entity metadata has not been bootstrapped');
+    }
+    const primaryKey = findPrimaryKey(table);
+    const pkValue = (entity as Record<string, any>)[primaryKey];
+    if (pkValue !== undefined && pkValue !== null) {
+      this.trackManaged(table, pkValue, entity);
+    } else {
+      this.trackNew(table, entity);
+    }
+  }
+
+  async remove(entity: object): Promise<void> {
+    this.markRemoved(entity);
+  }
+
+  async flush(): Promise<void> {
+    await this.unitOfWork.flush();
+  }
+
+  async commit(): Promise<void> {
+    await runInTransaction(this.executor, async () => {
+      for (const interceptor of this.interceptors) {
+        await interceptor.beforeFlush?.(this);
+      }
+
+      await this.unitOfWork.flush();
+      await this.relationChanges.process();
+      await this.unitOfWork.flush();
+
+      for (const interceptor of this.interceptors) {
+        await interceptor.afterFlush?.(this);
+      }
+    });
+
+    await this.domainEvents.dispatch(this.unitOfWork.getTracked(), this);
+  }
+
+  async rollback(): Promise<void> {
+    await this.executor.rollbackTransaction?.();
+    this.unitOfWork.reset();
+    this.relationChanges.reset();
+  }
+
+  getExecutionContext(): ExecutionContext {
+    return {
+      dialect: this.orm.dialect,
+      executor: this.executor,
+      interceptors: this.orm.interceptors
+    };
+  }
+
+  getHydrationContext(): HydrationContext {
+    return {
+      identityMap: this.identityMap,
+      unitOfWork: this.unitOfWork,
+      domainEvents: this.domainEvents,
+      relationChanges: this.relationChanges,
+      entityContext: this
+    };
+  }
+}
+
+const buildRelationChangeEntry = (
+  root: any,
+  relationKey: RelationKey,
+  rootTable: TableDef,
+  relationName: string,
+  relation: RelationDef,
+  change: RelationChange<any>
+): RelationChangeEntry => ({
+  root,
+  relationKey,
+  rootTable,
+  relationName,
+  relation,
+  change
+});

package/src/orm/orm.ts

@@ -0,0 +1,58 @@
+import type { Dialect } from '../core/dialect/abstract.js';
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import type { NamingStrategy } from '../codegen/naming-strategy.js';
+import { InterceptorPipeline } from './interceptor-pipeline.js';
+import { DefaultNamingStrategy } from '../codegen/naming-strategy.js';
+import { OrmSession } from './orm-session.ts';
+
+export interface OrmOptions {
+  dialect: Dialect;
+  executorFactory: DbExecutorFactory;
+  interceptors?: InterceptorPipeline;
+  namingStrategy?: NamingStrategy;
+  // model registrations etc.
+}
+
+export interface DbExecutorFactory {
+  createExecutor(options?: { tx?: ExternalTransaction }): DbExecutor;
+  createTransactionalExecutor(): DbExecutor;
+}
+
+export interface ExternalTransaction {
+  // Transaction-specific properties
+}
+
+export class Orm {
+  readonly dialect: Dialect;
+  readonly interceptors: InterceptorPipeline;
+  readonly namingStrategy: NamingStrategy;
+  private readonly executorFactory: DbExecutorFactory;
+
+  constructor(opts: OrmOptions) {
+    this.dialect = opts.dialect;
+    this.interceptors = opts.interceptors ?? new InterceptorPipeline();
+    this.namingStrategy = opts.namingStrategy ?? new DefaultNamingStrategy();
+    this.executorFactory = opts.executorFactory;
+  }
+
+  createSession(options?: { tx?: ExternalTransaction }): OrmSession {
+    const executor = this.executorFactory.createExecutor(options?.tx);
+    return new OrmSession({ orm: this, executor });
+  }
+
+  // Nice convenience:
+  async transaction<T>(fn: (session: OrmSession) => Promise<T>): Promise<T> {
+    const executor = this.executorFactory.createTransactionalExecutor();
+    const session = new OrmSession({ orm: this, executor });
+    try {
+      const result = await fn(session);
+      await session.commit();
+      return result;
+    } catch (err) {
+      await session.rollback();
+      throw err;
+    } finally {
+      // executor cleanup if needed
+    }
+  }
+}

package/src/orm/query-logger.ts

@@ -1,4 +1,4 @@
-import type { DbExecutor } from './db-executor.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
 
 export interface QueryLogEntry {
   sql: string;

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

@@ -3,10 +3,10 @@ import type { Dialect } from '../core/dialect/abstract.js';
 import { DeleteQueryBuilder } from '../query-builder/delete.js';
 import { InsertQueryBuilder } from '../query-builder/insert.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import type { BelongsToManyRelation, HasManyRelation } from '../schema/relation.js';
+import type { BelongsToManyRelation, HasManyRelation, HasOneRelation } from '../schema/relation.js';
 import { RelationKinds } from '../schema/relation.js';
 import type { TableDef } from '../schema/table.js';
-import type { DbExecutor } from './db-executor.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
 import type { RelationChangeEntry } from './runtime-types.js';
 import { UnitOfWork } from './unit-of-work.js';
 
@@ -17,12 +17,16 @@ export class RelationChangeProcessor {
     private readonly unitOfWork: UnitOfWork,
     private readonly dialect: Dialect,
     private readonly executor: DbExecutor
-  ) {}
+  ) { }
 
   registerChange(entry: RelationChangeEntry): void {
     this.relationChanges.push(entry);
   }
 
+  reset(): void {
+    this.relationChanges.length = 0;
+  }
+
   async process(): Promise<void> {
     if (!this.relationChanges.length) return;
     const entries = [...this.relationChanges];
@@ -33,6 +37,9 @@ export class RelationChangeProcessor {
         case RelationKinds.HasMany:
           await this.handleHasManyChange(entry);
           break;
+        case RelationKinds.HasOne:
+          await this.handleHasOneChange(entry);
+          break;
         case RelationKinds.BelongsToMany:
           await this.handleBelongsToManyChange(entry);
           break;
@@ -66,6 +73,29 @@ export class RelationChangeProcessor {
     }
   }
 
+  private async handleHasOneChange(entry: RelationChangeEntry): Promise<void> {
+    const relation = entry.relation as HasOneRelation;
+    const target = entry.change.entity;
+    if (!target) return;
+
+    const tracked = this.unitOfWork.findTracked(target);
+    if (!tracked) return;
+
+    const localKey = relation.localKey || findPrimaryKey(entry.rootTable);
+    const rootValue = entry.root[localKey];
+    if (rootValue === undefined || rootValue === null) return;
+
+    if (entry.change.kind === 'attach' || entry.change.kind === 'add') {
+      this.assignHasOneForeignKey(tracked.entity, relation, rootValue);
+      this.unitOfWork.markDirty(tracked.entity);
+      return;
+    }
+
+    if (entry.change.kind === 'remove') {
+      this.detachHasOneChild(tracked.entity, relation);
+    }
+  }
+
   private async handleBelongsToChange(_entry: RelationChangeEntry): Promise<void> {
     // Reserved for future cascade/persist behaviors for belongs-to relations.
   }
@@ -108,6 +138,21 @@ export class RelationChangeProcessor {
     this.unitOfWork.markDirty(child);
   }
 
+  private assignHasOneForeignKey(child: any, relation: HasOneRelation, rootValue: unknown): void {
+    const current = child[relation.foreignKey];
+    if (current === rootValue) return;
+    child[relation.foreignKey] = rootValue;
+  }
+
+  private detachHasOneChild(child: any, relation: HasOneRelation): void {
+    if (relation.cascade === 'all' || relation.cascade === 'remove') {
+      this.unitOfWork.markRemoved(child);
+      return;
+    }
+    child[relation.foreignKey] = null;
+    this.unitOfWork.markDirty(child);
+  }
+
   private async insertPivotRow(relation: BelongsToManyRelation, rootId: string | number, targetId: string | number): Promise<void> {
     const payload = {
       [relation.pivotForeignKeyToRoot]: rootId,

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

@@ -1,45 +1,46 @@
 import { BelongsToReference } from '../../schema/types.js';
-import { OrmContext, RelationKey } from '../orm-context.js';
+import { EntityContext } from '../entity-context.js';
+import { RelationKey } from '../runtime-types.js';
 import { BelongsToRelation } from '../../schema/relation.js';
 import { TableDef } from '../../schema/table.js';
 import { EntityMeta, getHydrationRecord, hasEntityMeta } 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 DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
-  private loaded = false;
-  private current: TParent | null = null;
-
-  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 DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
+  private loaded = false;
+  private current: TParent | null = null;
+
+  constructor(
+    private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<any>,
     private readonly root: any,
     private readonly relationName: string,
     private readonly relation: BelongsToRelation,
     private readonly rootTable: TableDef,
     private readonly loader: () => Promise<Map<string, Rows>>,
-    private readonly createEntity: (row: Record<string, any>) => TParent,
-    private readonly targetKey: string
-  ) {
-    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'targetKey']);
-    this.populateFromHydrationCache();
-  }
-
-  async load(): Promise<TParent | null> {
-    if (this.loaded) return this.current;
+    private readonly createEntity: (row: Record<string, any>) => TParent,
+    private readonly targetKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'targetKey']);
+    this.populateFromHydrationCache();
+  }
+
+  async load(): Promise<TParent | null> {
+    if (this.loaded) return this.current;
     const map = await this.loader();
     const fkValue = this.root[this.relation.foreignKey];
     if (fkValue === null || fkValue === undefined) {
@@ -93,16 +94,16 @@ export class DefaultBelongsToReference<TParent> implements BelongsToReference<TP
     return `${this.rootTable.name}.${this.relationName}`;
   }
 
-  private populateFromHydrationCache(): void {
-    const fkValue = this.root[this.relation.foreignKey];
-    if (fkValue === undefined || fkValue === null) return;
-    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
-    if (!row) return;
-    this.current = this.createEntity(row);
-    this.loaded = true;
-  }
-
-  toJSON(): TParent | null {
-    return this.current;
-  }
-}
+  private populateFromHydrationCache(): void {
+    const fkValue = this.root[this.relation.foreignKey];
+    if (fkValue === undefined || fkValue === null) return;
+    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
+    if (!row) return;
+    this.current = this.createEntity(row);
+    this.loaded = true;
+  }
+
+  toJSON(): TParent | null {
+    return this.current;
+  }
+}

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;
+  }
+}