metal-orm 1.0.60 → 1.0.63

package/README.md

@@ -149,7 +149,7 @@ If you like explicit model classes, you can add a thin decorator layer on top of
 - `@BelongsTo({ target, foreignKey, ... })`
 - `@BelongsToMany({ target, pivotTable, ... })`
 - `bootstrapEntities()` scans metadata, builds `TableDef`s, wires relations with the same `hasOne` / `hasMany` / `belongsTo` / `belongsToMany` helpers you would use manually, and returns the resulting tables. (If you forget to call it, `getTableDefFromEntity` / `selectFromEntity` will bootstrap lazily on first use, but bootstrapping once at startup lets you reuse the same table defs and generate schema SQL.)
-- `selectFromEntity(MyEntity)` lets you start a `SelectQueryBuilder` directly from the class.
+- `selectFromEntity(MyEntity)` lets you start a `SelectQueryBuilder` directly from the class. By default, `execute(session)` returns actual entity instances with all columns selected.
 - **Generate entities from an existing DB**: `npx metal-orm-gen -- --dialect=postgres --url=$DATABASE_URL --schema=public --out=src/entities.ts` introspects your schema and spits out `@Entity` / `@Column` classes you can immediately `bootstrapEntities()` with.
 
 You don’t have to use decorators, but when you do, you’re still on the same AST + dialect + runtime foundation.
@@ -465,14 +465,14 @@ What the runtime gives you:
 <a id="level-3"></a>
 ### Level 3: Decorator entities ✨
 
