@simplysm/orm-common 14.0.1 → 14.0.4

package/src/utils/result-parser.ts

@@ -5,7 +5,7 @@ import type { ResultMeta } from "../types/db";
 declare function setImmediate(callback: () => void): void;
 
 // ============================================
-// Type Parsers
+// 타입 파서
 // ============================================
 
 /**
@@ -61,7 +61,7 @@ function parseValue(value: unknown, type: ColumnPrimitiveStr): unknown {
 }
 
 // ============================================
-// Grouping Utilities
+// 그룹핑 유틸리티
 // ============================================
 
 /** flatToNested용 사전 계산된 column 메타데이터 */
@@ -127,7 +127,7 @@ function isEmptyObject(record: Record<string, unknown>): boolean {
 }
 
 // ============================================
-// Main Function
+// 메인 함수
 // ============================================
 
 /** 양보 간격: N개 레코드마다 이벤트 루프에 양보 */
@@ -140,28 +140,28 @@ const yieldToEventLoop: () => Promise<void> =
     : () => new Promise<void>((resolve) => setTimeout(resolve, 0));
 
 /**
- * Transform DB query result to TypeScript object via ResultMeta
+ * ResultMeta를 통해 DB 쿼리 결과를 TypeScript 객체로 변환
  *
- * @param rawResults - Raw result array from database
- * @param meta - Type transformation and JOIN structure information (required)
- * @returns Type-transformed and nested result array. Returns undefined if input is empty or no valid results
- * @throws Error if type parsing fails
+ * @param rawResults - 데이터베이스에서 반환된 원시 결과 배열
+ * @param meta - 타입 변환 및 JOIN 구조 정보 (필수)
+ * @returns 타입 변환 및 중첩된 결과 배열. 입력이 비어있거나 유효한 결과가 없으면 undefined 반환
+ * @throws 타입 파싱 실패 시 Error
  *
  * @remarks
- * - meta required: no need to call this function without meta (input = output)
- * - async only: no synchronous version provided for large-scale processing to allow external interrupts
- * - browser/node compatible: yields via setTimeout(resolve, 0)
- * - empty result handling: returns undefined if input array is empty or all records are empty objects after parsing
+ * - meta 필수: meta 없이는 이 함수를 호출할 필요 없음 (입력 = 출력)
+ * - async 전용: 대규모 처리 시 외부 인터럽트 허용을 위해 동기 버전 미제공
+ * - 브라우저/Node 호환: setTimeout(resolve, 0)으로 양보
+ * - 빈 결과 처리: 입력 배열이 비어있거나 파싱 후 모든 레코드가 빈 객체이면 undefined 반환
  *
  * @example
  * ```typescript
- * // 1. Simple type parsing
+ * // 1. 단순 타입 파싱
  * const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
  * const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
  * const result = await parseQueryResult(raw, meta);
  * // [{ id: 1, createdAt: DateTime(...) }]
  *
- * // 2. JOIN result nesting
+ * // 2. JOIN 결과 중첩
  * const raw = [
  *   { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
  *   { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
@@ -178,19 +178,19 @@ export async function parseQueryResult<TRecord>(
   rawResults: Record<string, unknown>[],
   meta: ResultMeta,
 ): Promise<TRecord[] | undefined> {
-  // Handle empty input
+  // 빈 입력 처리
   if (rawResults.length === 0) {
     return undefined;
   }
 
   const joinKeys = Object.keys(meta.joins);
 
-  // No JOINs: simple type parsing only
+  // JOIN 없음: 단순 타입 파싱만 수행
   if (joinKeys.length === 0) {
     return parseSimpleRecords<TRecord>(rawResults, meta.columns);
   }
 
-  // With JOINs: grouping + nesting
+  // JOIN 있음: 그룹핑 + 중첩
   return parseJoinedRecords<TRecord>(rawResults, meta);
 }
 
@@ -241,7 +241,7 @@ async function parseJoinedRecords<TRecord>(
   rawResults: Record<string, unknown>[],
   meta: ResultMeta,
 ): Promise<TRecord[] | undefined> {
-  // 1. Transform all records to nested structure
+  // 1. 모든 레코드를 중첩 구조로 변환
   const columnInfos = buildColumnInfos(meta.columns);
   const nestedRecords: Record<string, unknown>[] = [];
   for (let i = 0; i < rawResults.length; i++) {
@@ -251,13 +251,13 @@ async function parseJoinedRecords<TRecord>(
     nestedRecords.push(flatToNested(rawResults[i], columnInfos));
   }
 
-  // 2. Sort JOIN keys by depth (shallower ones first)
+  // 2. JOIN key를 깊이순으로 정렬 (얕은 것 우선)
   const sortedJoinKeys = sortJoinKeysByDepth(Object.keys(meta.joins));
 
-  // 3. Recursively group from root level
+  // 3. 루트 레벨부터 재귀적으로 그룹핑
   const results = groupRecordsRecursively(nestedRecords, sortedJoinKeys, meta.joins, "");
 
-  // 4. Filter empty results
+  // 4. 빈 결과 필터링
   const filteredResults = results.filter((r) => !isEmptyObject(r));
 
   return filteredResults.length > 0 ? (filteredResults as TRecord[]) : undefined;
@@ -282,14 +282,14 @@ function serializeGroupKey(groupKey: Record<string, unknown>, cachedKeyOrder?: s
 }
 
 /**
- * Recursively group records for current path
+ * 현재 경로에 대해 레코드를 재귀적으로 그룹핑
  *
- * Achieves O(n) complexity with Map-based grouping
+ * Map 기반 그룹핑으로 O(n) 복잡도 달성
  *
- * @param records - Record array to group
- * @param allJoinKeys - All JOIN keys (sorted by depth)
- * @param joinsConfig - JOIN configuration
- * @param currentPath - Current path (e.g., "", "posts", "posts.comments")
+ * @param records - 그룹핑할 레코드 배열
+ * @param allJoinKeys - 모든 JOIN key (깊이순 정렬)
+ * @param joinsConfig - JOIN 설정
+ * @param currentPath - 현재 경로 (예: "", "posts", "posts.comments")
  */
 function groupRecordsRecursively(
   records: Record<string, unknown>[],
@@ -297,15 +297,15 @@ function groupRecordsRecursively(
   joinsConfig: Record<string, { isSingle: boolean }>,
   currentPath: string,
 ): Record<string, unknown>[] {
-  // Find JOIN keys directly corresponding to current path
-  // e.g., currentPath="" → ["posts", "company"]
-  // e.g., currentPath="posts" → ["posts.comments"]
+  // 현재 경로에 직접 대응하는 JOIN key 찾기
+  // 예: currentPath="" → ["posts", "company"]
+  // 예: currentPath="posts" → ["posts.comments"]
   const childJoinKeys = allJoinKeys.filter((key) => {
     if (currentPath === "") {
-      // Root level: keys without dots
+      // 루트 레벨: 점이 없는 key
       return !key.includes(".");
     } else {
-      // Sublevel: current path + "." + key
+      // 하위 레벨: 현재 경로 + "." + key
       return (
         key.startsWith(currentPath + ".") && key.slice(currentPath.length + 1).indexOf(".") === -1
       );
@@ -313,21 +313,21 @@ function groupRecordsRecursively(
   });
 
   if (childJoinKeys.length === 0) {
-    // No more JOINs to group
+    // 더 이상 그룹핑할 JOIN 없음
     return records;
   }
 
-  // Map-based grouping (O(n) complexity)
+  // Map 기반 그룹핑 (O(n) 복잡도)
   const groupMap = new Map<string, Record<string, unknown>>();
 
-  // Precompute join key exclusion set for O(1) lookup
+  // O(1) 조회를 위한 JOIN key 제외 집합 사전 계산
   const joinKeyExclusions = buildJoinKeyExclusionSet(childJoinKeys);
 
-  // Key order caching (determined from first record and reused)
+  // Key 순서 캐싱 (첫 번째 레코드에서 결정 후 재사용)
   let groupKeyOrder: string[] | undefined;
 
   for (const record of records) {
-    // Extract and serialize group key (excluding JOIN keys)
+    // 그룹 key 추출 및 직렬화 (JOIN key 제외)
     const groupKey = extractGroupKey(record, joinKeyExclusions);
     if (groupKeyOrder == null) {
       groupKeyOrder = Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
@@ -337,27 +337,27 @@ function groupRecordsRecursively(
     const existingGroup = groupMap.get(keyStr);
 
     if (existingGroup != null) {
-      // Merge JOIN data to existing group
+      // 기존 그룹에 JOIN 데이터 병합
       for (const joinKey of childJoinKeys) {
         const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
         mergeJoinData(existingGroup, record, localKey, joinsConfig[joinKey].isSingle);
       }
     } else {
-      // Generate new group
+      // 새 그룹 생성
       const newGroup = { ...record };
 
-      // Initialize each JOIN key as array or single object
+      // 각 JOIN key를 배열 또는 단일 객체로 초기화
       for (const joinKey of childJoinKeys) {
         const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
         const joinData = newGroup[localKey] as Record<string, unknown> | undefined;
 
         if (joinData != null && !isEmptyObject(joinData)) {
           if (!joinsConfig[joinKey].isSingle) {
-            // Transform to array
+            // 배열로 변환
             newGroup[localKey] = [joinData];
           }
         } else {
-          // Delete key if data is empty
+          // 데이터가 비어있으면 key 삭제
           delete newGroup[localKey];
         }
       }
@@ -366,17 +366,17 @@ function groupRecordsRecursively(
     }
   }
 
-  // Transform Map to array
+  // Map을 배열로 변환
   const grouped = Array.from(groupMap.values());
 
-  // Recursively process sublevel of each JOIN
+  // 각 JOIN의 하위 레벨을 재귀적으로 처리
   for (const group of grouped) {
     for (const joinKey of childJoinKeys) {
       const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
       const joinData = group[localKey];
 
       if (Array.isArray(joinData) && joinData.length > 0) {
-        // Array case: process sublevel recursively
+        // 배열인 경우: 하위 레벨을 재귀적으로 처리
         group[localKey] = groupRecordsRecursively(
           joinData as Record<string, unknown>[],
           allJoinKeys,
@@ -384,7 +384,7 @@ function groupRecordsRecursively(
           joinKey,
         );
       } else if (joinData != null && typeof joinData === "object" && !Array.isArray(joinData)) {
-        // Single object case (isSingle: true)
+        // 단일 객체인 경우 (isSingle: true)
         const processed = groupRecordsRecursively(
           [joinData as Record<string, unknown>],
           allJoinKeys,
@@ -398,7 +398,7 @@ function groupRecordsRecursively(
     }
   }
 
-  // Remove __hashSet__ internal property (temporary property for duplicate checking)
+  // __hashSet__ 내부 속성 제거 (중복 검사용 임시 속성)
   for (const group of grouped) {
     for (const key of Object.keys(group)) {
       if (key.startsWith("__hashSet__")) {
@@ -464,7 +464,7 @@ function mergeJoinData(
   const existingJoinData = existingGroup[localKey];
 
   if (isSingle) {
-    // isSingle: true - error if data exists and values differ
+    // isSingle: true - 데이터가 존재하고 값이 다르면 에러
     if (existingJoinData != null) {
       if (!obj.equal(existingJoinData as Record<string, unknown>, newJoinData)) {
         throw new Error(`isSingle 관계 '${localKey}'에 여러 개의 다른 결과가 있습니다.`);
@@ -473,7 +473,7 @@ function mergeJoinData(
       existingGroup[localKey] = newJoinData;
     }
   } else {
-    // isSingle: false → Add to array
+    // isSingle: false → 배열에 추가
     const hashSetKey = `__hashSet__${localKey}`;
     if (!Array.isArray(existingJoinData)) {
       existingGroup[localKey] = [newJoinData];