metal-orm 1.0.60 → 1.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.60",
+  "version": "1.0.62",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/decorators/bootstrap.ts

@@ -3,25 +3,25 @@ import {
   hasMany,
   hasOne,
   belongsTo,
-  belongsToMany,
-  RelationKinds,
-  type HasManyRelation,
-  type HasOneRelation,
-  type BelongsToRelation,
+  belongsToMany,
+  RelationKinds,
+  type HasManyRelation,
+  type HasOneRelation,
+  type BelongsToRelation,
   type BelongsToManyRelation,
   type RelationDef
 } from '../schema/relation.js';
-import { TableDef } from '../schema/table.js';
-import { isTableDef } from '../schema/table-guards.js';
-import {
-  buildTableDef,
-  EntityConstructor,
-  EntityMetadata,
-  EntityOrTableTarget,
-  EntityOrTableTargetResolver,
-  getAllEntityMetadata,
-  getEntityMetadata
-} from '../orm/entity-metadata.js';
+import { TableDef } from '../schema/table.js';
+import { isTableDef } from '../schema/table-guards.js';
+import {
+  buildTableDef,
+  EntityConstructor,
+  EntityMetadata,
+  EntityOrTableTarget,
+  EntityOrTableTargetResolver,
+  getAllEntityMetadata,
+  getEntityMetadata
+} from '../orm/entity-metadata.js';
 
 import { tableRef, type TableRef } from '../schema/table.js';
 import {
@@ -41,10 +41,10 @@ const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget
   return target as EntityOrTableTarget;
 };
 
