@simplysm/core-common 13.0.100 → 14.0.4

package/dist/utils/obj.js

@@ -3,553 +3,763 @@ import { DateOnly } from "../types/date-only.js";
 import { Time } from "../types/time.js";
 import { Uuid } from "../types/uuid.js";
 import { ArgumentError } from "../errors/argument-error.js";
-function clone(source) {
-  return cloneImpl(source);
+//#region clone
+/**
+ * 깊은 복사
+ * - 순환 참조 지원
+ * - 커스텀 타입 복사 지원 (DateTime, DateOnly, Time, Uuid, Uint8Array)
+ *
+ * @note 함수와 Symbol은 복사되지 않고 참조가 유지됨
+ * @note WeakMap과 WeakSet은 지원되지 않음 (일반 객체로 복사되어 빈 객체가 됨)
+ * @note 프로토타입 체인이 유지됨 (Object.setPrototypeOf 사용)
+ * @note Getter/setter는 현재 값으로 평가되어 복사됨 (접근자 속성 자체는 복사되지 않음)
+ */
+export function clone(source) {
+    return cloneImpl(source);
 }
 function cloneImpl(source, prevClones) {
-  if (typeof source !== "object" || source === null) {
-    return source;
-  }
-  if (source instanceof Date) {
-    return new Date(source.getTime());
-  }
-  if (source instanceof DateTime) {
-    return new DateTime(source.tick);
-  }
-  if (source instanceof DateOnly) {
-    return new DateOnly(source.tick);
-  }
-  if (source instanceof Time) {
-    return new Time(source.tick);
-  }
-  if (source instanceof Uuid) {
-    return new Uuid(source.toString());
-  }
-  if (source instanceof RegExp) {
-    return new RegExp(source.source, source.flags);
-  }
-  const currPrevClones = prevClones ?? /* @__PURE__ */ new WeakMap();
-  if (currPrevClones.has(source)) {
-    return currPrevClones.get(source);
-  }
-  if (source instanceof Error) {
-    const cloned = Object.create(Object.getPrototypeOf(source));
-    currPrevClones.set(source, cloned);
-    cloned.message = source.message;
-    cloned.name = source.name;
-    cloned.stack = source.stack;
-    if (source.cause !== void 0) {
-      cloned.cause = cloneImpl(source.cause, currPrevClones);
+    // 원시 값은 그대로 반환
+    if (typeof source !== "object" || source === null) {
+        return source;
     }
+    // 불변과 유사한 타입 (내부 객체 참조 없음)
+    if (source instanceof Date) {
+        return new Date(source.getTime());
+    }
+    if (source instanceof DateTime) {
+        return new DateTime(source.tick);
+    }
+    if (source instanceof DateOnly) {
+        return new DateOnly(source.tick);
+    }
+    if (source instanceof Time) {
+        return new Time(source.tick);
+    }
+    if (source instanceof Uuid) {
+        return new Uuid(source.toString());
+    }
+    // RegExp
+    if (source instanceof RegExp) {
+        return new RegExp(source.source, source.flags);
+    }
+    // 순환 참조 검사 (Error를 포함한 모든 객체 타입에 적용)
+    const currPrevClones = prevClones ?? new WeakMap();
+    if (currPrevClones.has(source)) {
+        return currPrevClones.get(source);
+    }
+    // Error (cause 포함)
+    // 생성자 호출 대신 프로토타입 기반 복사 - 커스텀 Error 클래스 호환성 보장
+    if (source instanceof Error) {
+        const cloned = Object.create(Object.getPrototypeOf(source));
+        currPrevClones.set(source, cloned);
+        cloned.message = source.message;
+        cloned.name = source.name;
+        cloned.stack = source.stack;
+        if (source.cause !== undefined) {
+            cloned.cause = cloneImpl(source.cause, currPrevClones);
+        }
+        // 커스텀 Error 속성 복사
+        for (const key of Object.keys(source)) {
+            if (!["message", "name", "stack", "cause"].includes(key)) {
+                const desc = Object.getOwnPropertyDescriptor(source, key);
+                if (desc !== undefined) {
+                    Object.defineProperty(cloned, key, {
+                        ...desc,
+                        value: "value" in desc ? cloneImpl(desc.value, currPrevClones) : desc.value,
+                    });
+                }
+            }
+        }
+        return cloned;
+    }
+    if (source instanceof Uint8Array) {
+        const result = source.slice();
+        currPrevClones.set(source, result);
+        return result;
+    }
+    if (source instanceof Array) {
+        const result = [];
+        currPrevClones.set(source, result);
+        for (const item of source) {
+            result.push(cloneImpl(item, currPrevClones));
+        }
+        return result;
+    }
+    if (source instanceof Map) {
+        const result = new Map();
+        currPrevClones.set(source, result);
+        for (const [key, value] of source) {
+            result.set(cloneImpl(key, currPrevClones), cloneImpl(value, currPrevClones));
+        }
+        return result;
+    }
+    if (source instanceof Set) {
+        const result = new Set();
+        currPrevClones.set(source, result);
+        for (const item of source) {
+            result.add(cloneImpl(item, currPrevClones));
+        }
+        return result;
+    }
+    // 기타 Object 타입
+    const result = {};
+    Object.setPrototypeOf(result, Object.getPrototypeOf(source));
+    currPrevClones.set(source, result);
     for (const key of Object.keys(source)) {
-      if (!["message", "name", "stack", "cause"].includes(key)) {
-        const desc = Object.getOwnPropertyDescriptor(source, key);
-        if (desc !== void 0) {
-          Object.defineProperty(cloned, key, {
-            ...desc,
-            value: "value" in desc ? cloneImpl(desc.value, currPrevClones) : desc.value
-          });
-        }
-      }
-    }
-    return cloned;
-  }
-  if (source instanceof Uint8Array) {
-    const result2 = source.slice();
-    currPrevClones.set(source, result2);
-    return result2;
-  }
-  if (source instanceof Array) {
-    const result2 = [];
-    currPrevClones.set(source, result2);
-    for (const item of source) {
-      result2.push(cloneImpl(item, currPrevClones));
-    }
-    return result2;
-  }
-  if (source instanceof Map) {
-    const result2 = /* @__PURE__ */ new Map();
-    currPrevClones.set(source, result2);
-    for (const [key, value] of source) {
-      result2.set(cloneImpl(key, currPrevClones), cloneImpl(value, currPrevClones));
-    }
-    return result2;
-  }
-  if (source instanceof Set) {
-    const result2 = /* @__PURE__ */ new Set();
-    currPrevClones.set(source, result2);
-    for (const item of source) {
-      result2.add(cloneImpl(item, currPrevClones));
-    }
-    return result2;
-  }
-  const result = {};
-  Object.setPrototypeOf(result, Object.getPrototypeOf(source));
-  currPrevClones.set(source, result);
-  for (const key of Object.keys(source)) {
-    const value = source[key];
-    result[key] = cloneImpl(value, currPrevClones);
-  }
-  return result;
+        const value = source[key];
+        result[key] = cloneImpl(value, currPrevClones);
+    }
+    return result;
 }
-function equal(source, target, options) {
-  if (source === target) return true;
-  if (source == null || target == null) return false;
-  if (typeof source !== typeof target) return false;
-  if (source instanceof Date && target instanceof Date) {
-    return source.getTime() === target.getTime();
-  }
-  if (source instanceof DateTime && target instanceof DateTime || source instanceof DateOnly && target instanceof DateOnly || source instanceof Time && target instanceof Time) {
-    return source.tick === target.tick;
-  }
-  if (source instanceof Uuid && target instanceof Uuid) {
-    return source.toString() === target.toString();
-  }
-  if (source instanceof RegExp && target instanceof RegExp) {
-    return source.source === target.source && source.flags === target.flags;
-  }
-  if (source instanceof Array && target instanceof Array) {
-    return equalArray(source, target, options);
-  }
-  if (source instanceof Map && target instanceof Map) {
-    return equalMap(source, target, options);
-  }
-  if (source instanceof Set && target instanceof Set) {
-    return equalSet(source, target, options);
-  }
-  if (typeof source === "object" && typeof target === "object") {
-    return equalObject(
-      source,
-      target,
-      options
-    );
-  }
-  return false;
+/**
+ * 깊은 동등성 비교
+ *
+ * @param source 비교 대상 1
+ * @param target 비교 대상 2
+ * @param options 비교 옵션
+ * @param options.topLevelIncludes 비교할 key 목록. 지정 시 해당 key만 비교 (최상위 레벨에만 적용)
+ *   @example `{ topLevelIncludes: ["id", "name"] }` - id와 name key만 비교
+ * @param options.topLevelExcludes 비교에서 제외할 key 목록 (최상위 레벨에만 적용)
+ *   @example `{ topLevelExcludes: ["updatedAt"] }` - updatedAt key를 제외하고 비교
+ * @param options.ignoreArrayIndex array 순서를 무시할지 여부. true면 O(n²) 복잡도
+ * @param options.shallow 얕은 비교 여부. true면 1단계만 비교 (참조 비교)
+ *
+ * @note topLevelIncludes/topLevelExcludes 옵션은 객체 속성 key에만 적용됨.
+ *       Map의 모든 key는 항상 비교에 포함됨.
+ * @note 성능 고려사항:
+ * - 기본 array 비교: O(n) 시간 복잡도
+ * - `ignoreArrayIndex: true` 사용 시: O(n²) 시간 복잡도
+ *   (대형 array에서 성능 저하 가능)
+ * @note `ignoreArrayIndex: true` 동작 특성:
+ * - array 순서를 무시하고 요소가 같은 집합의 순열인지 확인
+ * - 예: `[1,2,3]`과 `[3,2,1]` → true, `[1,1,1]`과 `[1,2,3]` → false
+ */
+export function equal(source, target, options) {
+    if (source === target)
+        return true;
+    if (source == null || target == null)
+        return false;
+    if (typeof source !== typeof target)
+        return false;
+    if (source instanceof Date && target instanceof Date) {
+        return source.getTime() === target.getTime();
+    }
+    if ((source instanceof DateTime && target instanceof DateTime) ||
+        (source instanceof DateOnly && target instanceof DateOnly) ||
+        (source instanceof Time && target instanceof Time)) {
+        return source.tick === target.tick;
+    }
+    if (source instanceof Uuid && target instanceof Uuid) {
+        return source.toString() === target.toString();
+    }
+    if (source instanceof RegExp && target instanceof RegExp) {
+        return source.source === target.source && source.flags === target.flags;
+    }
+    if (source instanceof Array && target instanceof Array) {
+        return equalArray(source, target, options);
+    }
+    if (source instanceof Map && target instanceof Map) {
+        return equalMap(source, target, options);
+    }
+    if (source instanceof Set && target instanceof Set) {
+        return equalSet(source, target, options);
+    }
+    if (typeof source === "object" && typeof target === "object") {
+        return equalObject(source, target, options);
+    }
+    return false;
 }
 function equalArray(source, target, options) {
-  if (source.length !== target.length) {
-    return false;
-  }
-  if (options == null ? void 0 : options.ignoreArrayIndex) {
-    const matchedIndices = /* @__PURE__ */ new Set();
-    if (options.shallow) {
-      return source.every((sourceItem) => {
-        const idx = target.findIndex((t, i) => !matchedIndices.has(i) && t === sourceItem);
-        if (idx !== -1) {
-          matchedIndices.add(idx);
-          return true;
-        }
+    if (source.length !== target.length) {
         return false;
-      });
-    } else {
-      const recursiveOptions = {
-        ignoreArrayIndex: options.ignoreArrayIndex,
-        shallow: options.shallow
-      };
-      return source.every((sourceItem) => {
-        const idx = target.findIndex(
-          (t, i) => !matchedIndices.has(i) && equal(t, sourceItem, recursiveOptions)
-        );
-        if (idx !== -1) {
-          matchedIndices.add(idx);
-          return true;
+    }
+    if (options?.ignoreArrayIndex) {
+        const matchedIndices = new Set();
+        if (options.shallow) {
+            return source.every((sourceItem) => {
+                const idx = target.findIndex((t, i) => !matchedIndices.has(i) && t === sourceItem);
+                if (idx !== -1) {
+                    matchedIndices.add(idx);
+                    return true;
+                }
+                return false;
+            });
         }
-        return false;
-      });
-    }
-  } else {
-    if (options == null ? void 0 : options.shallow) {
-      for (let i = 0; i < source.length; i++) {
-        if (source[i] !== target[i]) {
-          return false;
-        }
-      }
-    } else {
-      for (let i = 0; i < source.length; i++) {
-        if (!equal(source[i], target[i], {
-          ignoreArrayIndex: options == null ? void 0 : options.ignoreArrayIndex,
-          shallow: options == null ? void 0 : options.shallow
-        })) {
-          return false;
-        }
-      }
-    }
-  }
-  return true;
+        else {
+            // 재귀 호출 시 topLevelIncludes/topLevelExcludes 옵션은 최상위 레벨에만 적용되므로 제외
+            const recursiveOptions = {
+                ignoreArrayIndex: options.ignoreArrayIndex,
+                shallow: options.shallow,
+            };
+            return source.every((sourceItem) => {
+                const idx = target.findIndex((t, i) => !matchedIndices.has(i) && equal(t, sourceItem, recursiveOptions));
+                if (idx !== -1) {
+                    matchedIndices.add(idx);
+                    return true;
+                }
+                return false;
+            });
+        }
+    }
+    else {
+        if (options?.shallow) {
+            for (let i = 0; i < source.length; i++) {
+                if (source[i] !== target[i]) {
+                    return false;
+                }
+            }
+        }
+        else {
+            // 재귀 호출 시 topLevelIncludes/topLevelExcludes 옵션은 최상위 레벨에만 적용되므로 제외
+            for (let i = 0; i < source.length; i++) {
+                if (!equal(source[i], target[i], {
+                    ignoreArrayIndex: options?.ignoreArrayIndex,
+                    shallow: options?.shallow,
+                })) {
+                    return false;
+                }
+            }
+        }
+    }
+    return true;
 }
+/**
+ * Map 객체 비교
+ * @note 비문자열 key(객체, array 등) 처리 시 O(n²) 복잡도
+ * @note 대용량 데이터에는 shallow: true 옵션 사용 권장 (참조 비교로 O(n)으로 개선)
+ */
 function equalMap(source, target, options) {
-  const sourceKeys = Array.from(source.keys()).filter((key) => source.get(key) != null);
-  const targetKeys = Array.from(target.keys()).filter((key) => target.get(key) != null);
-  if (sourceKeys.length !== targetKeys.length) {
-    return false;
-  }
-  const usedTargetKeys = /* @__PURE__ */ new Set();
-  for (const sourceKey of sourceKeys) {
-    if (typeof sourceKey === "string") {
-      const sourceValue = source.get(sourceKey);
-      const targetValue = target.get(sourceKey);
-      if (options == null ? void 0 : options.shallow) {
-        if (sourceValue !== targetValue) return false;
-      } else {
-        if (!equal(sourceValue, targetValue, {
-          ignoreArrayIndex: options == null ? void 0 : options.ignoreArrayIndex,
-          shallow: options == null ? void 0 : options.shallow
-        })) {
-          return false;
-        }
-      }
-    } else {
-      let found = false;
-      for (let i = 0; i < targetKeys.length; i++) {
-        const targetKey = targetKeys[i];
-        if (typeof targetKey === "string" || usedTargetKeys.has(i)) continue;
-        if ((options == null ? void 0 : options.shallow) ? sourceKey === targetKey : equal(sourceKey, targetKey)) {
-          usedTargetKeys.add(i);
-          const sourceValue = source.get(sourceKey);
-          const targetValue = target.get(targetKey);
-          if (options == null ? void 0 : options.shallow) {
-            if (sourceValue !== targetValue) return false;
-          } else {
-            if (!equal(sourceValue, targetValue, {
-              ignoreArrayIndex: options == null ? void 0 : options.ignoreArrayIndex,
-              shallow: options == null ? void 0 : options.shallow
-            })) {
-              return false;
+    // Map 비교 시 topLevelIncludes/topLevelExcludes 옵션은 무시됨 (객체 속성 key에만 적용)
+    const sourceKeys = Array.from(source.keys()).filter((key) => source.get(key) != null);
+    const targetKeys = Array.from(target.keys()).filter((key) => target.get(key) != null);
+    if (sourceKeys.length !== targetKeys.length) {
+        return false;
+    }
+    const usedTargetKeys = new Set();
+    for (const sourceKey of sourceKeys) {
+        // 문자열 key: 직접 비교
+        if (typeof sourceKey === "string") {
+            const sourceValue = source.get(sourceKey);
+            const targetValue = target.get(sourceKey);
+            if (options?.shallow) {
+                if (sourceValue !== targetValue)
+                    return false;
             }
-          }
-          found = true;
-          break;
+            else {
+                if (!equal(sourceValue, targetValue, {
+                    ignoreArrayIndex: options?.ignoreArrayIndex,
+                    shallow: options?.shallow,
+                })) {
+                    return false;
+                }
+            }
+        }
+        else {
+            // 비문자열 key: targetKeys에서 동등한 key 검색
+            let found = false;
+            for (let i = 0; i < targetKeys.length; i++) {
+                const targetKey = targetKeys[i];
+                if (typeof targetKey === "string" || usedTargetKeys.has(i))
+                    continue;
+                if (options?.shallow ? sourceKey === targetKey : equal(sourceKey, targetKey)) {
+                    usedTargetKeys.add(i);
+                    const sourceValue = source.get(sourceKey);
+                    const targetValue = target.get(targetKey);
+                    if (options?.shallow) {
+                        if (sourceValue !== targetValue)
+                            return false;
+                    }
+                    else {
+                        if (!equal(sourceValue, targetValue, {
+                            ignoreArrayIndex: options?.ignoreArrayIndex,
+                            shallow: options?.shallow,
+                        })) {
+                            return false;
+                        }
+                    }
+                    found = true;
+                    break;
+                }
+            }
+            if (!found)
+                return false;
         }
-      }
-      if (!found) return false;
     }
-  }
-  return true;
+    return true;
 }
 function equalObject(source, target, options) {
-  const sourceKeys = Object.keys(source).filter(
-    (key) => {
-      var _a;
-      return ((options == null ? void 0 : options.topLevelIncludes) === void 0 || options.topLevelIncludes.includes(key)) && !((_a = options == null ? void 0 : options.topLevelExcludes) == null ? void 0 : _a.includes(key)) && source[key] != null;
-    }
-  );
-  const targetKeys = Object.keys(target).filter(
-    (key) => {
-      var _a;
-      return ((options == null ? void 0 : options.topLevelIncludes) === void 0 || options.topLevelIncludes.includes(key)) && !((_a = options == null ? void 0 : options.topLevelExcludes) == null ? void 0 : _a.includes(key)) && target[key] != null;
-    }
-  );
-  if (sourceKeys.length !== targetKeys.length) {
-    return false;
-  }
-  for (const key of sourceKeys) {
-    if (options == null ? void 0 : options.shallow) {
-      if (source[key] !== target[key]) {
+    const sourceKeys = Object.keys(source).filter((key) => (options?.topLevelIncludes === undefined || options.topLevelIncludes.includes(key)) &&
+        !options?.topLevelExcludes?.includes(key) &&
+        source[key] != null);
+    const targetKeys = Object.keys(target).filter((key) => (options?.topLevelIncludes === undefined || options.topLevelIncludes.includes(key)) &&
+        !options?.topLevelExcludes?.includes(key) &&
+        target[key] != null);
+    if (sourceKeys.length !== targetKeys.length) {
         return false;
-      }
-    } else {
-      if (!equal(source[key], target[key], {
-        ignoreArrayIndex: options == null ? void 0 : options.ignoreArrayIndex
-      })) {
-        return false;
-      }
     }
-  }
-  return true;
+    for (const key of sourceKeys) {
+        if (options?.shallow) {
+            if (source[key] !== target[key]) {
+                return false;
+            }
+        }
+        else {
+            if (!equal(source[key], target[key], {
+                ignoreArrayIndex: options?.ignoreArrayIndex,
+            })) {
+                return false;
+            }
+        }
+    }
+    return true;
 }
+/**
+ * Set 깊은 동등성 비교
+ * @note 깊은 비교(`shallow: false`)는 O(n²) 시간 복잡도.
+ *   원시 타입 Set이거나 성능이 중요한 경우 `shallow: true` 사용 권장
+ */
 function equalSet(source, target, options) {
-  if (source.size !== target.size) {
-    return false;
-  }
-  if (options == null ? void 0 : options.shallow) {
-    for (const sourceItem of source) {
-      if (!target.has(sourceItem)) {
+    if (source.size !== target.size) {
         return false;
-      }
-    }
-  } else {
-    const targetArr = [...target];
-    const matchedIndices = /* @__PURE__ */ new Set();
-    for (const sourceItem of source) {
-      const idx = targetArr.findIndex(
-        (t, i) => !matchedIndices.has(i) && equal(sourceItem, t, options)
-      );
-      if (idx === -1) {
-        return false;
-      }
-      matchedIndices.add(idx);
     }
-  }
-  return true;
+    if (options?.shallow) {
+        for (const sourceItem of source) {
+            if (!target.has(sourceItem)) {
+                return false;
+            }
+        }
+    }
+    else {
+        // 깊은 비교: 루프 외부에서 target array를 한 번만 생성
+        // 중복 매칭 방지를 위해 매칭된 인덱스 추적
+        const targetArr = [...target];
+        const matchedIndices = new Set();
+        for (const sourceItem of source) {
+            const idx = targetArr.findIndex((t, i) => !matchedIndices.has(i) && equal(sourceItem, t, options));
+            if (idx === -1) {
+                return false;
+            }
+            matchedIndices.add(idx);
+        }
+    }
+    return true;
 }
-function merge(source, target, opt) {
-  if (source == null) {
-    return clone(target);
-  }
-  if (target === void 0) {
-    return clone(source);
-  }
-  if (target === null) {
-    return (opt == null ? void 0 : opt.useDelTargetNull) ? void 0 : clone(source);
-  }
-  if (typeof target !== "object") {
-    return target;
-  }
-  if (target instanceof Date || target instanceof DateTime || target instanceof DateOnly || target instanceof Time || target instanceof Uuid || target instanceof Uint8Array || (opt == null ? void 0 : opt.arrayProcess) === "replace" && target instanceof Array) {
-    return clone(target);
-  }
-  if (typeof source !== "object" || source.constructor !== target.constructor) {
-    return clone(target);
-  }
-  if (source instanceof Map && target instanceof Map) {
-    const result = clone(source);
-    for (const key of target.keys()) {
-      if (result.has(key)) {
-        result.set(key, merge(result.get(key), target.get(key), opt));
-      } else {
-        result.set(key, clone(target.get(key)));
-      }
+/**
+ * 깊은 병합 (source를 기반으로 target을 병합)
+ *
+ * @param source 기본 객체
+ * @param target 병합할 객체
+ * @param opt 병합 옵션
+ * @param opt.arrayProcess Array 처리 방식
+ *   - `"replace"`: target array로 교체 (기본값)
+ *   - `"concat"`: source와 target array를 병합 (Set으로 중복 제거)
+ * @param opt.useDelTargetNull target 값이 null일 때 해당 key를 삭제할지 여부
+ *   - `true`: target이 null이면 결과에서 해당 key 삭제
+ *   - `false` 또는 미지정: source 값 유지
+ *
+ * @note 원본 객체를 수정하지 않고 새 객체를 반환 (불변성 보장)
+ * @note arrayProcess="concat" 사용 시 Set으로 중복 제거되며,
+ *       객체 array의 경우 참조(주소) 비교로 중복 여부 판단
+ * @note 타입이 다르면 target 값으로 덮어씀
+ */
+export function merge(source, target, opt) {
+    if (source == null) {
+        return clone(target);
     }
-    return result;
-  }
-  if ((opt == null ? void 0 : opt.arrayProcess) === "concat" && source instanceof Array && target instanceof Array) {
-    let result = [.../* @__PURE__ */ new Set([...source, ...target])];
-    if (opt.useDelTargetNull) {
-      result = result.filter((item) => item !== null);
+    if (target === undefined) {
+        return clone(source);
     }
-    return result;
-  }
-  const sourceRec = source;
-  const targetRec = target;
-  const resultRec = clone(sourceRec);
-  for (const key of Object.keys(target)) {
-    resultRec[key] = merge(sourceRec[key], targetRec[key], opt);
-    if (resultRec[key] === void 0) {
-      delete resultRec[key];
-    }
-  }
-  return resultRec;
+    if (target === null) {
+        return opt?.useDelTargetNull
+            ? undefined
+            : clone(source);
+    }
+    if (typeof target !== "object") {
+        return target;
+    }
+    if (target instanceof Date ||
+        target instanceof DateTime ||
+        target instanceof DateOnly ||
+        target instanceof Time ||
+        target instanceof Uuid ||
+        target instanceof Uint8Array ||
+        (opt?.arrayProcess === "replace" && target instanceof Array)) {
+        return clone(target);
+    }
+    // source가 객체가 아니거나 source와 target이 다른 타입의 객체이면 target으로 덮어씀
+    if (typeof source !== "object" || source.constructor !== target.constructor) {
+        return clone(target);
+    }
+    if (source instanceof Map && target instanceof Map) {
+        const result = clone(source);
+        for (const key of target.keys()) {
+            if (result.has(key)) {
+                result.set(key, merge(result.get(key), target.get(key), opt));
+            }
+            else {
+                result.set(key, clone(target.get(key)));
+            }
+        }
+        return result;
+    }
+    if (opt?.arrayProcess === "concat" && source instanceof Array && target instanceof Array) {
+        let result = [...new Set([...source, ...target])];
+        if (opt.useDelTargetNull) {
+            result = result.filter((item) => item !== null);
+        }
+        return result;
+    }
+    const sourceRec = source;
+    const targetRec = target;
+    const resultRec = clone(sourceRec);
+    for (const key of Object.keys(target)) {
+        resultRec[key] = merge(sourceRec[key], targetRec[key], opt);
+        if (resultRec[key] === undefined) {
+            delete resultRec[key];
+        }
+    }
+    return resultRec;
 }
-function merge3(source, origin, target, optionsObj) {
-  let conflict = false;
-  const result = clone(origin);
-  const allKeys = /* @__PURE__ */ new Set([...Object.keys(source), ...Object.keys(target), ...Object.keys(origin)]);
-  for (const key of allKeys) {
-    if (equal(source[key], result[key], optionsObj == null ? void 0 : optionsObj[key])) {
-      result[key] = clone(target[key]);
-    } else if (equal(target[key], result[key], optionsObj == null ? void 0 : optionsObj[key])) {
-      result[key] = clone(source[key]);
-    } else if (equal(source[key], target[key], optionsObj == null ? void 0 : optionsObj[key])) {
-      result[key] = clone(source[key]);
-    } else {
-      conflict = true;
-    }
-  }
-  return {
-    conflict,
-    result
-  };
+/**
+ * 3-way 병합
+ *
+ * source, origin, target 세 객체를 비교하여 병합.
+ * - source와 origin이 같고 target이 다르면 → target 값 사용
+ * - target과 origin이 같고 source가 다르면 → source 값 사용
+ * - source와 target이 같으면 → 해당 값 사용
+ * - 세 값이 모두 다르면 → 충돌 발생 (origin 값 유지)
+ *
+ * @param source 변경된 버전 1
+ * @param origin 기본 버전 (공통 조상)
+ * @param target 변경된 버전 2
+ * @param optionsObj key별 비교 옵션. 각 key에 대해 equal() 비교 옵션을 개별 지정
+ *   - `keys`: 비교할 하위 key 목록 (equal의 topLevelIncludes와 동일)
+ *   - `excludes`: 비교에서 제외할 하위 key 목록
+ *   - `ignoreArrayIndex`: array 순서를 무시할지 여부
+ * @returns conflict: 충돌 발생 여부, result: 병합 결과
+ *
+ * @example
+ * const { conflict, result } = merge3(
+ *   { a: 1, b: 2 },  // source
+ *   { a: 1, b: 1 },  // origin
+ *   { a: 2, b: 1 },  // target
+ * );
+ * // conflict: false, result: { a: 2, b: 2 }
+ */
+export function merge3(source, origin, target, optionsObj) {
+    let conflict = false;
+    const result = clone(origin);
+    const allKeys = new Set([...Object.keys(source), ...Object.keys(target), ...Object.keys(origin)]);
+    for (const key of allKeys) {
+        if (equal(source[key], result[key], optionsObj?.[key])) {
+            result[key] = clone(target[key]);
+        }
+        else if (equal(target[key], result[key], optionsObj?.[key])) {
+            result[key] = clone(source[key]);
+        }
+        else if (equal(source[key], target[key], optionsObj?.[key])) {
+            result[key] = clone(source[key]);
+        }
+        else {
+            conflict = true;
+        }
+    }
+    return {
+        conflict,
+        result: result,
+    };
 }
-function omit(item, omitKeys) {
-  const result = {};
-  for (const key of Object.keys(item)) {
-    if (!omitKeys.includes(key)) {
-      result[key] = item[key];
-    }
-  }
-  return result;
+//#endregion
+//#region omit / pick
+/**
+ * 객체에서 특정 key 제외
+ * @param item 원본 객체
+ * @param omitKeys 제외할 key 배열
+ * @returns 지정된 key가 제외된 새 객체
+ * @example
+ * const user = { name: "Alice", age: 30, email: "alice@example.com" };
+ * omit(user, ["email"]);
+ * // { name: "Alice", age: 30 }
+ */
+export function omit(item, omitKeys) {
+    const result = {};
+    for (const key of Object.keys(item)) {
+        if (!omitKeys.includes(key)) {
+            result[key] = item[key];
+        }
+    }
+    return result;
 }
-function omitByFilter(item, omitKeyFn) {
-  const result = {};
-  for (const key of Object.keys(item)) {
-    if (!omitKeyFn(key)) {
-      result[key] = item[key];
-    }
-  }
-  return result;
+/**
+ * 조건에 맞는 key 제외
+ * @internal
+ * @param item 원본 객체
+ * @param omitKeyFn key를 받아 제외 여부를 반환하는 함수 (true면 제외)
+ * @returns 조건에 맞는 key가 제외된 새 객체
+ * @example
+ * const data = { name: "Alice", _internal: "secret", age: 30 };
+ * omitByFilter(data, (key) => key.startsWith("_"));
+ * // { name: "Alice", age: 30 }
+ */
+export function omitByFilter(item, omitKeyFn) {
+    const result = {};
+    for (const key of Object.keys(item)) {
+        if (!omitKeyFn(key)) {
+            result[key] = item[key];
+        }
+    }
+    return result;
 }
-function pick(item, pickKeys) {
-  const result = {};
-  for (const key of pickKeys) {
-    result[key] = item[key];
-  }
-  return result;
+/**
+ * 객체에서 특정 key만 선택
+ * @param item 원본 객체
+ * @param keys 선택할 key 배열
+ * @returns 지정된 key만 포함된 새 객체
+ * @example
+ * const user = { name: "Alice", age: 30, email: "alice@example.com" };
+ * pick(user, ["name", "age"]);
+ * // { name: "Alice", age: 30 }
+ */
+export function pick(item, pickKeys) {
+    const result = {};
+    for (const key of pickKeys) {
+        result[key] = item[key];
+    }
+    return result;
 }
+//#endregion
+//#region getChainValue / setChainValue / deleteChainValue
+// 정규식 캐싱 (모듈 로드 시 한 번만 생성)
 const chainSplitRegex = /[.[\]]/g;
 const chainCleanRegex = /[?!'"]/g;
 const chainNumericRegex = /^[0-9]*$/;
 function getChainSplits(chain) {
-  const split = chain.split(chainSplitRegex).map((item) => item.replace(chainCleanRegex, "")).filter((item) => Boolean(item));
-  const result = [];
-  for (const splitItem of split) {
-    if (chainNumericRegex.test(splitItem)) {
-      result.push(Number.parseInt(splitItem));
-    } else {
-      result.push(splitItem);
-    }
-  }
-  return result;
+    const split = chain
+        .split(chainSplitRegex)
+        .map((item) => item.replace(chainCleanRegex, ""))
+        .filter((item) => Boolean(item));
+    const result = [];
+    for (const splitItem of split) {
+        if (chainNumericRegex.test(splitItem)) {
+            result.push(Number.parseInt(splitItem));
+        }
+        else {
+            result.push(splitItem);
+        }
+    }
+    return result;
 }
-function getChainValue(obj, chain, optional) {
-  const splits = getChainSplits(chain);
-  let result = obj;
-  for (const splitItem of splits) {
-    if (optional && result === void 0) {
-      result = void 0;
-    } else {
-      result = result[splitItem];
-    }
-  }
-  return result;
+export function getChainValue(obj, chain, optional) {
+    const splits = getChainSplits(chain);
+    let result = obj;
+    for (const splitItem of splits) {
+        if (optional && result === undefined) {
+            result = undefined;
+        }
+        else {
+            result = result[splitItem];
+        }
+    }
+    return result;
 }
-function getChainValueByDepth(obj, key, depth, optional) {
-  if (depth < 1) {
-    throw new ArgumentError("depth must be 1 or greater", { depth });
-  }
-  let result = obj;
-  for (let i = 0; i < depth; i++) {
-    if (optional && result == null) {
-      result = void 0;
-    } else {
-      result = result[key];
-    }
-  }
-  return result;
+export function getChainValueByDepth(obj, key, depth, optional) {
+    if (depth < 1) {
+        throw new ArgumentError("depth는 1 이상이어야 합니다", { depth });
+    }
+    let result = obj;
+    for (let i = 0; i < depth; i++) {
+        if (optional && result == null) {
+            result = undefined;
+        }
+        else {
+            result = result[key];
+        }
+    }
+    return result;
 }
-function setChainValue(obj, chain, value) {
-  const splits = getChainSplits(chain);
-  if (splits.length === 0) {
-    throw new ArgumentError("Chain is empty", { chain });
-  }
-  let curr = obj;
-  for (const splitItem of splits.slice(0, -1)) {
-    curr[splitItem] = curr[splitItem] ?? {};
-    curr = curr[splitItem];
-  }
-  const last = splits[splits.length - 1];
-  curr[last] = value;
+/**
+ * 체인 경로로 값 설정
+ * @example setChainValue(obj, "a.b[0].c", value)
+ */
+export function setChainValue(obj, chain, value) {
+    const splits = getChainSplits(chain);
+    if (splits.length === 0) {
+        throw new ArgumentError("chain이 비어있습니다", { chain });
+    }
+    let curr = obj;
+    for (const splitItem of splits.slice(0, -1)) {
+        curr[splitItem] = curr[splitItem] ?? {};
+        curr = curr[splitItem];
+    }
+    const last = splits[splits.length - 1];
+    curr[last] = value;
 }
-function deleteChainValue(obj, chain) {
-  const splits = getChainSplits(chain);
-  if (splits.length === 0) {
-    throw new ArgumentError("Chain is empty", { chain });
-  }
-  let curr = obj;
-  for (const splitItem of splits.slice(0, -1)) {
-    const next = curr[splitItem];
-    if (next == null || typeof next !== "object") {
-      return;
-    }
-    curr = next;
-  }
-  const last = splits[splits.length - 1];
-  delete curr[last];
+/**
+ * 체인 경로로 값 삭제
+ * @example deleteChainValue(obj, "a.b[0].c")
+ */
+export function deleteChainValue(obj, chain) {
+    const splits = getChainSplits(chain);
+    if (splits.length === 0) {
+        throw new ArgumentError("chain이 비어있습니다", { chain });
+    }
+    let curr = obj;
+    for (const splitItem of splits.slice(0, -1)) {
+        const next = curr[splitItem];
+        // 중간 경로가 존재하지 않으면 조용히 반환 (삭제할 것이 없음)
+        if (next == null || typeof next !== "object") {
+            return;
+        }
+        curr = next;
+    }
+    const last = splits[splits.length - 1];
+    delete curr[last];
 }
-function clearUndefined(obj) {
-  const record = obj;
-  for (const key of Object.keys(record)) {
-    if (record[key] === void 0) {
-      delete record[key];
-    }
-  }
-  return obj;
+//#endregion
+//#region clearUndefined / clear / nullToUndefined / unflatten
+/**
+ * 객체에서 undefined 값을 가진 key 삭제
+ * @internal
+ *
+ * @mutates 원본 객체를 직접 수정
+ */
+export function clearUndefined(obj) {
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        if (record[key] === undefined) {
+            delete record[key];
+        }
+    }
+    return obj;
 }
-function clear(obj) {
-  for (const key of Object.keys(obj)) {
-    delete obj[key];
-  }
-  return obj;
+/**
+ * 객체의 모든 key 삭제
+ * @internal
+ *
+ * @mutates 원본 객체를 직접 수정
+ */
+export function clear(obj) {
+    for (const key of Object.keys(obj)) {
+        delete obj[key];
+    }
+    return obj;
 }
-function nullToUndefined(obj) {
-  return nullToUndefinedImpl(obj, /* @__PURE__ */ new WeakSet());
+/**
+ * null을 undefined로 변환 (재귀)
+ * @internal
+ *
+ * @mutates 원본 array/객체를 직접 수정
+ */
+export function nullToUndefined(obj) {
+    return nullToUndefinedImpl(obj, new WeakSet());
 }
 function nullToUndefinedImpl(obj, seen) {
-  if (obj == null) {
-    return void 0;
-  }
-  if (obj instanceof Date || obj instanceof DateTime || obj instanceof DateOnly || obj instanceof Time || obj instanceof Uuid) {
-    return obj;
-  }
-  if (obj instanceof Array) {
-    if (seen.has(obj)) return obj;
-    seen.add(obj);
-    for (let i = 0; i < obj.length; i++) {
-      obj[i] = nullToUndefinedImpl(obj[i], seen);
+    if (obj == null) {
+        return undefined;
     }
-    return obj;
-  }
-  if (typeof obj === "object") {
-    if (seen.has(obj)) return obj;
-    seen.add(obj);
-    const objRec = obj;
-    for (const key of Object.keys(obj)) {
-      objRec[key] = nullToUndefinedImpl(objRec[key], seen);
+    if (obj instanceof Date ||
+        obj instanceof DateTime ||
+        obj instanceof DateOnly ||
+        obj instanceof Time ||
+        obj instanceof Uuid) {
+        return obj;
+    }
+    if (obj instanceof Array) {
+        if (seen.has(obj))
+            return obj;
+        seen.add(obj);
+        for (let i = 0; i < obj.length; i++) {
+            obj[i] = nullToUndefinedImpl(obj[i], seen);
+        }
+        return obj;
+    }
+    if (typeof obj === "object") {
+        if (seen.has(obj))
+            return obj;
+        seen.add(obj);
+        const objRec = obj;
+        for (const key of Object.keys(obj)) {
+            objRec[key] = nullToUndefinedImpl(objRec[key], seen);
+        }
+        return obj;
     }
     return obj;
-  }
-  return obj;
 }
-function unflatten(flatObj) {
-  const result = {};
-  for (const key in flatObj) {
-    const parts = key.split(".");
-    let current = result;
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      if (i === parts.length - 1) {
-        current[part] = flatObj[key];
-      } else {
-        if (!(part in current)) {
-          current[part] = {};
-        }
-        current = current[part];
-      }
-    }
-  }
-  return result;
+/**
+ * 평탄화된 객체를 중첩 객체로 변환
+ * @internal
+ * @example unflatten({ "a.b.c": 1 }) => { a: { b: { c: 1 } } }
+ */
+export function unflatten(flatObj) {
+    const result = {};
+    for (const key in flatObj) {
+        const parts = key.split(".");
+        let current = result;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (i === parts.length - 1) {
+                current[part] = flatObj[key];
+            }
+            else {
+                if (!(part in current)) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+    }
+    return result;
 }
-function keys(obj) {
-  return Object.keys(obj);
+//#endregion
+/**
+ * 타입 안전한 Object.keys
+ * @param obj key를 추출할 객체
+ * @returns 객체 key 배열
+ */
+export function keys(obj) {
+    return Object.keys(obj);
 }
-function entries(obj) {
-  return Object.entries(obj);
+/**
+ * 타입 안전한 Object.entries
+ * @param obj 엔트리를 추출할 객체
+ * @returns [key, value] 튜플 배열
+ */
+export function entries(obj) {
+    return Object.entries(obj);
 }
-function fromEntries(entryPairs) {
-  return Object.fromEntries(entryPairs);
+/**
+ * 타입 안전한 Object.fromEntries
+ * @param entries [key, value] 튜플 배열
+ * @returns 생성된 객체
+ */
+export function fromEntries(entryPairs) {
+    return Object.fromEntries(entryPairs);
 }
-function map(obj, fn) {
-  return mapImpl(obj, fn);
+/**
+ * 객체의 각 엔트리를 변환하여 새 객체 반환
+ * @param obj 변환할 객체
+ * @param fn 변환 함수 (key, value) => [newKey, newValue]
+ * @returns key와 value가 변환된 새 객체
+ * @example
+ * const colors = { primary: "255, 0, 0", secondary: "0, 255, 0" };
+ *
+ * // 값만 변환
+ * map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
+ * // { primary: "rgb(255, 0, 0)", secondary: "rgb(0, 255, 0)" }
+ *
+ * // key와 값 모두 변환
+ * map(colors, (key, rgb) => [`${key}Light`, `rgb(${rgb})`]);
+ * // { primaryLight: "rgb(255, 0, 0)", secondaryLight: "rgb(0, 255, 0)" }
+ */
+export function map(obj, fn) {
+    return mapImpl(obj, fn);
 }
 function mapImpl(obj, fn) {
-  const result = {};
-  for (const key of Object.keys(obj)) {
-    const [newKey, newValue] = fn(
-      key,
-      obj[key]
-    );
-    result[newKey ?? key] = newValue;
-  }
-  return result;
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        const [newKey, newValue] = fn(key, obj[key]);
+        result[newKey ?? key] = newValue;
+    }
+    return result;
 }
-export {
-  clear,
-  clearUndefined,
-  clone,
-  deleteChainValue,
-  entries,
-  equal,
-  fromEntries,
-  getChainValue,
-  getChainValueByDepth,
-  keys,
-  map,
-  merge,
-  merge3,
-  nullToUndefined,
-  omit,
-  omitByFilter,
-  pick,
-  setChainValue,
-  unflatten
-};
-//# sourceMappingURL=obj.js.map
+//# sourceMappingURL=obj.js.map