metal-orm 1.0.81 → 1.0.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.81",
+  "version": "1.0.83",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

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/ast-validation.ts

@@ -0,0 +1,188 @@
+import type { ExpressionNode, OperandNode } from './expression-nodes.js';
+import { visitExpression, visitOperand } from './expression-visitor.js';
+import type { SelectQueryNode } from './query.js';
+
+const hasParamOperandsInExpression = (expr: ExpressionNode): boolean => {
+  let hasParams = false;
+
+  visitExpression(expr, {
+    visitBinaryExpression: (node) => {
+      visitOperand(node.left, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      visitOperand(node.right, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      if (node.escape) {
+        visitOperand(node.escape, {
+          visitParam: () => { hasParams = true; },
+          otherwise: () => {}
+        });
+      }
+    },
+    visitLogicalExpression: (node) => {
+      node.operands.forEach(operand => {
+        if (hasParamOperandsInExpression(operand)) {
+          hasParams = true;
+        }
+      });
+    },
+    visitNullExpression: () => {},
+    visitInExpression: (node) => {
+      visitOperand(node.left, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      if (Array.isArray(node.right)) {
+        node.right.forEach(operand => visitOperand(operand, {
+          visitParam: () => { hasParams = true; },
+          otherwise: () => {}
+        }));
+      }
+    },
+    visitExistsExpression: () => {},
+    visitBetweenExpression: (node) => {
+      visitOperand(node.left, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      visitOperand(node.lower, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      visitOperand(node.upper, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+    },
+    visitArithmeticExpression: (node) => {
+      visitOperand(node.left, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      visitOperand(node.right, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+    },
+    visitBitwiseExpression: (node) => {
+      visitOperand(node.left, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+      visitOperand(node.right, {
+        visitParam: () => { hasParams = true; },
+        otherwise: () => {}
+      });
+    },
+    otherwise: () => {}
+  });
+
+  return hasParams;
+};
+
+const hasParamOperandsInOperand = (operand: OperandNode): boolean => {
+  let hasParams = false;
+
+  visitOperand(operand, {
+    visitColumn: () => {},
+    visitLiteral: () => {},
+    visitParam: () => { hasParams = true; },
+    visitFunction: (node) => {
+      node.args?.forEach(arg => {
+        if (hasParamOperandsInOperand(arg)) {
+          hasParams = true;
+        }
+      });
+    },
+    visitJsonPath: () => {},
+    visitScalarSubquery: () => {},
+    visitCaseExpression: (node) => {
+      node.conditions.forEach(cond => {
+        if (hasParamOperandsInExpression(cond.when)) {
+          hasParams = true;
+        }
+        if (hasParamOperandsInOperand(cond.then)) {
+          hasParams = true;
+        }
+      });
+      if (node.else && hasParamOperandsInOperand(node.else)) {
+        hasParams = true;
+      }
+    },
+    visitCast: (node) => {
+      if (hasParamOperandsInOperand(node.expression)) {
+        hasParams = true;
+      }
+    },
+    visitWindowFunction: (node) => {
+      node.args?.forEach(arg => {
+        if (hasParamOperandsInOperand(arg)) {
+          hasParams = true;
+        }
+      });
+      node.orderBy?.forEach(ord => {
+        if (ord.term) {
+          if (hasParamOperandsInOperand(ord.term as OperandNode)) {
+            hasParams = true;
+          }
+        }
+      });
+    },
+    visitCollate: (node) => {
+      if (hasParamOperandsInOperand(node.expression)) {
+        hasParams = true;
+      }
+    },
+    visitAliasRef: () => {},
+    otherwise: () => {}
+  });
+
+  return hasParams;
+};
+
+export const hasParamOperandsInQuery = (ast: SelectQueryNode): boolean => {
+  if (ast.where && hasParamOperandsInExpression(ast.where)) {
+    return true;
+  }
+
+  if (ast.having && hasParamOperandsInExpression(ast.having)) {
+    return true;
+  }
+
+  ast.columns?.forEach(col => {
+    if (typeof col === 'object' && col !== null && 'type' in col) {
+      if (hasParamOperandsInOperand(col as OperandNode)) {
+        return true;
+      }
+    }
+  });
+
+  ast.orderBy?.forEach(ord => {
+    if (ord.term) {
+      if (hasParamOperandsInOperand(ord.term as OperandNode)) {
+        return true;
+      }
+    }
+  });
+
+  if (ast.ctes) {
+    for (const cte of ast.ctes) {
+      if (cte.query.where && hasParamOperandsInExpression(cte.query.where)) {
+        return true;
+      }
+    }
+  }
+
+  if (ast.setOps) {
+    for (const op of ast.setOps) {
+      if (hasParamOperandsInQuery(op.query)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+};

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

@@ -2,13 +2,14 @@ import { SelectQueryNode } from './query.js';
 import { SqlOperator, BitwiseOperator } from '../sql/sql.js';
 import { ColumnRef } from './types.js';
 import {
-  ColumnNode,
-  LiteralNode,
-  JsonPathNode,
-  OperandNode,
-  CaseExpressionNode,
-  CastExpressionNode,
-  BinaryExpressionNode,
+  ColumnNode,
+  LiteralNode,
+  ParamNode,
+  JsonPathNode,
+  OperandNode,
+  CaseExpressionNode,
+  CastExpressionNode,
+  BinaryExpressionNode,
   ExpressionNode,
   LogicalExpressionNode,
   NullExpressionNode,
@@ -47,12 +48,21 @@ const toLiteralNode = (value: LiteralValue): LiteralNode => ({
   type: 'Literal',
   value: value instanceof Date ? value.toISOString() : value
 });
-
-/**
- * Converts a ColumnRef to a ColumnNode
- * @throws Error if the ColumnRef doesn't have a table specified
- */
-const columnRefToNode = (col: ColumnRef): ColumnNode => {
+
+const toParamNode = (value: unknown): ParamNode | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const type = Object.getOwnPropertyDescriptor(value, 'type')?.value;
+  if (type !== 'Param') return undefined;
+  const name = Object.getOwnPropertyDescriptor(value, 'name')?.value;
+  if (typeof name !== 'string') return undefined;
+  return { type: 'Param', name };
+};
+
+/**
+ * Converts a ColumnRef to a ColumnNode
+ * @throws Error if the ColumnRef doesn't have a table specified
+ */
+const columnRefToNode = (col: ColumnRef): ColumnNode => {
   if (!col.table) {
     throw new Error(
       `Column "${col.name}" requires a table reference. ` +
@@ -67,11 +77,16 @@ const columnRefToNode = (col: ColumnRef): ColumnNode => {
  * @param value - Value to convert (OperandNode, ColumnRef, or literal value)
  * @returns OperandNode representing the value
  */
-const toOperandNode = (value: OperandNode | ColumnRef | LiteralValue): OperandNode => {
-  // Already an operand node
-  if (isOperandNode(value)) {
-    return value;
-  }
+const toOperandNode = (value: OperandNode | ColumnRef | LiteralValue): OperandNode => {
+  const paramNode = toParamNode(value);
+  if (paramNode) {
+    return paramNode;
+  }
+
+  // Already an operand node
+  if (isOperandNode(value)) {
+    return value;
+  }
 
   // Literal value
   if (isLiteralValue(value)) {
@@ -87,12 +102,16 @@ const toOperandNode = (value: OperandNode | ColumnRef | LiteralValue): OperandNo
  * @param value - Value or operand to normalize
  * @returns OperandNode representing the value
  */
-export const valueToOperand = (value: ValueOperandInput): OperandNode => {
-  if (isOperandNode(value)) {
-    return value;
-  }
-  return toLiteralNode(value);
-};
+export const valueToOperand = (value: ValueOperandInput): OperandNode => {
+  const paramNode = toParamNode(value);
+  if (paramNode) {
+    return paramNode;
+  }
+  if (isOperandNode(value)) {
+    return value;
+  }
+  return toLiteralNode(value);
+};
 
 /**
  * Converts various input types to an OperandNode

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,47 @@
+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 && name === '') {
+        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));
+      }
+      return buildParamProxy(String(prop));
+    }
+  }) as ParamProxyRoot;
+};