@simplysm/orm-common 13.0.99 → 14.0.1

package/src/exec/search-parser.ts

@@ -1,16 +1,16 @@
 /**
- * Search query parsing result (LIKE pattern)
+ * 검색 쿼리 파싱 결과 (LIKE 패턴)
  */
 export interface ParsedSearchQuery {
-  /** General search terms (OR condition) - LIKE pattern */
+  /** 일반 검색어 (OR 조건) - LIKE 패턴 */
   or: string[];
-  /** Required search terms (AND condition, + prefix or quotes) - LIKE pattern */
+  /** 필수 검색어 (AND 조건, + 접두사 또는 따옴표) - LIKE 패턴 */
   must: string[];
-  /** Excluded search terms (NOT condition, - prefix) - LIKE pattern */
+  /** 제외 검색어 (NOT 조건, - 접두사) - LIKE 패턴 */
   not: string[];
 }
 
-// Replace escape sequences with placeholders
+// 이스케이프 시퀀스를 플레이스홀더로 치환
 const ESC = {
   BACKSLASH: "\x00BACKSLASH\x00",
   ASTERISK: "\x00ASTERISK\x00",
@@ -21,38 +21,38 @@ const ESC = {
 };
 
 /**
- * Parse search query string and convert to SQL LIKE pattern.
+ * 검색 쿼리 문자열을 파싱하여 SQL LIKE 패턴으로 변환한다.
  *
- * ## Search Syntax
+ * ## 검색 구문
  *
- * | Syntax | Meaning | Example |
+ * | 구문 | 의미 | 예시 |
  * |--------|---------|---------|
- * | `term1 term2` | OR (one of them) | `apple banana` |
- * | `+term` | Required (AND) | `+apple +banana` |
- * | `-term` | Excluded (NOT) | `apple -banana` |
- * | `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
- * | `*` | Wildcard | `app*` → `app%` |
+ * | `term1 term2` | OR (하나 이상 일치) | `apple banana` |
+ * | `+term` | 필수 포함 (AND) | `+apple +banana` |
+ * | `-term` | 제외 (NOT) | `apple -banana` |
+ * | `"exact phrase"` | 정확한 구문 일치 (필수) | `"맛있는 과일"` |
+ * | `*` | 와일드카드 | `app*` → `app%` |
  *
- * ## Escape Sequences
+ * ## 이스케이프 시퀀스
  *
- * | Input | Meaning |
+ * | 입력 | 의미 |
  * |-------|---------|
- * | `\\` | Literal `\` |
- * | `\*` | Literal `*` |
- * | `\%` | Literal `%` |
- * | `\"` | Literal `"` |
- * | `\+` | Literal `+` |
- * | `\-` | Literal `-` |
+ * | `\\` | 리터럴 `\` |
+ * | `\*` | 리터럴 `*` |
+ * | `\%` | 리터럴 `%` |
+ * | `\"` | 리터럴 `"` |
+ * | `\+` | 리터럴 `+` |
+ * | `\-` | 리터럴 `-` |
  *
- * ## Special Cases
+ * ## 특수 케이스
  *
- * - Unclosed quotes (`"text`) are treated as regular text including the quote character.
+ * - 닫히지 않은 따옴표(`"text`)는 따옴표를 포함한 일반 텍스트로 처리된다.
  *
- * ## Examples
+ * ## 예시
  *
  * ```typescript
  * parseSearchQuery('apple "delicious fruit" -banana +strawberry')
- * // Result:
+ * // 결과:
  * // {
  * //   or: ["%apple%"],
  * //   must: ["%delicious fruit%", "%strawberry%"],
@@ -60,24 +60,24 @@ const ESC = {
  * // }
  *
  * parseSearchQuery('app* test')
- * // Result:
+ * // 결과:
  * // {
- * //   or: ["app%", "%test%"],  // app* starts with "app", test is substring match
+ * //   or: ["app%", "%test%"],  // app*는 "app"으로 시작, test는 부분 문자열 검색
  * //   must: [],
  * //   not: []
  * // }
  *
- * parseSearchQuery('app\\*test')  // escaped *
- * // Result:
+ * parseSearchQuery('app\\*test')  // 이스케이프된 *
+ * // 결과:
  * // {
- * //   or: ["%app*test%"],  // literal *
+ * //   or: ["%app*test%"],  // 리터럴 *
  * //   must: [],
  * //   not: []
  * // }
  * ```
  *
- * @param searchText Search query string
- * @returns Parsed search query object (LIKE pattern)
+ * @param searchText 검색 쿼리 문자열
+ * @returns 파싱된 검색 쿼리 객체 (LIKE 패턴)
  */
 export function parseSearchQuery(searchText: string): ParsedSearchQuery {
   const result: ParsedSearchQuery = {
@@ -98,7 +98,7 @@ export function parseSearchQuery(searchText: string): ParsedSearchQuery {
     .replace(/\\\+/g, ESC.PLUS)
     .replace(/\\-/g, ESC.MINUS);
 
-  // Extract quoted sections
+  // 따옴표 구간 추출
   const quotedRegex = /([+-]?)"([^"]*)"/g;
   let match: RegExpExecArray | null;
 
@@ -115,21 +115,21 @@ export function parseSearchQuery(searchText: string): ParsedSearchQuery {
     } else if (prefix === "-") {
       result.not.push(pattern);
     } else {
-      // Quoted text is treated as must (exact match = required)
+      // 따옴표 텍스트는 must로 처리 (정확한 일치 = 필수)
       result.must.push(pattern);
     }
   }
 
-  // Remove quoted sections
+  // 따옴표 구간 제거
   processed = processed.replace(/[+-]?"[^"]*"/g, " ");
 
-  // Split tokens by whitespace
+  // 공백으로 토큰 분리
   const tokens = processed.split(/\s+/).filter((t) => t.length > 0);
 
   for (let token of tokens) {
     let targetArray = result.or;
 
-    // Handle + or - prefix
+    // + 또는 - 접두사 처리
     if (token.startsWith("+")) {
       targetArray = result.must;
       token = token.slice(1);
@@ -148,32 +148,32 @@ export function parseSearchQuery(searchText: string): ParsedSearchQuery {
 }
 
 /**
- * Convert search term to SQL LIKE pattern (internal function)
+ * 검색어를 SQL LIKE 패턴으로 변환 (내부 함수)
  *
- * Wildcard rules:
- * - `apple` (no wildcard) → `%apple%` (substring match, default)
- * - `apple*` → `apple%` (starts with)
- * - `*apple` → `%apple` (ends with)
- * - `*apple*` → `%apple%` (explicit substring)
- * - `a*ple` → `a%ple` (in the middle)
+ * 와일드카드 규칙:
+ * - `apple` (와일드카드 없음) → `%apple%` (부분 문자열 검색, 기본값)
+ * - `apple*` → `apple%` (시작 일치)
+ * - `*apple` → `%apple` (끝 일치)
+ * - `*apple*` → `%apple%` (명시적 부분 문자열)
+ * - `a*ple` → `a%ple` (중간 일치)
  */
 function termToLikePattern(term: string): string {
-  // Convert wildcard * to temporary marker (escaped ones are already handled as ESC.ASTERISK)
+  // 와일드카드 *를 임시 마커로 변환 (이스케이프된 것은 이미 ESC.ASTERISK로 처리됨)
   const WILDCARD = "\x01WILDCARD\x01";
   const hasWildcard = term.includes("*");
   let pattern = term.replace(/\*/g, WILDCARD);
 
-  // Escape SQL LIKE special characters (\ → \\, % → \%, _ → \_, [ → \[)
+  // SQL LIKE 특수 문자 이스케이프 (\ → \\, % → \%, _ → \_, [ → \[)
   pattern = pattern
     .replace(/\\/g, "\\\\")
     .replace(/%/g, "\\%")
     .replace(/_/g, "\\_")
     .replace(/\[/g, "\\[");
 
-  // Convert wildcard marker → % (SQL wildcard)
+  // 와일드카드 마커 → % (SQL 와일드카드)로 변환
   pattern = pattern.replaceAll(WILDCARD, "%");
 
-  // Restore escape placeholders
+  // 이스케이프 플레이스홀더 복원
   pattern = pattern
     .replaceAll(ESC.BACKSLASH, "\\\\") // \\ → SQL \\
     .replaceAll(ESC.ASTERISK, "*") // \* → literal * (not special in SQL)
@@ -182,8 +182,8 @@ function termToLikePattern(term: string): string {
     .replaceAll(ESC.PLUS, "+")
     .replaceAll(ESC.MINUS, "-");
 
-  // If no wildcard, add % on both sides (default substring search)
-  // If wildcard exists, use the pattern as specified by the user
+  // 와일드카드가 없으면 양쪽에 % 추가 (기본 부분 문자열 검색)
+  // 와일드카드가 있으면 사용자가 지정한 패턴 그대로 사용
   if (hasWildcard) {
     return pattern;
   }

package/src/expr/expr-unit.ts

@@ -2,8 +2,8 @@ import type { ColumnPrimitive, ColumnPrimitiveStr } from "../types/column";
 import type { Expr, WhereExpr } from "../types/expr";
 
 /**
- * Type-safe expression wrapper
- * Tracks expression return type using TypeScript generics
+ * 타입 안전 표현식 래퍼
+ * TypeScript 제네릭을 사용하여 표현식 반환 타입을 추적한다
  */
 export class ExprUnit<TPrimitive extends ColumnPrimitive> {
   readonly $infer!: TPrimitive;
@@ -19,13 +19,13 @@ export class ExprUnit<TPrimitive extends ColumnPrimitive> {
 }
 
 /**
- * Expression wrapper for WHERE clause
+ * WHERE 절용 표현식 래퍼
  */
 export class WhereExprUnit {
   constructor(readonly expr: WhereExpr) {}
 }
 
 /**
- * Input type that accepts ExprUnit or literal values
+ * ExprUnit 또는 리터럴 값을 받는 입력 타입
  */
 export type ExprInput<TPrimitive extends ColumnPrimitive> = ExprUnit<TPrimitive> | TPrimitive;

package/src/expr/expr.ts

@@ -14,14 +14,14 @@ import type { Expr, DateUnit, WhereExpr, WinSpec } from "../types/expr";
 import type { SelectQueryDef } from "../types/query-def";
 import type { Queryable } from "../exec/queryable";
 
-// Window Function Spec Input (for user API)
+// Window 함수 Spec 입력 (사용자 API용)
 interface WinSpecInput {
   partitionBy?: ExprInput<ColumnPrimitive>[];
   orderBy?: [ExprInput<ColumnPrimitive>, ("ASC" | "DESC")?][];
 }
 
 /**
- * Switch expression builder interface
+ * Switch expression builder 인터페이스
  */
 export interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
   case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): SwitchExprBuilder<TPrimitive>;
@@ -29,10 +29,10 @@ export interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
 }
 
 /**
- * Dialect-independent SQL expression builder
+ * Dialect 독립적 SQL expression builder
  *
- * Generates JSON AST (Expr) instead of SQL strings, which QueryBuilder
- * converts to each DBMS (MySQL, MSSQL, PostgreSQL)
+ * SQL 문자열 대신 JSON AST(Expr)를 생성하며, QueryBuilder가
+ * 각 DBMS(MySQL, MSSQL, PostgreSQL)로 변환
  *
  * @example
  * ```typescript
@@ -55,11 +55,11 @@ export interface SwitchExprBuilder<TPrimitive extends ColumnPrimitive> {
  * }))
  * ```
  *
- * @see {@link Queryable} Query builder class
- * @see {@link ExprUnit} Expression wrapper class
+ * @see {@link Queryable} Query builder 클래스
+ * @see {@link ExprUnit} Expression 래퍼 클래스
  */
 export const expr = {
-  //#region ========== Value creation ==========
+  //#region ========== 값 생성 ==========
 
   /**
    * Wrap literal value as ExprUnit
@@ -1394,7 +1394,7 @@ export const expr = {
   //#endregion
 
   //#region ========== SELECT - Aggregate ==========
-  // Aggregates like SUM, AVG, MAX return NULL only when all values are NULL or no rows exist (rows with NULL values are ignored)
+  // SUM, AVG, MAX 등 집계는 모든 값이 NULL이거나 행이 없을 때만 NULL 반환 (NULL 값을 가진 행은 무시됨)
 
   /**
    * Count rows (COUNT)
@@ -2049,7 +2049,7 @@ export const expr = {
 
 //#region ========== Internal Helpers ==========
 
-// Return the first non-null value among multiple values (COALESCE)
+// 여러 값 중 첫 번째 non-null 값 반환 (COALESCE)
 function coalesce<TPrimitive extends ColumnPrimitive>(
   ...args: [
     ExprInput<TPrimitive | undefined>,
@@ -2071,7 +2071,7 @@ function coalesce<TPrimitive extends ColumnPrimitive>(
 
 function createSwitchBuilder<TPrimitive extends ColumnPrimitive>(): SwitchExprBuilder<TPrimitive> {
   const cases: { when: WhereExpr; then: Expr }[] = [];
-  const thenValues: ExprInput<TPrimitive>[] = []; // Store then values
+  const thenValues: ExprInput<TPrimitive>[] = []; // then 값 저장
 
   return {
     case(condition: WhereExprUnit, then: ExprInput<TPrimitive>): typeof this {
@@ -2084,7 +2084,7 @@ function createSwitchBuilder<TPrimitive extends ColumnPrimitive>(): SwitchExprBu
     },
     default(value: ExprInput<TPrimitive>): ExprUnit<TPrimitive> {
       const allValues = [...thenValues, value];
-      // 1. Find dataType from ExprUnit
+      // 1. ExprUnit에서 dataType 찾기
       const exprUnit = allValues.find((v): v is ExprUnit<TPrimitive> => v instanceof ExprUnit);
       if (exprUnit) {
         return new ExprUnit(exprUnit.dataType, {
@@ -2094,7 +2094,7 @@ function createSwitchBuilder<TPrimitive extends ColumnPrimitive>(): SwitchExprBu
         });
       }
 
-      // 2. Infer from non-null literal
+      // 2. non-null 리터럴에서 추론
       const nonNullLiteral = allValues.find((v) => v != null) as ColumnPrimitive;
       if (nonNullLiteral == null) {
         throw new Error("At least one of switch's case/default must be non-null.");

package/src/index.ts

@@ -1,6 +1,6 @@
 //#region ========== Core ==========
 
-// Functional API (recommended)
+// 함수형 API (권장)
 export * from "./define-db-context";
 export * from "./create-db-context";
 export * from "./types/db-context-def";
@@ -25,12 +25,12 @@ export * from "./expr/expr-unit";
 
 //#region ========== Schema Builders ==========
 
-// Table / View / Procedure
+// 테이블 / 뷰 / 프로시저
 export * from "./schema/table-builder";
 export * from "./schema/view-builder";
 export * from "./schema/procedure-builder";
 
-// Factory
+// 팩토리
 export * from "./schema/factory/column-builder";
 export * from "./schema/factory/index-builder";
 export * from "./schema/factory/relation-builder";
@@ -59,19 +59,19 @@ export * from "./query-builder/postgresql/postgresql-expr-renderer";
 
 //#region ========== Types ==========
 
-// Database types
+// 데이터베이스 타입
 export * from "./types/db";
 
-// Result parsing
+// 결과 파싱
 export * from "./utils/result-parser";
 
-// Column types
+// column 타입
 export * from "./types/column";
 
-// Expression types
+// 표현식 타입
 export * from "./types/expr";
 
-// QueryDef types
+// QueryDef 타입
 export * from "./types/query-def";
 
 //#endregion

package/src/models/system-migration.ts

@@ -4,5 +4,5 @@ export const _Migration = Table("_migration")
   .columns((c) => ({
     code: c.varchar(255),
   }))
-  .description("System Migration Table")
+  .description("시스템 마이그레이션 테이블")
   .primaryKey("code");

package/src/query-builder/base/expr-renderer-base.ts

@@ -68,12 +68,12 @@ import type {
 import type { SelectQueryDef } from "../../types/query-def";
 
 /**
- * Expr → SQL Render abstract base class
+ * Expr → SQL 렌더링 추상 기본 클래스
  *
- * Base principles:
- * - Implement only 100% identical logic across all dialects (dispatch)
- * - If different at all, make it abstract
- * - Method names match expr.type (enables dynamic dispatch)
+ * 기본 원칙:
+ * - 모든 dialect에서 100% 동일한 로직만 구현 (dispatch)
+ * - 조금이라도 다르면 abstract로 처리
+ * - 메서드 이름이 expr.type과 동일 (동적 dispatch 가능)
  */
 export abstract class ExprRendererBase {
   constructor(protected buildSelect: (def: SelectQueryDef) => string) {}
@@ -81,31 +81,31 @@ export abstract class ExprRendererBase {
   //#region ========== Public Utilities ==========
 
   /**
-   * Wrap identifier (table name, column name, etc.)
+   * 식별자 감싸기 (테이블명, column명 등)
    * MySQL: `name`, MSSQL: [name], PostgreSQL: "name"
    */
   abstract wrap(name: string): string;
 
   /**
-   * Escape for SQL string literals
-   * Called when used as a string value in dynamic SQL or system queries
-   * e.g.: WHERE schema_name = 'escaped_value'
+   * SQL 문자열 리터럴용 이스케이프
+   * 동적 SQL이나 시스템 쿼리에서 문자열 값으로 사용할 때 호출
+   * 예: WHERE schema_name = 'escaped_value'
    */
   abstract escapeString(value: string): string;
 
   /**
-   * Value escape (transform to appropriate SQL literal based on type)
+   * 값 이스케이프 (타입에 맞는 SQL 리터럴로 변환)
    */
   abstract escapeValue(value: unknown): string;
 
   //#endregion
 
-  //#region ========== Dispatch (100% identical) ==========
+  //#region ========== Dispatch (100% 동일) ==========
 
   render(expr: Expr | WhereExpr): string {
     const method = this[expr.type as keyof this];
     if (typeof method !== "function") {
-      throw new Error(`Unknown Expr type: ${expr.type}`);
+      throw new Error(`알 수 없는 Expr 타입: ${expr.type}`);
     }
     return (method as (e: Expr | WhereExpr) => string).call(this, expr);
   }
@@ -125,7 +125,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - comparison (null-safe required) ==========
+  //#region ========== Abstract - 비교 (null-safe 필수) ==========
 
   protected abstract eq(expr: ExprEq): string;
   protected abstract gt(expr: ExprGt): string;
@@ -142,7 +142,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - logic ==========
+  //#region ========== Abstract - 논리 ==========
 
   protected abstract not(expr: ExprNot): string;
   protected abstract and(expr: ExprAnd): string;
@@ -150,7 +150,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - String (null processing required) ==========
+  //#region ========== Abstract - 문자열 (null 처리 필수) ==========
 
   protected abstract concat(expr: ExprConcat): string;
   protected abstract left(expr: ExprLeft): string;
@@ -167,7 +167,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - Number ==========
+  //#region ========== Abstract - 숫자 ==========
 
   protected abstract abs(expr: ExprAbs): string;
   protected abstract round(expr: ExprRound): string;
@@ -176,7 +176,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - Date ==========
+  //#region ========== Abstract - 날짜 ==========
 
   protected abstract year(expr: ExprYear): string;
   protected abstract month(expr: ExprMonth): string;
@@ -193,7 +193,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - Condition ==========
+  //#region ========== Abstract - 조건 ==========
 
   protected abstract coalesce(expr: ExprCoalesce): string;
   protected abstract nullIf(expr: ExprNullIf): string;
@@ -203,7 +203,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - Aggregate ==========
+  //#region ========== Abstract - 집계 ==========
 
   protected abstract count(expr: ExprCount): string;
   protected abstract sum(expr: ExprSum): string;
@@ -213,7 +213,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - Other ==========
+  //#region ========== Abstract - 기타 ==========
 
   protected abstract greatest(expr: ExprGreatest): string;
   protected abstract least(expr: ExprLeast): string;
@@ -229,7 +229,7 @@ export abstract class ExprRendererBase {
 
   //#endregion
 
-  //#region ========== Abstract - System ==========
+  //#region ========== Abstract - 시스템 ==========
 
   protected abstract subquery(expr: ExprSubquery): string;
 

package/src/query-builder/base/query-builder-base.ts

@@ -37,14 +37,14 @@ import type { QueryBuildResult } from "../../types/db";
 import type { ExprRendererBase } from "./expr-renderer-base";
 
 /**
- * QueryDef → SQL render abstract base class
+ * QueryDef → SQL 렌더링 추상 기본 클래스
  *
- * Base principles:
- * - Implement only 100% identical logic across all dialects (dispatch)
- * - If different at all, make it abstract
- * - Method name identical to def.type (enables dynamic dispatch)
+ * 기본 원칙:
+ * - 모든 dialect에서 100% 동일한 로직만 구현 (dispatch)
+ * - 조금이라도 다르면 abstract로 처리
+ * - 메서드 이름이 def.type과 동일 (동적 dispatch 가능)
  */
-/** Properties that are part of a basic (non-LATERAL) JOIN */
+/** 기본(비 LATERAL) JOIN의 속성 목록 */
 const BASIC_JOIN_PROPS: ReadonlySet<string> = new Set<
   keyof Pick<SelectQueryDefJoin, "type" | "from" | "as" | "where" | "isSingle">
 >(["type", "from", "as", "where", "isSingle"]);
@@ -52,35 +52,35 @@ const BASIC_JOIN_PROPS: ReadonlySet<string> = new Set<
 export abstract class QueryBuilderBase {
   protected abstract expr: ExprRendererBase;
 
-  //#region ========== Dispatch (100% identical) ==========
+  //#region ========== Dispatch (100% 동일) ==========
 
   build(def: QueryDef): QueryBuildResult {
     const method = this[def.type as keyof this];
     if (typeof method !== "function") {
-      throw new Error(`Unknown QueryDef type: ${def.type}`);
+      throw new Error(`알 수 없는 QueryDef 타입: ${def.type}`);
     }
     return (method as (d: QueryDef) => QueryBuildResult).call(this, def);
   }
 
-  /** Helper to wrap SQL in QueryBuildResult */
+  /** SQL을 QueryBuildResult로 래핑하는 헬퍼 */
   protected result(sql: string, resultSetIndex?: number): QueryBuildResult {
     return resultSetIndex != null ? { sql, resultSetIndex } : { sql };
   }
 
   //#endregion
 
-  //#region ========== Common render method (100% identical) ==========
+  //#region ========== 공통 렌더링 메서드 (100% 동일) ==========
 
-  /** Table name render (different per dialect, so abstract) */
+  /** 테이블명 렌더링 (dialect마다 다르므로 abstract) */
   protected abstract tableName(obj: QueryDefObjectName): string;
 
-  /** WHERE clause render */
+  /** WHERE 절 렌더링 */
   protected renderWhere(wheres: WhereExpr[] | undefined): string {
     if (wheres == null || wheres.length === 0) return "";
     return ` WHERE ${this.expr.renderWhere(wheres)}`;
   }
 
-  /** ORDER BY clause render */
+  /** ORDER BY 절 렌더링 */
   protected renderOrderBy(orderBy: [Expr, ("ASC" | "DESC")?][] | undefined): string {
     if (orderBy == null || orderBy.length === 0) return "";
     const parts = orderBy.map(
@@ -89,58 +89,58 @@ export abstract class QueryBuilderBase {
     return ` ORDER BY ${parts.join(", ")}`;
   }
 
-  /** GROUP BY clause render */
+  /** GROUP BY 절 렌더링 */
   protected renderGroupBy(groupBy: Expr[] | undefined): string {
     if (groupBy == null || groupBy.length === 0) return "";
     return ` GROUP BY ${groupBy.map((g) => this.expr.render(g)).join(", ")}`;
   }
 
-  /** HAVING clause render */
+  /** HAVING 절 렌더링 */
   protected renderHaving(having: WhereExpr[] | undefined): string {
     if (having == null || having.length === 0) return "";
     return ` HAVING ${this.expr.renderWhere(having)}`;
   }
 
-  /** JOIN clause render */
+  /** JOIN 절 렌더링 */
   protected renderJoins(joins: SelectQueryDefJoin[] | undefined): string {
     if (joins == null || joins.length === 0) return "";
     return joins.map((j) => this.renderJoin(j)).join("");
   }
 
-  /** Single JOIN render (different per dialect, so abstract) */
+  /** 단일 JOIN 렌더링 (dialect마다 다르므로 abstract) */
   protected abstract renderJoin(join: SelectQueryDefJoin): string;
 
   /**
-   * Detect if JOIN needs LATERAL/CROSS APPLY
+   * JOIN에 LATERAL/CROSS APPLY가 필요한지 감지
    *
-   * If JOIN has only basic properties (type, from, as, where, isSingle), treat as normal JOIN.
-   * Otherwise, subquery is needed, so use LATERAL JOIN:
+   * JOIN이 기본 속성(type, from, as, where, isSingle)만 가지면 일반 JOIN으로 처리.
+   * 그 외의 경우 서브쿼리가 필요하므로 LATERAL JOIN 사용:
    *
-   * - select: column transformation/aggregation needed (normal JOIN references entire table)
-   * - joins: nested JOIN handled inside subquery
-   * - orderBy, top, limit: sorting/limit applied inside subquery
-   * - groupBy, having: aggregation performed inside subquery
-   * - distinct: deduplication applied inside subquery
-   * - from (array): UNION ALL pattern
+   * - select: column 변환/집계가 필요 (일반 JOIN은 전체 테이블 참조)
+   * - joins: 중첩 JOIN은 서브쿼리 내부에서 처리
+   * - orderBy, top, limit: 정렬/제한은 서브쿼리 내부에서 적용
+   * - groupBy, having: 집계는 서브쿼리 내부에서 수행
+   * - distinct: 중복 제거는 서브쿼리 내부에서 적용
+   * - from (array): UNION ALL 패턴
    *
-   * Note: select and joins are auto-generated during nested joins, so not in basicJoinProps.
-   * Even if user doesn't call .select() directly, internal .joinSingle() may add
-   * select/joins, which also requires subquery.
+   * 참고: select와 joins는 중첩 join 시 자동 생성되므로 basicJoinProps에 없음.
+   * 사용자가 직접 .select()를 호출하지 않더라도 내부 .joinSingle()이
+   * select/joins를 추가할 수 있으며, 이 경우에도 서브쿼리가 필요함.
    */
   protected needsLateral(join: SelectQueryDefJoin): boolean {
-    // If from is array, always LATERAL (UNION ALL pattern)
+    // from이 배열이면 항상 LATERAL (UNION ALL 패턴)
     if (Array.isArray(join.from)) {
       return true;
     }
 
-    // LATERAL needed if join has additional properties beyond basic JOIN properties
+    // 기본 JOIN 속성 외 추가 속성이 있으면 LATERAL 필요
     return Object.keys(join).some((key) => !BASIC_JOIN_PROPS.has(key));
   }
 
-  /** FROM clause source render */
+  /** FROM 절 소스 렌더링 */
   protected renderFrom(from: SelectQueryDef["from"]): string {
     if (from == null) {
-      throw new Error("FROM clause is required.");
+      throw new Error("FROM 절이 필요합니다.");
     }
     if (typeof from === "string") {
       return this.expr.wrap(from);