metal-orm 1.0.16 → 1.0.17

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/runtime-types.ts

@@ -1,39 +1,97 @@
 import { RelationDef } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
 
+/**
+ * Entity status enum representing the lifecycle state of an entity
+ */
 export enum EntityStatus {
+  /** Entity is newly created and not yet persisted */
   New = 'new',
+  /** Entity is managed by the ORM and synchronized with the database */
   Managed = 'managed',
+  /** Entity has been modified but not yet persisted */
   Dirty = 'dirty',
+  /** Entity has been marked for removal */
   Removed = 'removed',
+  /** Entity is detached from the ORM context */
   Detached = 'detached'
 }
 
+/**
+ * Represents an entity being tracked by the ORM
+ */
 export interface TrackedEntity {
+  /** The table definition this entity belongs to */
   table: TableDef;
+  /** The actual entity instance */
   entity: any;
+  /** Primary key value of the entity */
   pk: string | number | null;
+  /** Current status of the entity */
   status: EntityStatus;
+  /** Original values of the entity when it was loaded */
   original: Record<string, any> | null;
 }
 
+/**
+ * Type representing a key for relation navigation
+ */
 export type RelationKey = string;
 
+/**
+ * Represents a change operation on a relation
+ * @typeParam T - Type of the related entity
+ */
 export type RelationChange<T> =
   | { kind: 'add'; entity: T }
   | { kind: 'attach'; entity: T }
   | { kind: 'remove'; entity: T }
   | { kind: 'detach'; entity: T };
 
+/**
+ * Represents a relation change entry in the unit of work
+ */
 export interface RelationChangeEntry {
+  /** Root entity that owns the relation */
   root: any;
+  /** Key of the relation being changed */
   relationKey: RelationKey;
+  /** Table definition of the root entity */
   rootTable: TableDef;
+  /** Name of the relation */
   relationName: string;
+  /** Relation definition */
   relation: RelationDef;
+  /** The change being applied */
   change: RelationChange<any>;
 }
 
