metal-orm 1.0.80 → 1.0.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -59,11 +59,13 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "@types/express": "^5.0.6",
     "@typescript-eslint/eslint-plugin": "^8.20.0",
     "@typescript-eslint/parser": "^8.20.0",
     "@vitest/ui": "^4.0.14",
     "eslint": "^8.57.0",
     "eslint-plugin-deprecation": "^3.0.0",
+    "express": "^5.2.1",
     "mysql-memory-server": "^1.13.0",
     "mysql2": "^3.15.3",
     "pg": "^8.16.3",

package/src/codegen/typescript.ts

@@ -17,13 +17,14 @@ import {
   LiteralNode,
   FunctionNode,
   AliasRefNode,
-  CastExpressionNode,
-  CollateExpressionNode,
-  ExpressionVisitor,
-  OperandVisitor,
-  visitExpression,
-  visitOperand
-} from '../core/ast/expression.js';
+  CastExpressionNode,
+  CollateExpressionNode,
+  ParamNode,
+  ExpressionVisitor,
+  OperandVisitor,
+  visitExpression,
+  visitOperand
+} from '../core/ast/expression.js';
 import { SQL_OPERATOR_REGISTRY } from '../core/sql/sql-operator-config.js';
 import { SqlOperator } from '../core/sql/sql.js';
 import { isRelationAlias } from '../query-builder/relation-alias.js';
@@ -190,13 +191,14 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
       case 'ScalarSubquery':
       case 'CaseExpression':
       case 'WindowFunction':
