@simplysm/orm-common 13.0.99 → 14.0.1

package/src/types/query-def.ts

@@ -4,12 +4,12 @@ import type { Expr, WhereExpr } from "./expr";
 //#region ========== Common ==========
 
 /**
- * DB object name (table, View, Procedure, etc.)
+ * DB 객체 이름 (table, View, Procedure 등)
  *
- * DBMS-specific namespaces:
- * - MySQL: `database.name` (schema ignored)
- * - MSSQL: `database.schema.name` (schema defaults to dbo)
- * - PostgreSQL: `schema.name` (database is for connection only)
+ * DBMS별 네임스페이스:
+ * - MySQL: `database.name` (schema 무시)
+ * - MSSQL: `database.schema.name` (schema 기본값 dbo)
+ * - PostgreSQL: `schema.name` (database는 연결용)
  */
 export interface QueryDefObjectName {
   database?: string;
@@ -22,9 +22,9 @@ export interface QueryDefObjectName {
 //#region ========== DML ==========
 
 /**
- * CUD query OUTPUT clause definition
+ * CUD query OUTPUT 절 정의
  *
- * Define return values after INSERT/UPDATE/DELETE
+ * INSERT/UPDATE/DELETE 후 반환값 정의
  */
 export interface CudOutputDef {
   columns: string[];
@@ -33,22 +33,22 @@ export interface CudOutputDef {
 }
 
 /**
- * SELECT Query definition
+ * SELECT query 정의
  *
- * @property type - Query type ("select")
- * @property from - FROM clause (table/Subquery)
+ * @property type - Query 타입 ("select")
+ * @property from - FROM 절 (table/subquery)
  * @property as - Table alias
- * @property select - SELECT clause column mapping
- * @property distinct - Whether DISTINCT
+ * @property select - SELECT 절 column 매핑
+ * @property distinct - DISTINCT 여부
  * @property top - TOP N (MSSQL)
- * @property lock - Whether to lock
- * @property where - WHERE condition array
- * @property joins - JOIN definition array
- * @property orderBy - ORDER BY [column, direction] array
+ * @property lock - 잠금 여부
+ * @property where - WHERE 조건 배열
+ * @property joins - JOIN 정의 배열
+ * @property orderBy - ORDER BY [column, direction] 배열
  * @property limit - LIMIT [offset, count]
- * @property groupBy - GROUP BY expression array
- * @property having - HAVING condition array
- * @property with - Recursive CTE definition
+ * @property groupBy - GROUP BY expression 배열
+ * @property having - HAVING 조건 배열
+ * @property with - 재귀 CTE 정의
  */
 export interface SelectQueryDef {
   type: "select";
@@ -68,21 +68,21 @@ export interface SelectQueryDef {
 }
 
 /**
- * JOIN Query definition
+ * JOIN query 정의
  *
- * SelectQueryDef extension + isSingle flag
+ * SelectQueryDef 확장 + isSingle 플래그
  */
 export interface SelectQueryDefJoin extends SelectQueryDef {
-  /** Whether single result (1:1 relation) */
+  /** 단일 결과 여부 (1:1 관계) */
   isSingle?: boolean;
 }
 
 /**
- * INSERT Query definition
+ * INSERT query 정의
  *
- * @property records - Record array to insert
- * @property overrideIdentity - Whether to enable IDENTITY_INSERT
- * @property output - OUTPUT clause definition
+ * @property records - 삽입할 레코드 배열
+ * @property overrideIdentity - IDENTITY_INSERT 활성화 여부
+ * @property output - OUTPUT 절 정의
  */
 export interface InsertQueryDef {
   type: "insert";
@@ -93,9 +93,9 @@ export interface InsertQueryDef {
 }
 
 /**
- * Conditional INSERT Query definition
+ * 조건부 INSERT query 정의
  *
- * Insert only if not exists
+ * 존재하지 않을 때만 삽입
  */
 export interface InsertIfNotExistsQueryDef {
   type: "insertIfNotExists";
@@ -107,9 +107,9 @@ export interface InsertIfNotExistsQueryDef {
 }
 
 /**
- * INSERT INTO SELECT Query definition
+ * INSERT INTO SELECT query 정의
  *
- * Insert subquery results
+ * Subquery 결과를 삽입
  */
 export interface InsertIntoQueryDef {
   type: "insertInto";
@@ -120,10 +120,10 @@ export interface InsertIntoQueryDef {
 }
 
 /**
- * UPDATE Query definition
+ * UPDATE query 정의
  *
- * @property record - Column/value mapping to update
- * @property joins - UPDATE JOIN (when supported)
+ * @property record - 갱신할 column/값 매핑
+ * @property joins - UPDATE JOIN (지원 시)
  */
 export interface UpdateQueryDef {
   type: "update";
@@ -138,7 +138,7 @@ export interface UpdateQueryDef {
 }
 
 /**
- * DELETE Query definition
+ * DELETE query 정의
  */
 export interface DeleteQueryDef {
   type: "delete";
@@ -152,9 +152,9 @@ export interface DeleteQueryDef {
 }
 
 /**
- * UPSERT Query definition
+ * UPSERT query 정의
  *
- * INSERT or UPDATE (MERGE Pattern)
+ * INSERT 또는 UPDATE (MERGE 패턴)
  */
 export interface UpsertQueryDef {
   type: "upsert";
@@ -170,7 +170,7 @@ export interface UpsertQueryDef {
 
 //#region ========== Utils ==========
 
-/** FK constraint enable/disable */
+/** FK 제약조건 활성화/비활성화 */
 export interface SwitchFkQueryDef {
   type: "switchFk";
   table: QueryDefObjectName;
@@ -181,7 +181,7 @@ export interface SwitchFkQueryDef {
 
 //#region ========== DDL - Schema ==========
 
-/** Clear schema (delete all objects) */
+/** Schema 초기화 (모든 객체 삭제) */
 export interface ClearSchemaQueryDef {
   type: "clearSchema";
   database: string;
@@ -249,7 +249,7 @@ export interface DropColumnQueryDef {
   column: string;
 }
 
-/** MODIFY COLUMN (type/property change) */
+/** MODIFY COLUMN (타입/속성 변경) */
 export interface ModifyColumnQueryDef {
   type: "modifyColumn";
   table: QueryDefObjectName;
@@ -376,7 +376,7 @@ export interface ExecProcQueryDef {
 
 //#region ========== Meta ==========
 
-/** Check schema existence */
+/** Schema 존재 여부 확인 */
 export interface SchemaExistsQueryDef {
   type: "schemaExists";
   database: string;
@@ -385,13 +385,13 @@ export interface SchemaExistsQueryDef {
 
 //#endregion
 
-//#region ========== DDL type constants ==========
+//#region ========== DDL 타입 상수 ==========
 
 /**
- * DDL QueryDef union (for compile-time validation)
+ * DDL QueryDef union (컴파일 타임 검증용)
  *
  * @remarks
- * switchFk is excluded because it is not DDL (can be used within transactions)
+ * switchFk는 DDL이 아니므로 제외 (트랜잭션 내에서 사용 가능)
  */
 type DdlQueryDef =
   | ClearSchemaQueryDef
@@ -415,13 +415,13 @@ type DdlQueryDef =
   | DropProcQueryDef;
 
 /**
- * DDL (Data Definition Language) type constants
+ * DDL (Data Definition Language) 타입 상수
  *
- * Used for blocking DDL within transactions and DDL type validation
- * Uses satisfies keyword for compile-time synchronization with DdlQueryDef
+ * 트랜잭션 내 DDL 차단 및 DDL 타입 검증에 사용
+ * DdlQueryDef와의 컴파일 타임 동기화를 위해 satisfies 키워드 사용
  *
  * @remarks
- * switchFk is excluded because it is not DDL (can be used within transactions)
+ * switchFk는 DDL이 아니므로 제외 (트랜잭션 내에서 사용 가능)
  */
 export const DDL_TYPES = [
   "clearSchema",
@@ -445,15 +445,15 @@ export const DDL_TYPES = [
   "dropProc",
 ] as const satisfies readonly DdlQueryDef["type"][];
 
-/** DDL type union */
+/** DDL 타입 union */
 export type DdlType = (typeof DDL_TYPES)[number];
 
 //#endregion
 
-//#region ========== Combined Union Type ==========
+//#region ========== 결합 Union 타입 ==========
 
 /**
- * All Query definition union type
+ * 전체 query 정의 union 타입
  *
  * DML (SELECT/INSERT/UPDATE/DELETE/UPSERT) +
  * DDL (Table/Column/PK/FK/Index/View/Procedure) +

package/src/utils/result-parser.ts

@@ -9,15 +9,15 @@ declare function setImmediate(callback: () => void): void;
 // ============================================
 
 /**
- * Parse value to specified type
+ * 값을 지정된 타입으로 파싱
  *
- * @param value - value to parse
- * @param type - target type (ColumnPrimitiveStr)
- * @returns parsed value
- * @throws Error if parsing fails
+ * @param value - 파싱할 값
+ * @param type - 대상 타입 (ColumnPrimitiveStr)
+ * @returns 파싱된 값
+ * @throws 파싱 실패 시 Error
  */
 function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
-  // null/undefined returned as-is (key removal handled by caller)
+  // null/undefined는 그대로 반환 (key 제거는 호출자가 처리)
   if (value == null) {
     return undefined;
   }
@@ -26,7 +26,7 @@ function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
     case "number": {
       const num = Number(value);
       if (Number.isNaN(num)) {
-        throw new Error(`Failed to parse number: ${String(value)}`);
+        throw new Error(`숫자 파싱 실패: ${String(value)}`);
       }
       return num;
     }
@@ -35,7 +35,7 @@ function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
       return String(value);
 
     case "boolean":
-      // Handle 0, 1, "0", "1", true, false, etc.
+      // 0, 1, "0", "1", true, false 등 처리
       if (value === 0 || value === "0" || value === false) return false;
       if (value === 1 || value === "1" || value === true) return true;
       return Boolean(value);
@@ -56,7 +56,7 @@ function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
     case "Bytes":
       if (value instanceof Uint8Array) return value;
       if (typeof value === "string") return bytes.fromHex(value);
-      throw new Error(`Failed to parse Bytes: ${typeof value}`);
+      throw new Error(`Bytes 파싱 실패: ${typeof value}`);
   }
 }
 
@@ -64,14 +64,14 @@ function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
 // Grouping Utilities
 // ============================================
 
-/** Precomputed column metadata for flatToNested */
+/** flatToNested용 사전 계산된 column 메타데이터 */
 interface ColumnInfo {
   key: string;
   type: ColumnPrimitiveStr;
-  parts: string[] | undefined; // undefined for simple keys, string[] for nested keys
+  parts: string[] | undefined; // 단순 key는 undefined, 중첩 key는 string[]
 }
 
-/** Precompute column info once per unique columns object */
+/** 고유한 columns 객체마다 column 정보를 한 번만 사전 계산 */
 function buildColumnInfos(columns: Record<string, ColumnPrimitiveStr>): ColumnInfo[] {
   return Object.entries(columns).map(([key, type]) => ({
     key,
@@ -81,7 +81,7 @@ function buildColumnInfos(columns: Record<string, ColumnPrimitiveStr>): ColumnIn
 }
 
 /**
- * Transform flat record to nested object
+ * 플랫 레코드를 중첩 객체로 변환
  *
  * @example
  * { "posts.id": 1, "posts.title": "Hi" } → { posts: { id: 1, title: "Hi" } }
@@ -96,11 +96,11 @@ function flatToNested(
     const rawValue = record[key];
     const parsedValue = parseValue(rawValue, type);
 
-    // undefined values are not added as keys
+    // undefined 값은 key로 추가하지 않음
     if (parsedValue === undefined) continue;
 
     if (parts != null) {
-      // Nested key: "posts.id" → { posts: { id: ... } }
+      // 중첩 key: "posts.id" → { posts: { id: ... } }
       let current = result;
       for (let i = 0; i < parts.length - 1; i++) {
         const part = parts[i];
@@ -111,7 +111,7 @@ function flatToNested(
       }
       current[parts[parts.length - 1]] = parsedValue;
     } else {
-      // Simple key
+      // 단순 key
       result[key] = parsedValue;
     }
   }
@@ -120,7 +120,7 @@ function flatToNested(
 }
 
 /**
- * Check if object is empty (all values are undefined)
+ * 객체가 비어있는지 확인 (모든 값이 undefined)
  */
 function isEmptyObject(record: Record<string, unknown>): boolean {
   return Object.keys(record).length === 0;
@@ -130,10 +130,10 @@ function isEmptyObject(record: Record<string, unknown>): boolean {
 // Main Function
 // ============================================
 
-/** Yield interval: yield to event loop every N records */
+/** 양보 간격: N개 레코드마다 이벤트 루프에 양보 */
 const YIELD_INTERVAL = 100;
 
-/** Event loop yield: setImmediate for Node.js, setTimeout fallback for browser */
+/** 이벤트 루프 양보: Node.js는 setImmediate, 브라우저는 setTimeout 폴백 */
 const yieldToEventLoop: () => Promise<void> =
   typeof setImmediate !== "undefined"
     ? () => new Promise<void>((resolve) => setImmediate(resolve))
@@ -195,7 +195,7 @@ export async function parseQueryResult<TRecord>(
 }
 
 /**
- * Parse simple records without JOINs
+ * JOIN이 없는 단순 레코드 파싱
  */
 async function parseSimpleRecords<TRecord>(
   rawResults: Record<string, unknown>[],
@@ -205,37 +205,37 @@ async function parseSimpleRecords<TRecord>(
   const results: Record<string, unknown>[] = [];
 
   for (let i = 0; i < rawResults.length; i++) {
-    // Yield to event loop
+    // 이벤트 루프에 양보
     if (i > 0 && i % YIELD_INTERVAL === 0) {
       await yieldToEventLoop();
     }
 
     const parsed = flatToNested(rawResults[i], columnInfos);
 
-    // Exclude empty objects
+    // 빈 객체 제외
     if (!isEmptyObject(parsed)) {
       results.push(parsed);
     }
   }
 
-  // Return undefined for empty arrays
+  // 빈 배열은 undefined 반환
   return results.length > 0 ? (results as TRecord[]) : undefined;
 }
 
 /**
- * Sort JOIN keys by depth (shallower ones first)
+ * JOIN key를 깊이순으로 정렬 (얕은 것 우선)
  * "posts" (1) < "posts.comments" (2)
  */
 function sortJoinKeysByDepth(joinKeys: string[]): string[] {
   return [...joinKeys].sort((a, b) => {
     const depthA = a.split(".").length;
     const depthB = b.split(".").length;
-    return depthA - depthB; // Shallower ones first
+    return depthA - depthB; // 얕은 것 우선
   });
 }
 
 /**
- * Parse records with JOINs (recursive grouping)
+ * JOIN이 있는 레코드 파싱 (재귀 그룹핑)
  */
 async function parseJoinedRecords<TRecord>(
   rawResults: Record<string, unknown>[],
@@ -264,9 +264,9 @@ async function parseJoinedRecords<TRecord>(
 }
 
 /**
- * Serialize group key to string (used as Map key)
+ * 그룹 key를 문자열로 직렬화 (Map key로 사용)
  *
- * Custom serialization faster than JSON.stringify
+ * JSON.stringify보다 빠른 커스텀 직렬화
  */
 function serializeGroupKey(groupKey: Record<string, unknown>, cachedKeyOrder?: string[]): string {
   const keys = cachedKeyOrder ?? Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
@@ -411,13 +411,13 @@ function groupRecordsRecursively(
 }
 
 /**
- * Build a Set of keys that should be excluded from group key (join keys and their prefixes)
+ * 그룹 key에서 제외할 key의 Set 구성 (join key와 그 접두사)
  */
 function buildJoinKeyExclusionSet(joinKeys: string[]): Set<string> {
   const exclusions = new Set<string>();
   for (const jk of joinKeys) {
     exclusions.add(jk);
-    // Also exclude parent paths (e.g., "posts" for join key "posts.comments")
+    // 상위 경로도 제외 (예: join key "posts.comments"에 대해 "posts")
     const parts = jk.split(".");
     for (let i = 1; i < parts.length; i++) {
       exclusions.add(parts.slice(0, i).join("."));
@@ -427,7 +427,7 @@ function buildJoinKeyExclusionSet(joinKeys: string[]): Set<string> {
 }
 
 /**
- * Extract group key from record excluding JOIN keys
+ * JOIN key를 제외하고 레코드에서 그룹 key 추출
  */
 function extractGroupKey(
   record: Record<string, unknown>,
@@ -435,9 +435,9 @@ function extractGroupKey(
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(record)) {
-    // Only include non-JOIN keys
+    // JOIN이 아닌 key만 포함
     if (!joinKeyExclusions.has(key)) {
-      // Only use primitive values (not object/array) as group key
+      // 프리미티브 값만 그룹 key로 사용 (객체/배열 제외)
       if (value == null || typeof value !== "object") {
         result[key] = value;
       }
@@ -447,7 +447,7 @@ function extractGroupKey(
 }
 
 /**
- * Merge JOIN data to existing group
+ * 기존 그룹에 JOIN 데이터 병합
  */
 function mergeJoinData(
   existingGroup: Record<string, unknown>,
@@ -458,7 +458,7 @@ function mergeJoinData(
   const newJoinData = newRecord[localKey] as Record<string, unknown> | undefined;
 
   if (newJoinData == null || isEmptyObject(newJoinData)) {
-    return; // No data to merge
+    return; // 병합할 데이터 없음
   }
 
   const existingJoinData = existingGroup[localKey];
@@ -467,7 +467,7 @@ function mergeJoinData(
     // isSingle: true - error if data exists and values differ
     if (existingJoinData != null) {
       if (!obj.equal(existingJoinData as Record<string, unknown>, newJoinData)) {
-        throw new Error(`isSingle relationship '${localKey}' has multiple different results.`);
+        throw new Error(`isSingle 관계 '${localKey}'에 여러 개의 다른 결과가 있습니다.`);
       }
     } else {
       existingGroup[localKey] = newJoinData;
@@ -477,10 +477,10 @@ function mergeJoinData(
     const hashSetKey = `__hashSet__${localKey}`;
     if (!Array.isArray(existingJoinData)) {
       existingGroup[localKey] = [newJoinData];
-      // Initialize internal property for Set-based duplicate checking
+      // Set 기반 중복 검사용 내부 속성 초기화
       existingGroup[hashSetKey] = new Set([serializeGroupKey(newJoinData)]);
     } else {
-      // Set-based duplicate checking (O(1))
+      // Set 기반 중복 검사 (O(1))
       const hashSet = existingGroup[hashSetKey] as Set<string> | undefined;
       const newHash = serializeGroupKey(newJoinData);
       if (hashSet != null) {
@@ -489,7 +489,7 @@ function mergeJoinData(
           existingJoinData.push(newJoinData);
         }
       } else {
-        // Fallback without hashSet (legacy approach)
+        // hashSet 없는 폴백 (레거시 방식)
         const isDuplicate = existingJoinData.some((item) =>
           obj.equal(item as Record<string, unknown>, newJoinData),
         );