metal-orm 1.0.43 → 1.0.45

package/src/orm/lazy-batch.ts

@@ -7,14 +7,32 @@ import type { QueryResult } from '../core/execution/db-executor.js';
 import { ColumnDef } from '../schema/column.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) {
@@ -30,14 +48,115 @@ const rowsFromResults = (results: QueryResult[]): Rows => {
   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,
@@ -46,41 +165,27 @@ export const loadHasManyRelation = async (
 ): Promise<Map<string, Rows>> => {
   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);
-    }
-  }
+  const keys = collectKeysFromRoots(roots, localKey);
 
   if (!keys.size) {
     return new Map();
   }
 
-  const selectMap = selectAllColumns(relation.target);
-  const fb = new SelectQueryBuilder(relation.target).select(selectMap);
   const fkColumn = relation.target.columns[relation.foreignKey];
   if (!fkColumn) return new Map();
 
-  fb.where(inList(fkColumn, Array.from(keys) as (string | number | LiteralNode)[]));
-
-  const rows = await executeQuery(ctx, fb);
-  const grouped = new Map<string, Rows>();
-
-  for (const row of rows) {
-    const fkValue = row[relation.foreignKey];
-    if (fkValue === null || fkValue === undefined) continue;
-    const key = toKey(fkValue);
-    const bucket = grouped.get(key) ?? [];
-    bucket.push(row);
-    grouped.set(key, bucket);
-  }
-
-  return grouped;
+  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,
@@ -89,41 +194,27 @@ export const loadHasOneRelation = async (
 ): Promise<Map<string, Record<string, unknown>>> => {
   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);
-    }
-  }
+  const keys = collectKeysFromRoots(roots, localKey);
 
   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, unknown>>();
-
-  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;
+  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,
@@ -131,38 +222,28 @@ export const loadBelongsToRelation = async (
   relation: BelongsToRelation
 ): Promise<Map<string, Record<string, unknown>>> => {
   const roots = ctx.getEntitiesForTable(rootTable);
-  const foreignKeys = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[relation.foreignKey];
-    if (value !== null && value !== undefined) {
-      foreignKeys.add(value);
-    }
-  }
+  const foreignKeys = collectKeysFromRoots(roots, relation.foreignKey);
 
   if (!foreignKeys.size) {
     return new Map();
   }
 
-  const selectMap = selectAllColumns(relation.target);
-  const qb = new SelectQueryBuilder(relation.target).select(selectMap);
   const targetKey = relation.localKey || findPrimaryKey(relation.target);
   const pkColumn = relation.target.columns[targetKey];
   if (!pkColumn) return new Map();
 
-  qb.where(inList(pkColumn, Array.from(foreignKeys) as (string | number | LiteralNode)[]));
-  const rows = await executeQuery(ctx, qb);
-  const map = new Map<string, Record<string, unknown>>();
-
-  for (const row of rows) {
-    const keyValue = row[targetKey];
-    if (keyValue === null || keyValue === undefined) continue;
-    map.set(toKey(keyValue), row);
-  }
-
-  return 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,
@@ -171,27 +252,16 @@ export const loadBelongsToManyRelation = async (
 ): Promise<Map<string, Rows>> => {
   const rootKey = relation.localKey || findPrimaryKey(rootTable);
   const roots = ctx.getEntitiesForTable(rootTable);
-  const rootIds = new Set<unknown>();
-
-  for (const tracked of roots) {
-    const value = tracked.entity[rootKey];
-    if (value !== null && value !== undefined) {
-      rootIds.add(value);
-    }
-  }
+  const rootIds = collectKeysFromRoots(roots, rootKey);
 
   if (!rootIds.size) {
     return new Map();
   }
 
-  const pivotSelect = selectAllColumns(relation.pivotTable);
-  const pivotQb = new SelectQueryBuilder(relation.pivotTable).select(pivotSelect);
-  const pivotFkCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
-  if (!pivotFkCol) return new Map();
-
-  pivotQb.where(inList(pivotFkCol, Array.from(rootIds) as (string | number | LiteralNode)[]));
-  const pivotRows = await executeQuery(ctx, pivotQb);
+  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>();
 
@@ -214,22 +284,12 @@ export const loadBelongsToManyRelation = async (
     return new Map();
   }
 
-  const targetSelect = selectAllColumns(relation.target);
   const targetKey = relation.targetKey || findPrimaryKey(relation.target);
   const targetPkColumn = relation.target.columns[targetKey];
   if (!targetPkColumn) return new Map();
 
-  const targetQb = new SelectQueryBuilder(relation.target).select(targetSelect);
-  targetQb.where(inList(targetPkColumn, Array.from(targetIds) as (string | number | LiteralNode)[]));
-  const targetRows = await executeQuery(ctx, targetQb);
-  const targetMap = new Map<string, Record<string, unknown>>();
-
-  for (const row of targetRows) {
-    const pkValue = row[targetKey];
-    if (pkValue === null || pkValue === undefined) continue;
-    targetMap.set(toKey(pkValue), row);
-  }
-
+  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()) {

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

@@ -20,12 +20,28 @@ const hideInternal = (obj: object, keys: string[]): void => {
   }
 };
 