-      case 'Cast':
-      case 'Collate':
-        return this.printOperand(term);
-      default:
-        return this.printExpression(term);
-    }
-  }
+      case 'Cast':
+      case 'Collate':
+      case 'Param':
+        return this.printOperand(term);
+      default:
+        return this.printExpression(term);
+    }
+  }
 
   private getSelectionKey(selection: SelectionColumn, index: number): string {
     if (selection.alias) {
@@ -244,13 +246,17 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
     return this.printColumnOperand(node);
   }
 
-  public visitLiteral(node: LiteralNode): string {
-    return this.printLiteralOperand(node);
-  }
-
-  public visitFunction(node: FunctionNode): string {
-    return this.printFunctionOperand(node);
-  }
+  public visitLiteral(node: LiteralNode): string {
+    return this.printLiteralOperand(node);
+  }
+
+  public visitParam(node: ParamNode): string {
+    return this.printParamOperand(node);
+  }
+
+  public visitFunction(node: FunctionNode): string {
+    return this.printFunctionOperand(node);
+  }
 
   public visitJsonPath(node: JsonPathNode): string {
     return this.printJsonPathOperand(node);
@@ -379,14 +385,19 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
    * @param literal - Literal node
    * @returns TypeScript code representation
    */
-  private printLiteralOperand(literal: LiteralNode): string {
-    if (literal.value === null) return 'null';
-    return typeof literal.value === 'string' ? `'${literal.value}'` : String(literal.value);
-  }
-
-  /**
-   * Prints a function operand to TypeScript code
-   * @param fn - Function node
+  private printLiteralOperand(literal: LiteralNode): string {
+    if (literal.value === null) return 'null';
+    return typeof literal.value === 'string' ? `'${literal.value}'` : String(literal.value);
+  }
+
+  private printParamOperand(param: ParamNode): string {
+    const name = param.name.replace(/'/g, "\\'");
+    return `{ type: 'Param', name: '${name}' }`;
+  }
+
+  /**
+   * Prints a function operand to TypeScript code
+   * @param fn - Function node
    * @returns TypeScript code representation
    */
   private printFunctionOperand(fn: FunctionNode): string {

package/src/core/ast/expression-nodes.ts

@@ -2,14 +2,23 @@ import type { SelectQueryNode, OrderByNode } from './query.js';
 import { SqlOperator, BitwiseOperator } from '../sql/sql.js';
 import { ColumnRef } from './types.js';
 
-/**
- * AST node representing a literal value
- */
+/**
+ * AST node representing a literal value
+ */
 export interface LiteralNode {
   type: 'Literal';
   /** The literal value (string, number, boolean, Date, or null) */
   value: string | number | boolean | Date | null;
 }
+
+/**
+ * AST node representing a named parameter placeholder
+ */
+export interface ParamNode {
+  type: 'Param';
+  /** Stable parameter name */
+  name: string;
+}
 
 /**
  * AST node representing a reference to a SELECT alias (for ORDER BY / GROUP BY).
@@ -149,29 +158,31 @@ export interface ArithmeticExpressionNode {
 /**
  * Union type representing any operand that can be used in expressions
  */
-export type OperandNode =
-  | AliasRefNode
-  | ColumnNode
-  | LiteralNode
-  | FunctionNode
-  | JsonPathNode
-  | ScalarSubqueryNode
-  | CaseExpressionNode
-  | CastExpressionNode
+export type OperandNode =
+  | AliasRefNode
+  | ColumnNode
+  | LiteralNode
+  | ParamNode
+  | FunctionNode
+  | JsonPathNode
+  | ScalarSubqueryNode
+  | CaseExpressionNode
+  | CastExpressionNode
   | WindowFunctionNode
   | ArithmeticExpressionNode
   | BitwiseExpressionNode
   | CollateExpressionNode;
 
-const operandTypes = new Set<OperandNode['type']>([
-  'AliasRef',
-  'Column',
-  'Literal',
-  'Function',
-  'JsonPath',
-  'ScalarSubquery',
-  'CaseExpression',
-  'Cast',
+const operandTypes = new Set<OperandNode['type']>([
+  'AliasRef',
+  'Column',
+  'Literal',
+  'Param',
+  'Function',
+  'JsonPath',
+  'ScalarSubquery',
+  'CaseExpression',
+  'Cast',
   'WindowFunction',
   'ArithmeticExpression',
   'BitwiseExpression',

package/src/core/ast/expression-visitor.ts

@@ -18,7 +18,8 @@ import {
   WindowFunctionNode,
   CollateExpressionNode,
   AliasRefNode,
-  BitwiseExpressionNode
+  BitwiseExpressionNode,
+  ParamNode
 } from './expression-nodes.js';
 
 /**
@@ -42,6 +43,7 @@ export interface ExpressionVisitor<R> {
 export interface OperandVisitor<R> {
   visitColumn?(node: ColumnNode): R;
   visitLiteral?(node: LiteralNode): R;
+  visitParam?(node: ParamNode): R;
   visitFunction?(node: FunctionNode): R;
   visitJsonPath?(node: JsonPathNode): R;
   visitScalarSubquery?(node: ScalarSubqueryNode): R;
@@ -187,6 +189,9 @@ export const visitOperand = <R>(node: OperandNode, visitor: OperandVisitor<R>):
     case 'Literal':
       if (visitor.visitLiteral) return visitor.visitLiteral(node);
       break;
+    case 'Param':
+      if (visitor.visitParam) return visitor.visitParam(node);
+      break;
     case 'Function':
       if (visitor.visitFunction) return visitor.visitFunction(node);
       break;

package/src/core/ast/expression.ts

@@ -9,6 +9,7 @@ export * from './expression-builders.js';
 export * from './window-functions.js';
 export * from './aggregate-functions.js';
 export * from './expression-visitor.js';
+export * from './param-proxy.js';
 export type { ColumnRef, TableRef as AstTableRef } from './types.js';
 export * from './adapters.js';
 

package/src/core/ast/param-proxy.ts

@@ -0,0 +1,50 @@
+import type { ParamNode } from './expression-nodes.js';
+
+export type ParamProxy = ParamNode & {
+  [key: string]: ParamProxy;
+};
+
+export type ParamProxyRoot = {
+  [key: string]: ParamProxy;
+};
+
+const buildParamProxy = (name: string): ParamProxy => {
+  const target: ParamNode = { type: 'Param', name };
+  return new Proxy(target, {
+    get(t, prop, receiver) {
+      if (prop === 'then') return undefined;
+      if (typeof prop === 'symbol') {
+        return Reflect.get(t, prop, receiver);
+      }
+      if (typeof prop === 'string' && prop.startsWith('$')) {
+        const trimmed = prop.slice(1);
+        const nextName = name ? `${name}.${trimmed}` : trimmed;
+        return buildParamProxy(nextName);
+      }
+      if (prop in t) {
+        return (t as unknown as Record<string, unknown>)[prop];
+      }
+      const nextName = name ? `${name}.${prop}` : prop;
+      return buildParamProxy(nextName);
+    }
+  }) as ParamProxy;
+};
+
+export const createParamProxy = (): ParamProxyRoot => {
+  const target: Record<string, unknown> = {};
+  return new Proxy(target, {
+    get(t, prop, receiver) {
+      if (prop === 'then') return undefined;
+      if (typeof prop === 'symbol') {
+        return Reflect.get(t, prop, receiver);
+      }
+      if (typeof prop === 'string' && prop.startsWith('$')) {
+        return buildParamProxy(prop.slice(1));
+      }
+      if (prop in t) {
+        return (t as unknown as Record<string, unknown>)[prop];
+      }
+      return buildParamProxy(String(prop));
+    }
+  }) as ParamProxyRoot;
+};

package/src/core/dialect/abstract.ts

@@ -26,10 +26,11 @@ import {
   BetweenExpressionNode,
   ArithmeticExpressionNode,
   BitwiseExpressionNode,
-  CollateExpressionNode,
-  AliasRefNode,
-  isOperandNode
-} from '../ast/expression.js';
+  CollateExpressionNode,
+  AliasRefNode,
+  isOperandNode,
+  ParamNode
+} from '../ast/expression.js';
 import { DialectName } from '../sql/sql.js';
 import type { FunctionStrategy } from '../functions/types.js';
 import { StandardFunctionStrategy } from '../functions/standard-strategy.js';
@@ -453,12 +454,13 @@ export abstract class Dialect
   }
 
   private registerDefaultOperandCompilers(): void {
-    this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
-
-    this.registerOperandCompiler('AliasRef', (alias: AliasRefNode, _ctx) => {
-      void _ctx;
-      return this.quoteIdentifier(alias.name);
-    });
+    this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
+    this.registerOperandCompiler('Param', (_param: ParamNode, ctx) => ctx.addParameter(null));
+
+    this.registerOperandCompiler('AliasRef', (alias: AliasRefNode, _ctx) => {
+      void _ctx;
+      return this.quoteIdentifier(alias.name);
+    });
 
     this.registerOperandCompiler('Column', (column: ColumnNode, _ctx) => {
       void _ctx;

package/src/core/execution/db-executor.ts

@@ -1,10 +1,11 @@
 // src/core/execution/db-executor.ts
 
 // low-level canonical shape
-export type QueryResult = {
-  columns: string[];
-  values: unknown[][];
-};
+export type QueryResult = {
+  columns: string[];
+  values: unknown[][];
+  insertId?: number;
+};
 
 export interface DbExecutor {
   /** Capability flags so the runtime can make correct decisions without relying on optional methods. */

package/src/core/execution/executors/mysql-executor.ts

@@ -31,13 +31,15 @@ export function createMysqlExecutor(
     capabilities: {
       transactions: supportsTransactions,
     },
-    async executeSql(sql, params) {
-      const [rows] = await client.query(sql, params);
-
-      if (!Array.isArray(rows)) {
-        // e.g. insert/update returning only headers, treat as no rows
-        return [{ columns: [], values: [] }];
-      }
+    async executeSql(sql, params) {
+      const [rows] = await client.query(sql, params);
+
+      if (!Array.isArray(rows)) {
+        const insertId = (rows as { insertId?: number } | null)?.insertId;
+        const normalized = typeof insertId === 'number' && insertId > 0 ? insertId : undefined;
+        // e.g. insert/update returning only headers, treat as no rows
+        return [{ columns: [], values: [], insertId: normalized }];
+      }
 
       const result = rowsToQueryResult(
         rows as Array<Record<string, unknown>>

package/src/openapi/index.ts

@@ -1,3 +1,4 @@
 export * from './schema-types.js';
 export * from './type-mappers.js';
 export * from './schema-extractor.js';
+export * from './query-parameters.js';

package/src/openapi/query-parameters.ts

@@ -0,0 +1,207 @@
+import type { TableDef } from '../schema/table.js';
+import {
+  isOperandNode,
+  type ExpressionNode,
+  type OperandNode,
+  type ColumnNode,
+  type FunctionNode,
+  type JsonPathNode,
+  type CaseExpressionNode,
+  type CastExpressionNode,
+  type WindowFunctionNode,
+  type ArithmeticExpressionNode,
+  type BitwiseExpressionNode,
+  type CollateExpressionNode
+} from '../core/ast/expression.js';
+import type { TableSourceNode, OrderByNode, OrderingTerm } from '../core/ast/query.js';
+import type { ColumnSchemaOptions, JsonSchemaProperty, OpenApiParameter } from './schema-types.js';
+import { mapColumnType } from './type-mappers.js';
+
+const FILTER_PARAM_NAME = 'filter';
+
+const buildRootTableNames = (table: TableDef, from?: TableSourceNode): Set<string> => {
+  const names = new Set<string>([table.name]);
+  if (from?.type === 'Table') {
+    names.add(from.name);
+    if (from.alias) names.add(from.alias);
+  }
+  return names;
+};
+
+const collectFilterColumns = (
+  expr: ExpressionNode,
+  table: TableDef,
+  rootTables: Set<string>
+): Set<string> => {
+  const columns = new Set<string>();
+
+  const recordColumn = (node: ColumnNode): void => {
+    if (!rootTables.has(node.table)) return;
+    if (node.name in table.columns) {
+      columns.add(node.name);
+    }
+  };
+
+  const visitOrderingTerm = (term: OrderingTerm): void => {
+    if (!term || typeof term !== 'object') return;
+    if (isOperandNode(term)) {
+      visitOperand(term as OperandNode);
+      return;
+    }
+    if ('type' in term) {
+      visitExpression(term as ExpressionNode);
+    }
+  };
+
+  const visitOrderBy = (orderBy: OrderByNode[] | undefined): void => {
+    if (!orderBy) return;
+    orderBy.forEach(node => visitOrderingTerm(node.term));
+  };
+
+  const visitOperand = (node: OperandNode): void => {
+    switch (node.type) {
+      case 'Column':
+        recordColumn(node as ColumnNode);
+        return;
+      case 'Function': {
+        const fn = node as FunctionNode;
+        fn.args?.forEach(visitOperand);
+        visitOrderBy(fn.orderBy);
+        if (fn.separator) visitOperand(fn.separator);
+        return;
+      }
+      case 'JsonPath': {
+        const jp = node as JsonPathNode;
+        recordColumn(jp.column);
+        return;
+      }
+      case 'ScalarSubquery':
+        return;
+      case 'CaseExpression': {
+        const cs = node as CaseExpressionNode;
+        cs.conditions.forEach(condition => {
+          visitExpression(condition.when);
+          visitOperand(condition.then);
+        });
+        if (cs.else) visitOperand(cs.else);
+        return;
+      }
+      case 'Cast': {
+        const cast = node as CastExpressionNode;
+        visitOperand(cast.expression);
+        return;
+      }
+      case 'WindowFunction': {
+        const windowFn = node as WindowFunctionNode;
+        windowFn.args?.forEach(visitOperand);
+        windowFn.partitionBy?.forEach(recordColumn);
+        visitOrderBy(windowFn.orderBy);
+        return;
+      }
+      case 'ArithmeticExpression': {
+        const arith = node as ArithmeticExpressionNode;
+        visitOperand(arith.left);
+        visitOperand(arith.right);
+        return;
+      }
+      case 'BitwiseExpression': {
+        const bitwise = node as BitwiseExpressionNode;
+        visitOperand(bitwise.left);
+        visitOperand(bitwise.right);
+        return;
+      }
+      case 'Collate': {
+        const collate = node as CollateExpressionNode;
+        visitOperand(collate.expression);
+        return;
+      }
+      case 'AliasRef':
+      case 'Literal':
+      case 'Param':
+        return;
+      default:
+        return;
+    }
+  };
+
+  const visitExpression = (node: ExpressionNode): void => {
+    switch (node.type) {
+      case 'BinaryExpression':
+        visitOperand(node.left);
+        visitOperand(node.right);
+        if (node.escape) visitOperand(node.escape);
+        return;
+      case 'LogicalExpression':
+        node.operands.forEach(visitExpression);
+        return;
+      case 'NullExpression':
+        visitOperand(node.left);
+        return;
+      case 'InExpression':
+        visitOperand(node.left);
+        if (Array.isArray(node.right)) {
+          node.right.forEach(visitOperand);
+        }
+        return;
+      case 'ExistsExpression':
+        return;
+      case 'BetweenExpression':
+        visitOperand(node.left);
+        visitOperand(node.lower);
+        visitOperand(node.upper);
+        return;
+      case 'ArithmeticExpression':
+        visitOperand(node.left);
+        visitOperand(node.right);
+        return;
+      case 'BitwiseExpression':
+        visitOperand(node.left);
+        visitOperand(node.right);
+        return;
+      default:
+        return;
+    }
+  };
+
+  visitExpression(expr);
+  return columns;
+};
+
+export const buildFilterParameters = (
+  table: TableDef,
+  where: ExpressionNode | undefined,
+  from: TableSourceNode | undefined,
+  options: ColumnSchemaOptions = {}
+): OpenApiParameter[] => {
+  if (!where) return [];
+
+  const rootTables = buildRootTableNames(table, from);
+  const columnNames = collectFilterColumns(where, table, rootTables);
+
+  let schema: JsonSchemaProperty;
+  if (columnNames.size) {
+    const properties: Record<string, JsonSchemaProperty> = {};
+    for (const name of columnNames) {
+      const column = table.columns[name];
+      if (!column) continue;
+      properties[name] = mapColumnType(column, options);
+    }
+    schema = {
+      type: 'object',
+      properties
+    };
+  } else {
+    schema = {
+      type: 'object',
+      additionalProperties: true
+    };
+  }
+
+  return [{
+    name: FILTER_PARAM_NAME,
+    in: 'query',
+    style: 'deepObject',
+    explode: true,
+    schema
+  }];
+};