-const resolveTableTarget = (
-  target: EntityOrTableTargetResolver,
-  tableMap: Map<EntityConstructor, TableDef>
-): TableDef => {
+const resolveTableTarget = (
+  target: EntityOrTableTargetResolver,
+  tableMap: Map<EntityConstructor, TableDef>
+): TableDef => {
   const resolved = unwrapTarget(target);
   if (isTableDef(resolved)) {
     return resolved;
@@ -53,65 +53,65 @@ const resolveTableTarget = (
   if (!table) {
     throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
   }
-  return table;
-};
-
-const toSnakeCase = (value: string): string => {
-  return value
-    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-    .replace(/[^a-z0-9_]+/gi, '_')
-    .replace(/__+/g, '_')
-    .replace(/^_|_$/g, '')
-    .toLowerCase();
-};
-
-const normalizeEntityName = (value: string): string => {
-  const stripped = value.replace(/Entity$/i, '');
-  const normalized = toSnakeCase(stripped || value);
-  return normalized || 'unknown';
-};
-
-const getPivotKeyBaseFromTarget = (target: EntityOrTableTargetResolver): string => {
-  const resolved = unwrapTarget(target);
-  if (isTableDef(resolved)) {
-    return toSnakeCase(resolved.name || 'unknown');
-  }
-  const ctor = resolved as EntityConstructor;
-  return normalizeEntityName(ctor.name || 'unknown');
-};
-
-const getPivotKeyBaseFromRoot = (meta: EntityMetadata): string => {
-  return normalizeEntityName(meta.target.name || meta.tableName || 'unknown');
-};
-
-const buildRelationDefinitions = (
-  meta: EntityMetadata,
-  tableMap: Map<EntityConstructor, TableDef>
-): Record<string, RelationDef> => {
-  const relations: Record<string, RelationDef> = {};
-
-  for (const [name, relation] of Object.entries(meta.relations)) {
+  return table;
+};
+
+const toSnakeCase = (value: string): string => {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-z0-9_]+/gi, '_')
+    .replace(/__+/g, '_')
+    .replace(/^_|_$/g, '')
+    .toLowerCase();
+};
+
+const normalizeEntityName = (value: string): string => {
+  const stripped = value.replace(/Entity$/i, '');
+  const normalized = toSnakeCase(stripped || value);
+  return normalized || 'unknown';
+};
+
+const getPivotKeyBaseFromTarget = (target: EntityOrTableTargetResolver): string => {
+  const resolved = unwrapTarget(target);
+  if (isTableDef(resolved)) {
+    return toSnakeCase(resolved.name || 'unknown');
+  }
+  const ctor = resolved as EntityConstructor;
+  return normalizeEntityName(ctor.name || 'unknown');
+};
+
+const getPivotKeyBaseFromRoot = (meta: EntityMetadata): string => {
+  return normalizeEntityName(meta.target.name || meta.tableName || 'unknown');
+};
+
+const buildRelationDefinitions = (
+  meta: EntityMetadata,
+  tableMap: Map<EntityConstructor, TableDef>
+): Record<string, RelationDef> => {
+  const relations: Record<string, RelationDef> = {};
+
+  for (const [name, relation] of Object.entries(meta.relations)) {
     switch (relation.kind) {
-      case RelationKinds.HasOne: {
-        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
-        relations[name] = hasOne(
-          resolveTableTarget(relation.target, tableMap),
-          foreignKey,
-          relation.localKey,
-          relation.cascade
-        );
-        break;
-      }
-      case RelationKinds.HasMany: {
-        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
-        relations[name] = hasMany(
-          resolveTableTarget(relation.target, tableMap),
-          foreignKey,
-          relation.localKey,
-          relation.cascade
-        );
-        break;
-      }
+      case RelationKinds.HasOne: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
+        relations[name] = hasOne(
+          resolveTableTarget(relation.target, tableMap),
+          foreignKey,
+          relation.localKey,
+          relation.cascade
+        );
+        break;
+      }
+      case RelationKinds.HasMany: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
+        relations[name] = hasMany(
+          resolveTableTarget(relation.target, tableMap),
+          foreignKey,
+          relation.localKey,
+          relation.cascade
+        );
+        break;
+      }
       case RelationKinds.BelongsTo: {
         relations[name] = belongsTo(
           resolveTableTarget(relation.target, tableMap),
@@ -121,22 +121,22 @@ const buildRelationDefinitions = (
         );
         break;
       }
-      case RelationKinds.BelongsToMany: {
-        const pivotForeignKeyToRoot =
-          relation.pivotForeignKeyToRoot ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
-        const pivotForeignKeyToTarget =
-          relation.pivotForeignKeyToTarget ?? `${getPivotKeyBaseFromTarget(relation.target)}_id`;
-        relations[name] = belongsToMany(
-          resolveTableTarget(relation.target, tableMap),
-          resolveTableTarget(relation.pivotTable, tableMap),
-          {
-            pivotForeignKeyToRoot,
-            pivotForeignKeyToTarget,
-            localKey: relation.localKey,
-            targetKey: relation.targetKey,
-            pivotPrimaryKey: relation.pivotPrimaryKey,
-            defaultPivotColumns: relation.defaultPivotColumns,
-            cascade: relation.cascade
+      case RelationKinds.BelongsToMany: {
+        const pivotForeignKeyToRoot =
+          relation.pivotForeignKeyToRoot ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
+        const pivotForeignKeyToTarget =
+          relation.pivotForeignKeyToTarget ?? `${getPivotKeyBaseFromTarget(relation.target)}_id`;
+        relations[name] = belongsToMany(
+          resolveTableTarget(relation.target, tableMap),
+          resolveTableTarget(relation.pivotTable, tableMap),
+          {
+            pivotForeignKeyToRoot,
+            pivotForeignKeyToTarget,
+            localKey: relation.localKey,
+            targetKey: relation.targetKey,
+            pivotPrimaryKey: relation.pivotPrimaryKey,
+            defaultPivotColumns: relation.defaultPivotColumns,
+            cascade: relation.cascade
           }
         );
         break;
@@ -200,31 +200,39 @@ type EntityTable<TEntity extends object> =
   Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
     relations: {
       [K in RelationKeys<TEntity>]:
-        NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
-          ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
-          : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget, infer TPivot>
-            ? BelongsToManyRelation<
-                EntityTable<NonNullable<TTarget> & object>,
-                TPivot extends object ? EntityTable<NonNullable<TPivot> & object> : TableDef
-              >
-            : NonNullable<TEntity[K]> extends HasOneReference<infer TChild>
-              ? HasOneRelation<EntityTable<NonNullable<TChild> & object>>
-              : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent>
-                ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>>
-                : NonNullable<TEntity[K]> extends object
-                  ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
-                  : never;
+      NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
+      ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
+      : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget, infer TPivot>
+      ? BelongsToManyRelation<
+        EntityTable<NonNullable<TTarget> & object>,
+        TPivot extends object ? EntityTable<NonNullable<TPivot> & object> : TableDef
+      >
+      : NonNullable<TEntity[K]> extends HasOneReference<infer TChild>
+      ? HasOneRelation<EntityTable<NonNullable<TChild> & object>>
+      : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent>
+      ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>>
+      : NonNullable<TEntity[K]> extends object
+      ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
+      : never;
     };
   };
 
 export const selectFromEntity = <TEntity extends object>(
   ctor: EntityConstructor<TEntity>
-): SelectQueryBuilder<unknown, EntityTable<TEntity>> => {
+): SelectQueryBuilder<TEntity, EntityTable<TEntity>> => {
   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 unknown as EntityTable<TEntity>);
+  return new SelectQueryBuilder(
+    table as unknown as EntityTable<TEntity>,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    ctor
+  );
 };
 
 /**
@@ -233,12 +241,12 @@ export const selectFromEntity = <TEntity extends object>(
  * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
-export const entityRef = <TEntity extends object>(
-  ctor: EntityConstructor<TEntity>
-): TableRef<EntityTable<TEntity>> => {
-  const table = getTableDefFromEntity(ctor);
-  if (!table) {
-    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
-  }
-  return tableRef(table as EntityTable<TEntity>);
-};
+export const entityRef = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): TableRef<EntityTable<TEntity>> => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+  }
+  return tableRef(table as EntityTable<TEntity>);
+};

package/src/decorators/index.ts

@@ -6,3 +6,7 @@ export * from './column-decorator.js';
 export * from './relations.js';
 export * from './bootstrap.js';
 export { getDecoratorMetadata } from './decorator-metadata.js';
+
+// Entity Materialization - convert query results to real class instances
+export { materializeAs, DefaultEntityMaterializer, PrototypeMaterializationStrategy, ConstructorMaterializationStrategy } from '../orm/entity-materializer.js';
+export type { EntityMaterializer, EntityMaterializationStrategy } from '../orm/entity-materializer.js';

package/src/orm/entity-materializer.ts

@@ -0,0 +1,159 @@
+import { EntityConstructor } from './entity-metadata.js';
+import { rebuildRegistry } from './entity-registry.js';
+import { hasEntityMeta } from './entity-meta.js';
+
+/**
+ * Strategy interface for materializing entity instances (Open/Closed Principle).
+ */
+export interface EntityMaterializationStrategy {
+    /**
+     * Creates an instance of the entity class and populates it with data.
+     * @param ctor - The entity constructor
+     * @param data - The raw data to populate
+     * @returns The materialized entity instance
+     */
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
+}
+
+/**
+ * Default strategy: Uses Object.create() to create instance without calling constructor.
+ * Safe for classes with required constructor parameters.
+ */
+export class PrototypeMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
+        const instance = Object.create(ctor.prototype) as T;
+        Object.assign(instance, data);
+        return instance;
+    }
+}
+
+/**
+ * Alternative strategy: Calls default constructor then assigns properties.
+ * Use when class constructor initializes important state.
+ */
+export class ConstructorMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T {
+        const instance = Reflect.construct(ctor, []) as T & Record<string, unknown>;
+        Object.assign(instance, data);
+        return instance;
+    }
+}
+
+/**
+ * Interface for materializing query results into real entity class instances.
+ */
+export interface EntityMaterializer {
+    /**
+     * Materializes a single row into a real entity instance.
+     * @param entityClass - The entity constructor
+     * @param row - The raw data row
+     * @returns The materialized entity instance
+     */
+    materialize<T>(entityClass: EntityConstructor<T>, row: Record<string, unknown>): T;
+
+    /**
+     * Materializes multiple rows into real entity instances.
+     * @param entityClass - The entity constructor
+     * @param rows - The raw data rows
+     * @returns Array of materialized entity instances
+     */
+    materializeMany<T>(entityClass: EntityConstructor<T>, rows: Record<string, unknown>[]): T[];
+}
+
+/**
+ * Default implementation of EntityMaterializer.
+ * Converts query results into actual class instances with working methods.
+ * 
+ * @example
+ * const materializer = new DefaultEntityMaterializer();
+ * const users = materializer.materializeMany(User, queryResults);
+ * users[0] instanceof User; // true
+ * users[0].getFullName();   // works!
+ */
+export class DefaultEntityMaterializer implements EntityMaterializer {
+    constructor(
+        private readonly strategy: EntityMaterializationStrategy = new ConstructorMaterializationStrategy()
+    ) { }
+
+    materialize<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
+        if (hasEntityMeta(row)) {
+            return this.materializeEntityProxy(ctor, row);
+        }
+
+        const instance = this.strategy.materialize(ctor, row);
+        this.materializeRelations(instance as Record<string, unknown>);
+        return instance;
+    }
+
+    materializeMany<T>(ctor: EntityConstructor<T>, rows: Record<string, unknown>[]): T[] {
+        return rows.map(row => this.materialize(ctor, row));
+    }
+
+    /**
+     * Recursively materializes nested relation data.
+     */
+    private materializeRelations(instance: Record<string, unknown>): void {
+        // Rebuild registry to ensure we have latest metadata
+        rebuildRegistry();
+
+        for (const value of Object.values(instance)) {
+            if (value === null || value === undefined) continue;
+
+            // Handle has-one / belongs-to (single object)
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                const nested = value as Record<string, unknown>;
+                // Check if this looks like an entity (has common entity patterns)
+                if (this.isEntityLike(nested)) {
+                    // For now, keep as-is since we don't have relation metadata here
+                    // Future: use relation metadata to get target constructor
+                }
+            }
+
+            // Handle has-many / belongs-to-many (array)
+            if (Array.isArray(value) && value.length > 0) {
+                const first = value[0];
+                if (typeof first === 'object' && first !== null && this.isEntityLike(first)) {
+                    // For now, keep array as-is
+                    // Future: materialize each item if we can resolve the target class
+                }
+            }
+        }
+    }
+
+    /**
+     * Simple heuristic to check if an object looks like an entity.
+     */
+    private isEntityLike(obj: Record<string, unknown>): boolean {
+        return 'id' in obj || Object.keys(obj).some(k =>
+            k.endsWith('Id') || k === 'createdAt' || k === 'updatedAt'
+        );
+    }
+
+    private materializeEntityProxy<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T {
+        const proxy = row as Record<string, unknown>;
+        const baseline = this.strategy.materialize(ctor, {}) as Record<string, unknown>;
+        for (const key of Object.keys(baseline)) {
+            if (!Object.prototype.hasOwnProperty.call(proxy, key)) {
+                proxy[key] = baseline[key];
+            }
+        }
+        Object.setPrototypeOf(proxy, ctor.prototype);
+        return proxy as T;
+    }
+}
+
+/**
+ * Convenience function to materialize query results as real class instances.
+ * 
+ * @example
+ * const results = await selectFromEntity(User).execute(session);
+ * const users = materializeAs(User, results);
+ * users[0] instanceof User; // true!
+ */
+export const materializeAs = <TEntity extends object>(
+    ctor: EntityConstructor<TEntity>,
+    results: Record<string, unknown>[]
+): TEntity[] => {
+    const materializer = new DefaultEntityMaterializer();
+    return materializer.materializeMany(ctor, results);
+};

package/src/orm/entity-registry.ts

@@ -0,0 +1,39 @@
+import { TableDef } from '../schema/table.js';
+import { EntityConstructor, getAllEntityMetadata } from './entity-metadata.js';
+
+/**
+ * Reverse lookup registry: TableDef → EntityConstructor
+ */
+const tableToConstructor = new Map<TableDef, EntityConstructor>();
+
+/**
+ * Gets the entity constructor for a given table definition.
+ * @param table - The table definition
+ * @returns The entity constructor or undefined if not found
+ */
+export const getConstructorForTable = (table: TableDef): EntityConstructor | undefined => {
+    if (!tableToConstructor.size) {
+        rebuildRegistry();
+    }
+    return tableToConstructor.get(table);
+};
+
+/**
+ * Rebuilds the registry from entity metadata.
+ * Called automatically on first lookup or when metadata changes.
+ */
+export const rebuildRegistry = (): void => {
+    tableToConstructor.clear();
+    for (const meta of getAllEntityMetadata()) {
+        if (meta.table) {
+            tableToConstructor.set(meta.table, meta.target);
+        }
+    }
+};
+
+/**
+ * Clears the entity registry.
+ */
+export const clearEntityRegistry = (): void => {
+    tableToConstructor.clear();
+};

package/src/orm/execute.ts

@@ -61,26 +61,56 @@ const executeWithContexts = async <TTable extends TableDef>(
   await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
   return entities;
 };
-
-/**
- * Executes a hydrated query using the ORM session.
- * @template TTable - The table type
- * @param session - The ORM session
- * @param qb - The select query builder
+
+const executePlainWithContexts = async <TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  qb: SelectQueryBuilder<unknown, TTable>
+): Promise<Record<string, unknown>[]> => {
+  const ast = qb.getAST();
+  const compiled = execCtx.dialect.compileSelect(ast);
+  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const rows = flattenResults(executed);
+
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows;
+  }
+
+  return hydrateRows(rows, qb.getHydrationPlan());
+};
+
+/**
+ * Executes a hydrated query using the ORM session.
+ * @template TTable - The table type
+ * @param session - The ORM session
+ * @param qb - The select query builder
  * @returns Promise resolving to array of entity instances
  */
-export async function executeHydrated<TTable extends TableDef>(
-  session: OrmSession,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<EntityInstance<TTable>[]> {
-  return executeWithContexts(session.getExecutionContext(), session, qb);
-}
-
-/**
- * Executes a hydrated query using execution and hydration contexts.
- * @template TTable - The table type
- * @param _execCtx - The execution context (unused)
- * @param hydCtx - The hydration context
+export async function executeHydrated<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<unknown, TTable>
+): Promise<EntityInstance<TTable>[]> {
+  return executeWithContexts(session.getExecutionContext(), session, qb);
+}
+
+/**
+ * Executes a hydrated query and returns plain row objects (no entity proxies).
+ * @template TTable - The table type
+ * @param session - The ORM session
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of plain row objects
+ */
+export async function executeHydratedPlain<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<unknown, TTable>
+): Promise<Record<string, unknown>[]> {
+  return executePlainWithContexts(session.getExecutionContext(), qb);
+}
+
+/**
+ * Executes a hydrated query using execution and hydration contexts.
+ * @template TTable - The table type
+ * @param _execCtx - The execution context (unused)
+ * @param hydCtx - The hydration context
  * @param qb - The select query builder
  * @returns Promise resolving to array of entity instances
  */
@@ -96,6 +126,20 @@ export async function executeHydratedWithContexts<TTable extends TableDef>(
   return executeWithContexts(execCtx, entityCtx, qb);
 }
 
+/**
+ * Executes a hydrated query using execution context and returns plain row objects.
+ * @template TTable - The table type
+ * @param execCtx - The execution context
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of plain row objects
+ */
+export async function executeHydratedPlainWithContexts<TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  qb: SelectQueryBuilder<unknown, TTable>
+): Promise<Record<string, unknown>[]> {
+  return executePlainWithContexts(execCtx, qb);
+}
+
 const loadLazyRelationsForTable = async <TTable extends TableDef>(
   ctx: EntityContext,
   table: TTable,

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) {