@simplysm/orm-common 13.0.99 → 14.0.1

package/dist/utils/result-parser.js

@@ -1,265 +1,406 @@
 import { bytes, obj, DateOnly, DateTime, Time, Uuid } from "@simplysm/core-common";
+// ============================================
+// Type Parsers
+// ============================================
+/**
+ * 값을 지정된 타입으로 파싱
+ *
+ * @param value - 파싱할 값
+ * @param type - 대상 타입 (ColumnPrimitiveStr)
+ * @returns 파싱된 값
+ * @throws 파싱 실패 시 Error
+ */
 function parseValue(value, type) {
-  if (value == null) {
-    return void 0;
-  }
-  switch (type) {
-    case "number": {
-      const num = Number(value);
-      if (Number.isNaN(num)) {
-        throw new Error(`Failed to parse number: ${String(value)}`);
-      }
-      return num;
+    // null/undefined는 그대로 반환 (key 제거는 호출자가 처리)
+    if (value == null) {
+        return undefined;
+    }
+    switch (type) {
+        case "number": {
+            const num = Number(value);
+            if (Number.isNaN(num)) {
+                throw new Error(`숫자 파싱 실패: ${String(value)}`);
+            }
+            return num;
+        }
+        case "string":
+            return String(value);
+        case "boolean":
+            // 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);
+        case "DateTime":
+            return DateTime.parse(value);
+        case "DateOnly":
+            return DateOnly.parse(value);
+        case "Time":
+            return Time.parse(value);
+        case "Uuid":
+            if (value instanceof Uint8Array)
+                return Uuid.fromBytes(value);
+            return new Uuid(value);
+        case "Bytes":
+            if (value instanceof Uint8Array)
+                return value;
+            if (typeof value === "string")
+                return bytes.fromHex(value);
+            throw new Error(`Bytes 파싱 실패: ${typeof value}`);
     }
-    case "string":
-      return String(value);
-    case "boolean":
-      if (value === 0 || value === "0" || value === false) return false;
-      if (value === 1 || value === "1" || value === true) return true;
-      return Boolean(value);
-    case "DateTime":
-      return DateTime.parse(value);
-    case "DateOnly":
-      return DateOnly.parse(value);
-    case "Time":
-      return Time.parse(value);
-    case "Uuid":
-      if (value instanceof Uint8Array) return Uuid.fromBytes(value);
-      return new Uuid(value);
-    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}`);
-  }
 }
+/** 고유한 columns 객체마다 column 정보를 한 번만 사전 계산 */
 function buildColumnInfos(columns) {
-  return Object.entries(columns).map(([key, type]) => ({
-    key,
-    type,
-    parts: key.includes(".") ? key.split(".") : void 0
-  }));
+    return Object.entries(columns).map(([key, type]) => ({
+        key,
+        type,
+        parts: key.includes(".") ? key.split(".") : undefined,
+    }));
 }
+/**
+ * 플랫 레코드를 중첩 객체로 변환
+ *
+ * @example
+ * { "posts.id": 1, "posts.title": "Hi" } → { posts: { id: 1, title: "Hi" } }
+ */
 function flatToNested(record, columnInfos) {
-  const result = {};
-  for (const { key, type, parts } of columnInfos) {
-    const rawValue = record[key];
-    const parsedValue = parseValue(rawValue, type);
-    if (parsedValue === void 0) continue;
-    if (parts != null) {
-      let current = result;
-      for (let i = 0; i < parts.length - 1; i++) {
-        const part = parts[i];
-        if (current[part] == null) {
-          current[part] = {};
+    const result = {};
+    for (const { key, type, parts } of columnInfos) {
+        const rawValue = record[key];
+        const parsedValue = parseValue(rawValue, type);
+        // undefined 값은 key로 추가하지 않음
+        if (parsedValue === undefined)
+            continue;
+        if (parts != null) {
+            // 중첩 key: "posts.id" → { posts: { id: ... } }
+            let current = result;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const part = parts[i];
+                if (current[part] == null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+            current[parts[parts.length - 1]] = parsedValue;
+        }
+        else {
+            // 단순 key
+            result[key] = parsedValue;
         }
-        current = current[part];
-      }
-      current[parts[parts.length - 1]] = parsedValue;
-    } else {
-      result[key] = parsedValue;
     }
-  }
-  return result;
+    return result;
 }
+/**
+ * 객체가 비어있는지 확인 (모든 값이 undefined)
+ */
 function isEmptyObject(record) {
-  return Object.keys(record).length === 0;
+    return Object.keys(record).length === 0;
 }
+// ============================================
+// Main Function
+// ============================================
+/** 양보 간격: N개 레코드마다 이벤트 루프에 양보 */
 const YIELD_INTERVAL = 100;
-const yieldToEventLoop = typeof setImmediate !== "undefined" ? () => new Promise((resolve) => setImmediate(resolve)) : () => new Promise((resolve) => setTimeout(resolve, 0));
-async function parseQueryResult(rawResults, meta) {
-  if (rawResults.length === 0) {
-    return void 0;
-  }
-  const joinKeys = Object.keys(meta.joins);
-  if (joinKeys.length === 0) {
-    return parseSimpleRecords(rawResults, meta.columns);
-  }
-  return parseJoinedRecords(rawResults, meta);
+/** 이벤트 루프 양보: Node.js는 setImmediate, 브라우저는 setTimeout 폴백 */
+const yieldToEventLoop = typeof setImmediate !== "undefined"
+    ? () => new Promise((resolve) => setImmediate(resolve))
+    : () => new Promise((resolve) => setTimeout(resolve, 0));
+/**
+ * Transform DB query result to TypeScript object via ResultMeta
+ *
+ * @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
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * // 1. Simple type parsing
+ * 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
+ * const raw = [
+ *   { id: 1, name: "User1", "posts.id": 10, "posts.title": "Post1" },
+ *   { id: 1, name: "User1", "posts.id": 11, "posts.title": "Post2" },
+ * ];
+ * const meta = {
+ *   columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
+ *   joins: { posts: { isSingle: false } }
+ * };
+ * const result = await parseQueryResult(raw, meta);
+ * // [{ id: 1, name: "User1", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
+ * ```
+ */
+export async function parseQueryResult(rawResults, meta) {
+    // Handle empty input
+    if (rawResults.length === 0) {
+        return undefined;
+    }
+    const joinKeys = Object.keys(meta.joins);
+    // No JOINs: simple type parsing only
+    if (joinKeys.length === 0) {
+        return parseSimpleRecords(rawResults, meta.columns);
+    }
+    // With JOINs: grouping + nesting
+    return parseJoinedRecords(rawResults, meta);
 }
+/**
+ * JOIN이 없는 단순 레코드 파싱
+ */
 async function parseSimpleRecords(rawResults, columns) {
-  const columnInfos = buildColumnInfos(columns);
-  const results = [];
-  for (let i = 0; i < rawResults.length; i++) {
-    if (i > 0 && i % YIELD_INTERVAL === 0) {
-      await yieldToEventLoop();
-    }
-    const parsed = flatToNested(rawResults[i], columnInfos);
-    if (!isEmptyObject(parsed)) {
-      results.push(parsed);
+    const columnInfos = buildColumnInfos(columns);
+    const results = [];
+    for (let i = 0; i < rawResults.length; i++) {
+        // 이벤트 루프에 양보
+        if (i > 0 && i % YIELD_INTERVAL === 0) {
+            await yieldToEventLoop();
+        }
+        const parsed = flatToNested(rawResults[i], columnInfos);
+        // 빈 객체 제외
+        if (!isEmptyObject(parsed)) {
+            results.push(parsed);
+        }
     }
-  }
-  return results.length > 0 ? results : void 0;
+    // 빈 배열은 undefined 반환
+    return results.length > 0 ? results : undefined;
 }
+/**
+ * JOIN key를 깊이순으로 정렬 (얕은 것 우선)
+ * "posts" (1) < "posts.comments" (2)
+ */
 function sortJoinKeysByDepth(joinKeys) {
-  return [...joinKeys].sort((a, b) => {
-    const depthA = a.split(".").length;
-    const depthB = b.split(".").length;
-    return depthA - depthB;
-  });
+    return [...joinKeys].sort((a, b) => {
+        const depthA = a.split(".").length;
+        const depthB = b.split(".").length;
+        return depthA - depthB; // 얕은 것 우선
+    });
 }
+/**
+ * JOIN이 있는 레코드 파싱 (재귀 그룹핑)
+ */
 async function parseJoinedRecords(rawResults, meta) {
-  const columnInfos = buildColumnInfos(meta.columns);
-  const nestedRecords = [];
-  for (let i = 0; i < rawResults.length; i++) {
-    if (i > 0 && i % YIELD_INTERVAL === 0) {
-      await yieldToEventLoop();
+    // 1. Transform all records to nested structure
+    const columnInfos = buildColumnInfos(meta.columns);
+    const nestedRecords = [];
+    for (let i = 0; i < rawResults.length; i++) {
+        if (i > 0 && i % YIELD_INTERVAL === 0) {
+            await yieldToEventLoop();
+        }
+        nestedRecords.push(flatToNested(rawResults[i], columnInfos));
     }
-    nestedRecords.push(flatToNested(rawResults[i], columnInfos));
-  }
-  const sortedJoinKeys = sortJoinKeysByDepth(Object.keys(meta.joins));
-  const results = groupRecordsRecursively(nestedRecords, sortedJoinKeys, meta.joins, "");
-  const filteredResults = results.filter((r) => !isEmptyObject(r));
-  return filteredResults.length > 0 ? filteredResults : void 0;
+    // 2. Sort JOIN keys by depth (shallower ones first)
+    const sortedJoinKeys = sortJoinKeysByDepth(Object.keys(meta.joins));
+    // 3. Recursively group from root level
+    const results = groupRecordsRecursively(nestedRecords, sortedJoinKeys, meta.joins, "");
+    // 4. Filter empty results
+    const filteredResults = results.filter((r) => !isEmptyObject(r));
+    return filteredResults.length > 0 ? filteredResults : undefined;
 }
+/**
+ * 그룹 key를 문자열로 직렬화 (Map key로 사용)
+ *
+ * JSON.stringify보다 빠른 커스텀 직렬화
+ */
 function serializeGroupKey(groupKey, cachedKeyOrder) {
-  const keys = cachedKeyOrder ?? Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
-  let result = "";
-  for (let i = 0; i < keys.length; i++) {
-    if (i > 0) result += "|";
-    const v = groupKey[keys[i]];
-    result += keys[i];
-    result += ":";
-    result += v === null ? "null" : String(v);
-  }
-  return result;
+    const keys = cachedKeyOrder ?? Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
+    let result = "";
+    for (let i = 0; i < keys.length; i++) {
+        if (i > 0)
+            result += "|";
+        const v = groupKey[keys[i]];
+        result += keys[i];
+        result += ":";
+        result += v === null ? "null" : String(v);
+    }
+    return result;
 }
+/**
+ * Recursively group records for current path
+ *
+ * Achieves O(n) complexity with Map-based grouping
+ *
+ * @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")
+ */
 function groupRecordsRecursively(records, allJoinKeys, joinsConfig, currentPath) {
-  const childJoinKeys = allJoinKeys.filter((key) => {
-    if (currentPath === "") {
-      return !key.includes(".");
-    } else {
-      return key.startsWith(currentPath + ".") && key.slice(currentPath.length + 1).indexOf(".") === -1;
-    }
-  });
-  if (childJoinKeys.length === 0) {
-    return records;
-  }
-  const groupMap = /* @__PURE__ */ new Map();
-  const joinKeyExclusions = buildJoinKeyExclusionSet(childJoinKeys);
-  let groupKeyOrder;
-  for (const record of records) {
-    const groupKey = extractGroupKey(record, joinKeyExclusions);
-    if (groupKeyOrder == null) {
-      groupKeyOrder = Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
+    // Find JOIN keys directly corresponding to current path
+    // e.g., currentPath="" → ["posts", "company"]
+    // e.g., currentPath="posts" → ["posts.comments"]
+    const childJoinKeys = allJoinKeys.filter((key) => {
+        if (currentPath === "") {
+            // Root level: keys without dots
+            return !key.includes(".");
+        }
+        else {
+            // Sublevel: current path + "." + key
+            return (key.startsWith(currentPath + ".") && key.slice(currentPath.length + 1).indexOf(".") === -1);
+        }
+    });
+    if (childJoinKeys.length === 0) {
+        // No more JOINs to group
+        return records;
     }
-    const keyStr = serializeGroupKey(groupKey, groupKeyOrder);
-    const existingGroup = groupMap.get(keyStr);
-    if (existingGroup != null) {
-      for (const joinKey of childJoinKeys) {
-        const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
-        mergeJoinData(existingGroup, record, localKey, joinsConfig[joinKey].isSingle);
-      }
-    } else {
-      const newGroup = { ...record };
-      for (const joinKey of childJoinKeys) {
-        const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
-        const joinData = newGroup[localKey];
-        if (joinData != null && !isEmptyObject(joinData)) {
-          if (!joinsConfig[joinKey].isSingle) {
-            newGroup[localKey] = [joinData];
-          }
-        } else {
-          delete newGroup[localKey];
+    // Map-based grouping (O(n) complexity)
+    const groupMap = new Map();
+    // Precompute join key exclusion set for O(1) lookup
+    const joinKeyExclusions = buildJoinKeyExclusionSet(childJoinKeys);
+    // Key order caching (determined from first record and reused)
+    let groupKeyOrder;
+    for (const record of records) {
+        // Extract and serialize group key (excluding JOIN keys)
+        const groupKey = extractGroupKey(record, joinKeyExclusions);
+        if (groupKeyOrder == null) {
+            groupKeyOrder = Object.keys(groupKey).sort((a, b) => a.localeCompare(b));
+        }
+        const keyStr = serializeGroupKey(groupKey, groupKeyOrder);
+        const existingGroup = groupMap.get(keyStr);
+        if (existingGroup != null) {
+            // Merge JOIN data to existing group
+            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
+            for (const joinKey of childJoinKeys) {
+                const localKey = currentPath === "" ? joinKey : joinKey.slice(currentPath.length + 1);
+                const joinData = newGroup[localKey];
+                if (joinData != null && !isEmptyObject(joinData)) {
+                    if (!joinsConfig[joinKey].isSingle) {
+                        // Transform to array
+                        newGroup[localKey] = [joinData];
+                    }
+                }
+                else {
+                    // Delete key if data is empty
+                    delete newGroup[localKey];
+                }
+            }
+            groupMap.set(keyStr, newGroup);
         }
-      }
-      groupMap.set(keyStr, newGroup);
     }
-  }
-  const grouped = Array.from(groupMap.values());
-  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) {
-        group[localKey] = groupRecordsRecursively(
-          joinData,
-          allJoinKeys,
-          joinsConfig,
-          joinKey
-        );
-      } else if (joinData != null && typeof joinData === "object" && !Array.isArray(joinData)) {
-        const processed = groupRecordsRecursively(
-          [joinData],
-          allJoinKeys,
-          joinsConfig,
-          joinKey
-        );
-        if (processed.length > 0) {
-          group[localKey] = processed[0];
+    // Transform Map to array
+    const grouped = Array.from(groupMap.values());
+    // Recursively process sublevel of each 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, allJoinKeys, joinsConfig, joinKey);
+            }
+            else if (joinData != null && typeof joinData === "object" && !Array.isArray(joinData)) {
+                // Single object case (isSingle: true)
+                const processed = groupRecordsRecursively([joinData], allJoinKeys, joinsConfig, joinKey);
+                if (processed.length > 0) {
+                    group[localKey] = processed[0];
+                }
+            }
         }
-      }
     }
-  }
-  for (const group of grouped) {
-    for (const key of Object.keys(group)) {
-      if (key.startsWith("__hashSet__")) {
-        delete group[key];
-      }
+    // Remove __hashSet__ internal property (temporary property for duplicate checking)
+    for (const group of grouped) {
+        for (const key of Object.keys(group)) {
+            if (key.startsWith("__hashSet__")) {
+                delete group[key];
+            }
+        }
     }
-  }
-  return grouped;
+    return grouped;
 }
+/**
+ * 그룹 key에서 제외할 key의 Set 구성 (join key와 그 접두사)
+ */
 function buildJoinKeyExclusionSet(joinKeys) {
-  const exclusions = /* @__PURE__ */ new Set();
-  for (const jk of joinKeys) {
-    exclusions.add(jk);
-    const parts = jk.split(".");
-    for (let i = 1; i < parts.length; i++) {
-      exclusions.add(parts.slice(0, i).join("."));
+    const exclusions = new Set();
+    for (const jk of joinKeys) {
+        exclusions.add(jk);
+        // 상위 경로도 제외 (예: join key "posts.comments"에 대해 "posts")
+        const parts = jk.split(".");
+        for (let i = 1; i < parts.length; i++) {
+            exclusions.add(parts.slice(0, i).join("."));
+        }
     }
-  }
-  return exclusions;
+    return exclusions;
 }
+/**
+ * JOIN key를 제외하고 레코드에서 그룹 key 추출
+ */
 function extractGroupKey(record, joinKeyExclusions) {
-  const result = {};
-  for (const [key, value] of Object.entries(record)) {
-    if (!joinKeyExclusions.has(key)) {
-      if (value == null || typeof value !== "object") {
-        result[key] = value;
-      }
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        // JOIN이 아닌 key만 포함
+        if (!joinKeyExclusions.has(key)) {
+            // 프리미티브 값만 그룹 key로 사용 (객체/배열 제외)
+            if (value == null || typeof value !== "object") {
+                result[key] = value;
+            }
+        }
     }
-  }
-  return result;
+    return result;
 }
+/**
+ * 기존 그룹에 JOIN 데이터 병합
+ */
 function mergeJoinData(existingGroup, newRecord, localKey, isSingle) {
-  const newJoinData = newRecord[localKey];
-  if (newJoinData == null || isEmptyObject(newJoinData)) {
-    return;
-  }
-  const existingJoinData = existingGroup[localKey];
-  if (isSingle) {
-    if (existingJoinData != null) {
-      if (!obj.equal(existingJoinData, newJoinData)) {
-        throw new Error(`isSingle relationship '${localKey}' has multiple different results.`);
-      }
-    } else {
-      existingGroup[localKey] = newJoinData;
+    const newJoinData = newRecord[localKey];
+    if (newJoinData == null || isEmptyObject(newJoinData)) {
+        return; // 병합할 데이터 없음
+    }
+    const existingJoinData = existingGroup[localKey];
+    if (isSingle) {
+        // isSingle: true - error if data exists and values differ
+        if (existingJoinData != null) {
+            if (!obj.equal(existingJoinData, newJoinData)) {
+                throw new Error(`isSingle 관계 '${localKey}'에 여러 개의 다른 결과가 있습니다.`);
+            }
+        }
+        else {
+            existingGroup[localKey] = newJoinData;
+        }
     }
-  } else {
-    const hashSetKey = `__hashSet__${localKey}`;
-    if (!Array.isArray(existingJoinData)) {
-      existingGroup[localKey] = [newJoinData];
-      existingGroup[hashSetKey] = /* @__PURE__ */ new Set([serializeGroupKey(newJoinData)]);
-    } else {
-      const hashSet = existingGroup[hashSetKey];
-      const newHash = serializeGroupKey(newJoinData);
-      if (hashSet != null) {
-        if (!hashSet.has(newHash)) {
-          hashSet.add(newHash);
-          existingJoinData.push(newJoinData);
+    else {
+        // isSingle: false → Add to array
+        const hashSetKey = `__hashSet__${localKey}`;
+        if (!Array.isArray(existingJoinData)) {
+            existingGroup[localKey] = [newJoinData];
+            // Set 기반 중복 검사용 내부 속성 초기화
+            existingGroup[hashSetKey] = new Set([serializeGroupKey(newJoinData)]);
         }
-      } else {
-        const isDuplicate = existingJoinData.some(
-          (item) => obj.equal(item, newJoinData)
-        );
-        if (!isDuplicate) {
-          existingJoinData.push(newJoinData);
+        else {
+            // Set 기반 중복 검사 (O(1))
+            const hashSet = existingGroup[hashSetKey];
+            const newHash = serializeGroupKey(newJoinData);
+            if (hashSet != null) {
+                if (!hashSet.has(newHash)) {
+                    hashSet.add(newHash);
+                    existingJoinData.push(newJoinData);
+                }
+            }
+            else {
+                // hashSet 없는 폴백 (레거시 방식)
+                const isDuplicate = existingJoinData.some((item) => obj.equal(item, newJoinData));
+                if (!isDuplicate) {
+                    existingJoinData.push(newJoinData);
+                }
+            }
         }
-      }
     }
-  }
 }
-export {
-  parseQueryResult
-};
-//# sourceMappingURL=result-parser.js.map
+//# sourceMappingURL=result-parser.js.map