metal-orm 1.0.59 → 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: