metal-orm 1.0.60 → 1.0.63

package/src/query-builder/hydration-planner.ts

@@ -31,22 +31,20 @@ export class HydrationPlanner {
    * @param columns - Columns to capture
    * @returns Updated HydrationPlanner with captured columns
    */
-  captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
-    const currentPlan = this.getPlanOrDefault();
-    const rootCols = new Set(currentPlan.rootColumns);
-    let changed = false;
-
-    columns.forEach(node => {
-      if (node.type !== 'Column') return;
-      if (node.table !== this.table.name) return;
-
-      const alias = node.alias || node.name;
-      if (isRelationAlias(alias)) return;
-      if (!rootCols.has(alias)) {
-        rootCols.add(alias);
-        changed = true;
-      }
-    });
+  captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
+    const currentPlan = this.getPlanOrDefault();
+    const rootCols = new Set(currentPlan.rootColumns);
+    let changed = false;
+
+    columns.forEach(node => {
+      const alias = node.type === 'Column' ? (node.alias || node.name) : node.alias;
+      if (!alias || isRelationAlias(alias)) return;
+      if (node.type === 'Column' && node.table !== this.table.name) return;
+      if (!rootCols.has(alias)) {
+        rootCols.add(alias);
+        changed = true;
+      }
+    });
 
     if (!changed) return this;
     return new HydrationPlanner(this.table, {

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

@@ -9,7 +9,6 @@ import { SelectPredicateFacet } from './predicate-facet.js';
 import { SelectRelationFacet } from './relation-facet.js';
 import { ORDER_DIRECTIONS, OrderDirection } from '../../core/sql/sql.js';
 import { OrmSession } from '../../orm/orm-session.js';
-import { EntityInstance } from '../../schema/types.js';
 import type { SelectQueryBuilder } from '../select.js';
 
 export type WhereHasOptions = {
@@ -85,7 +84,7 @@ export async function executePagedQuery<T, TTable extends TableDef>(
   session: OrmSession,
   options: { page: number; pageSize: number },
   countCallback: (session: OrmSession) => Promise<number>
-): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
+): Promise<{ items: T[]; totalItems: number }> {
   const { page, pageSize } = options;
 
   if (!Number.isInteger(page) || page < 1) {

package/src/query-builder/select.ts

@@ -2,18 +2,19 @@ import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column-types.js';
 import { OrderingTerm, SelectQueryNode, SetOperationKind } from '../core/ast/query.js';
 import { HydrationPlan } from '../core/hydration/types.js';
-import {
-  ColumnNode,
-  ExpressionNode,
-  FunctionNode,
-  BinaryExpressionNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
-  and,
-  exists,
-  notExists,
-  OperandNode
-} from '../core/ast/expression.js';
+import {
+  ColumnNode,
+  ExpressionNode,
+  FunctionNode,
+  BinaryExpressionNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  and,
+  exists,
+  notExists,
+  OperandNode
+} from '../core/ast/expression.js';
+import type { TypedExpression } from '../core/ast/expression.js';
 import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 
@@ -31,11 +32,14 @@ import { ColumnSelector } from './column-selector.js';
 import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
 import { RelationKinds } from '../schema/relation.js';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
-import { EntityInstance, RelationMap } from '../schema/types.js';
+import { EntityInstance, RelationMap } from '../schema/types.js';
+import type { ColumnToTs, InferRow } from '../schema/types.js';
 import { OrmSession } from '../orm/orm-session.ts';
 import { ExecutionContext } from '../orm/execution-context.js';
 import { HydrationContext } from '../orm/hydration-context.js';
-import { executeHydrated, executeHydratedWithContexts } from '../orm/execute.js';
+import { executeHydrated, executeHydratedPlain, executeHydratedWithContexts } from '../orm/execute.js';
+import { EntityConstructor } from '../orm/entity-metadata.js';
+import { materializeAs } from '../orm/entity-materializer.js';
 import { resolveSelectQuery } from './query-resolution.js';
 import {
   applyOrderBy,
@@ -53,8 +57,27 @@ import { SelectCTEFacet } from './select/cte-facet.js';
 import { SelectSetOpFacet } from './select/setop-facet.js';
 import { SelectRelationFacet } from './select/relation-facet.js';
 
-type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
-
+type ColumnSelectionValue =
+  | ColumnDef
+  | FunctionNode
+  | CaseExpressionNode
+  | WindowFunctionNode
+  | TypedExpression<unknown>;
+
+type SelectionValueType<TValue> =
+  TValue extends TypedExpression<infer TRuntime> ? TRuntime :
+  TValue extends ColumnDef ? ColumnToTs<TValue> :
+  unknown;
+
+type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
+  [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
+};
+
+type SelectionFromKeys<
+  TTable extends TableDef,
+  K extends keyof TTable['columns'] & string
+> = Pick<InferRow<TTable>, K>;
+
 type DeepSelectEntry<TTable extends TableDef> = {
   type: 'root';
   columns: (keyof TTable['columns'] & string)[];
@@ -71,7 +94,7 @@ type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
  * @typeParam T - Result type for projections (unused)
  * @typeParam TTable - Table definition being queried
  */
-export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef> {
+export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends TableDef = TableDef> {
   private readonly env: SelectQueryBuilderEnvironment;
   private readonly context: SelectQueryBuilderContext;
   private readonly columnSelector: ColumnSelector;
@@ -84,6 +107,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   private readonly relationFacet: SelectRelationFacet;
   private readonly lazyRelations: Set<string>;
   private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
+  private readonly entityConstructor?: EntityConstructor;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -98,7 +122,8 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     hydration?: HydrationManager,
     dependencies?: Partial<SelectQueryBuilderDependencies>,
     lazyRelations?: Set<string>,
-    lazyRelationOptions?: Map<string, RelationIncludeOptions>
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
+    entityConstructor?: EntityConstructor
   ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
@@ -111,6 +136,7 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
     };
     this.lazyRelations = new Set(lazyRelations ?? []);
     this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
+    this.entityConstructor = entityConstructor;
     this.columnSelector = deps.createColumnSelector(this.env);
     const relationManager = deps.createRelationManager(this.env);
     this.fromFacet = new SelectFromFacet(this.env, createAstService);
@@ -128,20 +154,21 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  private clone(
-    context: SelectQueryBuilderContext = this.context,
-    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,
-      lazyRelationOptions
-    );
-  }
+  private clone<TNext = T>(
+    context: SelectQueryBuilderContext = this.context,
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions)
+  ): SelectQueryBuilder<TNext, TTable> {
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions,
+      this.entityConstructor
+    ) as SelectQueryBuilder<TNext, TTable>;
+  }
 
   /**
    * Applies an alias to the root FROM table.
@@ -207,32 +234,41 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    *   fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
    * });
    */
-  select<K extends keyof TTable['columns'] & string>(
-    ...args: K[]
-  ): SelectQueryBuilder<T, TTable>;
-  select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
-  select<K extends keyof TTable['columns'] & string>(
-    ...args: K[] | [Record<string, ColumnSelectionValue>]
-  ): SelectQueryBuilder<T, TTable> {
+  select<K extends keyof TTable['columns'] & string>(
+    ...args: K[]
+  ): SelectQueryBuilder<T & SelectionFromKeys<TTable, K>, TTable>;
+  select<TSelection extends Record<string, ColumnSelectionValue>>(
+    columns: TSelection
+  ): SelectQueryBuilder<T & SelectionResult<TSelection>, TTable>;
+  select<
+    K extends keyof TTable['columns'] & string,
+    TSelection extends Record<string, ColumnSelectionValue>
+  >(
+    ...args: K[] | [TSelection]
+  ): SelectQueryBuilder<T, TTable> {
     // If first arg is an object (not a string), treat as projection map
     if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null && typeof args[0] !== 'string') {
-      const columns = args[0] as Record<string, ColumnSelectionValue>;
-      return this.clone(this.projectionFacet.select(this.context, columns));
-    }
+      const columns = args[0] as TSelection;
+      return this.clone<T & SelectionResult<TSelection>>(
+        this.projectionFacet.select(this.context, columns)
+      );
+    }
 
     // Otherwise, treat as column names
     const cols = args as K[];
     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.clone(this.projectionFacet.select(this.context, selection));
-  }
+    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.clone<T & SelectionFromKeys<TTable, K>>(
+      this.projectionFacet.select(this.context, selection)
+    );
+  }
 
   /**
    * Selects raw column expressions
@@ -348,10 +384,15 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * qb.select('id', 'name')
    *   .selectSubquery('postCount', postCount);
    */
-  selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable> {
-    const query = resolveSelectQuery(sub);
-    return this.clone(this.projectionFacet.selectSubquery(this.context, alias, query));
-  }
+  selectSubquery<TValue = unknown, K extends string = string, TSub extends TableDef = TableDef>(
+    alias: K,
+    sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+  ): SelectQueryBuilder<T & Record<K, TValue>, TTable> {
+    const query = resolveSelectQuery(sub);
+    return this.clone<T & Record<K, TValue>>(
+      this.projectionFacet.selectSubquery(this.context, alias, query)
+    );
+  }
 
   /**
    * Adds a JOIN against a derived table (subquery with alias)
@@ -625,16 +666,75 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   }
 
   /**
-   * Executes the query and returns hydrated results
+   * Ensures that if no columns are selected, all columns from the table are selected by default.
+   */
+  private ensureDefaultSelection(): SelectQueryBuilder<T, TTable> {
+    const columns = this.context.state.ast.columns;
+    if (!columns || columns.length === 0) {
+      const columnKeys = Object.keys(this.env.table.columns) as (keyof TTable['columns'] & string)[];
+      return this.select(...columnKeys);
+    }
+    return this;
+  }
+
+  /**
+   * Executes the query and returns hydrated results.
+   * If the builder was created with an entity constructor (e.g. via selectFromEntity),
+   * this will automatically return fully materialized entity instances.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of entity instances (or objects if generic T is not an entity)
+   * @example
+   * const users = await selectFromEntity(User).execute(session);
+   * // users is User[]
+   * users[0] instanceof User; // true
+   */
+  async execute(ctx: OrmSession): Promise<T[]> {
+    if (this.entityConstructor) {
+      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
+    }
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder) as unknown as T[];
+  }
+
+  /**
+   * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.
+   * Use this if you want raw data even when using selectFromEntity.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of plain entity instances
+   * @example
+   * const rows = await selectFromEntity(User).executePlain(session);
+   * // rows is EntityInstance<UserTable>[] (plain objects)
+   * rows[0] instanceof User; // false
+   */
+  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
+    const builder = this.ensureDefaultSelection();
+    const rows = await executeHydratedPlain(ctx, builder);
+    return rows as EntityInstance<TTable>[];
+  }
+
+  /**
+   * Executes the query and returns results as real class instances.
+   * Unlike execute(), this returns actual instances of the decorated entity class
+   * with working methods and proper instanceof checks.
+   * @param entityClass - The entity class constructor
    * @param ctx - ORM session context
-   * @returns Promise of entity instances
+   * @returns Promise of entity class instances
    * @example
-   * const users = await qb.select('id', 'name')
-   *   .where(eq(userTable.columns.active, true))
-   *   .execute(session);
+   * const users = await selectFromEntity(User)
+   *   .include('posts')
+   *   .executeAs(User, session);
+   * users[0] instanceof User; // true!
+   * users[0].getFullName();   // works!
    */
-  async execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    return executeHydrated(ctx, this);
+  async executeAs<TEntity extends object>(
+    entityClass: EntityConstructor<TEntity>,
+    ctx: OrmSession
+  ): Promise<TEntity[]> {
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydrated(ctx, builder);
+    return materializeAs(entityClass, results as unknown as Record<string, unknown>[]);
   }
 
   /**
@@ -656,8 +756,9 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
   async executePaged(
     session: OrmSession,
     options: { page: number; pageSize: number }
-  ): Promise<{ items: EntityInstance<TTable>[]; totalItems: number }> {
-    return executePagedQuery(this, session, options, sess => this.count(sess));
+  ): Promise<{ items: T[]; totalItems: number }> {
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, sess => this.count(sess));
   }
 
   /**
@@ -670,8 +771,13 @@ export class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef>
    * const hydCtx = new HydrationContext();
    * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
-  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]> {
-    return executeHydratedWithContexts(execCtx, hydCtx, this);
+  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<T[]> {
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
+    if (this.entityConstructor) {
+      return materializeAs(this.entityConstructor, results as unknown as Record<string, unknown>[]) as unknown as T[];
+    }
+    return results as unknown as T[];
   }
 
   /**