+/**
+ * Default implementation of HasManyCollection for managing one-to-many relationships.
+ * @template TChild - The type of child entities in the collection
+ */
 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>();
 
+  /**
+   * Creates a new DefaultHasManyCollection instance.
+   * @param ctx - The entity context
+   * @param meta - The entity metadata
+   * @param root - The root entity
+   * @param relationName - The relation name
+   * @param relation - The relation definition
+   * @param rootTable - The root table definition
+   * @param loader - The loader function for lazy loading
+   * @param createEntity - Function to create entities from rows
+   * @param localKey - The local key for the relation
+   */
   constructor(
     private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<TableDef>,
@@ -41,6 +57,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.hydrateFromCache();
   }
 
+  /**
+   * Loads the related entities if not already loaded.
+   * @returns Promise resolving to the array of child entities
+   */
   async load(): Promise<TChild[]> {
     if (this.loaded) return this.items;
     const map = await this.loader();
@@ -51,10 +71,19 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return this.items;
   }
 
+  /**
+   * Gets the current items in the collection.
+   * @returns Array of child entities
+   */
   getItems(): TChild[] {
     return this.items;
   }
 
+  /**
+   * Adds a new child entity to the collection.
+   * @param data - Partial data for the new entity
+   * @returns The created entity
+   */
   add(data: Partial<TChild>): TChild {
     const keyValue = (this.root as Record<string, unknown>)[this.localKey];
     const childRow: Record<string, unknown> = {
@@ -75,6 +104,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return entity;
   }
 
+  /**
+   * Attaches an existing entity to the collection.
+   * @param entity - The entity to attach
+   */
   attach(entity: TChild): void {
     const keyValue = this.root[this.localKey];
     (entity as Record<string, unknown>)[this.relation.foreignKey] = keyValue;
@@ -90,6 +123,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     );
   }
 
+  /**
+   * Removes an entity from the collection.
+   * @param entity - The entity to remove
+   */
   remove(entity: TChild): void {
     this.items = this.items.filter(item => item !== entity);
     this.removed.add(entity);
@@ -103,6 +140,9 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     );
   }
 
