metal-orm 1.0.57 → 1.0.59

package/src/orm/lazy-batch.ts

@@ -1,310 +1,5 @@
-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 { EntityContext } from './entity-context.js';
-import type { QueryResult } from '../core/execution/db-executor.js';
-import { ColumnDef } from '../schema/column-types.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-
-/**
- * An array of database rows, each represented as a record of string keys to unknown values.
- */
-type Rows = Record<string, unknown>[];
-
-/**
- * Represents a single tracked entity from the EntityContext for a table.
- */
-type EntityTracker = ReturnType<EntityContext['getEntitiesForTable']>[number];
-
-/**
- * Creates a record of all columns from the given table definition.
- * @param table - The table definition to select columns from.
- * @returns A record mapping column names to their definitions.
- */
-const selectAllColumns = (table: TableDef): Record<string, ColumnDef> =>
-  Object.entries(table.columns).reduce((acc, [name, def]) => {
-    acc[name] = def;
-    return acc;
-  }, {} as Record<string, ColumnDef>);
-
-/**
- * Extracts rows from query results into a standardized format.
- * @param results - The query results to process.
- * @returns An array of rows as records.
- */
-const rowsFromResults = (results: QueryResult[]): Rows => {
-  const rows: Rows = [];
-  for (const result of results) {
-    const { columns, values } = result;
-    for (const valueRow of values) {
-      const row: Record<string, unknown> = {};
-      columns.forEach((column, idx) => {
-        row[column] = valueRow[idx];
-      });
-      rows.push(row);
-    }
-  }
-  return rows;
-};
-
-/**
- * Executes a select query and returns the resulting rows.
- * @param ctx - The entity context for execution.
- * @param qb - The select query builder.
- * @returns A promise resolving to the rows from the query.
- */
-const executeQuery = async (ctx: EntityContext, qb: SelectQueryBuilder<unknown, TableDef>): Promise<Rows> => {
-  const compiled = ctx.dialect.compileSelect(qb.getAST());
-  const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
-  return rowsFromResults(results);
-};
-
-/**
- * Converts a value to a string key, handling null and undefined as empty string.
- * @param value - The value to convert.
- * @returns The string representation of the value.
- */
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-/**
- * Collects unique keys from the root entities based on the specified key property.
- * @param roots - The tracked entities to collect keys from.
- * @param key - The property name to use as the key.
- * @returns A set of unique key values.
- */
-const collectKeysFromRoots = (roots: EntityTracker[], key: string): Set<unknown> => {
-  const collected = new Set<unknown>();
-  for (const tracked of roots) {
-    const value = tracked.entity[key];
-    if (value !== null && value !== undefined) {
-      collected.add(value);
-    }
-  }
-  return collected;
-};
-
-/**
- * Builds an array of values suitable for an IN list expression from a set of keys.
- * @param keys - The set of keys to convert.
- * @returns An array of string, number, or LiteralNode values.
- */
-const buildInListValues = (keys: Set<unknown>): (string | number | LiteralNode)[] =>
-  Array.from(keys) as (string | number | LiteralNode)[];
-
-/**
- * Fetches rows from a table where the specified column matches any of the given keys.
- * @param ctx - The entity context.
- * @param table - The target table.
- * @param column - The column to match against.
- * @param keys - The set of keys to match.
- * @returns A promise resolving to the matching rows.
- */
-const fetchRowsForKeys = async (
-  ctx: EntityContext,
-  table: TableDef,
-  column: ColumnDef,
-  keys: Set<unknown>
-): Promise<Rows> => {
-  const qb = new SelectQueryBuilder(table).select(selectAllColumns(table));
-  qb.where(inList(column, buildInListValues(keys)));
-  return executeQuery(ctx, qb);
-};
-
-/**
- * Groups rows by the value of a key column, allowing multiple rows per key.
- * @param rows - The rows to group.
- * @param keyColumn - The column name to group by.
- * @returns A map from key strings to arrays of rows.
- */
-const groupRowsByMany = (rows: Rows, keyColumn: string): Map<string, Rows> => {
-  const grouped = new Map<string, Rows>();
-  for (const row of rows) {
-    const value = row[keyColumn];
-    if (value === null || value === undefined) continue;
-    const key = toKey(value);
-    const bucket = grouped.get(key) ?? [];
-    bucket.push(row);
-    grouped.set(key, bucket);
-  }
-  return grouped;
-};
-
-/**
- * Groups rows by the value of a key column, keeping only one row per key.
- * @param rows - The rows to group.
- * @param keyColumn - The column name to group by.
- * @returns A map from key strings to single rows.
- */
-const groupRowsByUnique = (rows: Rows, keyColumn: string): Map<string, Record<string, unknown>> => {
-  const lookup = new Map<string, Record<string, unknown>>();
-  for (const row of rows) {
-    const value = row[keyColumn];
-    if (value === null || value === undefined) continue;
-    const key = toKey(value);
-    if (!lookup.has(key)) {
-      lookup.set(key, row);
-    }
-  }
-  return lookup;
-};
-
-/**
- * Loads related entities for a has-many relation in batch.
- * @param ctx - The entity context.
- * @param rootTable - The root table of the relation.
- * @param _relationName - The name of the relation (unused).
- * @param relation - The has-many relation definition.
- * @returns A promise resolving to a map of root keys to arrays of related rows.
- */
-export const loadHasManyRelation = async (
-  ctx: EntityContext,
-  rootTable: TableDef,
-  _relationName: string,
-  relation: HasManyRelation
-): Promise<Map<string, Rows>> => {
-  const localKey = relation.localKey || findPrimaryKey(rootTable);
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = collectKeysFromRoots(roots, localKey);
-
-  if (!keys.size) {
-    return new Map();
-  }
-
-  const fkColumn = relation.target.columns[relation.foreignKey];
-  if (!fkColumn) return new Map();
-
-  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
-  return groupRowsByMany(rows, relation.foreignKey);
-};
-
-/**
- * Loads related entities for a has-one relation in batch.
- * @param ctx - The entity context.
- * @param rootTable - The root table of the relation.
- * @param _relationName - The name of the relation (unused).
- * @param relation - The has-one relation definition.
- * @returns A promise resolving to a map of root keys to single related rows.
- */
-export const loadHasOneRelation = async (
-  ctx: EntityContext,
-  rootTable: TableDef,
-  _relationName: string,
-  relation: HasOneRelation
-): Promise<Map<string, Record<string, unknown>>> => {
-  const localKey = relation.localKey || findPrimaryKey(rootTable);
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const keys = collectKeysFromRoots(roots, localKey);
-
-  if (!keys.size) {
-    return new Map();
-  }
-
-  const fkColumn = relation.target.columns[relation.foreignKey];
-  if (!fkColumn) return new Map();
-
-  const rows = await fetchRowsForKeys(ctx, relation.target, fkColumn, keys);
-  return groupRowsByUnique(rows, relation.foreignKey);
-};
-
-/**
- * Loads related entities for a belongs-to relation in batch.
- * @param ctx - The entity context.
- * @param rootTable - The root table of the relation.
- * @param _relationName - The name of the relation (unused).
- * @param relation - The belongs-to relation definition.
- * @returns A promise resolving to a map of foreign keys to single related rows.
- */
-export const loadBelongsToRelation = async (
-  ctx: EntityContext,
-  rootTable: TableDef,
-  _relationName: string,
-  relation: BelongsToRelation
-): Promise<Map<string, Record<string, unknown>>> => {
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const foreignKeys = collectKeysFromRoots(roots, relation.foreignKey);
-
-  if (!foreignKeys.size) {
-    return new Map();
-  }
-
-  const targetKey = relation.localKey || findPrimaryKey(relation.target);
-  const pkColumn = relation.target.columns[targetKey];
-  if (!pkColumn) return new Map();
-
-  const rows = await fetchRowsForKeys(ctx, relation.target, pkColumn, foreignKeys);
-  return groupRowsByUnique(rows, targetKey);
-};
-
-/**
- * Loads related entities for a belongs-to-many relation in batch, including pivot data.
- * @param ctx - The entity context.
- * @param rootTable - The root table of the relation.
- * @param _relationName - The name of the relation (unused).
- * @param relation - The belongs-to-many relation definition.
- * @returns A promise resolving to a map of root keys to arrays of related rows with pivot data.
- */
-export const loadBelongsToManyRelation = async (
-  ctx: EntityContext,
-  rootTable: TableDef,
-  _relationName: string,
-  relation: BelongsToManyRelation
-): Promise<Map<string, Rows>> => {
-  const rootKey = relation.localKey || findPrimaryKey(rootTable);
-  const roots = ctx.getEntitiesForTable(rootTable);
-  const rootIds = collectKeysFromRoots(roots, rootKey);
-
-  if (!rootIds.size) {
-    return new Map();
-  }
-
-  const pivotColumn = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
-  if (!pivotColumn) return new Map();
-
-  const pivotRows = await fetchRowsForKeys(ctx, relation.pivotTable, pivotColumn, rootIds);
-  const rootLookup = new Map<string, { targetId: unknown; pivot: Record<string, unknown> }[]>();
-  const targetIds = new Set<unknown>();
-
-  for (const pivot of pivotRows) {
-    const rootValue = pivot[relation.pivotForeignKeyToRoot];
-    const targetValue = pivot[relation.pivotForeignKeyToTarget];
-    if (rootValue === null || rootValue === undefined || targetValue === null || targetValue === undefined) {
-      continue;
-    }
-    const bucket = rootLookup.get(toKey(rootValue)) ?? [];
-    bucket.push({
-      targetId: targetValue,
-      pivot: { ...pivot }
-    });
-    rootLookup.set(toKey(rootValue), bucket);
-    targetIds.add(targetValue);
-  }
-
-  if (!targetIds.size) {
-    return new Map();
-  }
-
-  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
-  const targetPkColumn = relation.target.columns[targetKey];
-  if (!targetPkColumn) return new Map();
-
-  const targetRows = await fetchRowsForKeys(ctx, relation.target, targetPkColumn, targetIds);
-  const targetMap = groupRowsByUnique(targetRows, targetKey);
-  const result = new Map<string, Rows>();
-
-  for (const [rootId, entries] of rootLookup.entries()) {
-    const bucket: Rows = [];
-    for (const entry of entries) {
-      const targetRow = targetMap.get(toKey(entry.targetId));
-      if (!targetRow) continue;
-      bucket.push({
-        ...targetRow,
-        _pivot: entry.pivot
-      });
-    }
-    result.set(rootId, bucket);
-  }
-
-  return result;
-};
+export { loadHasManyRelation } from './lazy-batch/has-many.js';
+export { loadHasOneRelation } from './lazy-batch/has-one.js';
+export { loadBelongsToRelation } from './lazy-batch/belongs-to.js';
+export { loadBelongsToManyRelation } from './lazy-batch/belongs-to-many.js';
 

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

