metal-orm 1.0.14 → 1.0.16

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, RelationMap, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
+import { EntityContext } from './entity-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, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
-import { loadHasManyRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.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>[];
@@ -44,7 +45,7 @@ export const createEntityProxy = <
   TTable extends TableDef,
   TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>
 >(
-  ctx: OrmContext,
+  ctx: EntityContext,
   table: TTable,
   row: Record<string, any>,
   lazyRelations: TLazy[] = [] as TLazy[]
@@ -104,7 +105,7 @@ export const createEntityProxy = <
 };
 
 export const createEntityFromRow = <TTable extends TableDef>(
-  ctx: OrmContext,
+  ctx: EntityContext,
   table: TTable,
   row: Record<string, any>,
   lazyRelations: (keyof RelationMap<TTable>)[] = []
@@ -128,48 +129,60 @@ export const createEntityFromRow = <TTable extends TableDef>(
 
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
-  const populateHydrationCache = <TTable extends TableDef>(
-    entity: any,
-    row: Record<string, any>,
-    meta: EntityMeta<TTable>
-  ): 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 localKey = relation.localKey || findPrimaryKey(meta.table);
-        const rootValue = entity[localKey];
-        if (rootValue === undefined || rootValue === null) continue;
-        const cache = new Map<string, Rows>();
-        cache.set(toKey(rootValue), data as Rows);
+const populateHydrationCache = <TTable extends TableDef>(
+  entity: any,
+  row: Record<string, any>,
+  meta: EntityMeta<TTable>
+): void => {
+  for (const relationName of Object.keys(meta.table.relations)) {
+    const relation = meta.table.relations[relationName];
+    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;
+      const cache = new Map<string, Rows>();
+      cache.set(toKey(rootValue), data as Rows);
+      meta.relationHydration.set(relationName, cache);
+      meta.relationCache.set(relationName, Promise.resolve(cache));
+      continue;
+    }
+
+    if (relation.type === RelationKinds.BelongsTo) {
+      const targetKey = relation.localKey || findPrimaryKey(relation.target);
+      const cache = new Map<string, Record<string, any>>();
+      for (const item of data) {
+        const pkValue = item[targetKey];
+        if (pkValue === undefined || pkValue === null) continue;
+        cache.set(toKey(pkValue), item);
+      }
+      if (cache.size) {
         meta.relationHydration.set(relationName, cache);
         meta.relationCache.set(relationName, Promise.resolve(cache));
-        continue;
-      }
-
-      if (relation.type === RelationKinds.BelongsTo) {
-        const targetKey = relation.localKey || findPrimaryKey(relation.target);
-        const cache = new Map<string, Record<string, any>>();
-        for (const item of data) {
-          const pkValue = item[targetKey];
-          if (pkValue === undefined || pkValue === null) continue;
-          cache.set(toKey(pkValue), item);
-        }
-        if (cache.size) {
-          meta.relationHydration.set(relationName, cache);
-          meta.relationCache.set(relationName, Promise.resolve(cache));
-        }
       }
     }
-  };
+  }
+};
 
 const getRelationWrapper = (
   meta: EntityMeta<any>,
   relationName: string,
   owner: any
-): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+): HasManyCollection<any> | HasOneReference<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
   if (meta.relationWrappers.has(relationName)) {
     return meta.relationWrappers.get(relationName) as HasManyCollection<any>;
   }
@@ -188,10 +201,28 @@ const getRelationWrapper = (
 const instantiateWrapper = (
   meta: EntityMeta<any>,
   relationName: string,
-  relation: HasManyRelation | BelongsToRelation | BelongsToManyRelation,
+  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
   owner: any
-): HasManyCollection<any> | BelongsToReference<any> | ManyToManyCollection<any> | undefined => {
+): 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);

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,12 @@
+import type { Dialect } from '../core/dialect/abstract.js';
+import type { DbExecutor } from '../core/execution/db-executor.js';
+import { InterceptorPipeline } from './interceptor-pipeline.js';
+
+export interface ExecutionContext {
+  dialect: Dialect;
+  executor: DbExecutor;
+  interceptors: InterceptorPipeline;
+  // plus anything *purely about executing SQL*:
+  // - logging
+  // - query timeout config
+}

package/src/orm/hydration-context.ts

@@ -0,0 +1,14 @@
+import { IdentityMap } from './identity-map.js';
+import { UnitOfWork } from './unit-of-work.js';
+import { DomainEventBus } from './domain-event-bus.js';
+import { RelationChangeProcessor } from './relation-change-processor.js';
+import { EntityContext } from './entity-context.js';
+
+export interface HydrationContext {
+  identityMap: IdentityMap;
+  unitOfWork: UnitOfWork;
+  domainEvents: DomainEventBus<any>;
+  relationChanges: RelationChangeProcessor;
+  entityContext: EntityContext;
+  // maybe mapping registry, converters, etc.
+}

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/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

@@ -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 { 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';
 
@@ -29,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);
@@ -38,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
@@ -80,8 +81,51 @@ export const loadHasManyRelation = async (
   return grouped;
 };
 
+export const loadHasOneRelation = async (
+  ctx: EntityContext,
+  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,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: BelongsToRelation
@@ -120,7 +164,7 @@ export const loadBelongsToRelation = async (
 };
 
 export const loadBelongsToManyRelation = async (
-  ctx: OrmContext,
+  ctx: EntityContext,
   rootTable: TableDef,
   _relationName: string,
   relation: BelongsToManyRelation