-Finally, you can describe your models with decorators and still use the same runtime and query builder.
-
-The decorator layer is built on the TC39 Stage 3 standard (TypeScript 5.6+), so you simply decorate class fields (or accessors if you need custom logic) and the standard `ClassFieldDecoratorContext` keeps a metadata bag on `context.metadata`/`Symbol.metadata`. `@Entity` reads that bag when it runs and builds your `TableDef`s—no `experimentalDecorators`, parameter decorators, or extra polyfills required.
-
-```ts
-import mysql from 'mysql2/promise';
-import {
-  Orm,
+Finally, you can describe your models with decorators and still use the same runtime and query builder.
+
+The decorator layer is built on the TC39 Stage 3 standard (TypeScript 5.6+), so you simply decorate class fields (or accessors if you need custom logic) and the standard `ClassFieldDecoratorContext` keeps a metadata bag on `context.metadata`/`Symbol.metadata`. `@Entity` reads that bag when it runs and builds your `TableDef`s—no `experimentalDecorators`, parameter decorators, or extra polyfills required.
+
+```ts
+import mysql from 'mysql2/promise';
+import {
+  Orm,
   OrmSession,
   MySqlDialect,
   col,
@@ -547,13 +547,17 @@ const [user] = await selectFromEntity(User)
   .select('id', 'name')
   .includeLazy('posts')
   .where(eq(U.id, 1))
-  .execute(session);
+  .execute(session); // user is an actual instance of the User class!
+
+// Use executePlain() if you want raw POJOs instead of class instances
+const [rawUser] = await selectFromEntity(User).executePlain(session);
 
 user.posts.add({ title: 'From decorators' });
 await session.commit();
 ```
 
-Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over.
+Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over. By default, `selectFromEntity` selects all columns if you don't specify any.
+
 
 This level is nice when:
 

package/dist/index.cjs

@@ -47,7 +47,9 @@ __export(index_exports, {
   BelongsTo: () => BelongsTo,
   BelongsToMany: () => BelongsToMany,
   Column: () => Column,
+  ConstructorMaterializationStrategy: () => ConstructorMaterializationStrategy,
   DefaultBelongsToReference: () => DefaultBelongsToReference,
+  DefaultEntityMaterializer: () => DefaultEntityMaterializer,
   DefaultHasManyCollection: () => DefaultHasManyCollection,
   DefaultManyToManyCollection: () => DefaultManyToManyCollection,
   DeleteQueryBuilder: () => DeleteQueryBuilder,
@@ -63,6 +65,7 @@ __export(index_exports, {
   Pool: () => Pool,
   PostgresDialect: () => PostgresDialect,
   PrimaryKey: () => PrimaryKey,
+  PrototypeMaterializationStrategy: () => PrototypeMaterializationStrategy,
   RelationKinds: () => RelationKinds,
   STANDARD_COLUMN_TYPES: () => STANDARD_COLUMN_TYPES,
   SelectQueryBuilder: () => SelectQueryBuilder,
@@ -78,6 +81,7 @@ __export(index_exports, {
   aliasRef: () => aliasRef,
   and: () => and,
   arrayAppend: () => arrayAppend,
+  asType: () => asType,
   ascii: () => ascii,
   asin: () => asin,
   atan: () => atan,
@@ -143,6 +147,8 @@ __export(index_exports, {
   eq: () => eq,
   esel: () => esel,
   executeHydrated: () => executeHydrated,
+  executeHydratedPlain: () => executeHydratedPlain,
+  executeHydratedPlainWithContexts: () => executeHydratedPlainWithContexts,
   executeHydratedWithContexts: () => executeHydratedWithContexts,
   executeSchemaSql: () => executeSchemaSql,
   executeSchemaSqlFor: () => executeSchemaSqlFor,
@@ -214,6 +220,7 @@ __export(index_exports, {
   lt: () => lt,
   lte: () => lte,
   ltrim: () => ltrim,
+  materializeAs: () => materializeAs,
   max: () => max,
   md5: () => md5,
   min: () => min,
@@ -1099,6 +1106,9 @@ var toTableRef = (table) => ({
   alias: hasAlias(table) ? table.alias : void 0
 });
 
+// src/core/ast/expression.ts
+var asType = (expr) => expr;
+
 // src/core/functions/function-registry.ts
 var FunctionRegistry = class {
   renderers = /* @__PURE__ */ new Map();
@@ -3712,10 +3722,9 @@ var HydrationPlanner = class _HydrationPlanner {
     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;
+      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;
@@ -6181,9 +6190,22 @@ var executeWithContexts = async (execCtx, entityCtx, qb) => {
   await loadLazyRelationsForTable(entityCtx, qb.getTable(), lazyRelations, lazyRelationOptions);
   return entities;
 };
+var executePlainWithContexts = async (execCtx, qb) => {
+  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());
+};
 async function executeHydrated(session, qb) {
   return executeWithContexts(session.getExecutionContext(), session, qb);
 }
+async function executeHydratedPlain(session, qb) {
+  return executePlainWithContexts(session.getExecutionContext(), qb);
+}
 async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
   const entityCtx = hydCtx.entityContext;
   if (!entityCtx) {
@@ -6191,6 +6213,9 @@ async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
   }
   return executeWithContexts(execCtx, entityCtx, qb);
 }
+async function executeHydratedPlainWithContexts(execCtx, qb) {
+  return executePlainWithContexts(execCtx, qb);
+}
 var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOptions) => {
   if (!lazyRelations.length) return;
   const tracked = ctx.getEntitiesForTable(table);
@@ -6238,6 +6263,146 @@ var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOp
   }
 };
 
+// src/orm/entity-metadata.ts
+var metadataMap = /* @__PURE__ */ new Map();
+var ensureEntityMetadata = (target) => {
+  let meta = metadataMap.get(target);
+  if (!meta) {
+    meta = {
+      target,
+      tableName: target.name || "unknown",
+      columns: {},
+      relations: {}
+    };
+    metadataMap.set(target, meta);
+  }
+  return meta;
+};
+var getEntityMetadata = (target) => {
+  return metadataMap.get(target);
+};
+var getAllEntityMetadata = () => {
+  return Array.from(metadataMap.values());
+};
+var addColumnMetadata = (target, propertyKey, column) => {
+  const meta = ensureEntityMetadata(target);
+  meta.columns[propertyKey] = { ...column };
+};
+var addRelationMetadata = (target, propertyKey, relation) => {
+  const meta = ensureEntityMetadata(target);
+  meta.relations[propertyKey] = relation;
+};
+var setEntityTableName = (target, tableName, hooks) => {
+  const meta = ensureEntityMetadata(target);
+  if (tableName && tableName.length > 0) {
+    meta.tableName = tableName;
+  }
+  if (hooks) {
+    meta.hooks = hooks;
+  }
+};
+var buildTableDef = (meta) => {
+  if (meta.table) {
+    return meta.table;
+  }
+  const columns = {};
+  for (const [key, def] of Object.entries(meta.columns)) {
+    columns[key] = {
+      ...def,
+      name: key,
+      table: meta.tableName
+    };
+  }
+  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
+  meta.table = table;
+  return table;
+};
+
+// src/orm/entity-registry.ts
+var tableToConstructor = /* @__PURE__ */ new Map();
+var rebuildRegistry = () => {
+  tableToConstructor.clear();
+  for (const meta of getAllEntityMetadata()) {
+    if (meta.table) {
+      tableToConstructor.set(meta.table, meta.target);
+    }
+  }
+};
+
+// src/orm/entity-materializer.ts
+var PrototypeMaterializationStrategy = class {
+  materialize(ctor, data) {
+    const instance = Object.create(ctor.prototype);
+    Object.assign(instance, data);
+    return instance;
+  }
+};
+var ConstructorMaterializationStrategy = class {
+  materialize(ctor, data) {
+    const instance = Reflect.construct(ctor, []);
+    Object.assign(instance, data);
+    return instance;
+  }
+};
+var DefaultEntityMaterializer = class {
+  constructor(strategy = new ConstructorMaterializationStrategy()) {
+    this.strategy = strategy;
+  }
+  materialize(ctor, row) {
+    if (hasEntityMeta(row)) {
+      return this.materializeEntityProxy(ctor, row);
+    }
+    const instance = this.strategy.materialize(ctor, row);
+    this.materializeRelations(instance);
+    return instance;
+  }
+  materializeMany(ctor, rows) {
+    return rows.map((row) => this.materialize(ctor, row));
+  }
+  /**
+   * Recursively materializes nested relation data.
+   */
+  materializeRelations(instance) {
+    rebuildRegistry();
+    for (const value of Object.values(instance)) {
+      if (value === null || value === void 0) continue;
+      if (typeof value === "object" && !Array.isArray(value)) {
+        const nested = value;
+        if (this.isEntityLike(nested)) {
+        }
+      }
+      if (Array.isArray(value) && value.length > 0) {
+        const first = value[0];
+        if (typeof first === "object" && first !== null && this.isEntityLike(first)) {
+        }
+      }
+    }
+  }
+  /**
+   * Simple heuristic to check if an object looks like an entity.
+   */
+  isEntityLike(obj) {
+    return "id" in obj || Object.keys(obj).some(
+      (k) => k.endsWith("Id") || k === "createdAt" || k === "updatedAt"
+    );
+  }
+  materializeEntityProxy(ctor, row) {
+    const proxy = row;
+    const baseline = this.strategy.materialize(ctor, {});
+    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;
+  }
+};
+var materializeAs = (ctor, results) => {
+  const materializer = new DefaultEntityMaterializer();
+  return materializer.materializeMany(ctor, results);
+};
+
 // src/query-builder/query-resolution.ts
 function resolveSelectQuery(query) {
   const candidate = query;
@@ -6648,6 +6813,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   relationFacet;
   lazyRelations;
   lazyRelationOptions;
+  entityConstructor;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6655,7 +6821,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions) {
+  constructor(table, state, hydration, dependencies, lazyRelations, lazyRelationOptions, entityConstructor) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState) => deps.createQueryAstService(table, nextState);
@@ -6667,6 +6833,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     };
     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);
@@ -6690,7 +6857,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       context.hydration,
       this.env.deps,
       lazyRelations,
-      lazyRelationOptions
+      lazyRelationOptions,
+      this.entityConstructor
     );
   }
   /**
@@ -6738,7 +6906,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   select(...args) {
     if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && typeof args[0] !== "string") {
       const columns = args[0];
-      return this.clone(this.projectionFacet.select(this.context, columns));
+      return this.clone(
+        this.projectionFacet.select(this.context, columns)
+      );
     }
     const cols = args;
     const selection = {};
@@ -6749,7 +6919,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       }
       selection[key] = col2;
     }
-    return this.clone(this.projectionFacet.select(this.context, selection));
+    return this.clone(
+      this.projectionFacet.select(this.context, selection)
+    );
   }
   /**
    * Selects raw column expressions
@@ -6853,7 +7025,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    */
   selectSubquery(alias, sub2) {
     const query = resolveSelectQuery(sub2);
-    return this.clone(this.projectionFacet.selectSubquery(this.context, alias, query));
+    return this.clone(
+      this.projectionFacet.selectSubquery(this.context, alias, query)
+    );
   }
   /**
    * Adds a JOIN against a derived table (subquery with alias)
@@ -7081,16 +7255,69 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.env.table;
   }
   /**
-   * Executes the query and returns hydrated results
+   * Ensures that if no columns are selected, all columns from the table are selected by default.
+   */
+  ensureDefaultSelection() {
+    const columns = this.context.state.ast.columns;
+    if (!columns || columns.length === 0) {
+      const columnKeys = Object.keys(this.env.table.columns);
+      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
+   * @returns Promise of entity instances (or objects if generic T is not an entity)
    * @example
-   * const users = await qb.select('id', 'name')
-   *   .where(eq(userTable.columns.active, true))
-   *   .execute(session);
+   * const users = await selectFromEntity(User).execute(session);
+   * // users is User[]
+   * users[0] instanceof User; // true
    */
   async execute(ctx) {
-    return executeHydrated(ctx, this);
+    if (this.entityConstructor) {
+      return this.executeAs(this.entityConstructor, ctx);
+    }
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder);
+  }
+  /**
+   * 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) {
+    const builder = this.ensureDefaultSelection();
+    const rows = await executeHydratedPlain(ctx, builder);
+    return rows;
+  }
+  /**
+   * 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 class instances
+   * @example
+   * const users = await selectFromEntity(User)
+   *   .include('posts')
+   *   .executeAs(User, session);
+   * users[0] instanceof User; // true!
+   * users[0].getFullName();   // works!
+   */
+  async executeAs(entityClass, ctx) {
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydrated(ctx, builder);
+    return materializeAs(entityClass, results);
   }
   /**
    * Executes a count query for the current builder without LIMIT/OFFSET clauses.
@@ -7108,7 +7335,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const { items, totalItems } = await qb.executePaged(session, { page: 1, pageSize: 20 });
    */
   async executePaged(session, options) {
-    return executePagedQuery(this, session, options, (sess) => this.count(sess));
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, (sess) => this.count(sess));
   }
   /**
    * Executes the query with provided execution and hydration contexts
@@ -7121,7 +7349,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
   async executeWithContexts(execCtx, hydCtx) {
-    return executeHydratedWithContexts(execCtx, hydCtx, this);
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
+    if (this.entityConstructor) {
+      return materializeAs(this.entityConstructor, results);
+    }
+    return results;
   }
   /**
    * Adds a WHERE condition to the query
@@ -7414,61 +7647,6 @@ var isTableDef = (value) => {
   return true;
 };
 
-// src/orm/entity-metadata.ts
-var metadataMap = /* @__PURE__ */ new Map();
-var ensureEntityMetadata = (target) => {
-  let meta = metadataMap.get(target);
-  if (!meta) {
-    meta = {
-      target,
-      tableName: target.name || "unknown",
-      columns: {},
-      relations: {}
-    };
-    metadataMap.set(target, meta);
-  }
-  return meta;
-};
-var getEntityMetadata = (target) => {
-  return metadataMap.get(target);
-};
-var getAllEntityMetadata = () => {
-  return Array.from(metadataMap.values());
-};
-var addColumnMetadata = (target, propertyKey, column) => {
-  const meta = ensureEntityMetadata(target);
-  meta.columns[propertyKey] = { ...column };
-};
-var addRelationMetadata = (target, propertyKey, relation) => {
-  const meta = ensureEntityMetadata(target);
-  meta.relations[propertyKey] = relation;
-};
-var setEntityTableName = (target, tableName, hooks) => {
-  const meta = ensureEntityMetadata(target);
-  if (tableName && tableName.length > 0) {
-    meta.tableName = tableName;
-  }
-  if (hooks) {
-    meta.hooks = hooks;
-  }
-};
-var buildTableDef = (meta) => {
-  if (meta.table) {
-    return meta.table;
-  }
-  const columns = {};
-  for (const [key, def] of Object.entries(meta.columns)) {
-    columns[key] = {
-      ...def,
-      name: key,
-      table: meta.tableName
-    };
-  }
-  const table = defineTable(meta.tableName, columns, {}, meta.hooks);
-  meta.table = table;
-  return table;
-};
-
 // src/decorators/bootstrap.ts
 var unwrapTarget = (target) => {
   if (typeof target === "function" && target.prototype === void 0) {
@@ -7588,7 +7766,15 @@ var selectFromEntity = (ctor) => {
   if (!table) {
     throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
-  return new SelectQueryBuilder(table);
+  return new SelectQueryBuilder(
+    table,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    void 0,
+    ctor
+  );
 };
 var entityRef = (ctor) => {
   const table = getTableDefFromEntity(ctor);
@@ -12834,7 +13020,9 @@ function createPooledExecutorFactory(opts) {
   BelongsTo,
   BelongsToMany,
   Column,
+  ConstructorMaterializationStrategy,
   DefaultBelongsToReference,
+  DefaultEntityMaterializer,
   DefaultHasManyCollection,
   DefaultManyToManyCollection,
   DeleteQueryBuilder,
@@ -12850,6 +13038,7 @@ function createPooledExecutorFactory(opts) {
   Pool,
   PostgresDialect,
   PrimaryKey,
+  PrototypeMaterializationStrategy,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
@@ -12865,6 +13054,7 @@ function createPooledExecutorFactory(opts) {
   aliasRef,
   and,
   arrayAppend,
+  asType,
   ascii,
   asin,
   atan,
@@ -12930,6 +13120,8 @@ function createPooledExecutorFactory(opts) {
   eq,
   esel,
   executeHydrated,
+  executeHydratedPlain,
+  executeHydratedPlainWithContexts,
   executeHydratedWithContexts,
   executeSchemaSql,
   executeSchemaSqlFor,
@@ -13001,6 +13193,7 @@ function createPooledExecutorFactory(opts) {
   lt,
   lte,
   ltrim,
+  materializeAs,
   max,
   md5,
   min,