metal-orm 1.0.16 → 1.0.18

package/README.md

@@ -105,9 +105,10 @@ If you like explicit model classes, you can add a thin decorator layer on top of
   - `@HasMany({ target, foreignKey, ... })`
   - `@HasOne({ target, foreignKey, ... })`
   - `@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.
-- `selectFromEntity(MyEntity)` lets you start a `SelectQueryBuilder` directly from the class.
+- `@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.
+- `selectFromEntity(MyEntity)` lets you start a `SelectQueryBuilder` directly from the class.
+- **Generate entities from an existing DB**: `node scripts/generate-entities.mjs --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.
 
@@ -325,16 +326,12 @@ const orm = new Orm({
 const session = new OrmSession({ orm, executor });
 
 // 2) Load entities with lazy relations
-const [user] = await new SelectQueryBuilder(users)
-  .select({
-    id: users.columns.id,
-    name: users.columns.name,
-    email: users.columns.email,
-  })
-  .includeLazy('posts')  // HasMany as a lazy collection
-  .includeLazy('roles')  // BelongsToMany as a lazy collection
-  .where(eq(users.columns.id, 1))
-  .execute(session);
+const [user] = await new SelectQueryBuilder(users)
+  .selectColumns('id', 'name', 'email')
+  .includeLazy('posts')  // HasMany as a lazy collection
+  .includeLazy('roles')  // BelongsToMany as a lazy collection
+  .where(eq(users.columns.id, 1))
+  .execute(session);
 
 // user is an Entity<typeof users>
 // scalar props are normal:
@@ -355,10 +352,11 @@ await session.commit();
 What the runtime gives you:
 
 - [Identity map](https://en.wikipedia.org/wiki/Identity_map_pattern) (per context).
-- [Unit of Work](https://en.wikipedia.org/wiki/Unit_of_work) style change tracking on scalar properties.
-- Relation tracking (add/remove/sync on collections).
-- Cascades on relations: `'all' | 'persist' | 'remove' | 'link'`.
-- Single flush: `session.commit()` figures out inserts, updates, deletes, and pivot changes.
+- [Unit of Work](https://en.wikipedia.org/wiki/Unit_of_work) style change tracking on scalar properties.
+- Relation tracking (add/remove/sync on collections).
+- Cascades on relations: `'all' | 'persist' | 'remove' | 'link'`.
+- Single flush: `session.commit()` figures out inserts, updates, deletes, and pivot changes.
+- Column pickers to stay DRY: `selectColumns` on the root table, `selectRelationColumns` / `includePick` on relations, and `selectColumnsDeep` or the `sel`/`esel` helpers to build typed selection maps without repeating `table.columns.*`.
 
 <a id="level-3"></a>
 ### Level 3: Decorator entities ✨
@@ -370,11 +368,11 @@ Finally, you can describe your models with decorators and still use the same run
 ```ts
 import mysql from 'mysql2/promise';
 import { Orm, OrmSession, MySqlDialect, col, createMysqlExecutor } from 'metal-orm';
-import {
-  Entity,
-  Column,
-  PrimaryKey,
-  HasMany,
+import {
+  Entity,
+  Column,
+  PrimaryKey,
+  HasMany,
   BelongsTo,
   bootstrapEntities,
   selectFromEntity,
@@ -432,24 +430,23 @@ const orm = new Orm({
 });
 const session = new OrmSession({ orm, executor });
 
-// 3) Query starting from the entity class
-const [user] = await selectFromEntity(User)
-  .select({
-    id: User.prototype.id,   // or map to columns by name/alias as you prefer
-    name: User.prototype.name,
-  })
-  .includeLazy('posts')
-  .where(/* same eq()/and() API as before */)
-  .execute(session);
-
-user.posts.add({ title: 'From decorators' });
-await session.commit();
-```
-
-This level is nice when:
-
-- You want classes as your domain model, but don’t want a separate schema DSL.
-- You like decorators for explicit mapping but still want AST-first SQL and a disciplined runtime.
+// 3) Query starting from the entity class
+const [user] = await selectFromEntity(User)
+  .selectColumns('id', 'name')
+  .includeLazy('posts')
+  .where(/* same eq()/and() API as before */)
+  .execute(session);
+
+user.posts.add({ title: 'From decorators' });
+await session.commit();
+```
+
+Tip: to keep selections terse, use `selectColumns`/`selectRelationColumns` or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over.
+
+This level is nice when:
+
+- You want classes as your domain model, but don't want a separate schema DSL.
+- You like decorators for explicit mapping but still want AST-first SQL and a disciplined runtime.
 
 ---