-export interface HasDomainEvents {
-  domainEvents?: any[];
+/**
+ * Represents a domain event that can be emitted by entities
+ * @typeParam TType - Type of the event (string literal)
+ */
+export interface DomainEvent<TType extends string = string> {
+  /** Type identifier for the event */
+  readonly type: TType;
+  /** Timestamp when the event occurred */
+  readonly occurredAt?: Date;
+}
+
+/**
+ * Type representing any domain event
+ */
+export type AnyDomainEvent = DomainEvent<string>;
+
+/**
+ * Type representing ORM-specific domain events
+ */
+export type OrmDomainEvent = AnyDomainEvent;
+
+/**
+ * Interface for entities that can emit domain events
+ * @typeParam E - Type of domain events this entity can emit
+ */
+export interface HasDomainEvents<E extends DomainEvent = AnyDomainEvent> {
+  /** Array of domain events emitted by this entity */
+  domainEvents?: E[];
 }

package/src/orm/transaction-runner.ts

@@ -1,5 +1,12 @@
 import type { DbExecutor } from '../core/execution/db-executor.js';
 
+/**
+ * Executes a function within a database transaction
+ * @param executor - Database executor to use for transaction operations
+ * @param action - Function to execute within the transaction
+ * @returns Promise that resolves when the transaction is complete
+ * @throws Re-throws any errors that occur during the transaction (after rolling back)
+ */
 export const runInTransaction = async (executor: DbExecutor, action: () => Promise<void>): Promise<void> => {
   if (!executor.beginTransaction) {
     await action();

package/src/orm/unit-of-work.ts

@@ -215,6 +215,7 @@ export class UnitOfWork {
   private extractColumns(table: TableDef, entity: any): Record<string, unknown> {
     const payload: Record<string, unknown> = {};
     for (const column of Object.keys(table.columns)) {
+      if (entity[column] === undefined) continue;
       payload[column] = entity[column];
     }
     return payload;

package/src/query-builder/insert-query-state.ts

@@ -1,6 +1,6 @@
 import { TableDef } from '../schema/table.js';
 import { InsertQueryNode, TableNode } from '../core/ast/query.js';
-import { ColumnNode, OperandNode, valueToOperand } from '../core/ast/expression.js';
+import { ColumnNode, OperandNode, isValueOperandInput, valueToOperand } from '../core/ast/expression.js';
 import { buildColumnNodes, createTableNode } from '../core/ast/builders.js';
 
 /**
@@ -31,8 +31,18 @@ export class InsertQueryState {
       ? this.ast.columns
       : buildColumnNodes(this.table, Object.keys(rows[0]));
 
-    const newRows: OperandNode[][] = rows.map(row =>
-      definedColumns.map(column => valueToOperand(row[column.name]))
+    const newRows: OperandNode[][] = rows.map((row, rowIndex) =>
+      definedColumns.map(column => {
+        const rawValue = row[column.name];
+
+        if (!isValueOperandInput(rawValue)) {
+          throw new Error(
+            `Invalid insert value for column "${column.name}" in row ${rowIndex}: only primitives, null, or OperandNodes are allowed`
+          );
+        }
+
+        return valueToOperand(rawValue);
+      })
     );
 
     return this.clone({

package/src/query-builder/select-helpers.ts

@@ -0,0 +1,50 @@
+import type { TableDef } from '../schema/table.js';
+import type { ColumnDef } from '../schema/column.js';
+import { getTableDefFromEntity } from '../decorators/bootstrap.js';
+
+/**
+ * Build a typed selection map from a TableDef.
+ */
+export function sel<
+  TTable extends TableDef,
+  K extends keyof TTable['columns'] & string
+>(table: TTable, ...cols: K[]): Record<K, TTable['columns'][K]> {
+  const selection = {} as Record<K, TTable['columns'][K]>;
+
+  for (const col of cols) {
+    const def = table.columns[col] as TTable['columns'][K];
+    if (!def) {
+      throw new Error(`Column '${col}' not found on table '${table.name}'`);
+    }
+    selection[col] = def;
+  }
+
+  return selection;
+}
+
+type Ctor<T> = { new (...args: any[]): T };
+
+/**
+ * Build a typed selection map from an entity constructor.
+ */
+export function esel<TEntity, K extends keyof TEntity & string>(
+  entity: Ctor<TEntity>,
+  ...props: K[]
+): Record<K, ColumnDef> {
+  const table = getTableDefFromEntity(entity) as TableDef | undefined;
+  if (!table) {
+    throw new Error(`No table definition registered for entity '${entity.name}'`);
+  }
+
+  const selection = {} as Record<K, ColumnDef>;
+
+  for (const prop of props) {
+    const col = table.columns[prop];
+    if (!col) {
+      throw new Error(`No column '${prop}' found for entity '${entity.name}'`);
+    }
+    selection[prop] = col;
+  }
+
+  return selection;
+}

package/src/query-builder/select.ts

@@ -54,15 +54,17 @@ import {
 
 import { QueryAstService } from './query-ast-service.js';
 
-import { ColumnSelector } from './column-selector.js';
-
-import { RelationManager } from './relation-manager.js';
-
-import { RelationIncludeOptions } from './relation-types.js';
-
-import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
-
-import { Entity, RelationMap } from '../schema/types.js';
+import { ColumnSelector } from './column-selector.js';
+
+import { RelationManager } from './relation-manager.js';
+
+import { RelationIncludeOptions } from './relation-types.js';
+
+import type { RelationDef } from '../schema/relation.js';
+
+import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
+
+import { Entity, RelationMap, RelationTargetTable } from '../schema/types.js';
 
 import { OrmSession } from '../orm/orm-session.ts';
 
@@ -72,11 +74,21 @@ import { HydrationContext } from '../orm/hydration-context.js';
 
 import { executeHydrated, executeHydratedWithContexts } from '../orm/execute.js';
 
-import { createJoinNode } from '../core/ast/join-node.js';
-
-
-
-/**
+import { createJoinNode } from '../core/ast/join-node.js';
+
+
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+
+type DeepSelectConfig<TTable extends TableDef> = {
+  root?: (keyof TTable['columns'] & string)[];
+} & {
+  [K in keyof TTable['relations'] & string]?: (
+    keyof RelationTargetTable<TTable['relations'][K]>['columns'] & string
+  )[];
+};
+
+
+/**
 
  * Main query builder class for constructing SQL SELECT queries
 
@@ -252,12 +264,31 @@ export class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
 
    */
 
-  select(columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>): SelectQueryBuilder<T, TTable> {
-
-    return this.clone(this.columnSelector.select(this.context, columns));
-
-  }
-
+  select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable> {
+
+    return this.clone(this.columnSelector.select(this.context, columns));
+
+  }
+
+
+  /**
+   * Selects columns from the root table by name (typed).
+   * @param cols - Column names on the root table
+   */
+  selectColumns<K extends keyof TTable['columns'] & string>(...cols: K[]): SelectQueryBuilder<T, TTable> {
+    const selection: Record<string, ColumnDef> = {};
+
+    for (const key of cols) {
+      const col = this.env.table.columns[key];
+      if (!col) {
+        throw new Error(`Column '${key}' not found on table '${this.env.table.name}'`);
+      }
+      selection[key] = col;
+    }
+
+    return this.select(selection);
+  }
+
 
 
   /**
@@ -494,16 +525,77 @@ export class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
 
 
 
-  includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable> {
-
-    const nextLazy = new Set(this.lazyRelations);
-
-    nextLazy.add(relationName as string);
-
-    return this.clone(this.context, nextLazy);
-
-  }
-
+  includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable> {
+
+    const nextLazy = new Set(this.lazyRelations);
+
+    nextLazy.add(relationName as string);
+
+    return this.clone(this.context, nextLazy);
+
+  }
+
+  /**
+   * Selects columns for a related table in a single hop.
+   */
+  selectRelationColumns<
+    K extends keyof TTable['relations'] & string,
+    TRel extends RelationDef = TTable['relations'][K],
+    TTarget extends TableDef = RelationTargetTable<TRel>,
+    C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string
+  >(relationName: K, ...cols: C[]): SelectQueryBuilder<T, TTable> {
+    const relation = this.env.table.relations[relationName] as RelationDef | undefined;
+    if (!relation) {
+      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
+    }
+    const target = relation.target;
+
+    for (const col of cols) {
+      if (!target.columns[col]) {
+        throw new Error(
+          `Column '${col}' not found on related table '${target.name}' for relation '${relationName}'`
+        );
+      }
+    }
+
+    return this.include(relationName as string, { columns: cols as string[] });
+  }
+
+
+  /**
+   * Convenience alias for selecting specific columns from a relation.
+   */
+  includePick<
+    K extends keyof TTable['relations'] & string,
+    TRel extends RelationDef = TTable['relations'][K],
+    TTarget extends TableDef = RelationTargetTable<TRel>,
+    C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string
+  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
+    return this.selectRelationColumns(relationName, ...cols);
+  }
+
+
+  /**
+   * Selects columns for the root table and relations from a single config object.
+   */
+  selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable> {
+    let qb: SelectQueryBuilder<T, TTable> = this;
+
+    if (config.root?.length) {
+      qb = qb.selectColumns(...config.root);
+    }
+
+    for (const key of Object.keys(config) as (keyof typeof config)[]) {
+      if (key === 'root') continue;
+      const relName = key as keyof TTable['relations'] & string;
+      const cols = config[relName as keyof DeepSelectConfig<TTable>] as string[] | undefined;
+      if (!cols || !cols.length) continue;
+      qb = qb.selectRelationColumns(relName, ...(cols as string[]));
+    }
+
+    return qb;
+  }
+
 
 
   getLazyRelations(): (keyof RelationMap<TTable>)[] {

package/src/query-builder/update-query-state.ts

@@ -1,7 +1,21 @@
 import { TableDef } from '../schema/table.js';
-import { ColumnNode, ExpressionNode, valueToOperand } from '../core/ast/expression.js';
+import { ColumnNode, ExpressionNode, OperandNode, isOperandNode, valueToOperand } from '../core/ast/expression.js';
 import { TableNode, UpdateQueryNode, UpdateAssignmentNode } from '../core/ast/query.js';
 import { createTableNode } from '../core/ast/builders.js';
+type LiteralValue = string | number | boolean | null;
+type UpdateValue = OperandNode | LiteralValue;
+
+const isUpdateValue = (value: unknown): value is UpdateValue => {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return true;
+    default:
+      return isOperandNode(value);
+  }
+};
 
 /**
  * Immutable state for UPDATE queries
@@ -24,14 +38,22 @@ export class UpdateQueryState {
   }
 
   withSet(values: Record<string, unknown>): UpdateQueryState {
-    const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, value]) => ({
-      column: {
-        type: 'Column',
-        table: this.table.name,
-        name: column
-      },
-      value: valueToOperand(value)
-    }));
+    const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, rawValue]) => {
+      if (!isUpdateValue(rawValue)) {
+        throw new Error(
+          `Invalid update value for column "${column}": only primitives, null, or OperandNodes are allowed`
+        );
+      }
+
+      return {
+        column: {
+          type: 'Column',
+          table: this.table.name,
+          name: column
+        },
+        value: valueToOperand(rawValue)
+      };
+    });
 
     return this.clone({
       ...this.ast,

package/src/schema/types.ts

@@ -1,5 +1,5 @@
-import { ColumnDef } from './column.js';
-import { TableDef } from './table.js';
+import { ColumnDef } from './column.js';
+import { TableDef } from './table.js';
 import {
   RelationDef,
   HasManyRelation,
@@ -7,10 +7,20 @@ import {
   BelongsToRelation,
   BelongsToManyRelation
 } from './relation.js';
-
-/**
- * Maps a ColumnDef to its TypeScript type representation
- */
+
+/**
+ * Resolves a relation definition to its target table type.
+ */
+export type RelationTargetTable<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget> ? TTarget :
+  TRel extends HasOneRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToManyRelation<infer TTarget> ? TTarget :
+  never;
+
+/**
+ * Maps a ColumnDef to its TypeScript type representation
+ */
 export type ColumnToTs<T extends ColumnDef> =
   T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
   T['type'] extends 'BIGINT' | 'bigint' ? number | bigint :