metal-orm 1.0.55 → 1.0.57

package/src/core/functions/standard-strategy.ts

@@ -1,131 +1,102 @@
+
 import { FunctionStrategy, FunctionRenderer, FunctionRenderContext } from './types.js';
-import { LiteralNode, OperandNode, isOperandNode } from '../ast/expression.js';
+import type { LiteralNode, OperandNode } from '../ast/expression.js';
+import { FunctionRegistry } from './function-registry.js';
+import type { FunctionDefinition } from './function-registry.js';
+import { aggregateFunctionDefinitions } from './definitions/aggregate.js';
+import { stringFunctionDefinitions } from './definitions/string.js';
+import { dateTimeFunctionDefinitions } from './definitions/datetime.js';
+import { numericFunctionDefinitions } from './definitions/numeric.js';
+import { controlFlowFunctionDefinitions } from './definitions/control-flow.js';
+import { jsonFunctionDefinitions } from './definitions/json.js';
+import {
+  renderStandardGroupConcat,
+  buildGroupConcatOrderBy as buildGroupConcatOrderByClause,
+  formatGroupConcatSeparator as formatGroupConcatSeparatorClause,
+  getGroupConcatSeparatorOperand as resolveGroupConcatSeparatorOperand,
+  DEFAULT_GROUP_CONCAT_SEPARATOR as DEFAULT_GROUP_CONCAT_SEPARATOR_LITERAL
+} from './group-concat-helpers.js';
 
 /**
  * Standard implementation of FunctionStrategy for ANSI SQL functions.
  */
 export class StandardFunctionStrategy implements FunctionStrategy {
-    protected renderers: Map<string, FunctionRenderer> = new Map();
+  protected readonly registry: FunctionRegistry;
+
+  /**
+   * Creates a new StandardFunctionStrategy and registers standard functions.
+   */
+  constructor(registry?: FunctionRegistry) {
+    this.registry = registry ?? new FunctionRegistry();
+    this.registerStandard();
+  }
 
-    /**
-     * Creates a new StandardFunctionStrategy and registers standard functions.
-     */
-    constructor() {
-        this.registerStandard();
-    }
+  protected registerStandard(): void {
+    this.registerDefinitions(aggregateFunctionDefinitions);
+    this.registerDefinitions(stringFunctionDefinitions);
+    this.registerDefinitions(dateTimeFunctionDefinitions);
+    this.registerDefinitions(numericFunctionDefinitions);
+    this.registerDefinitions(controlFlowFunctionDefinitions);
+    this.registerDefinitions(jsonFunctionDefinitions);
+    this.add('GROUP_CONCAT', ctx => this.renderGroupConcat(ctx));
+  }
 
-    protected registerStandard() {
-        // Register ANSI standard implementations
-        this.add('COUNT', ({ compiledArgs }) => compiledArgs.length ? `COUNT(${compiledArgs.join(', ')})` : 'COUNT(*)');
-        this.add('SUM', ({ compiledArgs }) => `SUM(${compiledArgs[0]})`);
-        this.add('AVG', ({ compiledArgs }) => `AVG(${compiledArgs[0]})`);
-        this.add('MIN', ({ compiledArgs }) => `MIN(${compiledArgs[0]})`);
-        this.add('MAX', ({ compiledArgs }) => `MAX(${compiledArgs[0]})`);
-        this.add('ABS', ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
-        this.add('UPPER', ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
-        this.add('LOWER', ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
-        this.add('LENGTH', ({ compiledArgs }) => `LENGTH(${compiledArgs[0]})`);
-        this.add('TRIM', ({ compiledArgs }) => `TRIM(${compiledArgs[0]})`);
-        this.add('LTRIM', ({ compiledArgs }) => `LTRIM(${compiledArgs[0]})`);
-        this.add('RTRIM', ({ compiledArgs }) => `RTRIM(${compiledArgs[0]})`);
-        this.add('SUBSTRING', ({ compiledArgs }) => `SUBSTRING(${compiledArgs.join(', ')})`);
-        this.add('CONCAT', ({ compiledArgs }) => `CONCAT(${compiledArgs.join(', ')})`);
-        this.add('NOW', () => `NOW()`);
-        this.add('CURRENT_DATE', () => `CURRENT_DATE`);
-        this.add('CURRENT_TIME', () => `CURRENT_TIME`);
-        this.add('EXTRACT', ({ compiledArgs }) => `EXTRACT(${compiledArgs[0]} FROM ${compiledArgs[1]})`);
-        this.add('YEAR', ({ compiledArgs }) => `EXTRACT(YEAR FROM ${compiledArgs[0]})`);
-        this.add('MONTH', ({ compiledArgs }) => `EXTRACT(MONTH FROM ${compiledArgs[0]})`);
-        this.add('DAY', ({ compiledArgs }) => `EXTRACT(DAY FROM ${compiledArgs[0]})`);
-        this.add('DATE_ADD', ({ compiledArgs }) => `(${compiledArgs[0]} + INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
-        this.add('DATE_SUB', ({ compiledArgs }) => `(${compiledArgs[0]} - INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
-        this.add('DATE_DIFF', ({ compiledArgs }) => `DATEDIFF(${compiledArgs[0]}, ${compiledArgs[1]})`);
-        this.add('DATE_FORMAT', ({ compiledArgs }) => `DATE_FORMAT(${compiledArgs[0]}, ${compiledArgs[1]})`);
-        this.add('UNIX_TIMESTAMP', () => `UNIX_TIMESTAMP()`);
-        this.add('FROM_UNIXTIME', ({ compiledArgs }) => `FROM_UNIXTIME(${compiledArgs[0]})`);
-        this.add('END_OF_MONTH', ({ compiledArgs }) => `LAST_DAY(${compiledArgs[0]})`);
-        this.add('DAY_OF_WEEK', ({ compiledArgs }) => `DAYOFWEEK(${compiledArgs[0]})`);
-        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
-        this.add('DATE_TRUNC', ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
-        this.add('GROUP_CONCAT', ctx => this.renderGroupConcat(ctx));
-    }
+  protected registerDefinitions(definitions: FunctionDefinition[]): void {
+    this.registry.register(definitions);
+  }
 
-    /**
-     * Registers a renderer for a function name.
-     * @param name - The function name.
-     * @param renderer - The renderer function.
-     */
-    protected add(name: string, renderer: FunctionRenderer) {
-        this.renderers.set(name, renderer);
-    }
+  /**
+   * Registers a renderer for a function name.
+   * @param name - The function name.
+   * @param renderer - The renderer function.
+   */
+  protected add(name: string, renderer: FunctionRenderer): void {
+    this.registry.add(name, renderer);
+  }
 
-    /**
-     * @inheritDoc
-     */
-    getRenderer(name: string): FunctionRenderer | undefined {
-        return this.renderers.get(name);
-    }
+  /**
+   * @inheritDoc
+   */
+  getRenderer(name: string): FunctionRenderer | undefined {
+    return this.registry.get(name);
+  }
 
-    /**
-     * Renders the GROUP_CONCAT function with optional ORDER BY and SEPARATOR.
-     * @param ctx - The function render context.
-     * @returns The rendered SQL string.
-     */
-    private renderGroupConcat(ctx: FunctionRenderContext): string {
-        const arg = ctx.compiledArgs[0];
-        const orderClause = this.buildOrderByExpression(ctx);
-        const orderSegment = orderClause ? ` ${orderClause}` : '';
-        const separatorClause = this.formatGroupConcatSeparator(ctx);
-        return `GROUP_CONCAT(${arg}${orderSegment}${separatorClause})`;
-    }
+  /**
+   * Renders the GROUP_CONCAT function with optional ORDER BY and SEPARATOR.
+   * @param ctx - The function render context.
+   * @returns The rendered SQL string.
+   */
+  private renderGroupConcat(ctx: FunctionRenderContext): string {
+    return renderStandardGroupConcat(ctx);
+  }
 
-    /**
-     * Builds the ORDER BY clause for functions like GROUP_CONCAT.
-     * @param ctx - The function render context.
-     * @returns The ORDER BY SQL clause or empty string.
-     */
-    protected buildOrderByExpression(ctx: FunctionRenderContext): string {
-        const orderBy = ctx.node.orderBy;
-        if (!orderBy || orderBy.length === 0) {
-            return '';
-        }
-        const parts = orderBy.map(order => {
-            const term = isOperandNode(order.term)
-                ? ctx.compileOperand(order.term)
-                : (() => {
-                    throw new Error('ORDER BY expressions inside functions must be operands');
-                })();
-            const collation = order.collation ? ` COLLATE ${order.collation}` : '';
-            const nulls = order.nulls ? ` NULLS ${order.nulls}` : '';
-            return `${term} ${order.direction}${collation}${nulls}`;
-        });
-        return `ORDER BY ${parts.join(', ')}`;
-    }
+  /**
+   * Builds the ORDER BY clause for functions like GROUP_CONCAT.
+   * @param ctx - The function render context.
+   * @returns The ORDER BY SQL clause or empty string.
+   */
+  protected buildOrderByExpression(ctx: FunctionRenderContext): string {
+    return buildGroupConcatOrderByClause(ctx);
+  }
 
-    /**
-     * Formats the SEPARATOR clause for GROUP_CONCAT.
-     * @param ctx - The function render context.
-     * @returns The SEPARATOR SQL clause or empty string.
-     */
-    protected formatGroupConcatSeparator(ctx: FunctionRenderContext): string {
-        if (!ctx.node.separator) {
-            return '';
-        }
-        return ` SEPARATOR ${ctx.compileOperand(ctx.node.separator)}`;
-    }
+  /**
+   * Formats the SEPARATOR clause for GROUP_CONCAT.
+   * @param ctx - The function render context.
+   * @returns The SEPARATOR SQL clause or empty string.
+   */
+  protected formatGroupConcatSeparator(ctx: FunctionRenderContext): string {
+    return formatGroupConcatSeparatorClause(ctx);
+  }
 
-    /**
-     * Gets the separator operand for GROUP_CONCAT, defaulting to comma.
-     * @param ctx - The function render context.
-     * @returns The separator operand.
-     */
-    protected getGroupConcatSeparatorOperand(ctx: FunctionRenderContext): OperandNode {
-        return ctx.node.separator ?? StandardFunctionStrategy.DEFAULT_GROUP_CONCAT_SEPARATOR;
-    }
+  /**
+   * Gets the separator operand for GROUP_CONCAT, defaulting to comma.
+   * @param ctx - The function render context.
+   * @returns The separator operand.
+   */
+  protected getGroupConcatSeparatorOperand(ctx: FunctionRenderContext): OperandNode {
+    return resolveGroupConcatSeparatorOperand(ctx);
+  }
 
-    /** Default separator for GROUP_CONCAT, a comma. */
-    protected static readonly DEFAULT_GROUP_CONCAT_SEPARATOR: LiteralNode = {
-        type: 'Literal',
-        value: ','
-    };
+  /** Default separator for GROUP_CONCAT, a comma. */
+  protected static readonly DEFAULT_GROUP_CONCAT_SEPARATOR: LiteralNode = DEFAULT_GROUP_CONCAT_SEPARATOR_LITERAL;
 }

package/src/core/functions/standard-table-strategy.ts

@@ -0,0 +1,13 @@
+import type { TableFunctionRenderer, TableFunctionStrategy } from './table-types.js';
+
+export class StandardTableFunctionStrategy implements TableFunctionStrategy {
+  protected renderers: Map<string, TableFunctionRenderer> = new Map();
+
+  protected add(key: string, renderer: TableFunctionRenderer) {
+    this.renderers.set(key, renderer);
+  }
+
+  getRenderer(key: string): TableFunctionRenderer | undefined {
+    return this.renderers.get(key);
+  }
+}

package/src/core/functions/table-types.ts

@@ -0,0 +1,15 @@
+import type { OperandNode } from '../ast/expression.js';
+import type { FunctionTableNode } from '../ast/query.js';
+
+export interface TableFunctionRenderContext {
+  node: FunctionTableNode;
+  compiledArgs: string[];
+  compileOperand: (operand: OperandNode) => string;
+  quoteIdentifier: (id: string) => string;
+}
+
+export type TableFunctionRenderer = (ctx: TableFunctionRenderContext) => string;
+
+export interface TableFunctionStrategy {
+  getRenderer(key: string): TableFunctionRenderer | undefined;
+}

package/src/core/functions/text.ts

@@ -208,3 +208,60 @@ export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput):
  */
 export const space = (count: OperandInput): FunctionNode => fn('SPACE', [count]);
 
+/**
+ * Reverses a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the REVERSE SQL function.
+ */
+export const reverse = (value: OperandInput): FunctionNode => fn('REVERSE', [value]);
+
+/**
+ * Capitalizes the first letter of each word in a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the INITCAP SQL function.
+ */
+export const initcap = (value: OperandInput): FunctionNode => fn('INITCAP', [value]);
+
+/**
+ * Returns the MD5 hash of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the MD5 SQL function.
+ */
+export const md5 = (value: OperandInput): FunctionNode => fn('MD5', [value]);
+
+/**
+ * Returns the SHA-1 hash of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the SHA1 SQL function.
+ */
+export const sha1 = (value: OperandInput): FunctionNode => fn('SHA1', [value]);
+
+/**
+ * Returns the SHA-2 hash of a string with a specified bit length.
+ * @param value - The string value.
+ * @param bits - The bit length (e.g., 224, 256, 384, 512).
+ * @returns A FunctionNode representing the SHA2 SQL function.
+ */
+export const sha2 = (value: OperandInput, bits: OperandInput): FunctionNode => fn('SHA2', [value, bits]);
+
+/**
+ * Returns the length of a string in bits.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the BIT_LENGTH SQL function.
+ */
+export const bitLength = (value: OperandInput): FunctionNode => fn('BIT_LENGTH', [value]);
+
+/**
+ * Returns the length of a string in bytes.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the OCTET_LENGTH SQL function.
+ */
+export const octetLength = (value: OperandInput): FunctionNode => fn('OCTET_LENGTH', [value]);
+
+/**
+ * Returns a string from an ASCII code.
+ * @param code - The ASCII code.
+ * @returns A FunctionNode representing the CHR/CHAR SQL function.
+ */
+export const chr = (code: OperandInput): FunctionNode => fn('CHR', [code]);
+

package/src/core/sql/sql.ts

@@ -33,44 +33,65 @@ export const SQL_KEYWORDS = {
 /**
  * SQL operators used in query conditions
  */
-export const SQL_OPERATORS = {
-  /** Equality operator */
-  EQUALS: '=',
-  /** Not equals operator */
-  NOT_EQUALS: '!=',
-  /** Greater than operator */
-  GREATER_THAN: '>',
-  /** Greater than or equal operator */
-  GREATER_OR_EQUAL: '>=',
-  /** Less than operator */
-  LESS_THAN: '<',
-  /** Less than or equal operator */
-  LESS_OR_EQUAL: '<=',
-  /** LIKE pattern matching operator */
-  LIKE: 'LIKE',
-  /** NOT LIKE pattern matching operator */
-  NOT_LIKE: 'NOT LIKE',
-  /** IN membership operator */
-  IN: 'IN',
-  /** NOT IN membership operator */
-  NOT_IN: 'NOT IN',
-  /** BETWEEN range operator */
-  BETWEEN: 'BETWEEN',
-  /** NOT BETWEEN range operator */
-  NOT_BETWEEN: 'NOT BETWEEN',
-  /** IS NULL null check operator */
-  IS_NULL: 'IS NULL',
-  /** IS NOT NULL null check operator */
-  IS_NOT_NULL: 'IS NOT NULL',
-  /** Logical AND operator */
-  AND: 'AND',
-  /** Logical OR operator */
-  OR: 'OR',
-  /** EXISTS operator */
-  EXISTS: 'EXISTS',
-  /** NOT EXISTS operator */
-  NOT_EXISTS: 'NOT EXISTS'
-} as const;
+export const SQL_OPERATORS = {
+  /** Equality operator */
+  EQUALS: '=',
+  /** Not equals operator */
+  NOT_EQUALS: '!=',
+  /** Greater than operator */
+  GREATER_THAN: '>',
+  /** Greater than or equal operator */
+  GREATER_OR_EQUAL: '>=',
+  /** Less than operator */
+  LESS_THAN: '<',
+  /** Less than or equal operator */
+  LESS_OR_EQUAL: '<=',
+  /** LIKE pattern matching operator */
+  LIKE: 'LIKE',
+  /** NOT LIKE pattern matching operator */
+  NOT_LIKE: 'NOT LIKE',
+  /** IN membership operator */
+  IN: 'IN',
+  /** NOT IN membership operator */
+  NOT_IN: 'NOT IN',
+  /** BETWEEN range operator */
+  BETWEEN: 'BETWEEN',
+  /** NOT BETWEEN range operator */
+  NOT_BETWEEN: 'NOT BETWEEN',
+  /** IS NULL null check operator */
+  IS_NULL: 'IS NULL',
+  /** IS NOT NULL null check operator */
+  IS_NOT_NULL: 'IS NOT NULL',
+  /** Logical AND operator */
+  AND: 'AND',
+  /** Logical OR operator */
+  OR: 'OR',
+  /** EXISTS operator */
+  EXISTS: 'EXISTS',
+  /** NOT EXISTS operator */
+  NOT_EXISTS: 'NOT EXISTS'
+} as const;
+
+/**
+ * SQL bitwise operators
+ */
+export const BITWISE_OPERATORS = {
+  /** Bitwise AND */
+  AND: '&',
+  /** Bitwise OR */
+  OR: '|',
+  /** Bitwise XOR */
+  XOR: '^',
+  /** Bitwise Shift Left */
+  SHIFT_LEFT: '<<',
+  /** Bitwise Shift Right */
+  SHIFT_RIGHT: '>>'
+} as const;
+
+/**
+ * Type representing supported bitwise operators
+ */
+export type BitwiseOperator = (typeof BITWISE_OPERATORS)[keyof typeof BITWISE_OPERATORS];
 
 /**
  * Type representing any supported SQL operator

package/src/decorators/bootstrap.ts

@@ -20,6 +20,7 @@ import {
 } from '../orm/entity-metadata.js';
 
 import { tableRef, type TableRef } from '../schema/table.js';
+import { SelectableKeys, ColumnDef } from '../schema/types.js';
 
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -143,14 +144,14 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
  * @param ctor - The entity constructor.
  * @returns A select query builder for the entity.
  */
-export const selectFromEntity = <TTable extends TableDef = TableDef>(
-  ctor: EntityConstructor
-): SelectQueryBuilder<unknown, TTable> => {
+export const selectFromEntity = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): SelectQueryBuilder<unknown, TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>> => {
   const table = getTableDefFromEntity(ctor);
   if (!table) {
     throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
-  return new SelectQueryBuilder(table as TTable);
+  return new SelectQueryBuilder(table as unknown as TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>);
 };
 
 /**

package/src/index.ts

@@ -1,3 +1,7 @@
+/**
+ * MetalORM core exports.
+ * Provides schema definition, query building, and ORM capabilities.
+ */
 export * from './schema/table.js';
 export * from './schema/column-types.js';
 export * from './schema/relation.js';
@@ -19,16 +23,19 @@ export * from './core/ddl/schema-types.js';
 export * from './core/ddl/schema-diff.js';
 export * from './core/ddl/schema-introspect.js';
 export * from './core/ddl/introspect/registry.js';
-export * from './core/functions/text.js';
-export * from './core/functions/numeric.js';
-export * from './core/functions/datetime.js';
+export * from './core/functions/text.js';
+export * from './core/functions/numeric.js';
+export * from './core/functions/datetime.js';
+export * from './core/functions/control-flow.js';
+export * from './core/functions/json.js';
+export * from './core/functions/array.js';
 export * from './orm/als.js';
 export * from './orm/hydration.js';
 export * from './codegen/typescript.js';
-export * from './orm/orm-session.js';
-export * from './orm/orm.js';
-export * from './orm/entity.js';
-export * from './orm/lazy-batch.js';
+export * from './orm/orm-session.js';
+export * from './orm/orm.js';
+export * from './orm/entity.js';
+export * from './orm/lazy-batch.js';
 export * from './orm/relations/has-many.js';
 export * from './orm/relations/belongs-to.js';
 export * from './orm/relations/many-to-many.js';
@@ -38,10 +45,10 @@ export * from './orm/execution-context.js';
 export * from './orm/hydration-context.js';
 export * from './orm/domain-event-bus.js';
 export * from './orm/runtime-types.js';
-export * from './orm/query-logger.js';
-export * from './orm/jsonify.js';
-export * from './orm/save-graph-types.js';
-export * from './decorators/index.js';
+export * from './orm/query-logger.js';
+export * from './orm/jsonify.js';
+export * from './orm/save-graph-types.js';
+export * from './decorators/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';

package/src/orm/hydration-context.ts

@@ -6,11 +6,21 @@ import type { EntityContext } from './entity-context.js';
 import type { AnyDomainEvent, DomainEvent } from './runtime-types.js';
 import type { OrmSession } from './orm-session.js';
 
+/**
+ * Context used during the hydration of entities from database results.
+ * It carries necessary services and processors to handle identity management,
+ * unit of work registration, and relation changes.
+ */
 export interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
+  /** The identity map used to track and reuse entity instances. */
   identityMap: IdentityMap;
+  /** The unit of work used to track changes in hydrated entities. */
   unitOfWork: UnitOfWork;
+  /** The bus used to dispatch domain events during or after hydration. */
   domainEvents: DomainEventBus<E, OrmSession<E>>;
+  /** Processor for handling changes in entity relations during hydration. */
   relationChanges: RelationChangeProcessor;
+  /** Context providing access to entity-specific metadata and services. */
   entityContext: EntityContext;
   // maybe mapping registry, converters, etc.
 }

package/src/orm/identity-map.ts

@@ -1,6 +1,10 @@
 import type { TableDef } from '../schema/table.js';
 import type { TrackedEntity } from './runtime-types.js';
 
+/**
+ * Simple identity map for tracking entities within a session.
+ * Ensures that the same database record is represented by a single entity instance.
+ */
 export class IdentityMap {
   private readonly buckets = new Map<string, Map<string, TrackedEntity>>();
 
@@ -8,11 +12,21 @@ export class IdentityMap {
     return this.buckets;
   }
 
+  /**
+   * Retrieves an entity from the identity map if it exists.
+   * @param table The table definition of the entity.
+   * @param pk The primary key value.
+   * @returns The entity instance if found, undefined otherwise.
+   */
   getEntity(table: TableDef, pk: string | number): unknown | undefined {
     const bucket = this.buckets.get(table.name);
     return bucket?.get(this.toIdentityKey(pk))?.entity;
   }
 
+  /**
+   * Registers a tracked entity in the identity map.
+   * @param tracked The tracked entity metadata and instance.
+   */
   register(tracked: TrackedEntity): void {
     if (tracked.pk == null) return;
     const bucket = this.buckets.get(tracked.table.name) ?? new Map<string, TrackedEntity>();
@@ -26,6 +40,11 @@ export class IdentityMap {
     bucket?.delete(this.toIdentityKey(tracked.pk));
   }
 
+  /**
+   * Returns all tracked entities for a specific table.
+   * @param table The table definition.
+   * @returns Array of tracked entities.
+   */
   getEntitiesForTable(table: TableDef): TrackedEntity[] {
     const bucket = this.buckets.get(table.name);
     return bucket ? Array.from(bucket.values()) : [];

package/src/orm/interceptor-pipeline.ts

@@ -8,6 +8,10 @@ export interface QueryContext {
 
 export type QueryInterceptor = (ctx: QueryContext, next: () => Promise<QueryResult[]>) => Promise<QueryResult[]>;
 
+/**
+ * Pipeline for query interceptors.
+ * Interceptors can wrap query execution to add logging, tracing, caching, etc.
+ */
 export class InterceptorPipeline {
   private interceptors: QueryInterceptor[] = [];
 

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

@@ -20,10 +20,27 @@ const hideInternal = (obj: object, keys: string[]): void => {
   }
 };
 
+/**
+ * Default implementation of a belongs-to reference.
+ * Manages a reference to a parent entity from a child entity through a foreign key.
+ *
+ * @template TParent The type of the parent entity.
+ */
 export class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
   private loaded = false;
   private current: TParent | null = null;
 
+  /**
+   * @param ctx The entity context for tracking changes.
+   * @param meta Metadata for the child entity.
+   * @param root The child entity instance (carrying the foreign key).
+   * @param relationName The name of the relation.
+   * @param relation Relation definition.
+   * @param rootTable Table definition of the child entity.
+   * @param loader Function to load the parent entity.
+   * @param createEntity Function to create entity instances from rows.
+   * @param targetKey The primary key of the target (parent) table.
+   */
   constructor(
     private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<TableDef>,

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

@@ -20,10 +20,27 @@ const hideInternal = (obj: object, keys: string[]): void => {
   }
 };
 
+/**
+ * Default implementation of a has-one reference.
+ * Manages a reference to a child entity where the child carries the foreign key.
+ *
+ * @template TChild The type of the child entity.
+ */
 export class DefaultHasOneReference<TChild> implements HasOneReference<TChild> {
   private loaded = false;
   private current: TChild | null = null;
 
+  /**
+   * @param ctx The entity context for tracking changes.
+   * @param meta Metadata for the parent entity.
+   * @param root The parent entity instance.
+   * @param relationName The name of the relation.
+   * @param relation Relation definition.
+   * @param rootTable Table definition of the parent entity.
+   * @param loader Function to load the child entity.
+   * @param createEntity Function to create entity instances from rows.
+   * @param localKey The local key on the parent entity used for the relation.
+   */
   constructor(
     private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<TableDef>,