metal-orm 1.0.81 → 1.0.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.81",
+  "version": "1.0.82",
   "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/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/openapi/query-parameters.ts

@@ -117,6 +117,7 @@ const collectFilterColumns = (
       }
       case 'AliasRef':
       case 'Literal':
+      case 'Param':
         return;
       default:
         return;

package/src/query-builder/relation-filter-utils.ts

@@ -144,6 +144,7 @@ const collectFromOperand = (node: OperandNode, collector: FilterTableCollector):
       break;
     case 'Literal':
     case 'AliasRef':
+    case 'Param':
       break;
     default:
       break;