metal-orm 1.0.56 → 1.0.58

package/src/query-builder/select.ts

@@ -32,7 +32,7 @@ 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 type { RelationDef } from '../schema/relation.js';
+import { RelationKinds, type RelationDef } from '../schema/relation.js';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
 import { EntityInstance, RelationMap, RelationTargetTable } from '../schema/types.js';
 import { OrmSession } from '../orm/orm-session.ts';
@@ -76,6 +76,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   private readonly columnSelector: ColumnSelector;
   private readonly relationManager: RelationManager;
   private readonly lazyRelations: Set<string>;
+  private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -89,7 +90,8 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     state?: SelectQueryState,
     hydration?: HydrationManager,
     dependencies?: Partial<SelectQueryBuilderDependencies>,
-    lazyRelations?: Set<string>
+    lazyRelations?: Set<string>,
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>
   ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
@@ -100,6 +102,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
       hydration: initialHydration
     };
     this.lazyRelations = new Set(lazyRelations ?? []);
+    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
     this.columnSelector = deps.createColumnSelector(this.env);
     this.relationManager = deps.createRelationManager(this.env);
   }
@@ -112,9 +115,17 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    */
   private clone(
     context: SelectQueryBuilderContext = this.context,
-    lazyRelations = new Set(this.lazyRelations)
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions)
   ): SelectQueryBuilder<T, TTable> {
-    return new SelectQueryBuilder(this.env.table as TTable, context.state, context.hydration, this.env.deps, lazyRelations);
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions
+    );
   }
 
   /**
@@ -445,42 +456,41 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   /**
    * Includes a relation lazily in the query results
    * @param relationName - Name of the relation to include lazily
+   * @param options - Optional include options for lazy loading
    * @returns New query builder instance with lazy relation inclusion
    */
-  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[] });
-  }
+  includeLazy<K extends keyof RelationMap<TTable>>(
+    relationName: K,
+    options?: RelationIncludeOptions
+  ): SelectQueryBuilder<T, TTable> {
+    let nextContext = this.context;
+    const relation = this.env.table.relations[relationName as string];
+    if (relation?.type === RelationKinds.BelongsTo) {
+      const foreignKey = relation.foreignKey;
+      const fkColumn = this.env.table.columns[foreignKey];
+      if (fkColumn) {
+        const hasAlias = nextContext.state.ast.columns.some(col => {
+          const node = col as { alias?: string; name?: string };
+          return (node.alias ?? node.name) === foreignKey;
+        });
+        if (!hasAlias) {
+          nextContext = this.columnSelector.select(nextContext, { [foreignKey]: fkColumn });
+        }
+      }
+    }
+    const nextLazy = new Set(this.lazyRelations);
+    nextLazy.add(relationName as string);
+    const nextOptions = new Map(this.lazyRelationOptions);
+    if (options) {
+      nextOptions.set(relationName as string, options);
+    } else {
+      nextOptions.delete(relationName as string);
+    }
+    return this.clone(nextContext, nextLazy, nextOptions);
+  }
 
   /**
-   * Convenience alias for selecting specific columns from a relation.
+   * Convenience alias for including only specific columns from a relation.
    */
   includePick<
     K extends keyof TTable['relations'] & string,
@@ -488,7 +498,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     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);
+    return this.include(relationName, { columns: cols as readonly string[] });
   }
 
 
@@ -505,7 +515,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
       if (entry.type === 'root') {
         currBuilder = currBuilder.select(...entry.columns);
       } else {
-        currBuilder = currBuilder.selectRelationColumns(entry.relationName, ...(entry.columns as string[]));
+        currBuilder = currBuilder.include(entry.relationName, { columns: entry.columns as string[] });
       }
     }
 
@@ -520,6 +530,14 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     return Array.from(this.lazyRelations) as (keyof RelationMap<TTable>)[];
   }
 
+  /**
+   * Gets lazy relation include options
+   * @returns Map of relation names to include options
+   */
+  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
+    return new Map(this.lazyRelationOptions);
+  }
+
   /**
    * Gets the table definition for this query builder
    * @returns Table definition
@@ -533,74 +551,74 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param ctx - ORM session context
    * @returns Promise of entity instances
    */
