metal-orm 1.0.15 → 1.0.17

package/src/orm/execute.ts

@@ -1,9 +1,12 @@
 import { TableDef } from '../schema/table.js';
 import { Entity } from '../schema/types.js';
-import { hydrateRows } from './hydration.js';
-import { OrmContext } from './orm-context.js';
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import { createEntityFromRow, createEntityProxy } from './entity.js';
+import { hydrateRows } from './hydration.js';
+import { OrmSession } from './orm-session.ts';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { createEntityProxy, createEntityFromRow } from './entity.js';
+import { EntityContext } from './entity-context.js';
+import { ExecutionContext } from './execution-context.js';
+import { HydrationContext } from './hydration-context.js';
 
 type Row = Record<string, any>;
 
@@ -22,24 +25,38 @@ const flattenResults = (results: { columns: string[]; values: unknown[][] }[]):
   return rows;
 };
 
-export async function executeHydrated<TTable extends TableDef>(
-  ctx: OrmContext,
-  qb: SelectQueryBuilder<any, TTable>
-): Promise<Entity<TTable>[]> {
-  const ast = qb.getAST();
-  const compiled = ctx.dialect.compileSelect(ast);
-  const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
-  const rows = flattenResults(executed);
-
-  // Set-operation queries cannot be reliably hydrated and should not collapse duplicates.
-  if (ast.setOps && ast.setOps.length > 0) {
-    return rows.map(row =>
-      createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
-    );
-  }
-
-  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
-  return hydrated.map(row =>
-    createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
-  );
-}
+const executeWithEntityContext = async <TTable extends TableDef>(
+  entityCtx: EntityContext,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> => {
+  const ast = qb.getAST();
+  const compiled = entityCtx.dialect.compileSelect(ast);
+  const executed = await entityCtx.executor.executeSql(compiled.sql, compiled.params);
+  const rows = flattenResults(executed);
+
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows.map(row => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+  }
+
+  const hydrated = hydrateRows(rows, qb.getHydrationPlan());
+  return hydrated.map(row => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
+};
+
+export async function executeHydrated<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> {
+  return executeWithEntityContext(session, qb);
+}
+
+export async function executeHydratedWithContexts<TTable extends TableDef>(
+  _execCtx: ExecutionContext,
+  hydCtx: HydrationContext,
+  qb: SelectQueryBuilder<any, TTable>
+): Promise<Entity<TTable>[]> {
+  const entityCtx = hydCtx.entityContext;
+  if (!entityCtx) {
+    throw new Error('Hydration context is missing an EntityContext');
+  }
+  return executeWithEntityContext(entityCtx, qb);
+}

package/src/orm/execution-context.ts

@@ -0,0 +1,18 @@
+import type { Dialect } from '../core/dialect/abstract.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
+import { InterceptorPipeline } from './interceptor-pipeline.js';
+
+/**
+ * Context for SQL query execution
+ */
+export interface ExecutionContext {
+  /** Database dialect to use for SQL generation */
+  dialect: Dialect;
+  /** Database executor for running SQL queries */
+  executor: DbExecutor;
+  /** Interceptor pipeline for query processing */
+  interceptors: InterceptorPipeline;
+  // plus anything *purely about executing SQL*:
+  // - logging
+  // - query timeout config
+}

package/src/orm/hydration-context.ts

@@ -0,0 +1,16 @@
+import { IdentityMap } from './identity-map.js';
+import { UnitOfWork } from './unit-of-work.js';
+import type { DomainEventBus } from './domain-event-bus.js';
+import { RelationChangeProcessor } from './relation-change-processor.js';
+import type { EntityContext } from './entity-context.js';
+import type { AnyDomainEvent, DomainEvent } from './runtime-types.js';
+import type { OrmSession } from './orm-session.js';
+
+export interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
+  identityMap: IdentityMap;
+  unitOfWork: UnitOfWork;
+  domainEvents: DomainEventBus<E, OrmSession<E>>;
+  relationChanges: RelationChangeProcessor;
+  entityContext: EntityContext;
+  // maybe mapping registry, converters, etc.
+}

package/src/orm/identity-map.ts

@@ -31,6 +31,10 @@ export class IdentityMap {
     return bucket ? Array.from(bucket.values()) : [];
   }
 
+  clear(): void {
+    this.buckets.clear();
+  }
+
   private toIdentityKey(pk: string | number): string {
     return String(pk);
   }

package/src/orm/interceptor-pipeline.ts

@@ -0,0 +1,29 @@
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+
+export interface QueryContext {
+  sql: string;
+  params: unknown[];
+  // maybe metadata like entity type, operation type, etc.
+}
+
+export type QueryInterceptor = (ctx: QueryContext, next: () => Promise<QueryResult[]>) => Promise<QueryResult[]>;
+
+export class InterceptorPipeline {
+  private interceptors: QueryInterceptor[] = [];
+
+  use(interceptor: QueryInterceptor) {
+    this.interceptors.push(interceptor);
+  }
+
+  async run(ctx: QueryContext, executor: DbExecutor): Promise<QueryResult[]> {
+    let i = 0;
+    const dispatch = async (): Promise<QueryResult[]> => {
+      const interceptor = this.interceptors[i++];
+      if (!interceptor) {
+        return executor.executeSql(ctx.sql, ctx.params);
+      }
+      return interceptor(ctx, dispatch);
+    };
+    return dispatch();
+  }
+}

package/src/orm/lazy-batch.ts

@@ -2,7 +2,7 @@ import { TableDef } from '../schema/table.js';
 import { BelongsToManyRelation, HasManyRelation, HasOneRelation, BelongsToRelation } from '../schema/relation.js';
 import { SelectQueryBuilder } from '../query-builder/select.js';
 import { inList, LiteralNode } from '../core/ast/expression.js';
-import { OrmContext } from './orm-context.js';
+import { EntityContext } from './entity-context.js';
 import type { QueryResult } from '../core/execution/db-executor.js';
 import { ColumnDef } from '../schema/column.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
@@ -30,7 +30,7 @@ const rowsFromResults = (results: QueryResult[]): Rows => {
   return rows;
 };
 
-const executeQuery = async (ctx: OrmContext, qb: SelectQueryBuilder<any, TableDef<any>>): Promise<Rows> => {
+const executeQuery = async (ctx: EntityContext, qb: SelectQueryBuilder<any, TableDef<any>>): Promise<Rows> => {
   const compiled = ctx.dialect.compileSelect(qb.getAST());
   const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
   return rowsFromResults(results);
@@ -39,7 +39,7 @@ const executeQuery = async (ctx: OrmContext, qb: SelectQueryBuilder<any, TableDe
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
 export const loadHasManyRelation = async (
-  ctx: OrmContext,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: HasManyRelation
@@ -82,7 +82,7 @@ export const loadHasManyRelation = async (
 };
 
 export const loadHasOneRelation = async (
-  ctx: OrmContext,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: HasOneRelation
@@ -125,7 +125,7 @@ export const loadHasOneRelation = async (
 };
 
 export const loadBelongsToRelation = async (
-  ctx: OrmContext,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: BelongsToRelation
@@ -164,7 +164,7 @@ export const loadBelongsToRelation = async (
 };
 
 export const loadBelongsToManyRelation = async (
-  ctx: OrmContext,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: BelongsToManyRelation

package/src/orm/orm-session.ts

@@ -0,0 +1,245 @@
+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 { ColumnDef } from '../schema/column.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, InitialHandlers } 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 type { HydrationContext } from './hydration-context.js';
+import type { EntityContext } from './entity-context.js';
+import {
+  DomainEvent,
+  OrmDomainEvent,
+  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<E extends DomainEvent = OrmDomainEvent> {
+  orm: Orm<E>;
+  executor: DbExecutor;
+  queryLogger?: QueryLogger;
+  interceptors?: OrmInterceptor[];
+  domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
+}
+
+export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+  readonly orm: Orm<E>;
+  readonly executor: DbExecutor;
+  readonly identityMap: IdentityMap;
+  readonly unitOfWork: UnitOfWork;
+  readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
+  readonly relationChanges: RelationChangeProcessor;
+
+  private readonly interceptors: OrmInterceptor[];
+
+  constructor(opts: OrmSessionOptions<E>) {
+    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<E, OrmSession<E>>(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<TType extends E['type']>(
+    type: TType,
+    handler: DomainEventHandler<Extract<E, { type: TType }>, OrmSession<E>>
+  ): void {
+    this.domainEvents.on(type, 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 columnSelections = Object.values(table.columns).reduce<Record<string, ColumnDef>>((acc, col) => {
+      acc[col.name] = col;
+      return acc;
+    }, {});
+    const qb = selectFromEntity<TTable>(entityClass)
+      .select(columnSelections)
+      .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<E> {
+    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 { DomainEvent, OrmDomainEvent } from './runtime-types.js';
+import type { Dialect } from '../core/dialect/abstract.js';
+import type { DbExecutor } 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.js';
+
+export interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
+  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<E extends DomainEvent = OrmDomainEvent> {
+  readonly dialect: Dialect;
+  readonly interceptors: InterceptorPipeline;
+  readonly namingStrategy: NamingStrategy;
+  private readonly executorFactory: DbExecutorFactory;
+
+  constructor(opts: OrmOptions<E>) {
+    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<E> {
+    const executor = this.executorFactory.createExecutor(options?.tx);
+    return new OrmSession<E>({ orm: this, executor });
+  }
+
+  async transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T> {
+    const executor = this.executorFactory.createTransactionalExecutor();
+    const session = new OrmSession<E>({ 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,12 +1,27 @@
 import type { DbExecutor } from '../core/execution/db-executor.js';
 
+/**
+ * Represents a single SQL query log entry
+ */
 export interface QueryLogEntry {
+  /** The SQL query that was executed */
   sql: string;
+  /** Parameters used in the query */
   params?: unknown[];
 }
 
+/**
+ * Function type for query logging callbacks
+ * @param entry - The query log entry to process
+ */
 export type QueryLogger = (entry: QueryLogEntry) => void;
 
+/**
+ * Creates a wrapped database executor that logs all SQL queries
+ * @param executor - Original database executor to wrap
+ * @param logger - Optional logger function to receive query log entries
+ * @returns Wrapped executor that logs queries before execution
+ */
 export const createQueryLoggingExecutor = (
   executor: DbExecutor,
   logger?: QueryLogger

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

@@ -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];

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