+  /**
+   * Clears all entities from the collection.
+   */
   clear(): void {
     for (const entity of [...this.items]) {
       this.remove(entity);
@@ -122,6 +162,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.loaded = true;
   }
 
+  /**
+   * Returns the items for JSON serialization.
+   * @returns Array of child entities
+   */
   toJSON(): TChild[] {
     return this.items;
   }

package/src/orm/save-graph.ts

@@ -20,13 +20,30 @@ import type { EntityConstructor } from './entity-metadata.js';
 import { getTableDefFromEntity } from '../decorators/bootstrap.js';
 import type { OrmSession } from './orm-session.js';
 
+/**
+ * Options for controlling the behavior of save graph operations.
+ */
 export interface SaveGraphOptions {
   /** Remove existing collection members that are not present in the payload */
   pruneMissing?: boolean;
 }
 
+/** Represents an entity object with arbitrary properties. */
+
+/** Represents an entity object with arbitrary properties. */
+
 type AnyEntity = Record<string, unknown>;
 
+/**
+
+ * Converts a value to a string key, returning an empty string for null or undefined.
+
+ * @param value - The value to convert.
+
+ * @returns The string representation or empty string.
+
+ */
+
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
 
 const pickColumns = (table: TableDef, payload: AnyEntity): Record<string, unknown> => {
@@ -292,18 +309,46 @@ export const saveGraph = async <TTable extends TableDef>(
   return root;
 };
 
+/**
+
+ * Internal version of saveGraph with typed return based on the constructor.
+
+ * @param session - The ORM session.
+
+ * @param entityClass - The entity constructor.
+
+ * @param payload - The payload data for the root entity and its relations.
+
+ * @param options - Options for the save operation.
+
+ * @returns The root entity instance.
+
+ */
+
 export const saveGraphInternal = async <TCtor extends EntityConstructor>(
+
   session: OrmSession,
+
   entityClass: TCtor,
+
   payload: AnyEntity,
+
   options: SaveGraphOptions = {}
+
 ): Promise<InstanceType<TCtor>> => {
+
   const table = getTableDefFromEntity(entityClass);
+
   if (!table) {
+
     throw new Error('Entity metadata has not been bootstrapped');
+
   }
 
   const root = ensureEntity(session, table, payload);
+
   await applyGraphToEntity(session, table, root as AnyEntity, payload, options);
+
   return root as unknown as InstanceType<TCtor>;
+
 };

package/src/query/index.ts

@@ -0,0 +1,74 @@
+import { TableDef } from '../schema/table.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { InsertQueryBuilder } from '../query-builder/insert.js';
+import { UpdateQueryBuilder } from '../query-builder/update.js';
+import { DeleteQueryBuilder } from '../query-builder/delete.js';
+import { QueryTarget, resolveTable } from './target.js';
+
+/**
+ * Creates a SELECT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to query from
+ * @returns A new SelectQueryBuilder instance for building SELECT queries
+ *
+ * @example
+ * ```typescript
+ * const query = selectFrom(UserTable).select('id', 'name');
+ * ```
+ */
+export const selectFrom = <TTable extends TableDef>(target: QueryTarget<TTable>): SelectQueryBuilder<unknown, TTable> => {
+    const table = resolveTable(target);
+    return new SelectQueryBuilder(table);
+};
+
+/**
+ * Creates an INSERT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to insert into
+ * @returns A new InsertQueryBuilder instance for building INSERT queries
+ *
+ * @example
+ * ```typescript
+ * const query = insertInto(UserTable).values({ name: 'John', email: 'john@example.com' });
+ * ```
+ */
+export const insertInto = <TTable extends TableDef>(target: QueryTarget<TTable>): InsertQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new InsertQueryBuilder(table);
+};
+
+/**
+ * Creates an UPDATE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to update
+ * @returns A new UpdateQueryBuilder instance for building UPDATE queries
+ *
+ * @example
+ * ```typescript
+ * const query = update(UserTable).set({ name: 'Jane' }).where(eq(UserTable.id, 1));
+ * ```
+ */
+export const update = <TTable extends TableDef>(target: QueryTarget<TTable>): UpdateQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new UpdateQueryBuilder(table);
+};
+
+/**
+ * Creates a DELETE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to delete from
+ * @returns A new DeleteQueryBuilder instance for building DELETE queries
+ *
+ * @example
+ * ```typescript
+ * const query = deleteFrom(UserTable).where(eq(UserTable.id, 1));
+ * ```
+ */
+export const deleteFrom = <TTable extends TableDef>(target: QueryTarget<TTable>): DeleteQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new DeleteQueryBuilder(table);
+};

package/src/query/target.ts

@@ -0,0 +1,46 @@
+import { TableDef } from '../schema/table.js';
+import { isTableDef } from '../schema/table-guards.js';
+import { EntityConstructor } from '../orm/entity-metadata.js';
+import { getTableDefFromEntity } from '../decorators/bootstrap.js';
+
+/**
+ * Represents a target for query operations, which can be either a table definition
+ * or an entity constructor. This type allows flexible targeting of database tables
+ * through either direct table definitions or entity classes decorated with ORM metadata.
+ *
+ * @template TTable - The table definition type, defaults to TableDef
+ */
+export type QueryTarget<TTable extends TableDef = TableDef> = TTable | EntityConstructor;
+
+const resolveEntityTarget = <TTable extends TableDef>(ctor: EntityConstructor): TTable => {
+    const table = getTableDefFromEntity(ctor);
+    if (!table) {
+        throw new Error(`Entity '${ctor.name}' is not registered with decorators`);
+    }
+    return table as TTable;
+};
+
+/**
+ * Resolves a QueryTarget to its corresponding table definition.
+ *
+ * If the target is already a TableDef, it returns it directly.
+ * If the target is an EntityConstructor, it retrieves the associated table definition
+ * from the entity's metadata.
+ *
+ * @template TTable - The table definition type
+ * @param target - The query target to resolve
+ * @returns The resolved table definition
+ * @throws Error if the entity constructor is not registered with decorators
+ *
+ * @example
+ * ```typescript
+ * const table = resolveTable(UserTable); // Returns UserTable directly
+ * const table2 = resolveTable(UserEntity); // Returns table def from UserEntity metadata
+ * ```
+ */
+export const resolveTable = <TTable extends TableDef>(target: QueryTarget<TTable>): TTable => {
+    if (isTableDef(target)) {
+        return target as TTable;
+    }
+    return resolveEntityTarget(target as EntityConstructor);
+};