metal-orm 1.0.41 → 1.0.42

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,7 @@ import {
   eq,
   count,
   rowNumber,
+  sel,
   hydrateRows,
 } from 'metal-orm';
 
@@ -257,19 +300,15 @@ users.columns.email.unique = true;
 // Build a query with relation & window function
 const builder = new SelectQueryBuilder(users)
   .select({
-    id: users.columns.id,
-    name: users.columns.name,
-    email: users.columns.email,
+    ...sel(users, 'id', 'name', 'email'),
     postCount: count(posts.columns.id),
-    rank: rowNumber(),           // window function helper
+    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')
   .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 { sql, params } = builder.compile(dialect);
 const [rows] = await connection.execute(sql, params);

package/dist/index.cjs

@@ -225,6 +225,7 @@ __export(index_exports, {
   substr: () => substr,
   sum: () => sum,
   synchronizeSchema: () => synchronizeSchema,
+  tableRef: () => tableRef,
   tan: () => tan,
   toColumnRef: () => toColumnRef,
   toTableRef: () => toTableRef,
@@ -264,6 +265,54 @@ var defineTable = (name, columns, relations = {}, hooks, options = {}) => {
     collation: options.collation
   };
 };
+var TABLE_REF_CACHE = /* @__PURE__ */ new WeakMap();
+var withColumnProps = (table) => {
+  const cached = TABLE_REF_CACHE.get(table);
+  if (cached) return cached;
+  const proxy = new Proxy(table, {
+    get(target, prop, receiver) {
+      if (prop === "$") return target.columns;
+      if (Reflect.has(target, prop)) return Reflect.get(target, prop, receiver);
+      if (typeof prop === "string" && prop in target.columns) return target.columns[prop];
+      return void 0;
+    },
+    has(target, prop) {
+      return prop === "$" || Reflect.has(target, prop) || typeof prop === "string" && prop in target.columns;
+    },
+    ownKeys(target) {
+      const base = Reflect.ownKeys(target);
+      const cols = Object.keys(target.columns);
+      for (const k of cols) {
+        if (!base.includes(k)) base.push(k);
+      }
+      if (!base.includes("$")) base.push("$");
+      return base;
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop === "$") {
+        return {
+          configurable: true,
+          enumerable: false,
+          get() {
+            return target.columns;
+          }
+        };
+      }
+      if (typeof prop === "string" && prop in target.columns && !Reflect.has(target, prop)) {
+        return {
+          configurable: true,
+          enumerable: true,
+          value: target.columns[prop],
+          writable: false
+        };
+      }
+      return Reflect.getOwnPropertyDescriptor(target, prop);
+    }
+  });
+  TABLE_REF_CACHE.set(table, proxy);
+  return proxy;
+};
+var tableRef = (table) => withColumnProps(table);
 
 // src/schema/column.ts
 var col = {
@@ -3214,7 +3263,7 @@ var QueryAstService = class {
   }
   normalizeOrderingTerm(term) {
     const from = this.state.ast.from;
-    const tableRef = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
+    const tableRef2 = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
     const termType = term?.type;
     if (termType === "Column") {
       return term;
@@ -3228,7 +3277,7 @@ var QueryAstService = class {
     if (termType === "BinaryExpression" || termType === "LogicalExpression" || termType === "NullExpression" || termType === "InExpression" || termType === "ExistsExpression" || termType === "BetweenExpression" || termType === "ArithmeticExpression") {
       return term;
     }
-    return buildColumnNode(tableRef, term);
+    return buildColumnNode(tableRef2, term);
   }
 };
 
@@ -3634,8 +3683,8 @@ var ColumnSelector = class {
    */
   distinct(context, columns) {
     const from = context.state.ast.from;
-    const tableRef = from.type === "Table" && from.alias ? { ...this.env.table, alias: from.alias } : this.env.table;
-    const nodes = columns.map((col2) => buildColumnNode(tableRef, col2));
+    const tableRef2 = from.type === "Table" && from.alias ? { ...this.env.table, alias: from.alias } : this.env.table;
+    const nodes = columns.map((col2) => buildColumnNode(tableRef2, col2));
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withDistinct(nodes);
     return { state: nextState, hydration: context.hydration };
@@ -9595,6 +9644,7 @@ function createPooledExecutorFactory(opts) {
   substr,
   sum,
   synchronizeSchema,
+  tableRef,
   tan,
   toColumnRef,
   toTableRef,