@simplysm/orm-common 14.0.1 → 14.0.4

package/dist/expr/expr.js

@@ -34,13 +34,13 @@ import { ExprUnit, WhereExprUnit } from "./expr-unit.js";
 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
@@ -61,13 +61,13 @@ export const expr = {
         return new ExprUnit(dataType, { type: "value", value });
     },
     /**
-     * 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
@@ -79,13 +79,13 @@ export const expr = {
         return new ExprUnit(dataType, { type: "column", path });
     },
     /**
-     * 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
@@ -103,7 +103,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;
             }, "");
@@ -114,13 +114,13 @@ export const expr = {
     //#endregion
     //#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
@@ -136,11 +136,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
@@ -156,11 +156,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
@@ -176,11 +176,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
@@ -196,11 +196,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
@@ -218,12 +218,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
@@ -270,7 +270,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)
@@ -294,9 +294,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
@@ -340,7 +340,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
@@ -363,7 +363,7 @@ export const expr = {
     inQuery(source, query) {
         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",
@@ -374,7 +374,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
@@ -391,7 +391,7 @@ export const expr = {
      * ```
      */
     exists(query) {
-        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,
@@ -420,7 +420,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
@@ -474,9 +474,9 @@ export const expr = {
     //#endregion
     //#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
@@ -496,7 +496,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
@@ -518,7 +518,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
@@ -540,7 +540,7 @@ export const expr = {
         });
     },
     /**
-     * Remove whitespace from both sides of a string (TRIM)
+     * 문자열 양쪽 공백 제거 (TRIM)
      *
      * @param source - Original string
      * @returns String expression with whitespace removed
@@ -560,9 +560,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
@@ -587,7 +587,7 @@ export const expr = {
         });
     },
     /**
-     * String replacement (REPLACE)
+     * 문자열 치환 (REPLACE)
      *
      * @param source - Original string
      * @param from - String to find
@@ -611,7 +611,7 @@ export const expr = {
         });
     },
     /**
-     * Convert string to uppercase (UPPER)
+     * 문자열 대문자 변환 (UPPER)
      *
      * @param source - Original string
      * @returns Uppercase string expression
@@ -631,7 +631,7 @@ export const expr = {
         });
     },
     /**
-     * Convert string to lowercase (LOWER)
+     * 문자열 소문자 변환 (LOWER)
      *
      * @param source - Original string
      * @returns Lowercase string expression
@@ -651,7 +651,7 @@ export const expr = {
         });
     },
     /**
-     * String length (character count)
+     * 문자열 길이 (문자 수)
      *
      * @param source - Original string
      * @returns Character count
@@ -671,9 +671,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
@@ -693,9 +693,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)
@@ -720,9 +720,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
@@ -747,7 +747,7 @@ export const expr = {
     //#endregion
     //#region ========== SELECT - Number ==========
     /**
-     * Absolute value (ABS)
+     * 절대값 (ABS)
      *
      * @param source - Original number
      * @returns Absolute value expression
@@ -767,7 +767,7 @@ export const expr = {
         });
     },
     /**
-     * Round (ROUND)
+     * 반올림 (ROUND)
      *
      * @param source - Original number
      * @param digits - Number of decimal places
@@ -790,7 +790,7 @@ export const expr = {
         });
     },
     /**
-     * Ceiling (CEILING)
+     * 올림 (CEILING)
      *
      * @param source - Original number
      * @returns Ceiling number expression
@@ -811,7 +811,7 @@ export const expr = {
         });
     },
     /**
-     * Floor (FLOOR)
+     * 내림 (FLOOR)
      *
      * @param source - Original number
      * @returns Floor number expression
@@ -834,7 +834,7 @@ export const expr = {
     //#endregion
     //#region ========== SELECT - Date ==========
     /**
-     * Extract year (YEAR)
+     * 연도 추출 (YEAR)
      *
      * @param source - DateTime or DateOnly expression
      * @returns Year (4-digit number)
@@ -854,7 +854,7 @@ export const expr = {
         });
     },
     /**
-     * Extract month (MONTH)
+     * 월 추출 (MONTH)
      *
      * @param source - DateTime or DateOnly expression
      * @returns Month (1~12)
@@ -874,7 +874,7 @@ export const expr = {
         });
     },
     /**
-     * Extract day (DAY)
+     * 일 추출 (DAY)
      *
      * @param source - DateTime or DateOnly expression
      * @returns Day (1~31)
@@ -894,7 +894,7 @@ export const expr = {
         });
     },
     /**
-     * Extract hour (HOUR)
+     * 시 추출 (HOUR)
      *
      * @param source - DateTime or Time expression
      * @returns Hour (0~23)
@@ -914,7 +914,7 @@ export const expr = {
         });
     },
     /**
-     * Extract minute (MINUTE)
+     * 분 추출 (MINUTE)
      *
      * @param source - DateTime or Time expression
      * @returns Minute (0~59)
@@ -934,7 +934,7 @@ export const expr = {
         });
     },
     /**
-     * Extract second (SECOND)
+     * 초 추출 (SECOND)
      *
      * @param source - DateTime or Time expression
      * @returns Second (0~59)
@@ -954,7 +954,7 @@ export const expr = {
         });
     },
     /**
-     * Extract ISO week number
+     * ISO 주 번호 추출
      *
      * ISO 8601 week number (starts Monday, 1~53)
      *
@@ -978,7 +978,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)
@@ -1000,7 +1000,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
@@ -1020,7 +1020,7 @@ export const expr = {
         });
     },
     /**
-     * Calculate date difference (DATEDIFF)
+     * 날짜 차이 계산 (DATEDIFF)
      *
      * @param unit - Unit ("year", "month", "day", "hour", "minute", "second")
      * @param from - Start date
@@ -1044,7 +1044,7 @@ export const expr = {
         });
     },
     /**
-     * Add to date (DATEADD)
+     * 날짜 더하기 (DATEADD)
      *
      * @param unit - Unit ("year", "month", "day", "hour", "minute", "second")
      * @param source - Original date
@@ -1068,9 +1068,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")
@@ -1097,7 +1097,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
@@ -1112,9 +1112,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
@@ -1137,9 +1137,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
@@ -1161,7 +1161,7 @@ export const expr = {
     /**
      * CASE WHEN expression builder
      *
-     * Build conditional branches using method chaining
+     * 메서드 체이닝으로 조건 분기 구성
      *
      * @returns SwitchExprBuilder instance
      *
@@ -1181,7 +1181,7 @@ export const expr = {
         return createSwitchBuilder();
     },
     /**
-     * Simple IF condition (ternary operator)
+     * 단순 IF 조건 (삼항 연산자)
      *
      * @param condition - Condition
      * @param then - Value when condition is true
@@ -1224,7 +1224,7 @@ export const expr = {
     //#region ========== SELECT - Aggregate ==========
     // 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
@@ -1249,7 +1249,7 @@ export const expr = {
         });
     },
     /**
-     * Sum (SUM)
+     * 합계 (SUM)
      *
      * NULL values are ignored. Returns NULL if all values are NULL
      *
@@ -1271,7 +1271,7 @@ export const expr = {
         });
     },
     /**
-     * Average (AVG)
+     * 평균 (AVG)
      *
      * NULL values are ignored. Returns NULL if all values are NULL
      *
@@ -1293,7 +1293,7 @@ export const expr = {
         });
     },
     /**
-     * Maximum value (MAX)
+     * 최대값 (MAX)
      *
      * NULL values are ignored. Returns NULL if all values are NULL
      *
@@ -1315,7 +1315,7 @@ export const expr = {
         });
     },
     /**
-     * Minimum value (MIN)
+     * 최소값 (MIN)
      *
      * NULL values are ignored. Returns NULL if all values are NULL
      *
@@ -1339,7 +1339,7 @@ export const expr = {
     //#endregion
     //#region ========== SELECT - Other ==========
     /**
-     * Greatest value among multiple values (GREATEST)
+     * 여러 값 중 최대값 선택 (GREATEST)
      *
      * @param args - Values to compare
      * @returns Greatest value
@@ -1359,7 +1359,7 @@ export const expr = {
         });
     },
     /**
-     * Least value among multiple values (LEAST)
+     * 여러 값 중 최소값 선택 (LEAST)
      *
      * @param args - Values to compare
      * @returns Least value
@@ -1379,7 +1379,7 @@ export const expr = {
         });
     },
     /**
-     * Row number (sequential number for all rows without ROW_NUMBER)
+     * 행 번호 (ROW_NUMBER 없이 모든 행에 순번 부여)
      *
      * @returns Row number (starting from 1)
      *
@@ -1397,9 +1397,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
      *
@@ -1437,9 +1437,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
@@ -1470,7 +1470,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)
@@ -1806,7 +1806,7 @@ export const expr = {
     //#endregion
     //#region ========== Helper ==========
     /**
-     * Transform ExprInput to Expr (internal use)
+     * ExprInput을 Expr로 변환 (내부 사용)
      *
      * @param value - Value to transform
      * @returns Expr JSON AST