metal-orm 1.0.13 → 1.0.15

package/src/orm/entity.ts

@@ -1,12 +1,13 @@
 import { TableDef } from '../schema/table.js';
-import { Entity, RelationMap, HasManyCollection, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
-import { OrmContext } from './orm-context.js';
-import { ENTITY_META, EntityMeta, getEntityMeta } from './entity-meta.js';
-import { DefaultHasManyCollection } from './relations/has-many.js';
-import { DefaultBelongsToReference } from './relations/belongs-to.js';
-import { DefaultManyToManyCollection } from './relations/many-to-many.js';
-import { HasManyRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
-import { loadHasManyRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
+import { Entity, RelationMap, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
+import { OrmContext } from './orm-context.js';
+import { ENTITY_META, EntityMeta, getEntityMeta } from './entity-meta.js';
+import { DefaultHasManyCollection } from './relations/has-many.js';
+import { DefaultHasOneReference } from './relations/has-one.js';
+import { DefaultBelongsToReference } from './relations/belongs-to.js';
+import { DefaultManyToManyCollection } from './relations/many-to-many.js';
+import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
+import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 
 type Rows = Record<string, any>[];
@@ -135,10 +136,22 @@ const toKey = (value: unknown): string => (value === null || value === undefined
   ): void => {
     for (const relationName of Object.keys(meta.table.relations)) {
       const relation = meta.table.relations[relationName];
-      const data = row[relationName];
-      if (!Array.isArray(data)) continue;
-
-      if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
+      const data = row[relationName];
+      if (relation.type === RelationKinds.HasOne) {
+        const localKey = relation.localKey || findPrimaryKey(meta.table);
+        const rootValue = entity[localKey];
+        if (rootValue === undefined || rootValue === null) continue;
+        if (!data || typeof data !== 'object') continue;
+        const cache = new Map<string, Record<string, any>>();
+        cache.set(toKey(rootValue), data as Record<string, any>);
+        meta.relationHydration.set(relationName, cache);
+        meta.relationCache.set(relationName, Promise.resolve(cache));
+        continue;
+      }
+
+      if (!Array.isArray(data)) continue;
+
+      if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
         const localKey = relation.localKey || findPrimaryKey(meta.table);
         const rootValue = entity[localKey];
         if (rootValue === undefined || rootValue === null) continue;
@@ -165,11 +178,11 @@ const toKey = (value: unknown): string => (value === null || value === undefined
     }
   };
 
-const getRelationWrapper = (
-  meta: EntityMeta<any>,
-  relationName: string,
-  owner: any
-): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+const getRelationWrapper = (
+  meta: EntityMeta<any>,
+  relationName: string,
+  owner: any
+): HasManyCollection<any> | HasOneReference<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
   if (meta.relationWrappers.has(relationName)) {
     return meta.relationWrappers.get(relationName) as HasManyCollection<any>;
   }
@@ -185,16 +198,34 @@ const getRelationWrapper = (
   return wrapper;
 };
 
-const instantiateWrapper = (
-  meta: EntityMeta<any>,
-  relationName: string,
-  relation: HasManyRelation | BelongsToRelation | BelongsToManyRelation,
-  owner: any
-): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
-  switch (relation.type) {
-    case RelationKinds.HasMany: {
-      const hasMany = relation as HasManyRelation;
-      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+const instantiateWrapper = (
+  meta: EntityMeta<any>,
+  relationName: string,
+  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
+  owner: any
+): HasManyCollection<any> | HasOneReference<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+  switch (relation.type) {
+    case RelationKinds.HasOne: {
+      const hasOne = relation as HasOneRelation;
+      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
+      const loader = () => relationLoaderCache(meta, relationName, () =>
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne)
+      );
+      return new DefaultHasOneReference(
+        meta.ctx,
+        meta,
+        owner,
+        relationName,
+        hasOne,
+        meta.table,
+        loader,
+        (row: Record<string, any>) => createEntityFromRow(meta.ctx, hasOne.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.HasMany: {
+      const hasMany = relation as HasManyRelation;
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
       const loader = () => relationLoaderCache(meta, relationName, () =>
         loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany)
       );

package/src/orm/hydration.ts

@@ -1,5 +1,6 @@
-import { HydrationPlan, HydrationRelationPlan } from '../core/ast/query.js';
-import { isRelationAlias, makeRelationAlias } from '../query-builder/relation-alias.js';
+import { HydrationPlan, HydrationRelationPlan } from '../core/hydration/types.js';
+import { RelationKinds } from '../schema/relation.js';
+import { isRelationAlias, makeRelationAlias } from '../query-builder/relation-alias.js';
 
 /**
  * Hydrates query results according to a hydration plan
@@ -47,18 +48,25 @@ export const hydrateRows = (rows: Record<string, any>[], plan?: HydrationPlan):
     const parent = getOrCreateParent(row);
     if (!parent) continue;
 
-    for (const rel of plan.relations) {
-      const childPkKey = makeRelationAlias(rel.aliasPrefix, rel.targetPrimaryKey);
-      const childPk = row[childPkKey];
-      if (childPk === null || childPk === undefined) continue;
-
-      const seen = getRelationSeenSet(rootId, rel.name);
-      if (seen.has(childPk)) continue;
-      seen.add(childPk);
-
-      const bucket = parent[rel.name] as any[];
-      bucket.push(buildChild(row, rel));
-    }
+    for (const rel of plan.relations) {
+      const childPkKey = makeRelationAlias(rel.aliasPrefix, rel.targetPrimaryKey);
+      const childPk = row[childPkKey];
+      if (childPk === null || childPk === undefined) continue;
+
+      const seen = getRelationSeenSet(rootId, rel.name);
+      if (seen.has(childPk)) continue;
+      seen.add(childPk);
+
+      if (rel.type === RelationKinds.HasOne) {
+        if (!parent[rel.name]) {
+          parent[rel.name] = buildChild(row, rel);
+        }
+        continue;
+      }
+
+      const bucket = parent[rel.name] as any[];
+      bucket.push(buildChild(row, rel));
+    }
   }
 
   return Array.from(rootMap.values());
@@ -74,9 +82,9 @@ const createBaseRow = (row: Record<string, any>, plan: HydrationPlan): Record<st
     base[key] = row[key];
   }
 
-  for (const rel of plan.relations) {
-    base[rel.name] = [];
-  }
+  for (const rel of plan.relations) {
+    base[rel.name] = rel.type === RelationKinds.HasOne ? null : [];
+  }
 
   return base;
 };

package/src/orm/lazy-batch.ts

@@ -1,8 +1,9 @@
 import { TableDef } from '../schema/table.js';
-import { BelongsToManyRelation, HasManyRelation, BelongsToRelation } from '../schema/relation.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, QueryResult } from './orm-context.js';
+import { OrmContext } from './orm-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';
 
@@ -80,6 +81,49 @@ export const loadHasManyRelation = async (
   return grouped;
 };
 
+export const loadHasOneRelation = async (
+  ctx: OrmContext,
+  rootTable: TableDef,
+  _relationName: string,
+  relation: HasOneRelation
+): Promise<Map<string, Record<string, any>>> => {
+  const localKey = relation.localKey || findPrimaryKey(rootTable);
+  const roots = ctx.getEntitiesForTable(rootTable);
+  const keys = new Set<unknown>();
+
+  for (const tracked of roots) {
+    const value = tracked.entity[localKey];
+    if (value !== null && value !== undefined) {
+      keys.add(value);
+    }
+  }
+
+  if (!keys.size) {
+    return new Map();
+  }
+
+  const selectMap = selectAllColumns(relation.target);
+  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
+  const fkColumn = relation.target.columns[relation.foreignKey];
+  if (!fkColumn) return new Map();
+
+  qb.where(inList(fkColumn, Array.from(keys) as (string | number | LiteralNode)[]));
+
+  const rows = await executeQuery(ctx, qb);
+  const lookup = new Map<string, Record<string, any>>();
+
+  for (const row of rows) {
+    const fkValue = row[relation.foreignKey];
+    if (fkValue === null || fkValue === undefined) continue;
+    const key = toKey(fkValue);
+    if (!lookup.has(key)) {
+      lookup.set(key, row);
+    }
+  }
+
+  return lookup;
+};
+
 export const loadBelongsToRelation = async (
   ctx: OrmContext,
   rootTable: TableDef,

package/src/orm/orm-context.ts

@@ -1,21 +1,21 @@
 import type { Dialect } from '../core/dialect/abstract.js';
 import type { RelationDef } from '../schema/relation.js';
 import type { TableDef } from '../schema/table.js';
-import type { DbExecutor, QueryResult } from './db-executor.js';
-import { DomainEventBus, DomainEventHandler as DomainEventHandlerFn, addDomainEvent } from './domain-event-bus.js';
-import { IdentityMap } from './identity-map.js';
-import { RelationChangeProcessor } from './relation-change-processor.js';
-import { runInTransaction } from './transaction-runner.js';
-import { UnitOfWork } from './unit-of-work.js';
-import {
-  EntityStatus,
-  HasDomainEvents,
-  RelationChange,
-  RelationChangeEntry,
-  RelationKey,
-  TrackedEntity
-} from './runtime-types.js';
-import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import { DomainEventBus, DomainEventHandler as DomainEventHandlerFn, addDomainEvent } from './domain-event-bus.js';
+import { IdentityMap } from './identity-map.js';
+import { RelationChangeProcessor } from './relation-change-processor.js';
+import { runInTransaction } from './transaction-runner.js';
+import { UnitOfWork } from './unit-of-work.js';
+import {
+  EntityStatus,
+  HasDomainEvents,
+  RelationChange,
+  RelationChangeEntry,
+  RelationKey,
+  TrackedEntity
+} from './runtime-types.js';
+import { createQueryLoggingExecutor, QueryLogger } from './query-logger.js';
 
 export interface OrmInterceptor {
   beforeFlush?(ctx: OrmContext): Promise<void> | void;
@@ -24,46 +24,46 @@ export interface OrmInterceptor {
 
 export type DomainEventHandler = DomainEventHandlerFn<OrmContext>;
 
-export interface OrmContextOptions {
-  dialect: Dialect;
-  executor: DbExecutor;
-  interceptors?: OrmInterceptor[];
-  domainEventHandlers?: Record<string, DomainEventHandler[]>;
-  queryLogger?: QueryLogger;
-}
-
-export class OrmContext {
-  private readonly identityMap = new IdentityMap();
-  private readonly executorWithLogging: DbExecutor;
-  private readonly unitOfWork: UnitOfWork;
-  private readonly relationChanges: RelationChangeProcessor;
-  private readonly interceptors: OrmInterceptor[];
-  private readonly domainEvents: DomainEventBus<OrmContext>;
-
-  constructor(private readonly options: OrmContextOptions) {
-    this.interceptors = [...(options.interceptors ?? [])];
-    this.executorWithLogging = createQueryLoggingExecutor(options.executor, options.queryLogger);
-    this.unitOfWork = new UnitOfWork(
-      options.dialect,
-      this.executorWithLogging,
-      this.identityMap,
-      () => this
-    );
-    this.relationChanges = new RelationChangeProcessor(
-      this.unitOfWork,
-      options.dialect,
-      this.executorWithLogging
-    );
-    this.domainEvents = new DomainEventBus<OrmContext>(options.domainEventHandlers);
-  }
+export interface OrmContextOptions {
+  dialect: Dialect;
+  executor: DbExecutor;
+  interceptors?: OrmInterceptor[];
+  domainEventHandlers?: Record<string, DomainEventHandler[]>;
+  queryLogger?: QueryLogger;
+}
+
+export class OrmContext {
+  private readonly identityMap = new IdentityMap();
+  private readonly executorWithLogging: DbExecutor;
+  private readonly unitOfWork: UnitOfWork;
+  private readonly relationChanges: RelationChangeProcessor;
+  private readonly interceptors: OrmInterceptor[];
+  private readonly domainEvents: DomainEventBus<OrmContext>;
+
+  constructor(private readonly options: OrmContextOptions) {
+    this.interceptors = [...(options.interceptors ?? [])];
+    this.executorWithLogging = createQueryLoggingExecutor(options.executor, options.queryLogger);
+    this.unitOfWork = new UnitOfWork(
+      options.dialect,
+      this.executorWithLogging,
+      this.identityMap,
+      () => this
+    );
+    this.relationChanges = new RelationChangeProcessor(
+      this.unitOfWork,
+      options.dialect,
+      this.executorWithLogging
+    );
+    this.domainEvents = new DomainEventBus<OrmContext>(options.domainEventHandlers);
+  }
 
   get dialect(): Dialect {
     return this.options.dialect;
   }
 
-  get executor(): DbExecutor {
-    return this.executorWithLogging;
-  }
+  get executor(): DbExecutor {
+    return this.executorWithLogging;
+  }
 
   get identityBuckets(): Map<string, Map<string, TrackedEntity>> {
     return this.unitOfWork.identityBuckets;
@@ -147,13 +147,13 @@ export class OrmContext {
   }
 }
 
-export { addDomainEvent };
-export { EntityStatus };
-export type {
-  QueryResult,
-  DbExecutor,
-  RelationKey,
-  RelationChange,
-  HasDomainEvents
-};
-export type { QueryLogEntry, QueryLogger } from './query-logger.js';
+export { addDomainEvent };
+export { EntityStatus };
+export type {
+  QueryResult,
+  DbExecutor,
+  RelationKey,
+  RelationChange,
+  HasDomainEvents
+};
+export type { QueryLogEntry, QueryLogger } from './query-logger.js';

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';
 
@@ -33,6 +33,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 +69,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 +134,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/has-one.ts

@@ -0,0 +1,139 @@
+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;
+  }
+}

package/src/orm/transaction-runner.ts

@@ -1,4 +1,4 @@
-import type { DbExecutor } from './db-executor.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
 
 export const runInTransaction = async (executor: DbExecutor, action: () => Promise<void>): Promise<void> => {
   if (!executor.beginTransaction) {