-  async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    return executeHydrated(ctx, this);
-  }
-
-  private withAst(ast: SelectQueryNode): SelectQueryBuilder<T, TTable> {
-    const nextState = new SelectQueryState(this.env.table as TTable, ast);
-    const nextContext: SelectQueryBuilderContext = {
-      ...this.context,
-      state: nextState
-    };
-    return this.clone(nextContext);
-  }
-
-  async count(session: OrmSession): Promise<number> {
-    const unpagedAst: SelectQueryNode = {
-      ...this.context.state.ast,
-      orderBy: undefined,
-      limit: undefined,
-      offset: undefined
-    };
-
-    const subAst = this.withAst(unpagedAst).getAST();
-
-    const countQuery: SelectQueryNode = {
-      type: 'SelectQuery',
-      from: derivedTable(subAst, '__metal_count'),
-      columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
-      joins: []
-    };
-
-    const execCtx = session.getExecutionContext();
-    const compiled = execCtx.dialect.compileSelect(countQuery);
-    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-    const value = results[0]?.values?.[0]?.[0];
-
-    if (typeof value === 'number') return value;
-    if (typeof value === 'bigint') return Number(value);
-    if (typeof value === 'string') return Number(value);
-    return value === null || value === undefined ? 0 : Number(value);
-  }
-
-  async executePaged(
-    session: OrmSession,
-    options: { page: number; pageSize: number }
-  ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
-    const { page, pageSize } = options;
-    if (!Number.isInteger(page) || page < 1) {
-      throw new Error('executePaged: page must be an integer >= 1');
-    }
-    if (!Number.isInteger(pageSize) || pageSize < 1) {
-      throw new Error('executePaged: pageSize must be an integer >= 1');
-    }
-
-    const offset = (page - 1) * pageSize;
-    const [items, totalItems] = await Promise.all([
-      this.limit(pageSize).offset(offset).execute(session),
-      this.count(session)
-    ]);
-
-    return { items, totalItems };
-  }
-
-  /**
-   * Executes the query with provided execution and hydration contexts
-   * @param execCtx - Execution context
-   * @param hydCtx - Hydration context
-   * @returns Promise of entity instances
-   */
+  async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
+    return executeHydrated(ctx, this);
+  }
+
+  private withAst(ast: SelectQueryNode): SelectQueryBuilder<T, TTable> {
+    const nextState = new SelectQueryState(this.env.table as TTable, ast);
+    const nextContext: SelectQueryBuilderContext = {
+      ...this.context,
+      state: nextState
+    };
+    return this.clone(nextContext);
+  }
+
+  async count(session: OrmSession): Promise<number> {
+    const unpagedAst: SelectQueryNode = {
+      ...this.context.state.ast,
+      orderBy: undefined,
+      limit: undefined,
+      offset: undefined
+    };
+
+    const subAst = this.withAst(unpagedAst).getAST();
+
+    const countQuery: SelectQueryNode = {
+      type: 'SelectQuery',
+      from: derivedTable(subAst, '__metal_count'),
+      columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
+      joins: []
+    };
+
+    const execCtx = session.getExecutionContext();
+    const compiled = execCtx.dialect.compileSelect(countQuery);
+    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    const value = results[0]?.values?.[0]?.[0];
+
+    if (typeof value === 'number') return value;
+    if (typeof value === 'bigint') return Number(value);
+    if (typeof value === 'string') return Number(value);
+    return value === null || value === undefined ? 0 : Number(value);
+  }
+
+  async executePaged(
+    session: OrmSession,
+    options: { page: number; pageSize: number }
+  ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
+    const { page, pageSize } = options;
+    if (!Number.isInteger(page) || page < 1) {
+      throw new Error('executePaged: page must be an integer >= 1');
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1) {
+      throw new Error('executePaged: pageSize must be an integer >= 1');
+    }
+
+    const offset = (page - 1) * pageSize;
+    const [items, totalItems] = await Promise.all([
+      this.limit(pageSize).offset(offset).execute(session),
+      this.count(session)
+    ]);
+
+    return { items, totalItems };
+  }
+
+  /**
+   * Executes the query with provided execution and hydration contexts
+   * @param execCtx - Execution context
+   * @param hydCtx - Hydration context
+   * @returns Promise of entity instances
+   */
   async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]> {
     return executeHydratedWithContexts(execCtx, hydCtx, this);
   }

package/src/schema/table-guards.ts

@@ -9,6 +9,12 @@ const isRelationsRecord = (relations: unknown): relations is Record<string, unkn
     return typeof relations === 'object' && relations !== null;
 };
 
