@simplysm/orm-common 13.0.100 → 14.0.4

package/src/utils/result-parser.ts

@@ -5,19 +5,19 @@ import type { ResultMeta } from "../types/db";
 declare function setImmediate(callback: () => void): void;
 
 // ============================================
-// Type Parsers
+// 타입 파서
 // ============================================
 
 /**
- * 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,22 +56,22 @@ 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}`);
   }
 }
 
 // ============================================
-// 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,48 +120,48 @@ 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;
 }
 
 // ============================================
-// 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))
     : () => 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,24 +178,24 @@ 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);
 }
 
 /**
- * Parse simple records without JOINs
+ * JOIN이 없는 단순 레코드 파싱
  */
 async function parseSimpleRecords<TRecord>(
   rawResults: Record<string, unknown>[],
@@ -205,43 +205,43 @@ 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>[],
   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,22 +251,22 @@ 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;
 }
 
 /**
- * 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));
@@ -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__")) {
@@ -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,29 +458,29 @@ 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];
 
   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 relationship '${localKey}' has multiple different results.`);
+        throw new Error(`isSingle 관계 '${localKey}'에 여러 개의 다른 결과가 있습니다.`);
       }
     } else {
       existingGroup[localKey] = newJoinData;
     }
   } else {
-    // isSingle: false → Add to array
+    // isSingle: false → 배열에 추가
     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),
         );

package/docs/utilities.md

@@ -1,27 +0,0 @@
-# Utilities
-
-## `parseQueryResult`
-
-Transform raw DB query results to typed TypeScript objects via `ResultMeta`. Handles type parsing, nested object construction from flat JOIN results, and deduplication.
-
-```typescript
-async function parseQueryResult<TRecord>(
-  rawResults: Record<string, unknown>[],
-  meta: ResultMeta,
-): Promise<TRecord[] | undefined>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `rawResults` | `Record<string, unknown>[]` | Raw result array from database |
-| `meta` | `ResultMeta` | Type transformation and JOIN structure information |
-
-**Returns:** Type-transformed and nested result array. Returns `undefined` if input is empty or no valid results.
-
-### Behavior
-
-- **Type parsing**: Converts raw values to TypeScript types based on `meta.columns` mapping (e.g., string to `DateTime`, number to boolean).
-- **JOIN nesting**: Converts flat `"posts.id"` keys into nested `{ posts: { id: ... } }` structures.
-- **Deduplication**: Groups records by non-JOIN columns and collects JOIN data into arrays (or single objects for `isSingle: true`).
-- **Async**: Yields to the event loop every 100 records to prevent blocking.
-- **Empty handling**: Returns `undefined` for empty input or all-empty parsed records.