metal-orm 1.0.60 → 1.0.62

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,
@@ -214,6 +217,7 @@ __export(index_exports, {
   lt: () => lt,
   lte: () => lte,
   ltrim: () => ltrim,
+  materializeAs: () => materializeAs,
   max: () => max,
   md5: () => md5,
   min: () => min,
@@ -6238,6 +6242,132 @@ 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) {
+    const instance = this.strategy.materialize(ctor, row);
+    this.materializeRelations(instance, ctor);
+    return instance;
+  }
+  materializeMany(ctor, rows) {
+    return rows.map((row) => this.materialize(ctor, row));
+  }
+  /**
+   * Recursively materializes nested relation data.
+   */
+  materializeRelations(instance, _ctor) {
+    rebuildRegistry();
+    for (const [key, value] of Object.entries(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"
+    );
+  }
+};
+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 +6778,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   relationFacet;
   lazyRelations;
   lazyRelationOptions;
+  entityConstructor;
   /**
    * Creates a new SelectQueryBuilder instance
    * @param table - Table definition to query
@@ -6655,7 +6786,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 +6798,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 +6822,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
       context.hydration,
       this.env.deps,
       lazyRelations,
-      lazyRelationOptions
+      lazyRelationOptions,
+      this.entityConstructor
     );
   }
   /**
@@ -7081,16 +7214,67 @@ 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) {
+      return this.select(...Object.keys(this.env.table.columns));
+    }
+    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();
+    return executeHydrated(ctx, builder);
+  }
+  /**
+   * 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 +7292,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 +7306,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 +7604,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 +7723,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 +12977,9 @@ function createPooledExecutorFactory(opts) {
   BelongsTo,
   BelongsToMany,
   Column,
+  ConstructorMaterializationStrategy,
   DefaultBelongsToReference,
+  DefaultEntityMaterializer,
   DefaultHasManyCollection,
   DefaultManyToManyCollection,
   DeleteQueryBuilder,
@@ -12850,6 +12995,7 @@ function createPooledExecutorFactory(opts) {
   Pool,
   PostgresDialect,
   PrimaryKey,
+  PrototypeMaterializationStrategy,
   RelationKinds,
   STANDARD_COLUMN_TYPES,
   SelectQueryBuilder,
@@ -13001,6 +13147,7 @@ function createPooledExecutorFactory(opts) {
   lt,
   lte,
   ltrim,
+  materializeAs,
   max,
   md5,
   min,