+/**
+ * Type guard that checks if a value is a TableDef.
+ * 
+ * @param value The value to check.
+ * @returns True if the value follows the TableDef structure.
+ */
 export const isTableDef = (value: unknown): value is TableDef => {
     if (typeof value !== 'object' || value === null) {
         return false;

package/src/schema/types.ts

@@ -1,104 +1,128 @@
-import { ColumnDef } from './column-types.js';
-import { TableDef } from './table.js';
-import {
-  RelationDef,
-  HasManyRelation,
-  HasOneRelation,
-  BelongsToRelation,
-  BelongsToManyRelation
-} from './relation.js';
-
-/**
- * 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;
-
-type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
-
-/**
- * Maps a ColumnDef to its TypeScript type representation
- */
-export type ColumnToTs<T extends ColumnDef> =
-  [unknown] extends [T['tsType']]
-  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
-  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
-  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
-  NormalizedColumnType<T> extends 'boolean' ? boolean :
-  NormalizedColumnType<T> extends 'json' ? unknown :
-  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
-  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
-  string
-  : Exclude<T['tsType'], undefined>;
-
-/**
- * Infers a row shape from a table definition
- */
-export type InferRow<TTable extends TableDef> = {
-  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
-};
-
+import type { ColumnDef } from './column-types.js';
+export type { ColumnDef };
+import { TableDef } from './table.js';
+import {
+  RelationDef,
+  HasManyRelation,
+  HasOneRelation,
+  BelongsToRelation,
+  BelongsToManyRelation
+} from './relation.js';
+
+/**
+ * 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;
+
+type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
+
+/**
+ * Maps a ColumnDef to its TypeScript type representation
+ */
+export type ColumnToTs<T extends ColumnDef> =
+  [unknown] extends [T['tsType']]
+  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
+  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
+  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
+  NormalizedColumnType<T> extends 'boolean' ? boolean :
+  NormalizedColumnType<T> extends 'json' ? unknown :
+  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
+  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
+  string
+  : Exclude<T['tsType'], undefined>;
+
+/**
+ * Infers a row shape from a table definition
+ */
+export type InferRow<TTable extends TableDef> = {
+  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
+};
+
 type RelationResult<T extends RelationDef> =
   T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
   T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
   T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & { _pivot?: unknown })[] :
+  T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & { _pivot?: Record<string, unknown> })[] :
   never;
-
-/**
- * Maps relation names to the expected row results
- */
-export type RelationMap<TTable extends TableDef> = {
-  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
-};
+
+/**
+ * Maps relation names to the expected row results
+ */
+export type RelationMap<TTable extends TableDef> = {
+  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
+};
+
+type RelationWrapper<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget>
+    ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
+    : TRel extends HasOneRelation<infer TTarget>
+      ? HasOneReference<EntityInstance<TTarget>>
+      : TRel extends BelongsToManyRelation<infer TTarget>
+        ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
+          & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
+        : TRel extends BelongsToRelation<infer TTarget>
+          ? BelongsToReference<EntityInstance<TTarget>>
+          : never;
 
 export interface HasManyCollection<TChild> {
+  length: number;
+  [Symbol.iterator](): Iterator<TChild>;
   load(): Promise<TChild[]>;
   getItems(): TChild[];
   add(data: Partial<TChild>): TChild;
   attach(entity: TChild): void;
   remove(entity: TChild): void;
-  clear(): void;
-}
-
-export interface BelongsToReference<TParent> {
-  load(): Promise<TParent | null>;
-  get(): TParent | null;
-  set(data: Partial<TParent> | TParent | null): TParent | null;
-}
-
-export interface HasOneReference<TChild> {
-  load(): Promise<TChild | null>;
-  get(): TChild | null;
-  set(data: Partial<TChild> | TChild | null): TChild | null;
-}
-
+  clear(): void;
+}
+
+export interface BelongsToReferenceApi<TParent extends object = object> {
+  load(): Promise<TParent | null>;
+  get(): TParent | null;
+  set(data: Partial<TParent> | TParent | null): TParent | null;
+}
+
+export type BelongsToReference<TParent extends object = object> = BelongsToReferenceApi<TParent> & Partial<TParent>;
+
+export interface HasOneReferenceApi<TChild extends object = object> {
+  load(): Promise<TChild | null>;
+  get(): TChild | null;
+  set(data: Partial<TChild> | TChild | null): TChild | null;
+}
+
+export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
+
 export interface ManyToManyCollection<TTarget> {
+  length: number;
+  [Symbol.iterator](): Iterator<TTarget>;
   load(): Promise<TTarget[]>;
   getItems(): TTarget[];
   attach(target: TTarget | number | string): void;
   detach(target: TTarget | number | string): void;
   syncByIds(ids: (number | string)[]): Promise<void>;
-}
+}
+
+export type EntityInstance<
+  TTable extends TableDef,
+  TRow = InferRow<TTable>
+> = TRow & {
+  [K in keyof RelationMap<TTable>]: RelationWrapper<TTable['relations'][K]>;
+} & {
+  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
+};
+
+export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
+
+type IsAny<T> = 0 extends (1 & T) ? true : false;
 
-export type EntityInstance<
-  TTable extends TableDef,
-  TRow = InferRow<TTable>
-> = TRow & {
-  [K in keyof RelationMap<TTable>]:
-  TTable['relations'][K] extends HasManyRelation<infer TTarget>
-  ? HasManyCollection<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends HasOneRelation<infer TTarget>
-  ? HasOneReference<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
-  ? ManyToManyCollection<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
-  ? BelongsToReference<EntityInstance<TTarget>>
-  : never;
-} & {
-  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
-};
+export type SelectableKeys<T> = {
+  [K in keyof T]-?: IsAny<T[K]> extends true
+    ? never
+    : NonNullable<T[K]> extends Primitive
+      ? K
+      : never
+}[keyof T];