metal-orm 1.0.16 → 1.0.17

package/README.md

@@ -325,16 +325,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 +351,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 +367,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 +429,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.
 
 ---
 

package/dist/decorators/index.cjs

@@ -332,6 +332,15 @@ var isWindowFunctionNode = (node) => node?.type === "WindowFunction";
 var isExpressionSelectionNode = (node) => isFunctionNode(node) || isCaseExpressionNode(node) || isWindowFunctionNode(node);
 
 // src/core/ast/expression-builders.ts
+var valueToOperand = (value) => {
+  if (isOperandNode(value)) {
+    return value;
+  }
+  return {
+    type: "Literal",
+    value
+  };
+};
 var toNode = (col) => {
   if (isOperandNode(col)) return col;
   const def = col;
@@ -341,10 +350,10 @@ var toLiteralNode = (value) => ({
   type: "Literal",
   value
 });
+var isLiteralValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 var toOperand = (val) => {
-  if (val === null) return { type: "Literal", value: null };
-  if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
-    return { type: "Literal", value: val };
+  if (isLiteralValue(val)) {
+    return valueToOperand(val);
   }
   return toNode(val);
 };
@@ -385,6 +394,24 @@ var notExists = (subquery) => ({
   subquery
 });
 
+// src/core/sql/sql.ts
+var JOIN_KINDS = {
+  /** INNER JOIN type */
+  INNER: "INNER",
+  /** LEFT JOIN type */
+  LEFT: "LEFT",
+  /** RIGHT JOIN type */
+  RIGHT: "RIGHT",
+  /** CROSS JOIN type */
+  CROSS: "CROSS"
+};
+var ORDER_DIRECTIONS = {
+  /** Ascending order */
+  ASC: "ASC",
+  /** Descending order */
+  DESC: "DESC"
+};
+
 // src/core/ast/aggregate-functions.ts
 var buildAggregate = (name) => (col) => ({
   type: "Function",
@@ -394,14 +421,21 @@ var buildAggregate = (name) => (col) => ({
 var count = buildAggregate("COUNT");
 var sum = buildAggregate("SUM");
 var avg = buildAggregate("AVG");
+var min = buildAggregate("MIN");
+var max = buildAggregate("MAX");
 
 // src/core/functions/standard-strategy.ts
-var StandardFunctionStrategy = class {
+var StandardFunctionStrategy = class _StandardFunctionStrategy {
   constructor() {
     this.renderers = /* @__PURE__ */ new Map();
     this.registerStandard();
   }
   registerStandard() {
+    this.add("COUNT", ({ compiledArgs }) => `COUNT(${compiledArgs.join(", ")})`);
+    this.add("SUM", ({ compiledArgs }) => `SUM(${compiledArgs[0]})`);
+    this.add("AVG", ({ compiledArgs }) => `AVG(${compiledArgs[0]})`);
+    this.add("MIN", ({ compiledArgs }) => `MIN(${compiledArgs[0]})`);
+    this.add("MAX", ({ compiledArgs }) => `MAX(${compiledArgs[0]})`);
     this.add("ABS", ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
     this.add("UPPER", ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
     this.add("LOWER", ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
@@ -428,6 +462,7 @@ var StandardFunctionStrategy = class {
     this.add("DAY_OF_WEEK", ({ compiledArgs }) => `DAYOFWEEK(${compiledArgs[0]})`);
     this.add("WEEK_OF_YEAR", ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
     this.add("DATE_TRUNC", ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
+    this.add("GROUP_CONCAT", (ctx) => this.renderGroupConcat(ctx));
   }
   add(name, renderer) {
     this.renderers.set(name, renderer);
@@ -435,6 +470,36 @@ var StandardFunctionStrategy = class {
   getRenderer(name) {
     return this.renderers.get(name);
   }
+  renderGroupConcat(ctx) {
+    const arg = ctx.compiledArgs[0];
+    const orderClause = this.buildOrderByExpression(ctx);
+    const orderSegment = orderClause ? ` ${orderClause}` : "";
+    const separatorClause = this.formatGroupConcatSeparator(ctx);
+    return `GROUP_CONCAT(${arg}${orderSegment}${separatorClause})`;
+  }
+  buildOrderByExpression(ctx) {
+    const orderBy = ctx.node.orderBy;
+    if (!orderBy || orderBy.length === 0) {
+      return "";
+    }
+    const parts = orderBy.map((order) => `${ctx.compileOperand(order.column)} ${order.direction}`);
+    return `ORDER BY ${parts.join(", ")}`;
+  }
+  formatGroupConcatSeparator(ctx) {
+    if (!ctx.node.separator) {
+      return "";
+    }
+    return ` SEPARATOR ${ctx.compileOperand(ctx.node.separator)}`;
+  }
+  getGroupConcatSeparatorOperand(ctx) {
+    return ctx.node.separator ?? _StandardFunctionStrategy.DEFAULT_GROUP_CONCAT_SEPARATOR;
+  }
+  static {
+    this.DEFAULT_GROUP_CONCAT_SEPARATOR = {
+      type: "Literal",
+      value: ","
+    };
+  }
 };
 
 // src/core/dialect/abstract.ts
@@ -781,7 +846,11 @@ var Dialect = class _Dialect {
     const compiledArgs = fnNode.args.map((arg) => this.compileOperand(arg, ctx));
     const renderer = this.functionStrategy.getRenderer(fnNode.name);
     if (renderer) {
-      return renderer({ node: fnNode, compiledArgs });
+      return renderer({
+        node: fnNode,
+        compiledArgs,
+        compileOperand: (operand) => this.compileOperand(operand, ctx)
+      });
     }
     return `${fnNode.name}(${compiledArgs.join(", ")})`;
   }
@@ -1204,6 +1273,14 @@ var PostgresFunctionStrategy = class extends StandardFunctionStrategy {
       const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
       return `DATE_TRUNC('${partClean}', ${date})`;
     });
+    this.add("GROUP_CONCAT", (ctx) => {
+      const arg = ctx.compiledArgs[0];
+      const orderClause = this.buildOrderByExpression(ctx);
+      const orderSegment = orderClause ? ` ${orderClause}` : "";
+      const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+      const separator = ctx.compileOperand(separatorOperand);
+      return `STRING_AGG(${arg}, ${separator}${orderSegment})`;
+    });
   }
 };
 
@@ -1448,6 +1525,12 @@ var SqliteFunctionStrategy = class extends StandardFunctionStrategy {
       }
       return `date(${date}, 'start of ${partClean}')`;
     });
+    this.add("GROUP_CONCAT", (ctx) => {
+      const arg = ctx.compiledArgs[0];
+      const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+      const separator = ctx.compileOperand(separatorOperand);
+      return `GROUP_CONCAT(${arg}, ${separator})`;
+    });
   }
 };
 
@@ -1564,6 +1647,14 @@ var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
       const partClean = String(partArg.value).replace(/['"]/g, "").toLowerCase();
       return `DATETRUNC(${partClean}, ${date})`;
     });
+    this.add("GROUP_CONCAT", (ctx) => {
+      const arg = ctx.compiledArgs[0];
+      const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+      const separator = ctx.compileOperand(separatorOperand);
+      const orderClause = this.buildOrderByExpression(ctx);
+      const withinGroup = orderClause ? ` WITHIN GROUP (${orderClause})` : "";
+      return `STRING_AGG(${arg}, ${separator})${withinGroup}`;
+    });
   }
 };
 
@@ -1933,24 +2024,6 @@ var createJoinNode = (kind, tableName, condition, relationName) => ({
   meta: relationName ? { relationName } : void 0
 });
 
-// src/core/sql/sql.ts
-var JOIN_KINDS = {
-  /** INNER JOIN type */
-  INNER: "INNER",
-  /** LEFT JOIN type */
-  LEFT: "LEFT",
-  /** RIGHT JOIN type */
-  RIGHT: "RIGHT",
-  /** CROSS JOIN type */
-  CROSS: "CROSS"
-};
-var ORDER_DIRECTIONS = {
-  /** Ascending order */
-  ASC: "ASC",
-  /** Descending order */
-  DESC: "DESC"
-};
-
 // src/query-builder/hydration-manager.ts
 var HydrationManager = class _HydrationManager {
   /**
@@ -4059,6 +4132,21 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   select(columns) {
     return this.clone(this.columnSelector.select(this.context, columns));
   }
+  /**
+   * Selects columns from the root table by name (typed).
+   * @param cols - Column names on the root table
+   */
+  selectColumns(...cols) {
+    const selection = {};
+    for (const key of cols) {
+      const col = this.env.table.columns[key];
+      if (!col) {
+        throw new Error(`Column '${key}' not found on table '${this.env.table.name}'`);
+      }
+      selection[key] = col;
+    }
+    return this.select(selection);
+  }
   /**
   
      * Selects raw column expressions
@@ -4219,6 +4307,47 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     nextLazy.add(relationName);
     return this.clone(this.context, nextLazy);
   }
+  /**
+   * Selects columns for a related table in a single hop.
+   */
+  selectRelationColumns(relationName, ...cols) {
+    const relation = this.env.table.relations[relationName];
+    if (!relation) {
+      throw new Error(`Relation '${relationName}' not found on table '${this.env.table.name}'`);
+    }
+    const target = relation.target;
+    for (const col of cols) {
+      if (!target.columns[col]) {
+        throw new Error(
+          `Column '${col}' not found on related table '${target.name}' for relation '${relationName}'`
+        );
+      }
+    }
+    return this.include(relationName, { columns: cols });
+  }
+  /**
+   * Convenience alias for selecting specific columns from a relation.
+   */
+  includePick(relationName, cols) {
+    return this.selectRelationColumns(relationName, ...cols);
+  }
+  /**
+   * Selects columns for the root table and relations from a single config object.
+   */
+  selectColumnsDeep(config) {
+    let qb = this;
+    if (config.root?.length) {
+      qb = qb.selectColumns(...config.root);
+    }
+    for (const key of Object.keys(config)) {
+      if (key === "root") continue;
+      const relName = key;
+      const cols = config[relName];
+      if (!cols || !cols.length) continue;
+      qb = qb.selectRelationColumns(relName, ...cols);
+    }
+    return qb;
+  }
   getLazyRelations() {
     return Array.from(this.lazyRelations);
   }