metal-orm 1.0.1 → 1.0.3

package/src/codegen/typescript.ts

@@ -16,17 +16,41 @@ import {
   LiteralNode,
   FunctionNode
 } from '../ast/expression';
-
+import { SQL_OPERATOR_REGISTRY } from '../constants/sql-operator-config';
+import { SqlOperator } from '../constants/sql';
+import { isRelationAlias } from '../utils/relation-alias';
+
+/**
+ * Capitalizes the first letter of a string
+ * @param s - String to capitalize
+ * @returns Capitalized string
+ */
 const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
-const isRelationAlias = (alias?: string) => alias ? alias.includes('__') : false;
 
+const assertNever = (value: never): never => {
+  throw new Error(`Unhandled SQL operator: ${value}`);
+};
+
+/**
+ * Function type for printing expression nodes
+ */
 type ExpressionPrinter = (expr: ExpressionNode) => string;
+
+/**
+ * Function type for printing operand nodes
+ */
 type OperandPrinter = (node: OperandNode) => string;
 
+/**
+ * Generates TypeScript code from query AST nodes
+ */
 export class TypeScriptGenerator {
   private readonly expressionPrinters: Partial<Record<ExpressionNode['type'], ExpressionPrinter>>;
   private readonly operandPrinters: Partial<Record<OperandNode['type'], OperandPrinter>>;
 
+  /**
+   * Creates a new TypeScriptGenerator instance
+   */
   constructor() {
     this.expressionPrinters = {
       BinaryExpression: expr => this.printBinaryExpression(expr as BinaryExpressionNode),
@@ -48,6 +72,11 @@ export class TypeScriptGenerator {
     };
   }
 
+  /**
+   * Generates TypeScript code from a query AST
+   * @param ast - Query AST to generate code from
+   * @returns Generated TypeScript code
+   */
   generate(ast: SelectQueryNode): string {
     const chainLines = this.buildSelectLines(ast);
     const lines = chainLines.map((line, index) => (index === 0 ? `const query = ${line}` : line));
@@ -55,6 +84,11 @@ export class TypeScriptGenerator {
     return lines.join('\n');
   }
 
+  /**
+   * Builds TypeScript method chain lines from query AST
+   * @param ast - Query AST
+   * @returns Array of TypeScript method chain lines
+   */
   private buildSelectLines(ast: SelectQueryNode): string[] {
     const lines: string[] = [];
     const hydration = ast.meta?.hydration;
@@ -136,27 +170,53 @@ export class TypeScriptGenerator {
     return lines;
   }
 
+  /**
+   * Prints an expression node to TypeScript code
+   * @param expr - Expression node to print
+   * @returns TypeScript code representation
+   */
   private printExpression(expr: ExpressionNode): string {
     const printer = this.expressionPrinters[expr.type];
-    return printer ? printer(expr) : '';
+    if (!printer) {
+      throw new Error(`Unsupported expression type "${expr.type}" in TypeScript generator`);
+    }
+    return printer(expr);
   }
 
+  /**
+   * Prints an operand node to TypeScript code
+   * @param node - Operand node to print
+   * @returns TypeScript code representation
+   */
   private printOperand(node: OperandNode): string {
     const printer = this.operandPrinters[node.type];
-    return printer ? printer(node) : '';
+    if (!printer) {
+      throw new Error(`Unsupported operand type "${node.type}" in TypeScript generator`);
+    }
+    return printer(node);
   }
 
+  /**
+   * Prints a binary expression to TypeScript code
+   * @param binary - Binary expression node
+   * @returns TypeScript code representation
+   */
   private printBinaryExpression(binary: BinaryExpressionNode): string {
     const left = this.printOperand(binary.left);
     const right = this.printOperand(binary.right);
-    const base = `${left} ${binary.operator} ${right}`;
+    const fn = this.mapOp(binary.operator);
+    const args = [left, right];
     if (binary.escape) {
-      const escapeOperand = this.printOperand(binary.escape);
-      return `${base} ESCAPE ${escapeOperand}`;
+      args.push(this.printOperand(binary.escape));
     }
-    return base;
+    return `${fn}(${args.join(', ')})`;
   }
 
+  /**
+   * Prints a logical expression to TypeScript code
+   * @param logical - Logical expression node
+   * @returns TypeScript code representation
+   */
   private printLogicalExpression(logical: LogicalExpressionNode): string {
     if (logical.operands.length === 0) return '';
     const parts = logical.operands.map(op => {
@@ -166,17 +226,34 @@ export class TypeScriptGenerator {
     return `${this.mapOp(logical.operator)}(\n    ${parts.join(',\n    ')}\n  )`;
   }
 
+  /**
+   * Prints an IN expression to TypeScript code
+   * @param inExpr - IN expression node
+   * @returns TypeScript code representation
+   */
   private printInExpression(inExpr: InExpressionNode): string {
     const left = this.printOperand(inExpr.left);
     const values = inExpr.right.map(v => this.printOperand(v)).join(', ');
-    return `${left} ${inExpr.operator} (${values})`;
+    const fn = this.mapOp(inExpr.operator);
+    return `${fn}(${left}, [${values}])`;
   }
 
+  /**
+   * Prints a null expression to TypeScript code
+   * @param nullExpr - Null expression node
+   * @returns TypeScript code representation
+   */
   private printNullExpression(nullExpr: NullExpressionNode): string {
     const left = this.printOperand(nullExpr.left);
-    return `${left} ${nullExpr.operator}`;
+    const fn = this.mapOp(nullExpr.operator);
+    return `${fn}(${left})`;
   }
 
+  /**
+   * Prints a BETWEEN expression to TypeScript code
+   * @param betweenExpr - BETWEEN expression node
+   * @returns TypeScript code representation
+   */
   private printBetweenExpression(betweenExpr: BetweenExpressionNode): string {
     const left = this.printOperand(betweenExpr.left);
     const lower = this.printOperand(betweenExpr.lower);
@@ -184,34 +261,69 @@ export class TypeScriptGenerator {
     return `${this.mapOp(betweenExpr.operator)}(${left}, ${lower}, ${upper})`;
   }
 
+  /**
+   * Prints an EXISTS expression to TypeScript code
+   * @param existsExpr - EXISTS expression node
+   * @returns TypeScript code representation
+   */
   private printExistsExpression(existsExpr: ExistsExpressionNode): string {
     const subquery = this.inlineChain(this.buildSelectLines(existsExpr.subquery));
     return `${this.mapOp(existsExpr.operator)}(${subquery})`;
   }
 
+  /**
+   * Prints a column operand to TypeScript code
+   * @param column - Column node
+   * @returns TypeScript code representation
+   */
   private printColumnOperand(column: ColumnNode): string {
     return `${capitalize(column.table)}.${column.name}`;
   }
 
+  /**
+   * Prints a literal operand to TypeScript code
+   * @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
+   * @returns TypeScript code representation
+   */
   private printFunctionOperand(fn: FunctionNode): string {
     const args = fn.args.map(a => this.printOperand(a)).join(', ');
     return `${fn.name.toLowerCase()}(${args})`;
   }
 
+  /**
+   * Prints a JSON path operand to TypeScript code
+   * @param json - JSON path node
+   * @returns TypeScript code representation
+   */
   private printJsonPathOperand(json: JsonPathNode): string {
     return `jsonPath(${capitalize(json.column.table)}.${json.column.name}, '${json.path}')`;
   }
 
+  /**
+   * Prints a scalar subquery operand to TypeScript code
+   * @param node - Scalar subquery node
+   * @returns TypeScript code representation
+   */
   private printScalarSubqueryOperand(node: ScalarSubqueryNode): string {
     const subquery = this.inlineChain(this.buildSelectLines(node.query));
     return `(${subquery})`;
   }
 
+  /**
+   * Prints a CASE expression operand to TypeScript code
+   * @param node - CASE expression node
+   * @returns TypeScript code representation
+   */
   private printCaseExpressionOperand(node: CaseExpressionNode): string {
     const clauses = node.conditions.map(
       condition =>
@@ -221,6 +333,11 @@ export class TypeScriptGenerator {
     return `caseWhen([${clauses.join(', ')}]${elseValue})`;
   }
 
+  /**
+   * Prints a window function operand to TypeScript code
+   * @param node - Window function node
+   * @returns TypeScript code representation
+   */
   private printWindowFunctionOperand(node: WindowFunctionNode): string {
     let result = `${node.name}(`;
     if (node.args.length > 0) {
@@ -249,6 +366,11 @@ export class TypeScriptGenerator {
     return result;
   }
 
+  /**
+   * Converts method chain lines to inline format
+   * @param lines - Method chain lines
+   * @returns Inline method chain string
+   */
   private inlineChain(lines: string[]): string {
     return lines
       .map(line => line.trim())
@@ -256,40 +378,16 @@ export class TypeScriptGenerator {
       .join(' ');
   }
 
-  private mapOp(op: string): string {
-    switch (op) {
-      case '=':
-        return 'eq';
-      case '>':
-        return 'gt';
-      case '<':
-        return 'lt';
-      case 'LIKE':
-        return 'like';
-      case 'NOT LIKE':
-        return 'notLike';
-      case 'IN':
-        return 'inList';
-      case 'NOT IN':
-        return 'notInList';
-      case 'IS NULL':
-        return 'isNull';
-      case 'IS NOT NULL':
-        return 'isNotNull';
-      case 'AND':
-        return 'and';
-      case 'OR':
-        return 'or';
-      case 'BETWEEN':
-        return 'between';
-      case 'NOT BETWEEN':
-        return 'notBetween';
-      case 'EXISTS':
-        return 'exists';
-      case 'NOT EXISTS':
-        return 'notExists';
-      default:
-        return 'eq';
+  /**
+   * Maps SQL operators to TypeScript function names
+   * @param op - SQL operator
+   * @returns TypeScript function name
+   */
+  private mapOp(op: SqlOperator): string {
+    const config = SQL_OPERATOR_REGISTRY[op];
+    if (!config) {
+      return assertNever(op as never);
     }
+    return config.tsName;
   }
 }

package/src/constants/sql-operator-config.ts

@@ -0,0 +1,36 @@
+import { SQL_OPERATORS, SqlOperator } from './sql';
+
+/**
+ * Configuration for how SQL operators map to TypeScript builder helpers
+ */
+export interface SqlOperatorConfig {
+  /**
+   * SQL operator literal
+   */
+  sql: SqlOperator;
+  /**
+   * Corresponding TypeScript helper name
+   */
+  tsName: string;
+}
+
+/**
+ * Registry of supported SQL operators and their companion helper names
+ */
+export const SQL_OPERATOR_REGISTRY: Record<SqlOperator, SqlOperatorConfig> = {
+  [SQL_OPERATORS.EQUALS]: { sql: SQL_OPERATORS.EQUALS, tsName: 'eq' },
+  [SQL_OPERATORS.GREATER_THAN]: { sql: SQL_OPERATORS.GREATER_THAN, tsName: 'gt' },
+  [SQL_OPERATORS.LESS_THAN]: { sql: SQL_OPERATORS.LESS_THAN, tsName: 'lt' },
+  [SQL_OPERATORS.LIKE]: { sql: SQL_OPERATORS.LIKE, tsName: 'like' },
+  [SQL_OPERATORS.NOT_LIKE]: { sql: SQL_OPERATORS.NOT_LIKE, tsName: 'notLike' },
+  [SQL_OPERATORS.IN]: { sql: SQL_OPERATORS.IN, tsName: 'inList' },
+  [SQL_OPERATORS.NOT_IN]: { sql: SQL_OPERATORS.NOT_IN, tsName: 'notInList' },
+  [SQL_OPERATORS.IS_NULL]: { sql: SQL_OPERATORS.IS_NULL, tsName: 'isNull' },
+  [SQL_OPERATORS.IS_NOT_NULL]: { sql: SQL_OPERATORS.IS_NOT_NULL, tsName: 'isNotNull' },
+  [SQL_OPERATORS.AND]: { sql: SQL_OPERATORS.AND, tsName: 'and' },
+  [SQL_OPERATORS.OR]: { sql: SQL_OPERATORS.OR, tsName: 'or' },
+  [SQL_OPERATORS.BETWEEN]: { sql: SQL_OPERATORS.BETWEEN, tsName: 'between' },
+  [SQL_OPERATORS.NOT_BETWEEN]: { sql: SQL_OPERATORS.NOT_BETWEEN, tsName: 'notBetween' },
+  [SQL_OPERATORS.EXISTS]: { sql: SQL_OPERATORS.EXISTS, tsName: 'exists' },
+  [SQL_OPERATORS.NOT_EXISTS]: { sql: SQL_OPERATORS.NOT_EXISTS, tsName: 'notExists' }
+};

package/src/constants/sql.ts

@@ -1,57 +1,125 @@
-export const SQL_KEYWORDS = {
-  SELECT: 'SELECT',
-  FROM: 'FROM',
-  WHERE: 'WHERE',
-  JOIN: 'JOIN',
-  INNER_JOIN: 'INNER JOIN',
-  LEFT_JOIN: 'LEFT JOIN',
-  RIGHT_JOIN: 'RIGHT JOIN',
-  ORDER_BY: 'ORDER BY',
-  GROUP_BY: 'GROUP BY',
-  HAVING: 'HAVING',
-  DISTINCT: 'DISTINCT',
-  EXISTS: 'EXISTS',
-  NOT_EXISTS: 'NOT EXISTS'
-} as const;
-
-export const SQL_OPERATORS = {
-  EQUALS: '=',
-  GREATER_THAN: '>',
-  LESS_THAN: '<',
-  LIKE: 'LIKE',
-  NOT_LIKE: 'NOT LIKE',
-  IN: 'IN',
-  NOT_IN: 'NOT IN',
-  BETWEEN: 'BETWEEN',
-  NOT_BETWEEN: 'NOT BETWEEN',
-  IS_NULL: 'IS NULL',
-  IS_NOT_NULL: 'IS NOT NULL',
-  AND: 'AND',
-  OR: 'OR'
-} as const;
-
-export type SqlOperator = (typeof SQL_OPERATORS)[keyof typeof SQL_OPERATORS];
-
-export const JOIN_KINDS = {
-  INNER: 'INNER',
-  LEFT: 'LEFT',
-  RIGHT: 'RIGHT',
-  CROSS: 'CROSS'
-} as const;
-
-export type JoinKind = (typeof JOIN_KINDS)[keyof typeof JOIN_KINDS];
-
-export const ORDER_DIRECTIONS = {
-  ASC: 'ASC',
-  DESC: 'DESC'
-} as const;
-
-export type OrderDirection = (typeof ORDER_DIRECTIONS)[keyof typeof ORDER_DIRECTIONS];
-
-export const SUPPORTED_DIALECTS = {
-  MYSQL: 'mysql',
-  SQLITE: 'sqlite',
-  MSSQL: 'mssql'
-} as const;
-
-export type DialectName = (typeof SUPPORTED_DIALECTS)[keyof typeof SUPPORTED_DIALECTS];
+/**
+ * SQL keywords used in query generation
+ */
+export const SQL_KEYWORDS = {
+  /** SELECT clause keyword */
+  SELECT: 'SELECT',
+  /** FROM clause keyword */
+  FROM: 'FROM',
+  /** WHERE clause keyword */
+  WHERE: 'WHERE',
+  /** JOIN keyword */
+  JOIN: 'JOIN',
+  /** INNER JOIN keyword */
+  INNER_JOIN: 'INNER JOIN',
+  /** LEFT JOIN keyword */
+  LEFT_JOIN: 'LEFT JOIN',
+  /** RIGHT JOIN keyword */
+  RIGHT_JOIN: 'RIGHT JOIN',
+  /** ORDER BY clause keyword */
+  ORDER_BY: 'ORDER BY',
+  /** GROUP BY clause keyword */
+  GROUP_BY: 'GROUP BY',
+  /** HAVING clause keyword */
+  HAVING: 'HAVING',
+  /** DISTINCT keyword */
+  DISTINCT: 'DISTINCT',
+  /** EXISTS operator */
+  EXISTS: 'EXISTS',
+  /** NOT EXISTS operator */
+  NOT_EXISTS: 'NOT EXISTS'
+} as const;
+
+/**
+ * SQL operators used in query conditions
+ */
+export const SQL_OPERATORS = {
+  /** Equality operator */
+  EQUALS: '=',
+  /** Greater than operator */
+  GREATER_THAN: '>',
+  /** Less than operator */
+  LESS_THAN: '<',
+  /** LIKE pattern matching operator */
+  LIKE: 'LIKE',
+  /** NOT LIKE pattern matching operator */
+  NOT_LIKE: 'NOT LIKE',
+  /** IN membership operator */
+  IN: 'IN',
+  /** NOT IN membership operator */
+  NOT_IN: 'NOT IN',
+  /** BETWEEN range operator */
+  BETWEEN: 'BETWEEN',
+  /** NOT BETWEEN range operator */
+  NOT_BETWEEN: 'NOT BETWEEN',
+  /** IS NULL null check operator */
+  IS_NULL: 'IS NULL',
+  /** IS NOT NULL null check operator */
+  IS_NOT_NULL: 'IS NOT NULL',
+  /** Logical AND operator */
+  AND: 'AND',
+  /** Logical OR operator */
+  OR: 'OR',
+  /** EXISTS operator */
+  EXISTS: 'EXISTS',
+  /** NOT EXISTS operator */
+  NOT_EXISTS: 'NOT EXISTS'
+} as const;
+
+/**
+ * Type representing any supported SQL operator
+ */
+export type SqlOperator = (typeof SQL_OPERATORS)[keyof typeof SQL_OPERATORS];
+
+/**
+ * Types of SQL joins supported
+ */
+export const JOIN_KINDS = {
+  /** INNER JOIN type */
+  INNER: 'INNER',
+  /** LEFT JOIN type */
+  LEFT: 'LEFT',
+  /** RIGHT JOIN type */
+  RIGHT: 'RIGHT',
+  /** CROSS JOIN type */
+  CROSS: 'CROSS'
+} as const;
+
+/**
+ * Type representing any supported join kind
+ */
+export type JoinKind = (typeof JOIN_KINDS)[keyof typeof JOIN_KINDS];
+
+/**
+ * Ordering directions for result sorting
+ */
+export const ORDER_DIRECTIONS = {
+  /** Ascending order */
+  ASC: 'ASC',
+  /** Descending order */
+  DESC: 'DESC'
+} as const;
+
+/**
+ * Type representing any supported order direction
+ */
+export type OrderDirection = (typeof ORDER_DIRECTIONS)[keyof typeof ORDER_DIRECTIONS];
+
+/**
+ * Supported database dialects
+ */
+export const SUPPORTED_DIALECTS = {
+  /** MySQL database dialect */
+  MYSQL: 'mysql',
+  /** SQLite database dialect */
+  SQLITE: 'sqlite',
+  /** Microsoft SQL Server dialect */
+  MSSQL: 'mssql',
+  /** PostgreSQL database dialect */
+  POSTGRES: 'postgres'
+} as const;
+
+/**
+ * Type representing any supported database dialect
+ */
+export type DialectName = (typeof SUPPORTED_DIALECTS)[keyof typeof SUPPORTED_DIALECTS];