@@ -1,4 +1,4 @@
-import { BelongsToReference } from '../../schema/types.js';
+import { BelongsToReferenceApi } from '../../schema/types.js';
 import { EntityContext } from '../entity-context.js';
 import { RelationKey } from '../runtime-types.js';
 import { BelongsToRelation } from '../../schema/relation.js';
@@ -26,7 +26,7 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TParent The type of the parent entity.
  */
-export class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
+export class DefaultBelongsToReference<TParent extends object> implements BelongsToReferenceApi<TParent> {
   private loaded = false;
   private current: TParent | null = null;
 

package/src/orm/relations/has-many.ts

@@ -69,15 +69,29 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.items = rows.map(row => this.createEntity(row));
     this.loaded = true;
     return this.items;
-  }
-
-  /**
-   * Gets the current items in the collection.
-   * @returns Array of child entities
-   */
-  getItems(): TChild[] {
-    return this.items;
-  }
+  }
+
+  /**
+   * Gets the current items in the collection.
+   * @returns Array of child entities
+   */
+  getItems(): TChild[] {
+    return this.items;
+  }
+ 
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator](): Iterator<TChild> {
+    return this.items[Symbol.iterator]();
+  }
 
   /**
    * Adds a new child entity to the collection.

package/src/orm/relations/has-one.ts

@@ -1,4 +1,4 @@
-import { HasOneReference } from '../../schema/types.js';
+import { HasOneReferenceApi } from '../../schema/types.js';
 import { EntityContext } from '../entity-context.js';
 import { RelationKey } from '../runtime-types.js';
 import { HasOneRelation } from '../../schema/relation.js';
@@ -26,7 +26,7 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TChild The type of the child entity.
  */
