@simplysm/orm-common 14.0.1 → 14.0.4

package/src/expr/expr.ts

@@ -62,13 +62,13 @@ export const expr = {
   //#region ========== 값 생성 ==========
 
   /**
-   * Wrap literal value as ExprUnit
+   * 리터럴 값을 ExprUnit으로 래핑
    *
-   * Widen to base type matching dataType, remove literal type
+   * dataType에 맞는 기본 타입으로 확장, 리터럴 타입 제거
    *
-   * @param dataType - The data type of the value ("string", "number", "boolean", "DateTime", "DateOnly", "Time", "Uuid", "Buffer")
-   * @param value - Value to wrap (undefined allowed)
-   * @returns Wrapped ExprUnit instance
+   * @param dataType - 값의 데이터 타입 ("string", "number", "boolean", "DateTime", "DateOnly", "Time", "Uuid", "Buffer")
+   * @param value - 래핑할 값 (undefined 허용)
+   * @returns 래핑된 ExprUnit 인스턴스
    *
    * @example
    * ```typescript
@@ -95,13 +95,13 @@ export const expr = {
   },
 
   /**
-   * Generate column reference
+   * Column 참조 생성
    *
-   * Typically proxy objects are used inside Queryable callbacks
+   * 일반적으로 Queryable 콜백 내부에서 프록시 객체를 사용
    *
-   * @param dataType - Column data type
-   * @param path - Column path (table alias, column name, etc.)
-   * @returns Column reference ExprUnit instance
+   * @param dataType - Column 데이터 타입
+   * @param path - Column 경로 (테이블 별칭, column 이름 등)
+   * @returns Column 참조 ExprUnit 인스턴스
    *
    * @example
    * ```typescript
@@ -117,13 +117,13 @@ export const expr = {
   },
 
   /**
-   * Raw SQL expression Generate (escape hatch)
+   * Raw SQL expression 생성 (이스케이프 해치)
    *
-   * Use when you need to directly use DB-specific functions or syntax not supported by the ORM.
-   * Used as tagged template literal, interpolated values are automatically parameterized
+   * ORM에서 지원하지 않는 DB 전용 함수나 구문을 직접 사용해야 할 때 사용.
+   * 태그드 템플릿 리터럴로 사용하며, 보간된 값은 자동으로 파라미터화됨
    *
-   * @param dataType - Data type of the returned value
-   * @returns Tagged template function
+   * @param dataType - 반환 값의 데이터 타입
+   * @returns 태그드 템플릿 함수
    *
    * @example
    * ```typescript
@@ -146,7 +146,7 @@ export const expr = {
     return (strings, ...values) => {
       const sql = strings.reduce((acc, str, i) => {
         if (i < values.length) {
-          return acc + str + `$${i + 1}`; // placeholder (transformed by ExprRenderer)
+          return acc + str + `$${i + 1}`; // 플레이스홀더 (ExprRenderer에서 변환)
         }
         return acc + str;
       }, "");
@@ -162,13 +162,13 @@ export const expr = {
   //#region ========== WHERE - Comparison operators ==========
 
   /**
-   * Equality comparison (NULL-safe)
+   * 동등 비교 (NULL 안전)
    *
-   * Safely compare even NULL values (MySQL: `<=>`, MSSQL/PostgreSQL: `IS NULL OR =`)
+   * NULL 값도 안전하게 비교 (MySQL: `<=>`, MSSQL/PostgreSQL: `IS NULL OR =`)
    *
-   * @param source - Column or expression to compare
-   * @param target - Target value or expression for comparison
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param target - 비교 대상 값 또는 expression
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -185,11 +185,11 @@ export const expr = {
   },
 
   /**
-   * Greater than comparison (>)
+   * 초과 비교 (>)
    *
-   * @param source - Column or expression to compare
-   * @param target - Target value or expression for comparison
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param target - 비교 대상 값 또는 expression
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -206,11 +206,11 @@ export const expr = {
   },
 
   /**
-   * Less than comparison (<)
+   * 미만 비교 (<)
    *
-   * @param source - Column or expression to compare
-   * @param target - Target value or expression for comparison
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param target - 비교 대상 값 또는 expression
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -227,11 +227,11 @@ export const expr = {
   },
 
   /**
-   * Greater than or equal comparison (>=)
+   * 이상 비교 (>=)
    *
-   * @param source - Column or expression to compare
-   * @param target - Target value or expression for comparison
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param target - 비교 대상 값 또는 expression
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -248,11 +248,11 @@ export const expr = {
   },
 
   /**
-   * Less than or equal comparison (<=)
+   * 이하 비교 (<=)
    *
-   * @param source - Column or expression to compare
-   * @param target - Target value or expression for comparison
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param target - 비교 대상 값 또는 expression
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -271,12 +271,12 @@ export const expr = {
   /**
    * range comparison (BETWEEN)
    *
-   * If from/to is undefined, that direction is unbounded
+   * from/to가 undefined이면 해당 방향은 제한 없음
    *
-   * @param source - Column or expression to compare
-   * @param from - Start value (no lower bound if undefined)
-   * @param to - End value (no upper bound if undefined)
-   * @returns WHERE condition expression
+   * @param source - 비교할 column 또는 expression
+   * @param from - 시작 값 (undefined이면 하한 없음)
+   * @param to - 끝 값 (undefined이면 상한 없음)
+   * @returns WHERE 조건 expression
    *
    * @example
    * ```typescript
@@ -333,7 +333,7 @@ export const expr = {
    * LIKE pattern matching
    *
    * `%` matches zero or more characters, `_` matches a single character.
-   * Special characters are escaped with `\`
+   * 특수 문자는 `\`로 이스케이프됨
    *
    * @param source - Column or expression to search
    * @param pattern - Search pattern (%, _ wildcards available)
@@ -361,9 +361,9 @@ export const expr = {
   },
 
   /**
-   * Regular expression pattern matching
+   * 정규식 패턴 매칭
    *
-   * Note: regex syntax may differ between DBMS implementations
+   * 참고: 정규식 구문은 DBMS 구현에 따라 다를 수 있음
    *
    * @param source - Column or expression to search
    * @param pattern - Regular expression pattern
@@ -414,7 +414,7 @@ export const expr = {
   /**
    * IN (SELECT ...) - Compare against subquery results
    *
-   * The subquery must SELECT only a single column
+   * 서브쿼리는 단일 column만 SELECT해야 함
    *
    * @param source - Column or expression to compare
    * @param query - Queryable that returns a single column
@@ -440,7 +440,7 @@ export const expr = {
   ): WhereExprUnit {
     const queryDef = query.getSelectQueryDef();
     if (queryDef.select == null || Object.keys(queryDef.select).length !== 1) {
-      throw new Error("inQuery subquery must SELECT only a single column.");
+      throw new Error("inQuery 서브쿼리는 단일 column만 SELECT해야 합니다.");
     }
     return new WhereExprUnit({
       type: "inQuery",
@@ -452,7 +452,7 @@ export const expr = {
   /**
    * EXISTS (SELECT ...) - Check if subquery returns any rows
    *
-   * Returns true if the subquery returns one or more rows
+   * 서브쿼리가 하나 이상의 행을 반환하면 true 반환
    *
    * @param query - Queryable to check for existence
    * @returns WHERE condition expression
@@ -469,7 +469,7 @@ export const expr = {
    * ```
    */
   exists(query: Queryable<any, any>): WhereExprUnit {
-    const { select: _, ...queryDefWithoutSelect } = query.getSelectQueryDef(); // EXISTS does not need SELECT clause, saves packet size
+    const { select: _, ...queryDefWithoutSelect } = query.getSelectQueryDef(); // EXISTS는 SELECT 절이 불필요, 패킷 크기 절약
     return new WhereExprUnit({
       type: "exists",
       query: queryDefWithoutSelect,
@@ -502,7 +502,7 @@ export const expr = {
   /**
    * AND operator - All conditions must be satisfied
    *
-   * Combines multiple conditions with AND. Passing an array to where() automatically applies AND
+   * 여러 조건을 AND로 결합. where()에 배열을 전달하면 자동으로 AND 적용
    *
    * @param conditions - List of conditions to combine with AND
    * @returns Combined WHERE condition expression
@@ -560,9 +560,9 @@ export const expr = {
   //#region ========== SELECT - String ==========
 
   /**
-   * String concatenation (CONCAT)
+   * 문자열 연결 (CONCAT)
    *
-   * NULL values are treated as empty strings (auto-transformed per DBMS)
+   * NULL 값은 빈 문자열로 처리 (DBMS별 자동 변환)
    *
    * @param args - Strings to concatenate
    * @returns Concatenated string expression
@@ -583,7 +583,7 @@ export const expr = {
   },
 
   /**
-   * Extract specified length from the left of a string (LEFT)
+   * 문자열 왼쪽에서 지정 길이만큼 추출 (LEFT)
    *
    * @param source - Original string
    * @param length - Number of characters to extract
@@ -606,7 +606,7 @@ export const expr = {
   },
 
   /**
-   * Extract specified length from the right of a string (RIGHT)
+   * 문자열 오른쪽에서 지정 길이만큼 추출 (RIGHT)
    *
    * @param source - Original string
    * @param length - Number of characters to extract
@@ -629,7 +629,7 @@ export const expr = {
   },
 
   /**
-   * Remove whitespace from both sides of a string (TRIM)
+   * 문자열 양쪽 공백 제거 (TRIM)
    *
    * @param source - Original string
    * @returns String expression with whitespace removed
@@ -650,9 +650,9 @@ export const expr = {
   },
 
   /**
-   * Left padding (LPAD)
+   * 왼쪽 패딩 (LPAD)
    *
-   * Repeatedly adds fillString on the left until the target length is reached
+   * 대상 길이에 도달할 때까지 왼쪽에 fillString을 반복 추가
    *
    * @param source - Original string
    * @param length - Target length
@@ -682,7 +682,7 @@ export const expr = {
   },
 
   /**
-   * String replacement (REPLACE)
+   * 문자열 치환 (REPLACE)
    *
    * @param source - Original string
    * @param from - String to find
@@ -711,7 +711,7 @@ export const expr = {
   },
 
   /**
-   * Convert string to uppercase (UPPER)
+   * 문자열 대문자 변환 (UPPER)
    *
    * @param source - Original string
    * @returns Uppercase string expression
@@ -732,7 +732,7 @@ export const expr = {
   },
 
   /**
-   * Convert string to lowercase (LOWER)
+   * 문자열 소문자 변환 (LOWER)
    *
    * @param source - Original string
    * @returns Lowercase string expression
@@ -753,7 +753,7 @@ export const expr = {
   },
 
   /**
-   * String length (character count)
+   * 문자열 길이 (문자 수)
    *
    * @param source - Original string
    * @returns Character count
@@ -774,9 +774,9 @@ export const expr = {
   },
 
   /**
-   * String byte length
+   * 문자열 바이트 길이
    *
-   * In UTF-8, CJK characters are 3 bytes each
+   * UTF-8에서 CJK 문자는 각 3바이트
    *
    * @param source - Original string
    * @returns Byte count
@@ -797,9 +797,9 @@ export const expr = {
   },
 
   /**
-   * Extract part of a string (SUBSTRING)
+   * 문자열 부분 추출 (SUBSTRING)
    *
-   * Uses 1-based index per SQL standard
+   * SQL 표준에 따라 1부터 시작하는 인덱스 사용
    *
    * @param source - Original string
    * @param start - Start position (starting from 1)
@@ -829,9 +829,9 @@ export const expr = {
   },
 
   /**
-   * Find position within a string (LOCATE/CHARINDEX)
+   * 문자열 내 위치 찾기 (LOCATE/CHARINDEX)
    *
-   * Returns 1-based index, or 0 if not found
+   * 1부터 시작하는 인덱스 반환, 찾지 못하면 0 반환
    *
    * @param source - String to search in
    * @param search - String to find
@@ -859,7 +859,7 @@ export const expr = {
   //#region ========== SELECT - Number ==========
 
   /**
-   * Absolute value (ABS)
+   * 절대값 (ABS)
    *
    * @param source - Original number
    * @returns Absolute value expression
@@ -880,7 +880,7 @@ export const expr = {
   },
 
   /**
-   * Round (ROUND)
+   * 반올림 (ROUND)
    *
    * @param source - Original number
    * @param digits - Number of decimal places
@@ -904,7 +904,7 @@ export const expr = {
   },
 
   /**
-   * Ceiling (CEILING)
+   * 올림 (CEILING)
    *
    * @param source - Original number
    * @returns Ceiling number expression
@@ -926,7 +926,7 @@ export const expr = {
   },
 
   /**
-   * Floor (FLOOR)
+   * 내림 (FLOOR)
    *
    * @param source - Original number
    * @returns Floor number expression
@@ -952,7 +952,7 @@ export const expr = {
   //#region ========== SELECT - Date ==========
 
   /**
-   * Extract year (YEAR)
+   * 연도 추출 (YEAR)
    *
    * @param source - DateTime or DateOnly expression
    * @returns Year (4-digit number)
@@ -975,7 +975,7 @@ export const expr = {
   },
 
   /**
-   * Extract month (MONTH)
+   * 월 추출 (MONTH)
    *
    * @param source - DateTime or DateOnly expression
    * @returns Month (1~12)
@@ -998,7 +998,7 @@ export const expr = {
   },
 
   /**
-   * Extract day (DAY)
+   * 일 추출 (DAY)
    *
    * @param source - DateTime or DateOnly expression
    * @returns Day (1~31)
@@ -1021,7 +1021,7 @@ export const expr = {
   },
 
   /**
-   * Extract hour (HOUR)
+   * 시 추출 (HOUR)
    *
    * @param source - DateTime or Time expression
    * @returns Hour (0~23)
@@ -1044,7 +1044,7 @@ export const expr = {
   },
 
   /**
-   * Extract minute (MINUTE)
+   * 분 추출 (MINUTE)
    *
    * @param source - DateTime or Time expression
    * @returns Minute (0~59)
@@ -1067,7 +1067,7 @@ export const expr = {
   },
 
   /**
-   * Extract second (SECOND)
+   * 초 추출 (SECOND)
    *
    * @param source - DateTime or Time expression
    * @returns Second (0~59)
@@ -1090,7 +1090,7 @@ export const expr = {
   },
 
   /**
-   * Extract ISO week number
+   * ISO 주 번호 추출
    *
    * ISO 8601 week number (starts Monday, 1~53)
    *
@@ -1117,7 +1117,7 @@ export const expr = {
   /**
    * ISO week start date (Monday)
    *
-   * Returns the Monday of the week the given date belongs to
+   * 주어진 날짜가 속한 주의 월요일 반환
    *
    * @param source - DateOnly expression
    * @returns Week start date (Monday)
@@ -1140,7 +1140,7 @@ export const expr = {
   /**
    * ISO year-month (first day of the month)
    *
-   * Returns the first day of the month for the given date
+   * 주어진 날짜의 해당 월 첫째 날 반환
    *
    * @param source - DateOnly expression
    * @returns First day of the month
@@ -1161,7 +1161,7 @@ export const expr = {
   },
 
   /**
-   * Calculate date difference (DATEDIFF)
+   * 날짜 차이 계산 (DATEDIFF)
    *
    * @param unit - Unit ("year", "month", "day", "hour", "minute", "second")
    * @param from - Start date
@@ -1190,7 +1190,7 @@ export const expr = {
   },
 
   /**
-   * Add to date (DATEADD)
+   * 날짜 더하기 (DATEADD)
    *
    * @param unit - Unit ("year", "month", "day", "hour", "minute", "second")
    * @param source - Original date
@@ -1219,9 +1219,9 @@ export const expr = {
   },
 
   /**
-   * Date format (DATE_FORMAT)
+   * 날짜 포맷 (DATE_FORMAT)
    *
-   * Format string rules may differ between DBMS implementations
+   * 포맷 문자열 규칙은 DBMS 구현에 따라 다를 수 있음
    *
    * @param source - Date expression
    * @param format - Format string (e.g., "%Y-%m-%d")
@@ -1254,7 +1254,7 @@ export const expr = {
   /**
    * NULL replacement (COALESCE/IFNULL)
    *
-   * Returns the first non-null value. If the last argument is non-nullable, the result is also non-nullable
+   * 첫 번째 non-null 값 반환. 마지막 인수가 non-nullable이면 결과도 non-nullable
    *
    * @param args - Values to inspect (last is default value)
    * @returns First non-null value
@@ -1270,9 +1270,9 @@ export const expr = {
   coalesce,
 
   /**
-   * Return NULL if value matches (NULLIF)
+   * 값이 일치하면 NULL 반환 (NULLIF)
    *
-   * Returns NULL if source === value, otherwise returns source
+   * source === value이면 NULL 반환, 아니면 source 반환
    *
    * @param source - Original value
    * @param value - Value to compare
@@ -1299,9 +1299,9 @@ export const expr = {
   },
 
   /**
-   * Transform WHERE expression to boolean
+   * WHERE expression을 boolean으로 변환
    *
-   * Used when condition results should be used as a boolean column in SELECT clause
+   * 조건 결과를 SELECT 절에서 boolean column으로 사용할 때 사용
    *
    * @param condition - Condition to transform
    * @returns boolean expression
@@ -1324,7 +1324,7 @@ export const expr = {
   /**
    * CASE WHEN expression builder
    *
-   * Build conditional branches using method chaining
+   * 메서드 체이닝으로 조건 분기 구성
    *
    * @returns SwitchExprBuilder instance
    *
@@ -1345,7 +1345,7 @@ export const expr = {
   },
 
   /**
-   * Simple IF condition (ternary operator)
+   * 단순 IF 조건 (삼항 연산자)
    *
    * @param condition - Condition
    * @param then - Value when condition is true
@@ -1397,7 +1397,7 @@ export const expr = {
   // SUM, AVG, MAX 등 집계는 모든 값이 NULL이거나 행이 없을 때만 NULL 반환 (NULL 값을 가진 행은 무시됨)
 
   /**
-   * Count rows (COUNT)
+   * 행 수 세기 (COUNT)
    *
    * @param arg - Column to count (all rows if omitted)
    * @param distinct - If true, remove duplicates
@@ -1423,7 +1423,7 @@ export const expr = {
   },
 
   /**
-   * Sum (SUM)
+   * 합계 (SUM)
    *
    * NULL values are ignored. Returns NULL if all values are NULL
    *
@@ -1446,7 +1446,7 @@ export const expr = {
   },
 
   /**
-   * Average (AVG)
+   * 평균 (AVG)
    *
    * NULL values are ignored. Returns NULL if all values are NULL
    *
@@ -1469,7 +1469,7 @@ export const expr = {
   },
 
   /**
-   * Maximum value (MAX)
+   * 최대값 (MAX)
    *
    * NULL values are ignored. Returns NULL if all values are NULL
    *
@@ -1492,7 +1492,7 @@ export const expr = {
   },
 
   /**
-   * Minimum value (MIN)
+   * 최소값 (MIN)
    *
    * NULL values are ignored. Returns NULL if all values are NULL
    *
@@ -1519,7 +1519,7 @@ export const expr = {
   //#region ========== SELECT - Other ==========
 
   /**
-   * Greatest value among multiple values (GREATEST)
+   * 여러 값 중 최대값 선택 (GREATEST)
    *
    * @param args - Values to compare
    * @returns Greatest value
@@ -1540,7 +1540,7 @@ export const expr = {
   },
 
   /**
-   * Least value among multiple values (LEAST)
+   * 여러 값 중 최소값 선택 (LEAST)
    *
    * @param args - Values to compare
    * @returns Least value
@@ -1561,7 +1561,7 @@ export const expr = {
   },
 
   /**
-   * Row number (sequential number for all rows without ROW_NUMBER)
+   * 행 번호 (ROW_NUMBER 없이 모든 행에 순번 부여)
    *
    * @returns Row number (starting from 1)
    *
@@ -1580,9 +1580,9 @@ export const expr = {
   },
 
   /**
-   * Generate random number (RAND/RANDOM)
+   * 난수 생성 (RAND/RANDOM)
    *
-   * Returns a random number between 0 and 1. Mainly used for random ordering in ORDER BY
+   * 0과 1 사이의 난수 반환. 주로 ORDER BY에서 무작위 정렬에 사용
    *
    * @returns Random number between 0 and 1
    *
@@ -1625,9 +1625,9 @@ export const expr = {
   },
 
   /**
-   * Scalar Subquery - Subquery that returns a single value in SELECT clause
+   * 스칼라 Subquery - SELECT 절에서 단일 값을 반환하는 서브쿼리
    *
-   * The subquery must return exactly one row and one column
+   * 서브쿼리는 정확히 하나의 행과 하나의 column을 반환해야 함
    *
    * @param dataType - Data type of the returned value
    * @param queryable - Queryable that returns a scalar value
@@ -1664,7 +1664,7 @@ export const expr = {
   /**
    * ROW_NUMBER() - Row number within a partition
    *
-   * Assigns sequential numbers starting from 1 within each partition
+   * 각 파티션 내에서 1부터 시작하는 순번 부여
    *
    * @param spec - Window spec (partitionBy, orderBy)
    * @returns Row number (starting from 1)
@@ -2035,7 +2035,7 @@ export const expr = {
   //#region ========== Helper ==========
 
   /**
-   * Transform ExprInput to Expr (internal use)
+   * ExprInput을 Expr로 변환 (내부 사용)
    *
    * @param value - Value to transform
    * @returns Expr JSON AST