metal-orm 1.0.41 → 1.0.43

package/README.md

@@ -171,6 +171,7 @@ MetalORM can be just a straightforward query builder.
 import mysql from 'mysql2/promise';
 import {
   defineTable,
+  tableRef,
   col,
   SelectQueryBuilder,
   eq,
@@ -187,15 +188,14 @@ const todos = defineTable('todos', {
 todos.columns.title.notNull = true;
 todos.columns.done.default = false;
 
+// Optional: opt-in ergonomic column access
+const t = tableRef(todos);
+
 // 2) Build a simple query
 const listOpenTodos = new SelectQueryBuilder(todos)
-  .select({
-    id: todos.columns.id,
-    title: todos.columns.title,
-    done: todos.columns.done,
-  })
-  .where(eq(todos.columns.done, false))
-  .orderBy(todos.columns.id, 'ASC');
+  .selectColumns('id', 'title', 'done')
+  .where(eq(t.done, false))
+  .orderBy(t.id, 'ASC');
 
 // 3) Compile to SQL + params
 const dialect = new MySqlDialect();
@@ -214,6 +214,48 @@ console.log(rows);
 
 That’s it: schema, query, SQL, done.
 
+#### Column pickers (preferred selection helpers)
+
+`defineTable` still exposes the full `table.columns` map for schema metadata and constraint tweaks, but modern queries usually benefit from higher-level helpers instead of spelling `todo.columns.*` everywhere.
+
+```ts
+const t = tableRef(todos);
+
+const listOpenTodos = new SelectQueryBuilder(todos)
+  .selectColumns('id', 'title', 'done') // typed shorthand for the same fields
+  .where(eq(t.done, false))
+  .orderBy(t.id, 'ASC');
+```
+
+`selectColumns`, `selectRelationColumns`, `includePick`, `selectColumnsDeep`, the `sel()` helpers for tables, and `esel()` for entities all build typed selection maps without repeating `table.columns.*`. Use those helpers when building query selections and reserve `table.columns.*` for schema definition, relations, or rare cases where you need a column reference outside of a picker. See the [Query Builder docs](./docs/query-builder.md#selection-helpers) for the reference, examples, and best practices for these helpers.
+
+#### Ergonomic column access (opt-in) with `tableRef`
+
+If you still want the convenience of accessing columns without spelling `.columns`, you can opt-in with `tableRef()`:
+
+```ts
+import { tableRef, eq } from 'metal-orm';
+
+// Existing style (always works)
+const listOpenTodos = new SelectQueryBuilder(todos)
+  .selectColumns('id', 'title', 'done')
+  .where(eq(todos.columns.done, false))
+  .orderBy(todos.columns.id, 'ASC');
+
+// Opt-in ergonomic style
+const t = tableRef(todos);
+
+const listOpenTodos2 = new SelectQueryBuilder(todos)
+  .selectColumns('id', 'title', 'done')
+  .where(eq(t.done, false))
+  .orderBy(t.id, 'ASC');
+```
+
+Collision rule: real table fields win.
+
+- `t.name` is the table name (string)
+- `t.$.name` is the column definition for a colliding column name (escape hatch)
+
 #### 2. Relations & hydration (still no ORM)
 
 Now add relations and get nested objects, still without committing to a runtime.
@@ -227,6 +269,8 @@ import {
   eq,
   count,
   rowNumber,
+  MySqlDialect,
+  sel,
   hydrateRows,
 } from 'metal-orm';
 
@@ -255,22 +299,24 @@ users.columns.name.notNull = true;
 users.columns.email.unique = true;
 
 // Build a query with relation & window function
+const u = sel(users, 'id', 'name', 'email');
+const p = sel(posts, 'id', 'userId');
+
 const builder = new SelectQueryBuilder(users)
   .select({
-    id: users.columns.id,
-    name: users.columns.name,
-    email: users.columns.email,
-    postCount: count(posts.columns.id),
-    rank: rowNumber(),           // window function helper
+    ...u,
+    postCount: count(p.id),
+    rank: rowNumber(), // window function helper
   })
-  .leftJoin(posts, eq(posts.columns.userId, users.columns.id))
-  .groupBy(users.columns.id, users.columns.name, users.columns.email)
-  .orderBy(count(posts.columns.id), 'DESC')
+  .leftJoin(posts, eq(p.userId, u.id))
+  .groupBy(u.id)
+  .groupBy(u.name)
+  .groupBy(u.email)
+  .orderBy(count(p.id), 'DESC')
   .limit(10)
-  .include('posts', {
-    columns: [posts.columns.id, posts.columns.title, posts.columns.createdAt],
-  }); // eager relation for hydration
+  .includePick('posts', ['id', 'title', 'createdAt']); // eager relation for hydration
 
+const dialect = new MySqlDialect();
 const { sql, params } = builder.compile(dialect);
 const [rows] = await connection.execute(sql, params);
 
@@ -314,6 +360,7 @@ import {
   MySqlDialect,
   SelectQueryBuilder,
   eq,
+  tableRef,
   createMysqlExecutor,
 } from 'metal-orm';
 
@@ -326,16 +373,19 @@ const orm = new Orm({
   executorFactory: {
     createExecutor: () => executor,
     createTransactionalExecutor: () => executor,
+    dispose: async () => {},
   },
 });
 const session = new OrmSession({ orm, executor });
 
+const u = tableRef(users);
+
 // 2) Load entities with lazy relations
 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))
+  .where(eq(u.id, 1))
   .execute(session);
 
 // user is an EntityInstance<typeof users>
@@ -383,6 +433,8 @@ import {
   BelongsTo,
   bootstrapEntities,
   selectFromEntity,
+  entityRef,
+  eq,
 } from 'metal-orm';
 
 @Entity()
@@ -433,15 +485,17 @@ const orm = new Orm({
   executorFactory: {
     createExecutor: () => executor,
     createTransactionalExecutor: () => executor,
+    dispose: async () => {},
   },
 });
 const session = new OrmSession({ orm, executor });
 
 // 3) Query starting from the entity class
+const U = entityRef(User);
 const [user] = await selectFromEntity(User)
   .selectColumns('id', 'name')
   .includeLazy('posts')
-  .where(/* same eq()/and() API as before */)
+  .where(eq(U.id, 1))
   .execute(session);
 
 user.posts.add({ title: 'From decorators' });