@simplysm/core-common 13.0.100 → 14.0.4

package/dist/extensions/arr-ext.js

@@ -1,3 +1,8 @@
+/**
+ * Array 확장 메서드
+ *
+ * @remarks 각 메서드의 TSDoc은 타입 정의 파일(arr-ext.types.ts)을 참조
+ */
 import "./map-ext.js";
 import { clone, equal, merge } from "../utils/obj.js";
 import { DateTime } from "../types/date-time.js";
@@ -7,442 +12,473 @@ import { Uuid } from "../types/uuid.js";
 import { ArgumentError } from "../errors/argument-error.js";
 import { SdError } from "../errors/sd-error.js";
 import { compareForOrder, getDistinctIndices } from "./arr-ext.helpers.js";
+//#region Implementation
 const arrayReadonlyExtensions = {
-  single(predicate) {
-    const arr = predicate !== void 0 ? this.filter(predicate) : this;
-    if (arr.length > 1) {
-      throw new ArgumentError("Multiple results found.", { count: arr.length });
-    }
-    return arr[0];
-  },
-  first(predicate) {
-    return predicate !== void 0 ? this.find(predicate) : this[0];
-  },
-  async filterAsync(predicate) {
-    const arr = [];
-    for (let i = 0; i < this.length; i++) {
-      if (await predicate(this[i], i)) {
-        arr.push(this[i]);
-      }
-    }
-    return arr;
-  },
-  last(predicate) {
-    if (predicate !== void 0) {
-      for (let i = this.length - 1; i >= 0; i--) {
-        if (predicate(this[i], i)) {
-          return this[i];
+    single(predicate) {
+        const arr = predicate !== undefined ? this.filter(predicate) : this;
+        if (arr.length > 1) {
+            throw new ArgumentError("여러 개의 결과가 발견되었습니다.", { count: arr.length });
         }
-      }
-      return void 0;
-    } else {
-      return this[this.length - 1];
-    }
-  },
-  filterExists() {
-    return this.filter((item) => item != null);
-  },
-  ofType(type) {
-    if (typeof type === "string") {
-      return this.filter((item) => {
-        switch (type) {
-          case "string":
-            return typeof item === "string";
-          case "number":
-            return typeof item === "number";
-          case "boolean":
-            return typeof item === "boolean";
-          case "DateTime":
-            return item instanceof DateTime;
-          case "DateOnly":
-            return item instanceof DateOnly;
-          case "Time":
-            return item instanceof Time;
-          case "Uuid":
-            return item instanceof Uuid;
-          case "Bytes":
-            return item instanceof Uint8Array;
-          default: {
-            const _exhaustive = type;
-            throw new ArgumentError(`Unsupported type: ${_exhaustive}`);
-          }
+        return arr[0];
+    },
+    first(predicate) {
+        return predicate !== undefined ? this.find(predicate) : this[0];
+    },
+    async filterAsync(predicate) {
+        const arr = [];
+        for (let i = 0; i < this.length; i++) {
+            if (await predicate(this[i], i)) {
+                arr.push(this[i]);
+            }
         }
-      });
-    }
-    return this.filter((item) => item instanceof type || (item == null ? void 0 : item.constructor) === type);
-  },
-  async mapAsync(selector) {
-    const result = [];
-    for (let i = 0; i < this.length; i++) {
-      result.push(await selector(this[i], i));
-    }
-    return result;
-  },
-  mapMany(selector) {
-    const arr = selector ? this.map(selector) : this;
-    return arr.flat().filterExists();
-  },
-  async mapManyAsync(selector) {
-    const arr = selector !== void 0 ? await this.mapAsync(selector) : this;
-    return arr.mapMany();
-  },
-  parallelAsync(fn) {
-    return Promise.all(this.map(fn));
-  },
-  // Group array by key
-  // Performance considerations:
-  // - primitive key (string, number, etc.): O(n) - Map-based
-  // - object key: O(n²) - objEqual comparison
-  groupBy(keySelector, valueSelector) {
-    const result = [];
-    const primitiveKeyIndex = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const keyObj = keySelector(this[i], i);
-      const valueObj = valueSelector !== void 0 ? valueSelector(this[i], i) : this[i];
-      if (keyObj == null || typeof keyObj !== "object") {
-        const keyStr = typeof keyObj + ":" + String(keyObj);
-        const existingIndex = primitiveKeyIndex.get(keyStr);
-        if (existingIndex !== void 0) {
-          result[existingIndex].values.push(valueObj);
-        } else {
-          primitiveKeyIndex.set(keyStr, result.length);
-          result.push({ key: keyObj, values: [valueObj] });
+        return arr;
+    },
+    last(predicate) {
+        if (predicate !== undefined) {
+            for (let i = this.length - 1; i >= 0; i--) {
+                if (predicate(this[i], i)) {
+                    return this[i];
+                }
+            }
+            return undefined;
         }
-        continue;
-      }
-      const existsRecord = result.find((item) => equal(item.key, keyObj));
-      if (existsRecord !== void 0) {
-        existsRecord.values.push(valueObj);
-      } else {
-        result.push({ key: keyObj, values: [valueObj] });
-      }
-    }
-    return result;
-  },
-  toMap(keySelector, valueSelector) {
-    const result = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const keyObj = keySelector(item, i);
-      const valueObj = valueSelector !== void 0 ? valueSelector(item, i) : item;
-      if (result.has(keyObj)) {
-        throw new ArgumentError("Duplicated key.", { duplicatedKey: keyObj });
-      }
-      result.set(keyObj, valueObj);
-    }
-    return result;
-  },
-  async toMapAsync(keySelector, valueSelector) {
-    const result = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const keyObj = await keySelector(item, i);
-      const valueObj = valueSelector !== void 0 ? await valueSelector(item, i) : item;
-      if (result.has(keyObj)) {
-        throw new ArgumentError("Duplicated key.", { duplicatedKey: keyObj });
-      }
-      result.set(keyObj, valueObj);
-    }
-    return result;
-  },
-  toArrayMap(keySelector, valueSelector) {
-    const result = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const keyObj = keySelector(item, i);
-      const valueObj = valueSelector !== void 0 ? valueSelector(item, i) : item;
-      const arr = result.getOrCreate(keyObj, []);
-      arr.push(valueObj);
-    }
-    return result;
-  },
-  toSetMap(keySelector, valueSelector) {
-    const result = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const keyObj = keySelector(item, i);
-      const valueObj = valueSelector !== void 0 ? valueSelector(item, i) : item;
-      const set = result.getOrCreate(keyObj, /* @__PURE__ */ new Set());
-      set.add(valueObj);
-    }
-    return result;
-  },
-  toMapValues(keySelector, valueSelector) {
-    const itemsMap = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const keyObj = keySelector(item, i);
-      const arr = itemsMap.getOrCreate(keyObj, []);
-      arr.push(item);
-    }
-    const result = /* @__PURE__ */ new Map();
-    for (const key of itemsMap.keys()) {
-      result.set(key, valueSelector(itemsMap.get(key)));
-    }
-    return result;
-  },
-  toObject(keySelector, valueSelector) {
-    const result = {};
-    for (let i = 0; i < this.length; i++) {
-      const item = this[i];
-      const key = keySelector(item, i);
-      const valueObj = valueSelector !== void 0 ? valueSelector(item, i) : item;
-      if (result[key] !== void 0) {
-        throw new ArgumentError("Duplicated key.", { duplicatedKey: key });
-      }
-      result[key] = valueObj;
-    }
-    return result;
-  },
-  toTree(key, parentKey) {
-    const childrenMap = this.toArrayMap((item) => item[parentKey]);
-    const fn = (items) => {
-      return items.map((item) => ({
-        ...clone(item),
-        children: fn(childrenMap.get(item[key]) ?? [])
-      }));
-    };
-    const rootItems = this.filter((item1) => item1[parentKey] == null);
-    return fn(rootItems);
-  },
-  distinct(options) {
-    const keptIndices = getDistinctIndices(this, options);
-    return Array.from(keptIndices).map((i) => this[i]);
-  },
-  orderBy(selector) {
-    return [...this].sort((p, n) => {
-      const pp = selector == null ? p : selector(p);
-      const pn = selector == null ? n : selector(n);
-      return compareForOrder(pp, pn, false);
-    });
-  },
-  orderByDesc(selector) {
-    return [...this].sort((p, n) => {
-      const pp = selector == null ? p : selector(p);
-      const pn = selector == null ? n : selector(n);
-      return compareForOrder(pp, pn, true);
-    });
-  },
-  diffs(target, options) {
-    const result = [];
-    const uncheckedTarget = [...target];
-    const uncheckedTargetSet = new Set(uncheckedTarget);
-    const hasKeys = (options == null ? void 0 : options.keys) !== void 0 && options.keys.length > 0;
-    const excludeOpts = { topLevelExcludes: options == null ? void 0 : options.excludes };
-    const keyIndexedTarget = hasKeys ? /* @__PURE__ */ new Map() : void 0;
-    if (keyIndexedTarget) {
-      for (const targetItem of uncheckedTarget) {
-        const keyStr = JSON.stringify(
-          options.keys.map((k) => targetItem[k])
-        );
-        const arr = keyIndexedTarget.get(keyStr);
-        if (arr) {
-          arr.push(targetItem);
-        } else {
-          keyIndexedTarget.set(keyStr, [targetItem]);
+        else {
+            return this[this.length - 1];
         }
-      }
-    }
-    for (const sourceItem of this) {
-      let sameTarget;
-      let sameKeyTarget;
-      for (const targetItem of uncheckedTarget) {
-        if (!uncheckedTargetSet.has(targetItem)) continue;
-        if (equal(targetItem, sourceItem, excludeOpts)) {
-          sameTarget = targetItem;
-          break;
+    },
+    filterExists() {
+        return this.filter((item) => item != null);
+    },
+    ofType(type) {
+        // PrimitiveTypeStr 경우
+        if (typeof type === "string") {
+            return this.filter((item) => {
+                switch (type) {
+                    case "string":
+                        return typeof item === "string";
+                    case "number":
+                        return typeof item === "number";
+                    case "boolean":
+                        return typeof item === "boolean";
+                    case "DateTime":
+                        return item instanceof DateTime;
+                    case "DateOnly":
+                        return item instanceof DateOnly;
+                    case "Time":
+                        return item instanceof Time;
+                    case "Uuid":
+                        return item instanceof Uuid;
+                    case "Bytes":
+                        return item instanceof Uint8Array;
+                    default: {
+                        // 완전성 검사: PrimitiveTypeStr에 새 타입이 추가되면 컴파일 에러 발생
+                        const _exhaustive = type;
+                        throw new ArgumentError(`지원하지 않는 타입: ${_exhaustive}`);
+                    }
+                }
+            });
         }
-      }
-      if (sameTarget === void 0 && keyIndexedTarget) {
-        const sourceKeyStr = JSON.stringify(
-          options.keys.map((k) => sourceItem[k])
-        );
-        const candidates = keyIndexedTarget.get(sourceKeyStr);
-        if (candidates && candidates.length > 0) {
-          sameKeyTarget = candidates.find((c) => uncheckedTargetSet.has(c));
+        // Type<N> (생성자) 경우
+        return this.filter((item) => item instanceof type || item?.constructor === type);
+    },
+    async mapAsync(selector) {
+        const result = [];
+        for (let i = 0; i < this.length; i++) {
+            result.push(await selector(this[i], i));
         }
-      }
-      if (sameTarget !== void 0) {
-        uncheckedTargetSet.delete(sameTarget);
-      } else if (sameKeyTarget !== void 0) {
-        result.push({ source: sourceItem, target: sameKeyTarget });
-        uncheckedTargetSet.delete(sameKeyTarget);
-      } else {
-        result.push({ source: sourceItem, target: void 0 });
-      }
-    }
-    for (const uncheckedTargetItem of uncheckedTargetSet) {
-      result.push({ source: void 0, target: uncheckedTargetItem });
-    }
-    return result;
-  },
-  oneWayDiffs(orgItems, keyPropNameOrGetValFn, options) {
-    const orgItemMap = orgItems instanceof Map ? orgItems : orgItems.toMap(
-      (orgItem) => typeof keyPropNameOrGetValFn === "function" ? keyPropNameOrGetValFn(orgItem) : orgItem[keyPropNameOrGetValFn]
-    );
-    const includeSame = (options == null ? void 0 : options.includeSame) ?? false;
-    const diffs = [];
-    for (const item of this) {
-      const keyValue = typeof keyPropNameOrGetValFn === "function" ? keyPropNameOrGetValFn(item) : item[keyPropNameOrGetValFn];
-      if (keyValue == null) {
-        diffs.push({ type: "create", item, orgItem: void 0 });
-        continue;
-      }
-      const orgItem = orgItemMap.get(keyValue);
-      if (!orgItem) {
-        diffs.push({ type: "create", item, orgItem: void 0 });
-        continue;
-      }
-      if (equal(orgItem, item, {
-        topLevelExcludes: options == null ? void 0 : options.excludes,
-        topLevelIncludes: options == null ? void 0 : options.includes
-      })) {
-        if (includeSame) {
-          diffs.push({ type: "same", item, orgItem });
+        return result;
+    },
+    mapMany(selector) {
+        const arr = selector ? this.map(selector) : this;
+        return arr.flat().filterExists();
+    },
+    async mapManyAsync(selector) {
+        const arr = selector !== undefined ? await this.mapAsync(selector) : this;
+        return arr.mapMany();
+    },
+    parallelAsync(fn) {
+        return Promise.all(this.map(fn));
+    },
+    // key 기준으로 array 그룹화
+    // 성능 고려사항:
+    // - 원시 key (string, number 등): O(n) - Map 기반
+    // - 객체 key: O(n²) - objEqual 비교
+    groupBy(keySelector, valueSelector) {
+        const result = [];
+        // 원시 key 최적화를 위한 Map (key 문자열 -> result index)
+        const primitiveKeyIndex = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const keyObj = keySelector(this[i], i);
+            const valueObj = valueSelector !== undefined ? valueSelector(this[i], i) : this[i];
+            // 원시 key는 Map을 사용하여 O(n)으로 처리
+            if (keyObj == null || typeof keyObj !== "object") {
+                const keyStr = typeof keyObj + ":" + String(keyObj);
+                const existingIndex = primitiveKeyIndex.get(keyStr);
+                if (existingIndex !== undefined) {
+                    result[existingIndex].values.push(valueObj);
+                }
+                else {
+                    primitiveKeyIndex.set(keyStr, result.length);
+                    result.push({ key: keyObj, values: [valueObj] });
+                }
+                continue;
+            }
+            // 객체 key는 기존 방식 O(n²) 사용
+            const existsRecord = result.find((item) => equal(item.key, keyObj));
+            if (existsRecord !== undefined) {
+                existsRecord.values.push(valueObj);
+            }
+            else {
+                result.push({ key: keyObj, values: [valueObj] });
+            }
         }
-        continue;
-      }
-      diffs.push({ type: "update", item, orgItem });
-    }
-    return diffs;
-  },
-  merge(target, options) {
-    const diffs = this.diffs(target, options);
-    const result = clone(this);
-    const sourceIndexMap = /* @__PURE__ */ new Map();
-    for (let i = 0; i < this.length; i++) {
-      sourceIndexMap.set(this[i], i);
-    }
-    for (const diff of diffs) {
-      if (diff.source !== void 0 && diff.target !== void 0) {
-        const sourceIndex = sourceIndexMap.get(diff.source);
-        if (sourceIndex === void 0) {
-          throw new SdError("Unexpected error: source item not found in merge.");
+        return result;
+    },
+    toMap(keySelector, valueSelector) {
+        const result = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const keyObj = keySelector(item, i);
+            const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
+            if (result.has(keyObj)) {
+                throw new ArgumentError("중복된 key입니다.", { duplicatedKey: keyObj });
+            }
+            result.set(keyObj, valueObj);
         }
-        result[sourceIndex] = merge(diff.source, diff.target);
-      } else if (diff.target !== void 0) {
-        result.push(diff.target);
-      }
-    }
-    return result;
-  },
-  sum(selector) {
-    let result = 0;
-    for (let i = 0; i < this.length; i++) {
-      const item = selector !== void 0 ? selector(this[i], i) : this[i];
-      if (typeof item !== "number") {
-        throw new ArgumentError("sum can only be used with numbers.", {
-          type: typeof item
-        });
-      }
-      result += item;
-    }
-    return result;
-  },
-  min(selector) {
-    let result;
-    for (let i = 0; i < this.length; i++) {
-      const item = selector !== void 0 ? selector(this[i], i) : this[i];
-      if (typeof item !== "number" && typeof item !== "string") {
-        throw new ArgumentError("min can only be used with numbers/strings.", {
-          type: typeof item
+        return result;
+    },
+    async toMapAsync(keySelector, valueSelector) {
+        const result = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const keyObj = await keySelector(item, i);
+            const valueObj = valueSelector !== undefined ? await valueSelector(item, i) : item;
+            if (result.has(keyObj)) {
+                throw new ArgumentError("중복된 key입니다.", { duplicatedKey: keyObj });
+            }
+            result.set(keyObj, valueObj);
+        }
+        return result;
+    },
+    toArrayMap(keySelector, valueSelector) {
+        const result = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const keyObj = keySelector(item, i);
+            const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
+            const arr = result.getOrCreate(keyObj, []);
+            arr.push(valueObj);
+        }
+        return result;
+    },
+    toSetMap(keySelector, valueSelector) {
+        const result = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const keyObj = keySelector(item, i);
+            const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
+            const set = result.getOrCreate(keyObj, new Set());
+            set.add(valueObj);
+        }
+        return result;
+    },
+    toMapValues(keySelector, valueSelector) {
+        const itemsMap = new Map();
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const keyObj = keySelector(item, i);
+            const arr = itemsMap.getOrCreate(keyObj, []);
+            arr.push(item);
+        }
+        const result = new Map();
+        for (const key of itemsMap.keys()) {
+            result.set(key, valueSelector(itemsMap.get(key)));
+        }
+        return result;
+    },
+    toObject(keySelector, valueSelector) {
+        const result = {};
+        for (let i = 0; i < this.length; i++) {
+            const item = this[i];
+            const key = keySelector(item, i);
+            const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
+            // undefined 값은 "없음"으로 처리하여 덮어쓰기 허용
+            if (result[key] !== undefined) {
+                throw new ArgumentError("중복된 key입니다.", { duplicatedKey: key });
+            }
+            result[key] = valueObj;
+        }
+        return result;
+    },
+    toTree(key, parentKey) {
+        // O(n) 최적화: Map 기반 인덱싱
+        const childrenMap = this.toArrayMap((item) => item[parentKey]);
+        const fn = (items) => {
+            return items.map((item) => ({
+                ...clone(item),
+                children: fn(childrenMap.get(item[key]) ?? []),
+            }));
+        };
+        const rootItems = this.filter((item1) => item1[parentKey] == null);
+        return fn(rootItems);
+    },
+    distinct(options) {
+        const keptIndices = getDistinctIndices(this, options);
+        return Array.from(keptIndices).map((i) => this[i]);
+    },
+    orderBy(selector) {
+        return [...this].sort((p, n) => {
+            const pp = selector == null ? p : selector(p);
+            const pn = selector == null ? n : selector(n);
+            return compareForOrder(pp, pn, false);
         });
-      }
-      if (result === void 0 || result > item) {
-        result = item;
-      }
-    }
-    return result;
-  },
-  max(selector) {
-    let result;
-    for (let i = 0; i < this.length; i++) {
-      const item = selector !== void 0 ? selector(this[i], i) : this[i];
-      if (typeof item !== "number" && typeof item !== "string") {
-        throw new ArgumentError("max can only be used with numbers/strings.", {
-          type: typeof item
+    },
+    orderByDesc(selector) {
+        return [...this].sort((p, n) => {
+            const pp = selector == null ? p : selector(p);
+            const pn = selector == null ? n : selector(n);
+            return compareForOrder(pp, pn, true);
         });
-      }
-      if (result === void 0 || result < item) {
-        result = item;
-      }
-    }
-    return result;
-  },
-  shuffle() {
-    if (this.length <= 1) {
-      return [...this];
-    }
-    const result = [...this];
-    for (let i = result.length - 1; i > 0; i--) {
-      const j = Math.floor(Math.random() * (i + 1));
-      [result[i], result[j]] = [result[j], result[i]];
-    }
-    return result;
-  }
+    },
+    diffs(target, options) {
+        const result = [];
+        const uncheckedTarget = [...target];
+        const uncheckedTargetSet = new Set(uncheckedTarget);
+        const hasKeys = options?.keys !== undefined && options.keys.length > 0;
+        const excludeOpts = { topLevelExcludes: options?.excludes };
+        // keys 옵션이 제공되면 target을 Map으로 사전 인덱싱하여 O(n×m) → O(n+m)으로 개선
+        // 같은 key 값을 가진 target이 여러 개 존재할 수 있으므로 array로 저장
+        const keyIndexedTarget = hasKeys ? new Map() : undefined;
+        if (keyIndexedTarget) {
+            for (const targetItem of uncheckedTarget) {
+                const keyStr = JSON.stringify(options.keys.map((k) => targetItem[k]));
+                const arr = keyIndexedTarget.get(keyStr);
+                if (arr) {
+                    arr.push(targetItem);
+                }
+                else {
+                    keyIndexedTarget.set(keyStr, [targetItem]);
+                }
+            }
+        }
+        for (const sourceItem of this) {
+            // 전체 일치(sameTarget)를 우선하고, 없으면 key 일치(sameKeyTarget)를 검색
+            let sameTarget;
+            let sameKeyTarget;
+            // Set 기반 건너뛰기로 이미 매칭된 항목 스킵 (O(n) splice 제거 방지)
+            for (const targetItem of uncheckedTarget) {
+                if (!uncheckedTargetSet.has(targetItem))
+                    continue;
+                if (equal(targetItem, sourceItem, excludeOpts)) {
+                    sameTarget = targetItem;
+                    break;
+                }
+            }
+            // 전체 일치가 없고 keys 옵션이 있으면 Map에서 O(1) 조회 수행
+            if (sameTarget === undefined && keyIndexedTarget) {
+                const sourceKeyStr = JSON.stringify(options.keys.map((k) => sourceItem[k]));
+                const candidates = keyIndexedTarget.get(sourceKeyStr);
+                if (candidates && candidates.length > 0) {
+                    // uncheckedTargetSet에서 O(1) 조회로 남은 첫 번째 항목 선택
+                    sameKeyTarget = candidates.find((c) => uncheckedTargetSet.has(c));
+                }
+            }
+            if (sameTarget !== undefined) {
+                uncheckedTargetSet.delete(sameTarget);
+            }
+            else if (sameKeyTarget !== undefined) {
+                result.push({ source: sourceItem, target: sameKeyTarget });
+                uncheckedTargetSet.delete(sameKeyTarget);
+            }
+            else {
+                result.push({ source: sourceItem, target: undefined });
+            }
+        }
+        for (const uncheckedTargetItem of uncheckedTargetSet) {
+            result.push({ source: undefined, target: uncheckedTargetItem });
+        }
+        return result;
+    },
+    oneWayDiffs(orgItems, keyPropNameOrGetValFn, options) {
+        const orgItemMap = orgItems instanceof Map
+            ? orgItems
+            : orgItems.toMap((orgItem) => typeof keyPropNameOrGetValFn === "function"
+                ? keyPropNameOrGetValFn(orgItem)
+                : orgItem[keyPropNameOrGetValFn]);
+        const includeSame = options?.includeSame ?? false;
+        const diffs = [];
+        for (const item of this) {
+            const keyValue = typeof keyPropNameOrGetValFn === "function"
+                ? keyPropNameOrGetValFn(item)
+                : item[keyPropNameOrGetValFn];
+            if (keyValue == null) {
+                diffs.push({ type: "create", item, orgItem: undefined });
+                continue;
+            }
+            const orgItem = orgItemMap.get(keyValue);
+            if (!orgItem) {
+                diffs.push({ type: "create", item, orgItem: undefined });
+                continue;
+            }
+            if (equal(orgItem, item, {
+                topLevelExcludes: options?.excludes,
+                topLevelIncludes: options?.includes,
+            })) {
+                if (includeSame) {
+                    diffs.push({ type: "same", item, orgItem });
+                }
+                continue;
+            }
+            diffs.push({ type: "update", item, orgItem });
+        }
+        return diffs;
+    },
+    merge(target, options) {
+        const diffs = this.diffs(target, options);
+        const result = clone(this);
+        // source 항목의 원래 index를 사전 계산하여 O(n) 조회를 O(1)로 개선
+        const sourceIndexMap = new Map();
+        for (let i = 0; i < this.length; i++) {
+            sourceIndexMap.set(this[i], i);
+        }
+        for (const diff of diffs) {
+            // 업데이트 시
+            if (diff.source !== undefined && diff.target !== undefined) {
+                const sourceIndex = sourceIndexMap.get(diff.source);
+                if (sourceIndex === undefined) {
+                    throw new SdError("예상치 못한 오류: merge에서 source 항목을 찾을 수 없습니다.");
+                }
+                result[sourceIndex] = merge(diff.source, diff.target);
+            }
+            // 추가 시
+            else if (diff.target !== undefined) {
+                result.push(diff.target);
+            }
+        }
+        return result;
+    },
+    sum(selector) {
+        let result = 0;
+        for (let i = 0; i < this.length; i++) {
+            const item = selector !== undefined ? selector(this[i], i) : this[i];
+            if (typeof item !== "number") {
+                throw new ArgumentError("sum은 숫자에만 사용할 수 있습니다.", {
+                    type: typeof item,
+                });
+            }
+            result += item;
+        }
+        return result;
+    },
+    min(selector) {
+        let result;
+        for (let i = 0; i < this.length; i++) {
+            const item = selector !== undefined ? selector(this[i], i) : this[i];
+            if (typeof item !== "number" && typeof item !== "string") {
+                throw new ArgumentError("min은 숫자/문자열에만 사용할 수 있습니다.", {
+                    type: typeof item,
+                });
+            }
+            if (result === undefined || result > item) {
+                result = item;
+            }
+        }
+        return result;
+    },
+    max(selector) {
+        let result;
+        for (let i = 0; i < this.length; i++) {
+            const item = selector !== undefined ? selector(this[i], i) : this[i];
+            if (typeof item !== "number" && typeof item !== "string") {
+                throw new ArgumentError("max는 숫자/문자열에만 사용할 수 있습니다.", {
+                    type: typeof item,
+                });
+            }
+            if (result === undefined || result < item) {
+                result = item;
+            }
+        }
+        return result;
+    },
+    shuffle() {
+        if (this.length <= 1) {
+            return [...this];
+        }
+        const result = [...this];
+        for (let i = result.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [result[i], result[j]] = [result[j], result[i]];
+        }
+        return result;
+    },
 };
 const arrayMutableExtensions = {
-  distinctThis(options) {
-    const keptIndices = getDistinctIndices(this, options);
-    const indicesToRemove = [];
-    for (let i = 0; i < this.length; i++) {
-      if (!keptIndices.has(i)) {
-        indicesToRemove.push(i);
-      }
-    }
-    for (let i = indicesToRemove.length - 1; i >= 0; i--) {
-      this.splice(indicesToRemove[i], 1);
-    }
-    return this;
-  },
-  orderByThis(selector) {
-    return this.sort((p, n) => {
-      const pp = (selector == null ? void 0 : selector(p)) ?? p;
-      const pn = (selector == null ? void 0 : selector(n)) ?? n;
-      return compareForOrder(pp, pn, false);
-    });
-  },
-  orderByDescThis(selector) {
-    return this.sort((p, n) => {
-      const pp = (selector == null ? void 0 : selector(p)) ?? p;
-      const pn = (selector == null ? void 0 : selector(n)) ?? n;
-      return compareForOrder(pp, pn, true);
-    });
-  },
-  insert(index, ...items) {
-    this.splice(index, 0, ...items);
-    return this;
-  },
-  remove(itemOrSelector) {
-    const shouldRemove = typeof itemOrSelector === "function" ? itemOrSelector : (item) => item === itemOrSelector;
-    for (let i = this.length - 1; i >= 0; i--) {
-      if (shouldRemove(this[i], i)) {
-        this.splice(i, 1);
-      }
-    }
-    return this;
-  },
-  toggle(item) {
-    if (this.includes(item)) {
-      this.remove(item);
-    } else {
-      this.push(item);
-    }
-    return this;
-  },
-  clear() {
-    return this.remove(() => true);
-  }
+    distinctThis(options) {
+        const keptIndices = getDistinctIndices(this, options);
+        const indicesToRemove = [];
+        for (let i = 0; i < this.length; i++) {
+            if (!keptIndices.has(i)) {
+                indicesToRemove.push(i);
+            }
+        }
+        // index 변동을 방지하기 위해 역순으로 제거
+        for (let i = indicesToRemove.length - 1; i >= 0; i--) {
+            this.splice(indicesToRemove[i], 1);
+        }
+        return this;
+    },
+    orderByThis(selector) {
+        return this.sort((p, n) => {
+            const pp = selector?.(p) ?? p;
+            const pn = selector?.(n) ?? n;
+            return compareForOrder(pp, pn, false);
+        });
+    },
+    orderByDescThis(selector) {
+        return this.sort((p, n) => {
+            const pp = selector?.(p) ?? p;
+            const pn = selector?.(n) ?? n;
+            return compareForOrder(pp, pn, true);
+        });
+    },
+    insert(index, ...items) {
+        this.splice(index, 0, ...items);
+        return this;
+    },
+    remove(itemOrSelector) {
+        const shouldRemove = typeof itemOrSelector === "function"
+            ? itemOrSelector
+            : (item) => item === itemOrSelector;
+        // index 변경 문제를 방지하기 위한 역순 순회 (O(n) 성능)
+        for (let i = this.length - 1; i >= 0; i--) {
+            if (shouldRemove(this[i], i)) {
+                this.splice(i, 1);
+            }
+        }
+        return this;
+    },
+    toggle(item) {
+        if (this.includes(item)) {
+            this.remove(item);
+        }
+        else {
+            this.push(item);
+        }
+        return this;
+    },
+    clear() {
+        return this.remove(() => true);
+    },
 };
 for (const [name, fn] of Object.entries({
-  ...arrayReadonlyExtensions,
-  ...arrayMutableExtensions
+    ...arrayReadonlyExtensions,
+    ...arrayMutableExtensions,
 })) {
-  Object.defineProperty(Array.prototype, name, {
-    value: fn,
-    enumerable: false,
-    writable: true,
-    configurable: true
-  });
+    Object.defineProperty(Array.prototype, name, {
+        value: fn,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
 }
-//# sourceMappingURL=arr-ext.js.map
+//# sourceMappingURL=arr-ext.js.map