@simplysm/orm-common 13.0.100 → 14.0.4

package/src/exec/queryable.ts

@@ -35,7 +35,7 @@ import { expr } from "../expr/expr";
 /**
  * JOIN query builder
  *
- * Used internally by join/joinSingle methods to specify the table to join
+ * join/joinSingle 메서드 내부에서 조인할 table을 지정하는 데 사용
  */
 class JoinQueryable {
   constructor(
@@ -44,20 +44,20 @@ class JoinQueryable {
   ) {}
 
   /**
-   * Specify the table to join
+   * 조인할 table 지정
    *
-   * @param table - Table to join
-   * @returns Joined Queryable
+   * @param table - 조인할 table
+   * @returns 조인된 Queryable
    */
   from<T extends TableBuilder<any, any>>(table: T): Queryable<T["$inferSelect"], T> {
     return queryable(this._db, table, this._joinAlias)();
   }
 
   /**
-   * Directly specify columns in join result
+   * 조인 결과의 column을 직접 지정
    *
-   * @param columns - Custom column definition
-   * @returns Queryable with custom columns applied
+   * @param columns - 커스텀 column 정의
+   * @returns 커스텀 column이 적용된 Queryable
    */
   select<R extends DataRecord>(columns: QueryableRecord<R>): Queryable<R, never> {
     return new Queryable({
@@ -69,15 +69,15 @@ class JoinQueryable {
   }
 
   /**
-   * Combine multiple Queryables with UNION
+   * 여러 Queryable을 UNION으로 결합
    *
-   * @param queries - Array of Queryables to UNION (minimum 2)
-   * @returns UNION-ed Queryable
-   * @throws If less than 2 queryables are passed
+   * @param queries - UNION할 Queryable 배열 (최소 2개)
+   * @returns UNION된 Queryable
+   * @throws 2개 미만의 queryable이 전달되면 에러
    */
   union<TData extends DataRecord>(...queries: Queryable<TData, any>[]): Queryable<TData, never> {
     if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
+      throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
         provided: queries.length,
         minimum: 2,
       });
@@ -87,7 +87,7 @@ class JoinQueryable {
 
     return new Queryable({
       db: first.meta.db,
-      from: queries, // stored as Queryable[] array
+      from: queries, // Queryable[] 배열로 저장
       as: this._joinAlias,
       columns: transformColumnsAlias(first.meta.columns, this._joinAlias, ""),
     });
@@ -95,9 +95,9 @@ class JoinQueryable {
 }
 
 /**
- * Recursive CTE (Common Table Expression) builder
+ * 재귀 CTE (Common Table Expression) builder
  *
- * used internally in recursive() method, Defines the body of a recursive query
+ * recursive() 메서드 내부에서 사용되며, 재귀 쿼리의 본문을 정의한다
  *
  * @template TBaseData - Base query data type
  */
@@ -108,10 +108,10 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
   ) {}
 
   /**
-   * specify the target table for recursive query
+   * 재귀 query의 대상 table 지정
    *
-   * @param table - Target table to recurse
-   * @returns Queryable with self property added (for self-reference)
+   * @param table - 재귀할 대상 table
+   * @returns self 속성이 추가된 Queryable (자기 참조용)
    */
   from<T extends TableBuilder<any, any>>(
     table: T,
@@ -132,10 +132,10 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
   }
 
   /**
-   * Directly specify columns in recursive query
+   * 재귀 query의 column을 직접 지정
    *
-   * @param columns - Custom column definition
-   * @returns Queryable with self property added
+   * @param columns - 커스텀 column 정의
+   * @returns self 속성이 추가된 Queryable
    */
   select<R extends DataRecord>(
     columns: QueryableRecord<R>,
@@ -161,17 +161,17 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
   }
 
   /**
-   * Combine multiple Queryables with UNION (for recursive query)
+   * 여러 Queryable을 UNION으로 결합 (재귀 query용)
    *
-   * @param queries - Array of Queryables to UNION (minimum 2)
-   * @returns UNION Queryable with self property added
-   * @throws If less than 2 queryables are passed
+   * @param queries - UNION할 Queryable 배열 (최소 2개)
+   * @returns self 속성이 추가된 UNION Queryable
+   * @throws 2개 미만의 queryable이 전달되면 에러
    */
   union<TData extends DataRecord>(
     ...queries: Queryable<TData, any>[]
   ): Queryable<TData & { self?: TBaseData[] }, never> {
     if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
+      throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
         provided: queries.length,
         minimum: 2,
       });
@@ -183,7 +183,7 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
 
     return new Queryable<any, never>({
       db: first.meta.db,
-      from: queries, // stored as Queryable[] array
+      from: queries, // Queryable[] 배열로 저장
       as: this._cteName,
       columns: transformColumnsAlias(first.meta.columns, this._cteName, ""),
     }).join(
@@ -201,12 +201,12 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
 }
 
 /**
- * Query builder class
+ * Query builder 클래스
  *
- * Construct SELECT, INSERT, UPDATE, DELETE queries on tables/views in a chaining manner
+ * 체이닝 방식으로 table/view에 대한 SELECT, INSERT, UPDATE, DELETE query를 구성
  *
- * @template TData - Data type of query result
- * @template TFrom - Source table (needed for CUD operations)
+ * @template TData - Query 결과의 데이터 타입
+ * @template TFrom - 소스 table (CUD 연산에 필요)
  *
  * @example
  * ```typescript
@@ -227,17 +227,17 @@ class RecursiveQueryable<TBaseData extends DataRecord> {
  */
 export class Queryable<
   TData extends DataRecord,
-  TFrom extends TableBuilder<any, any> | never, // Only TableBuilder is supported for CUD operations
+  TFrom extends TableBuilder<any, any> | never, // CUD 연산은 TableBuilder만 지원
 > {
   constructor(readonly meta: QueryableMeta<TData>) {}
 
   //#region ========== option - SELECT / DISTINCT / LOCK ==========
 
   /**
-   * Specify columns to SELECT.
+   * SELECT할 column 지정.
    *
-   * @param fn - Column mapping function. Receives original columns and returns new column structure
-   * @returns Queryable with new column structure applied
+   * @param fn - Column 매핑 함수. 원본 column을 받아 새 column 구조를 반환
+   * @returns 새 column 구조가 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -269,9 +269,9 @@ export class Queryable<
   }
 
   /**
-   * Apply DISTINCT option to remove duplicate rows
+   * 중복 행 제거를 위한 DISTINCT 옵션 적용
    *
-   * @returns Queryable with DISTINCT applied
+   * @returns DISTINCT가 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -296,11 +296,11 @@ export class Queryable<
   }
 
   /**
-   * Apply row lock (FOR UPDATE)
+   * 행 잠금 적용 (FOR UPDATE)
    *
-   * Acquire exclusive lock on selected rows within transaction
+   * 트랜잭션 내에서 선택된 행에 대한 배타적 잠금 획득
    *
-   * @returns Queryable with lock applied
+   * @returns 잠금이 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -332,10 +332,10 @@ export class Queryable<
   //#region ========== restrict - TOP / LIMIT ==========
 
   /**
-   * Select only top N rows (can be used without ORDER BY)
+   * 상위 N개 행만 선택 (ORDER BY 없이도 사용 가능)
    *
-   * @param count - number of rows to select
-   * @returns Queryable with TOP applied
+   * @param count - 선택할 행 수
+   * @returns TOP이 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -361,13 +361,13 @@ export class Queryable<
   }
 
   /**
-   * Set LIMIT/OFFSET for pagination.
-   * Must call orderBy() first.
+   * 페이지네이션을 위한 LIMIT/OFFSET 설정.
+   * 먼저 orderBy()를 호출해야 함.
    *
-   * @param skip - number of rows to skip (OFFSET)
-   * @param take - number of rows to fetch (LIMIT)
-   * @returns Queryable with pagination applied
-   * @throws Error if no ORDER BY clause
+   * @param skip - 건너뛸 행 수 (OFFSET)
+   * @param take - 가져올 행 수 (LIMIT)
+   * @returns 페이지네이션이 적용된 Queryable
+   * @throws ORDER BY 절이 없으면 에러
    *
    * @example
    * ```typescript
@@ -386,7 +386,7 @@ export class Queryable<
     }
 
     if (!this.meta.orderBy) {
-      throw new ArgumentError("limit() requires ORDER BY clause.", {
+      throw new ArgumentError("limit()은 ORDER BY 절이 필요합니다.", {
         method: "limit",
         required: "orderBy",
       });
@@ -403,11 +403,11 @@ export class Queryable<
   //#region ========== sorting - ORDER BY ==========
 
   /**
-   * Add sorting condition. Multiple calls apply in order.
+   * 정렬 조건 추가. 여러 번 호출 시 순서대로 적용됨.
    *
-   * @param fn - function returning columns to sort by
-   * @param orderBy - Sort direction (ASC/DESC). Default: ASC
-   * @returns Queryable with sorting conditions added
+   * @param fn - 정렬할 column을 반환하는 함수
+   * @param orderBy - 정렬 방향 (ASC/DESC). 기본값: ASC
+   * @returns 정렬 조건이 추가된 Queryable
    *
    * @example
    * ```typescript
@@ -441,10 +441,10 @@ export class Queryable<
   //#region ========== Search - WHERE ==========
 
   /**
-   * Add WHERE condition. Multiple calls are combined with AND.
+   * WHERE 조건 추가. 여러 번 호출 시 AND로 결합됨.
    *
-   * @param predicate - Function returning an array of conditions
-   * @returns Queryable with conditions added
+   * @param predicate - 조건 배열을 반환하는 함수
+   * @returns 조건이 추가된 Queryable
    *
    * @example
    * ```typescript
@@ -471,16 +471,16 @@ export class Queryable<
   }
 
   /**
-   * Perform text search
+   * 텍스트 검색 수행
    *
-   * See {@link parseSearchQuery} for search syntax
-   * - Space-separated words are OR conditions
-   * - Words starting with `+` are required includes (AND condition)
-   * - Words starting with `-` are excludes (NOT condition)
+   * 검색 구문은 {@link parseSearchQuery} 참조
+   * - 공백으로 구분된 단어는 OR 조건
+   * - `+`로 시작하는 단어는 필수 포함 (AND 조건)
+   * - `-`로 시작하는 단어는 제외 (NOT 조건)
    *
-   * @param fn - Function returning target columns to search
-   * @param searchText - Search text
-   * @returns Queryable with search conditions added
+   * @param fn - 검색 대상 column을 반환하는 함수
+   * @param searchText - 검색 텍스트
+   * @returns 검색 조건이 추가된 Queryable
    *
    * @example
    * ```typescript
@@ -509,7 +509,7 @@ export class Queryable<
 
     const conditions: WhereExprUnit[] = [];
 
-    // OR condition: match if any pattern matches in any column
+    // OR 조건: 아무 column에서 아무 패턴이 매칭되면 일치
     if (parsed.or.length === 1) {
       const pattern = parsed.or[0];
       const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
@@ -524,13 +524,13 @@ export class Queryable<
       conditions.push(expr.or(orConditions));
     }
 
-    // MUST condition: each pattern must match in at least one column (AND)
+    // MUST 조건: 각 패턴이 최소 하나의 column에서 매칭되어야 함 (AND)
     for (const pattern of parsed.must) {
       const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
       conditions.push(expr.or(columnMatches));
     }
 
-    // NOT condition: must not match in any column (AND NOT)
+    // NOT 조건: 아무 column에서도 매칭되지 않아야 함 (AND NOT)
     for (const pattern of parsed.not) {
       const columnMatches = columns.map((col) => expr.like(expr.lower(col), pattern.toLowerCase()));
       conditions.push(expr.not(expr.or(columnMatches)));
@@ -548,10 +548,10 @@ export class Queryable<
   //#region ========== Group - GROUP BY / HAVING ==========
 
   /**
-   * Add GROUP BY clause
+   * GROUP BY 절 추가
    *
-   * @param fn - Function returning columns to group by
-   * @returns Queryable with GROUP BY applied
+   * @param fn - 그룹화할 column을 반환하는 함수
+   * @returns GROUP BY가 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -580,10 +580,10 @@ export class Queryable<
   }
 
   /**
-   * Add HAVING clause (filtering after GROUP BY)
+   * HAVING 절 추가 (GROUP BY 이후 필터링)
    *
-   * @param predicate - Function returning an array of conditions
-   * @returns Queryable with HAVING applied
+   * @param predicate - 조건 배열을 반환하는 함수
+   * @returns HAVING이 적용된 Queryable
    *
    * @example
    * ```typescript
@@ -618,11 +618,11 @@ export class Queryable<
   //#region ========== join - JOIN / JOIN SINGLE ==========
 
   /**
-   * Perform LEFT OUTER JOIN for 1:N relation (added as array to result)
+   * 1:N 관계에 대한 LEFT OUTER JOIN 수행 (결과에 배열로 추가)
    *
-   * @param as - Property name to add to result
-   * @param fn - Callback function defining join conditions
-   * @returns Queryable with join result added as array
+   * @param as - 결과에 추가할 속성 이름
+   * @param fn - 조인 조건을 정의하는 콜백 함수
+   * @returns 조인 결과가 배열로 추가된 Queryable
    *
    * @example
    * ```typescript
@@ -647,16 +647,16 @@ export class Queryable<
       });
     }
 
-    // 1. join alias Generate
+    // 1. JOIN 별칭 생성
     const joinAlias = `${this.meta.as}.${as}`;
 
-    // 2. Transform target → Queryable (pass alias)
+    // 2. 대상을 Queryable로 변환 (별칭 전달)
     const joinQr = new JoinQueryable(this.meta.db, joinAlias);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(joinQr, this.meta.columns);
 
-    // 4. Add join result to new columns
+    // 4. JOIN 결과를 새 column에 추가
     const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
 
     return new Queryable({
@@ -671,11 +671,11 @@ export class Queryable<
   }
 
   /**
-   * Perform LEFT OUTER JOIN for N:1 or 1:1 relation (added as single object to result)
+   * N:1 또는 1:1 관계에 대한 LEFT OUTER JOIN 수행 (결과에 단일 객체로 추가)
    *
-   * @param as - Property name to add to result
-   * @param fn - Callback function defining join conditions
-   * @returns Queryable with join result added as single object
+   * @param as - 결과에 추가할 속성 이름
+   * @param fn - 조인 조건을 정의하는 콜백 함수
+   * @returns 조인 결과가 단일 객체로 추가된 Queryable
    *
    * @example
    * ```typescript
@@ -703,16 +703,16 @@ export class Queryable<
       });
     }
 
-    // 1. join alias Generate
+    // 1. JOIN 별칭 생성
     const joinAlias = `${this.meta.as}.${as}`;
 
-    // 2. Transform target → Queryable (pass alias)
+    // 2. 대상을 Queryable로 변환 (별칭 전달)
     const joinQr = new JoinQueryable(this.meta.db, joinAlias);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(joinQr, this.meta.columns);
 
-    // 4. Add join result to new columns
+    // 4. JOIN 결과를 새 column에 추가
     const joinColumns = transformColumnsAlias(resultQr.meta.columns, joinAlias);
 
     return new Queryable({
@@ -731,12 +731,12 @@ export class Queryable<
   //#region ========== join - INCLUDE ==========
 
   /**
-   * Automatically JOIN related tables.
-   * Operates based on FK/FKT relations defined in TableBuilder.
+   * 관련 table을 자동으로 JOIN.
+   * TableBuilder에 정의된 FK/FKT 관계를 기반으로 동작.
    *
-   * @param fn - Function selecting relations to include (type-checked via PathProxy)
-   * @returns Queryable with JOINs added
-   * @throws Error if relation is not defined
+   * @param fn - 포함할 관계를 선택하는 함수 (PathProxy를 통해 타입 체크)
+   * @returns JOIN이 추가된 Queryable
+   * @throws 관계가 정의되지 않은 경우 에러
    *
    * @example
    * ```typescript
@@ -778,17 +778,17 @@ export class Queryable<
 
     for (const relationName of relationNames) {
       if (!(currentTable instanceof TableBuilder)) {
-        throw new Error("include() can only be used on TableBuilder-based queryables.");
+        throw new Error("include()는 TableBuilder 기반 queryable에서만 사용할 수 있습니다.");
       }
 
       const parentChain = chainParts.join(".");
       chainParts.push(relationName);
 
-      // Prevent duplicate add if already JOINed
+      // 이미 JOIN된 경우 중복 추가 방지
       const targetAlias = `${result.meta.as}.${chainParts.join(".")}`;
       const existingJoin = result.meta.joins?.find((j) => j.queryable.meta.as === targetAlias);
       if (existingJoin) {
-        // Update currentTable to the existing JOIN's table and continue
+        // 기존 JOIN의 table로 currentTable 갱신 후 계속
         const existingFrom = existingJoin.queryable.meta.from;
         if (existingFrom instanceof TableBuilder) {
           currentTable = existingFrom;
@@ -798,12 +798,12 @@ export class Queryable<
 
       const relationDef = currentTable.meta.relations?.[relationName];
       if (relationDef == null) {
-        throw new Error(`Relation '${relationName}' not found.`);
+        throw new Error(`관계 '${relationName}'을(를) 찾을 수 없습니다.`);
       }
 
       if (relationDef instanceof ForeignKeyBuilder || relationDef instanceof RelationKeyBuilder) {
         // FK/RelationKey (N:1): Post.user → User
-        // condition: Post.userId = User.id
+        // 조건: Post.userId = User.id
         const targetTable = relationDef.meta.targetFn();
         const fkColKeys = relationDef.meta.columns;
         const targetPkColKeys = getMatchedPrimaryKeys(fkColKeys, targetTable);
@@ -811,7 +811,7 @@ export class Queryable<
         result = result.joinSingle(chainParts.join("."), (joinQr, parentCols) => {
           const qr = joinQr.from(targetTable);
 
-          // FKT join is stored as array, so use first element if array
+          // FKT JOIN은 배열로 저장되므로, 배열이면 첫 번째 요소 사용
           const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
           const srcCols = (
             Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw
@@ -833,15 +833,15 @@ export class Queryable<
         relationDef instanceof ForeignKeyTargetBuilder ||
         relationDef instanceof RelationKeyTargetBuilder
       ) {
-        // FKT/RelationKeyTarget (1:N or 1:1): User.posts → Post[]
-        // condition: Post.userId = User.id
+        // FKT/RelationKeyTarget (1:N 또는 1:1): User.posts → Post[]
+        // 조건: Post.userId = User.id
         const targetTable = relationDef.meta.targetTableFn();
         const fkRelName = relationDef.meta.relationName;
         const sourceFk = targetTable.meta.relations?.[fkRelName];
         if (!(sourceFk instanceof ForeignKeyBuilder) && !(sourceFk instanceof RelationKeyBuilder)) {
           throw new Error(
-            `'${fkRelName}' referenced by '${relationName}' ` +
-              `is not a valid ForeignKey/RelationKey in ${targetTable.meta.name} table.`,
+            `'${relationName}'이(가) 참조하는 '${fkRelName}'은(는) ` +
+              `${targetTable.meta.name} 테이블에서 유효한 ForeignKey/RelationKey가 아닙니다.`,
           );
         }
         const sourceTable = targetTable;
@@ -853,7 +853,7 @@ export class Queryable<
         const buildJoin = (joinQr: JoinQueryable, parentCols: QueryableRecord<DataRecord>) => {
           const qr = joinQr.from(sourceTable);
 
-          // FKT join is stored as array, so use first element if array
+          // FKT JOIN은 배열로 저장되므로, 배열이면 첫 번째 요소 사용
           const srcColsRaw = parentChain ? parentCols[parentChain] : parentCols;
           const srcCols = (
             Array.isArray(srcColsRaw) ? srcColsRaw[0] : srcColsRaw
@@ -903,7 +903,7 @@ export class Queryable<
    * ```
    */
   wrap(): Queryable<TData, never> {
-    // Wrap the current Queryable as a Subquery
+    // 현재 Queryable을 서브쿼리로 래핑
     const wrapAlias = this.meta.db.getNextAlias();
     return new Queryable({
       db: this.meta.db,
@@ -932,7 +932,7 @@ export class Queryable<
     ...queries: Queryable<TData, any>[]
   ): Queryable<TData, never> {
     if (queries.length < 2) {
-      throw new ArgumentError("union requires at least 2 queryables.", {
+      throw new ArgumentError("union은 최소 2개의 queryable이 필요합니다.", {
         provided: queries.length,
         minimum: 2,
       });
@@ -942,7 +942,7 @@ export class Queryable<
     const unionAlias = first.meta.db.getNextAlias();
     return new Queryable({
       db: first.meta.db,
-      from: queries, // stored as Queryable[] array
+      from: queries, // Queryable[] 배열로 저장
       as: unionAlias,
       columns: transformColumnsAlias(first.meta.columns, unionAlias, ""),
     });
@@ -982,13 +982,13 @@ export class Queryable<
         columns: transformColumnsAlias(newFroms[0].meta.columns, this.meta.as, ""),
       });
     }
-    // Generate dynamic CTE name
+    // 동적 CTE 이름 생성
     const cteName = this.meta.db.getNextAlias();
 
-    // 2. Transform target to Queryable (pass CTE name)
+    // 2. 대상을 Queryable로 변환 (CTE 이름 전달)
     const cteQr = new RecursiveQueryable(this, cteName);
 
-    // 3. Execute fn (returns Queryable with conditions like where added)
+    // 3. fn 실행 (where 등 조건이 추가된 Queryable 반환)
     const resultQr = fn(cteQr);
 
     return new Queryable({
@@ -998,7 +998,7 @@ export class Queryable<
       columns: transformColumnsAlias(this.meta.columns, this.meta.as, ""),
       with: {
         name: cteName,
-        base: this as any, // Block circular reference type inference
+        base: this as any, // 순환 참조 타입 추론 차단
         recursive: resultQr,
       },
     });
@@ -1044,7 +1044,7 @@ export class Queryable<
   async single(): Promise<TData | undefined> {
     const result = await this.top(2).execute();
     if (result.length > 1) {
-      throw new ArgumentError("Expected single result but multiple results returned.", {
+      throw new ArgumentError("단일 결과를 기대했으나 복수 결과가 반환되었습니다.", {
         table: this._getSourceName(),
         resultCount: result.length,
       });
@@ -1053,7 +1053,7 @@ export class Queryable<
   }
 
   /**
-   * Return query source name (for error messages)
+   * Query 소스 이름 반환 (에러 메시지용)
    */
   private _getSourceName(): string {
     const from = this.meta.from;
@@ -1099,10 +1099,10 @@ export class Queryable<
    */
   async count(fn?: (cols: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>): Promise<number> {
     if (this.meta.distinct) {
-      throw new Error("Cannot use count() after distinct(). Use wrap() first.");
+      throw new Error("distinct() 이후에 count()를 사용할 수 없습니다. wrap()을 먼저 사용하세요.");
     }
     if (this.meta.groupBy) {
-      throw new Error("Cannot use count() after groupBy(). Use wrap() first.");
+      throw new Error("groupBy() 이후에 count()를 사용할 수 없습니다. wrap()을 먼저 사용하세요.");
     }
 
     const countQr = fn
@@ -1193,7 +1193,7 @@ export class Queryable<
       } else if (typeof val === "object" && val != null) {
         Object.assign(result, this._buildSelectDef(val, fullKey));
       } else {
-        // Plain value (string, number, boolean, etc.) — convert to Expr
+        // 일반 값 (string, number, boolean 등) — Expr로 변환
         result[fullKey] = expr.toExpr(val);
       }
     }
@@ -1230,16 +1230,16 @@ export class Queryable<
         if (outputColumns && !outputColumns.includes(fullKey)) continue;
 
         if (val instanceof ExprUnit) {
-          // primitive column
+          // 원시 column
           columns[fullKey] = val.dataType;
         } else if (Array.isArray(val)) {
-          // array (1:N relationship)
+          // 배열 (1:N 관계)
           if (val.length > 0) {
             joins[fullKey] = { isSingle: false };
             buildResultMeta(val[0], fullKey);
           }
         } else if (typeof val === "object") {
-          // Single object (N:1, 1:1 relationship)
+          // 단일 객체 (N:1, 1:1 관계)
           joins[fullKey] = { isSingle: true };
           buildResultMeta(val, fullKey);
         }
@@ -1291,7 +1291,7 @@ export class Queryable<
       return outputColumns ? [] : undefined;
     }
 
-    // Split into chunks for MSSQL's 1000 row limit
+    // MSSQL의 1000행 제한을 위해 청크로 분할
     const CHUNK_SIZE = 1000;
     const allResults: Pick<TFrom["$inferColumns"], K>[] = [];
 
@@ -1389,7 +1389,7 @@ export class Queryable<
     const from = this.meta.from as TableBuilder<any, any> | ViewBuilder<any, any, any>;
     const outputDef = this._getCudOutputDef();
 
-    // Set overrideIdentity if AI column has explicit values
+    // AI column에 명시적 값이 있으면 overrideIdentity 설정
     const overrideIdentity =
       outputDef.aiColName != null &&
       records.some((r) => (r as Record<string, unknown>)[outputDef.aiColName!] !== undefined);
@@ -1679,14 +1679,14 @@ export class Queryable<
 
     const { select: _sel, ...existsSelectQuery } = this.getSelectQueryDef();
 
-    // Generate updateRecord
+    // updateRecord 생성
     const updateQrRecord = updateRecordFn(this.meta.columns);
     const updateRecord: Record<string, Expr> = {};
     for (const [key, value] of Object.entries(updateQrRecord)) {
       updateRecord[key] = expr.toExpr(value);
     }
 
-    // Generate insertRecord (pass updateRecordRaw as second argument)
+    // insertRecord 생성 (updateRecordRaw를 두 번째 인자로 전달)
     const insertRecordRaw = insertRecordFn(updateQrRecord);
     const insertRecord = Object.fromEntries(
       Object.entries(insertRecordRaw).map(([key, value]) => [key, expr.toExpr(value)]),
@@ -1713,13 +1713,13 @@ export class Queryable<
   //#region ========== DDL Helper ==========
 
   /**
-   * FK constraint on/off (can be used within a transaction)
+   * FK 제약조건 활성화/비활성화 (트랜잭션 내에서 사용 가능)
    */
   async switchFk(enabled: boolean): Promise<void> {
     const from = this.meta.from;
     if (!(from instanceof TableBuilder) && !(from instanceof ViewBuilder)) {
       throw new Error(
-        "switchFk can only be used on TableBuilder or ViewBuilder based queryables.",
+        "switchFk는 TableBuilder 또는 ViewBuilder 기반 queryable에서만 사용할 수 있습니다.",
       );
     }
     await this.meta.db.switchFk(this.meta.db.getQueryDefObjectName(from), enabled);
@@ -1737,7 +1737,7 @@ export class Queryable<
 
     if (from instanceof TableBuilder) {
       if (from.meta.columns == null) {
-        throw new Error(`Table '${from.meta.name}' has no Column definition.`);
+        throw new Error(`테이블 '${from.meta.name}'에 Column 정의가 없습니다.`);
       }
 
       let aiColName: string | undefined;
@@ -1753,7 +1753,7 @@ export class Queryable<
       };
     }
 
-    throw new Error("CUD operations can only be used on TableBuilder-based queryables.");
+    throw new Error("CUD 작업은 TableBuilder 기반 queryable에서만 사용할 수 있습니다.");
   }
 
   //#endregion
@@ -1879,7 +1879,7 @@ export type QueryableWriteRecord<TData> = {
 };
 
 export type NullableQueryableRecord<TData extends DataRecord> = {
-  // Primitive — always | undefined (LEFT JOIN NULL propagation)
+  // 원시값 — 항상 | undefined (LEFT JOIN NULL 전파)
   [K in keyof TData]: TData[K] extends ColumnPrimitive
     ? ExprUnit<TData[K] | undefined>
     : TData[K] extends (infer U)[]
@@ -1898,9 +1898,9 @@ export type NullableQueryableRecord<TData extends DataRecord> = {
 };
 
 /**
- * Reverse-transform from QueryableRecord to DataRecord
+ * QueryableRecord에서 DataRecord로 역변환
  *
- * Unwraps ExprUnit<T> to T, recursively unwrapping nested objects/arrays
+ * ExprUnit<T>를 T로 언래핑, 중첩 객체/배열을 재귀적으로 언래핑
  */
 export type UnwrapQueryableRecord<R> = {
   [K in keyof R]: R[K] extends ExprUnit<infer T>
@@ -1917,27 +1917,27 @@ export type UnwrapQueryableRecord<R> = {
 //#region ========== PathProxy - Type-safe path builder for include ==========
 
 /**
- * Proxy type for specifying relationship paths in include() in a type-safe manner
- * Only non-ColumnPrimitive fields (FK, FKT relationships) are accessible
+ * include()에서 타입 안전하게 관계 경로를 지정하기 위한 Proxy 타입
+ * non-ColumnPrimitive 필드(FK, FKT 관계)만 접근 가능
  *
  * @example
  * ```typescript
- * // Accessing item.user.company internally collects path ["user", "company"]
+ * // item.user.company 접근 시 내부적으로 경로 ["user", "company"]를 수집
  * db.post.include(item => item.user.company)
  *
- * // item.title is string (ColumnPrimitive), so this is a compile error
- * db.post.include(item => item.title) // compile error
+ * // item.title은 string(ColumnPrimitive)이므로 컴파일 에러
+ * db.post.include(item => item.title) // 컴파일 에러
  * ```
  */
 /**
- * Extract element type if array
+ * 배열이면 요소 타입 추출
  */
 type UnwrapArray<TArray> = TArray extends (infer TElement)[] ? TElement : TArray;
 
 const PATH_SYMBOL = Symbol("path");
 
 /**
- * Type-safe path proxy for include()
+ * include()용 타입 안전 path proxy
  */
 export type PathProxy<TObject> = {
   [K in keyof TObject as TObject[K] extends ColumnPrimitive ? never : K]-?: PathProxy<
@@ -1946,8 +1946,8 @@ export type PathProxy<TObject> = {
 } & { readonly [PATH_SYMBOL]: string[] };
 
 /**
- * Generate PathProxy instance
- * Uses Proxy to intercept property access and collect paths
+ * PathProxy 인스턴스 생성
+ * Proxy를 사용하여 속성 접근을 가로채고 경로를 수집
  */
 function createPathProxy<TObject>(path: string[] = []): PathProxy<TObject> {
   return new Proxy({} as PathProxy<TObject>, {
@@ -1962,22 +1962,22 @@ function createPathProxy<TObject>(path: string[] = []): PathProxy<TObject> {
 //#endregion
 
 /**
- * Generate a Queryable factory function for a Table or View
+ * Table 또는 View용 Queryable factory 함수 생성
  *
- * Used when defining per-Table/View getters in DbContext
+ * DbContext에서 Table/View별 getter를 정의할 때 사용
  *
- * @param db - DbContext instance
- * @param tableOrView - TableBuilder or ViewBuilder instance
- * @param as - Alias specification (optional, auto-created if not specified)
- * @returns Factory function that returns a Queryable
+ * @param db - DbContext 인스턴스
+ * @param tableOrView - TableBuilder 또는 ViewBuilder 인스턴스
+ * @param as - Alias 지정 (선택, 미지정 시 자동 생성)
+ * @returns Queryable을 반환하는 factory 함수
  *
  * @example
  * ```typescript
  * class AppDbContext extends DbContext {
- *   // A new alias is assigned on each call
+ *   // 호출할 때마다 새 alias가 할당됨
  *   user = queryable(this, User);
  *
- *   // Usage example
+ *   // 사용 예시
  *   async getActiveUsers() {
  *     return this.user()
  *       .where((u) => [expr.eq(u.isActive, true)])
@@ -1992,8 +1992,8 @@ export function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<
   as?: string,
 ): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder<any, any> ? TBuilder : never> {
   return () => {
-    // If as is not specified, use db.getNextAlias() (counter increments)
-    // If as is specified, use it as-is (counter does not increment)
+    // as가 미지정이면 db.getNextAlias() 사용 (카운터 증가)
+    // as가 지정되면 그대로 사용 (카운터 증가 없음)
     const finalAs = as ?? db.getNextAlias();
 
     // TableBuilder + columns
@@ -2017,7 +2017,7 @@ export function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<
     if (tableOrView instanceof ViewBuilder && tableOrView.meta.viewFn != null) {
       const baseQr = tableOrView.meta.viewFn(db);
 
-      // Return with TFrom set to ViewBuilder
+      // TFrom을 ViewBuilder로 설정하여 반환
       return new Queryable({
         db,
         from: tableOrView,