-export class DefaultHasOneReference<TChild> implements HasOneReference<TChild> {
+export class DefaultHasOneReference<TChild extends object> implements HasOneReferenceApi<TChild> {
   private loaded = false;
   private current: TChild | null = null;
 

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

@@ -28,7 +28,8 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TTarget The type of the target entities in the collection.
  */
-export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
+export class DefaultManyToManyCollection<TTarget, TPivot extends object | undefined = undefined>
+  implements ManyToManyCollection<TTarget, TPivot> {
   private loaded = false;
   private items: TTarget[] = [];
 
@@ -78,19 +79,33 @@ export class DefaultManyToManyCollection<TTarget> implements ManyToManyCollectio
     return this.items;
   }
 
-  /**
-   * Returns the currently loaded items.
-   * @returns Array of target entities.
-   */
-  getItems(): TTarget[] {
-    return this.items;
-  }
-
-  /**
-   * Attaches an entity to the collection.
-   * Registers an 'attach' change in the entity context.
-   * @param target Entity instance or its primary key value.
-   */
+  /**
+   * Returns the currently loaded items.
+   * @returns Array of target entities.
+   */
+  getItems(): TTarget[] {
+    return this.items;
+  }
+
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator](): Iterator<TTarget> {
+    return this.items[Symbol.iterator]();
+  }
+
+  /**
+   * Attaches an entity to the collection.
+   * Registers an 'attach' change in the entity context.
+   * @param target Entity instance or its primary key value.
+   */
   attach(target: TTarget | number | string): void {
     const entity = this.ensureEntity(target);
     const id = this.extractId(entity);

package/src/orm/save-graph-types.ts

@@ -10,8 +10,8 @@ type AnyFn = (...args: unknown[]) => unknown;
 
 type RelationWrapper =
   | HasManyCollection<unknown>
-  | HasOneReference<unknown>
-  | BelongsToReference<unknown>
+  | HasOneReference
+  | BelongsToReference
   | ManyToManyCollection<unknown>;
 
 type FunctionKeys<T> = {

package/src/orm/save-graph.ts

@@ -184,15 +184,15 @@ const handleHasMany = async (
   }
 };
 
-const handleHasOne = async (
-  session: OrmSession,
-  root: AnyEntity,
-  relationName: string,
-  relation: HasOneRelation,
-  payload: unknown,
-  options: SaveGraphOptions
-): Promise<void> => {
-  const ref = root[relationName] as unknown as HasOneReference<unknown>;
+const handleHasOne = async (
+  session: OrmSession,
+  root: AnyEntity,
+  relationName: string,
+  relation: HasOneRelation,
+  payload: unknown,
+  options: SaveGraphOptions
+): Promise<void> => {
+  const ref = root[relationName] as unknown as HasOneReference<object>;
   if (payload === undefined) return;
   if (payload === null) {
     ref.set(null);
@@ -212,15 +212,15 @@ const handleHasOne = async (
   }
 };
 
-const handleBelongsTo = async (
-  session: OrmSession,
-  root: AnyEntity,
-  relationName: string,
-  relation: BelongsToRelation,
-  payload: unknown,
-  options: SaveGraphOptions
-): Promise<void> => {
-  const ref = root[relationName] as unknown as BelongsToReference<unknown>;
+const handleBelongsTo = async (
+  session: OrmSession,
+  root: AnyEntity,
+  relationName: string,
+  relation: BelongsToRelation,
+  payload: unknown,
+  options: SaveGraphOptions
+): Promise<void> => {
+  const ref = root[relationName] as unknown as BelongsToReference<object>;
   if (payload === undefined) return;
   if (payload === null) {
     ref.set(null);

package/src/query-builder/relation-conditions.ts

@@ -1,10 +1,11 @@
-import { TableDef } from '../schema/table.js';
-import { RelationDef, RelationKinds, BelongsToManyRelation } from '../schema/relation.js';
-import { ExpressionNode, eq, and } from '../core/ast/expression.js';
-import { findPrimaryKey } from './hydration-planner.js';
-import { JoinNode } from '../core/ast/join.js';
-import { JoinKind } from '../core/sql/sql.js';
-import { createJoinNode } from '../core/ast/join-node.js';
+import { TableDef } from '../schema/table.js';
+import { RelationDef, RelationKinds, BelongsToManyRelation } from '../schema/relation.js';
+import { ExpressionNode, eq, and } from '../core/ast/expression.js';
+import { TableSourceNode } from '../core/ast/query.js';
+import { findPrimaryKey } from './hydration-planner.js';
+import { JoinNode } from '../core/ast/join.js';
+import { JoinKind } from '../core/sql/sql.js';
+import { createJoinNode } from '../core/ast/join-node.js';
 
 /**
  * Utility function to handle unreachable code paths
@@ -21,26 +22,32 @@ const assertNever = (value: never): never => {
  * @param relation - Relation definition
  * @returns Expression node representing the join condition
  */
-const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
-  const rootTable = rootAlias || root.name;
-  const defaultLocalKey =
-    relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne
-      ? findPrimaryKey(root)
-      : findPrimaryKey(relation.target);
+const baseRelationCondition = (
+  root: TableDef,
+  relation: RelationDef,
+  rootAlias?: string,
+  targetTableName?: string
+): ExpressionNode => {
+  const rootTable = rootAlias || root.name;
+  const targetTable = targetTableName ?? relation.target.name;
+  const defaultLocalKey =
+    relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne
+      ? findPrimaryKey(root)
+      : findPrimaryKey(relation.target);
   const localKey = relation.localKey || defaultLocalKey;
 
   switch (relation.type) {
-    case RelationKinds.HasMany:
-    case RelationKinds.HasOne:
-      return eq(
-        { type: 'Column', table: relation.target.name, name: relation.foreignKey },
-        { type: 'Column', table: rootTable, name: localKey }
-      );
-    case RelationKinds.BelongsTo:
-      return eq(
-        { type: 'Column', table: relation.target.name, name: localKey },
-        { type: 'Column', table: rootTable, name: relation.foreignKey }
-      );
+    case RelationKinds.HasMany:
+    case RelationKinds.HasOne:
+      return eq(
+        { type: 'Column', table: targetTable, name: relation.foreignKey },
+        { type: 'Column', table: rootTable, name: localKey }
+      );
+    case RelationKinds.BelongsTo:
+      return eq(
+        { type: 'Column', table: targetTable, name: localKey },
+        { type: 'Column', table: rootTable, name: relation.foreignKey }
+      );
     case RelationKinds.BelongsToMany:
       throw new Error('BelongsToMany relations do not support the standard join condition builder');
     default:
@@ -58,14 +65,16 @@ const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?
  * @param rootAlias - Optional alias for the root table
  * @returns Array of join nodes for the pivot and target tables
  */
-export const buildBelongsToManyJoins = (
-  root: TableDef,
-  relationName: string,
-  relation: BelongsToManyRelation,
-  joinKind: JoinKind,
-  extra?: ExpressionNode,
-  rootAlias?: string
-): JoinNode[] => {
+export const buildBelongsToManyJoins = (
+  root: TableDef,
+  relationName: string,
+  relation: BelongsToManyRelation,
+  joinKind: JoinKind,
+  extra?: ExpressionNode,
+  rootAlias?: string,
+  targetTable?: TableSourceNode,
+  targetTableName?: string
+): JoinNode[] => {
   const rootKey = relation.localKey || findPrimaryKey(root);
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const rootTable = rootAlias || root.name;
@@ -81,21 +90,27 @@ export const buildBelongsToManyJoins = (
     pivotCondition
   );
 
-  let targetCondition: ExpressionNode = eq(
-    { type: 'Column', table: relation.target.name, name: targetKey },
-    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
-  );
-
-  if (extra) {
-    targetCondition = and(targetCondition, extra);
-  }
-
-  const targetJoin = createJoinNode(
-    joinKind,
-    { type: 'Table', name: relation.target.name, schema: relation.target.schema },
-    targetCondition,
-    relationName
-  );
+  const targetSource: TableSourceNode = targetTable ?? {
+    type: 'Table',
+    name: relation.target.name,
+    schema: relation.target.schema
+  };
+  const effectiveTargetName = targetTableName ?? relation.target.name;
+  let targetCondition: ExpressionNode = eq(
+    { type: 'Column', table: effectiveTargetName, name: targetKey },
+    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
+  );
+
+  if (extra) {
+    targetCondition = and(targetCondition, extra);
+  }
+
+  const targetJoin = createJoinNode(
+    joinKind,
+    targetSource,
+    targetCondition,
+    relationName
+  );
 
   return [pivotJoin, targetJoin];
 };
@@ -108,15 +123,16 @@ export const buildBelongsToManyJoins = (
  * @param rootAlias - Optional alias for the root table
  * @returns Expression node representing the complete join condition
  */
-export const buildRelationJoinCondition = (
-  root: TableDef,
-  relation: RelationDef,
-  extra?: ExpressionNode,
-  rootAlias?: string
-): ExpressionNode => {
-  const base = baseRelationCondition(root, relation, rootAlias);
-  return extra ? and(base, extra) : base;
-};
+export const buildRelationJoinCondition = (
+  root: TableDef,
+  relation: RelationDef,
+  extra?: ExpressionNode,
+  rootAlias?: string,
+  targetTableName?: string
+): ExpressionNode => {
+  const base = baseRelationCondition(root, relation, rootAlias, targetTableName);
+  return extra ? and(base, extra) : base;
+};
 
 /**
  * Builds a relation correlation condition for subqueries
@@ -125,6 +141,11 @@ export const buildRelationJoinCondition = (
  * @param rootAlias - Optional alias for the root table
  * @returns Expression node representing the correlation condition
  */
-export const buildRelationCorrelation = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
-  return baseRelationCondition(root, relation, rootAlias);
-};
+export const buildRelationCorrelation = (
+  root: TableDef,
+  relation: RelationDef,
+  rootAlias?: string,
+  targetTableName?: string
+): ExpressionNode => {
+  return baseRelationCondition(root, relation, rootAlias, targetTableName);
+};