@simplysm/core-common 13.0.69 → 13.0.71

package/src/extensions/arr-ext.ts

@@ -1,7 +1,7 @@
 /**
- * Array 확장 메서드
+ * Array extension methods
  *
- * @remarks 각 메서드의 TSDoc은 타입 정의 파일(arr-ext.types.ts) 참조
+ * @remarks See type definition file (arr-ext.types.ts) for TSDoc of each method
  */
 
 import "./map-ext";
@@ -22,13 +22,13 @@ import type {
   TreeArray,
 } from "./arr-ext.types";
 
-//#region 구현
+//#region Implementation
 
 const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
   single<T>(predicate?: (item: T, index: number) => boolean): T | undefined {
     const arr = predicate !== undefined ? this.filter(predicate) : this;
     if (arr.length > 1) {
-      throw new ArgumentError("복수의 결과물이 있습니다.", { count: arr.length });
+      throw new ArgumentError("Multiple results found.", { count: arr.length });
     }
     return arr[0];
   },
@@ -66,7 +66,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
   },
 
   ofType<T, N extends T>(type: PrimitiveTypeStr | Type<N>): N[] {
-    // PrimitiveTypeStr인 경우
+    // PrimitiveTypeStr case
     if (typeof type === "string") {
       return this.filter((item) => {
         switch (type) {
@@ -87,15 +87,15 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
           case "Bytes":
             return item instanceof Uint8Array;
           default: {
-            // exhaustive check: PrimitiveTypeStr에 새 타입 추가 시 컴파일 에러 발생
+            // exhaustive check: Compilation error when a new type is added to PrimitiveTypeStr
             const _exhaustive: never = type;
-            throw new ArgumentError(`지원하지 않는 타입: ${_exhaustive}`);
+            throw new ArgumentError(`Unsupported type: ${_exhaustive}`);
           }
         }
       }) as N[];
     }
 
-    // Type<N> (생성자)인 경우
+    // Type<N> (constructor) case
     return this.filter((item) => item instanceof type || item?.constructor === type) as N[];
   },
 
@@ -121,10 +121,10 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     return Promise.all(this.map(fn));
   },
 
-  // 배열을 키별로 그룹화
-  // 성능 고려사항:
-  // - primitive 키 (string, number 등): O(n) - Map 기반
-  // - 객체 키: O(n²) - objEqual 비교
+  // Group array by key
+  // Performance considerations:
+  // - primitive key (string, number, etc.): O(n) - Map-based
+  // - object key: O(n²) - objEqual comparison
   groupBy<T, K, V>(
     keySelector: (item: T, index: number) => K,
     valueSelector?: (item: T, index: number) => V,
@@ -134,14 +134,14 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
   }[] {
     const result: { key: K; values: (V | T)[] }[] = [];
 
-    // primitive 키 최적화를 위한 Map (키 문자열 -> result 인덱스)
+    // Map for primitive key optimization (key string -> result index)
     const primitiveKeyIndex = new Map<string, number>();
 
     for (let i = 0; i < this.length; i++) {
       const keyObj = keySelector(this[i], i);
       const valueObj = valueSelector !== undefined ? valueSelector(this[i], i) : this[i];
 
-      // primitive 키는 Map으로 O(n) 처리
+      // primitive keys are processed in O(n) using Map
       if (keyObj == null || typeof keyObj !== "object") {
         const keyStr = typeof keyObj + ":" + String(keyObj);
         const existingIndex = primitiveKeyIndex.get(keyStr);
@@ -154,7 +154,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
         continue;
       }
 
-      // 객체 키는 기존 방식 O(n²)
+      // Object keys use the existing approach O(n²)
       const existsRecord = result.find((item) => objEqual(item.key, keyObj));
       if (existsRecord !== undefined) {
         existsRecord.values.push(valueObj);
@@ -179,7 +179,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
       const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
 
       if (result.has(keyObj)) {
-        throw new ArgumentError("키가 중복되었습니다.", { duplicatedKey: keyObj });
+        throw new ArgumentError("Duplicated key.", { duplicatedKey: keyObj });
       }
       result.set(keyObj, valueObj);
     }
@@ -200,7 +200,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
       const valueObj = valueSelector !== undefined ? await valueSelector(item, i) : item;
 
       if (result.has(keyObj)) {
-        throw new ArgumentError("키가 중복되었습니다.", { duplicatedKey: keyObj });
+        throw new ArgumentError("Duplicated key.", { duplicatedKey: keyObj });
       }
       result.set(keyObj, valueObj);
     }
@@ -282,9 +282,9 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
       const key = keySelector(item, i);
       const valueObj = valueSelector !== undefined ? valueSelector(item, i) : item;
 
-      // undefined 값은 "없음"으로 취급하여 덮어쓰기 허용
+      // undefined values are treated as "none", allowing overwrite
       if (result[key] !== undefined) {
-        throw new ArgumentError("키가 중복되었습니다.", { duplicatedKey: key });
+        throw new ArgumentError("Duplicated key.", { duplicatedKey: key });
       }
       result[key] = valueObj;
     }
@@ -293,7 +293,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
   },
 
   toTree<T, K extends keyof T, P extends keyof T>(key: K, parentKey: P): TreeArray<T>[] {
-    // O(n) 최적화: 맵 기반 인덱싱
+    // O(n) optimization: Map-based indexing
     const childrenMap = this.toArrayMap((item) => item[parentKey]);
 
     const fn = (items: T[]): TreeArray<T>[] => {
@@ -310,13 +310,13 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
   distinct<T>(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
   ): T[] {
-    // 옵션 정규화
+    // Normalize options
     const opts = typeof options === "boolean" ? { matchAddress: options } : (options ?? {});
 
-    // matchAddress: Set 기반 O(n)
+    // matchAddress: Set-based O(n)
     if (opts.matchAddress === true) return [...new Set(this)];
 
-    // keyFn 제공 시: 커스텀 키 기반 O(n)
+    // keyFn provided: custom key-based O(n)
     if (opts.keyFn) {
       const seen = new Set<string | number>();
       const result: T[] = [];
@@ -330,17 +330,17 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
       return result;
     }
 
-    // 기본: 타입별 처리
+    // Default: type-based processing
     const seen = new Map<string, T>();
-    const seenRefs = new Set<symbol | ((...args: unknown[]) => unknown)>(); // symbol/function용 O(n) 처리
+    const seenRefs = new Set<symbol | ((...args: unknown[]) => unknown)>(); // O(n) processing for symbol/function
     const result: T[] = [];
 
     for (const item of this) {
-      // primitive 타입은 빠른 경로
+      // primitive types take the fast path
       if (item === null || typeof item !== "object") {
         const type = typeof item;
 
-        // symbol, function은 Set으로 identity 비교 (O(n))
+        // symbol, function use Set for identity comparison (O(n))
         if (type === "symbol" || type === "function") {
           if (!seenRefs.has(item)) {
             seenRefs.add(item);
@@ -349,7 +349,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
           continue;
         }
 
-        // 나머지 primitive는 타입 prefix + 특수 케이스 처리
+        // Other primitives: type prefix + special case handling
         let key = type + ":";
         if (Object.is(item, -0)) {
           key += "-0";
@@ -406,8 +406,8 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     const hasKeys = options?.keys !== undefined && options.keys.length > 0;
     const excludeOpts = { topLevelExcludes: options?.excludes };
 
-    // keys 옵션이 있는 경우 target을 keys 기준으로 Map에 미리 인덱싱하여 O(n×m) → O(n+m) 개선
-    // 키 값이 같은 target이 여러 개 있을 수 있으므로 배열로 저장
+    // If keys option is provided, pre-index target by keys in Map to improve O(n×m) → O(n+m)
+    // Multiple targets with the same key value can exist, so store as array
     const keyIndexedTarget = hasKeys ? new Map<string, P[]>() : undefined;
 
     if (keyIndexedTarget) {
@@ -425,11 +425,11 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     }
 
     for (const sourceItem of this) {
-      // 전체 일치(sameTarget) 우선, 없으면 키 일치(sameKeyTarget) 검색
+      // Prioritize full match (sameTarget), otherwise search for key match (sameKeyTarget)
       let sameTarget: P | undefined;
       let sameKeyTarget: P | undefined;
 
-      // Set 기반 건너뛰기로 이미 매칭된 항목 스킵 (splice O(n) 제거)
+      // Skip already matched items using Set-based skipping (avoid O(n) splice removal)
       for (const targetItem of uncheckedTarget) {
         if (!uncheckedTargetSet.has(targetItem)) continue;
         if (objEqual(targetItem, sourceItem, excludeOpts)) {
@@ -438,14 +438,14 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
         }
       }
 
-      // 전체 일치가 없고 keys 옵션이 있으면 Map에서 O(1) 조회
+      // If no full match and keys option exists, perform O(1) lookup in Map
       if (sameTarget === undefined && keyIndexedTarget) {
         const sourceKeyStr = JSON.stringify(
           options!.keys!.map((k) => (sourceItem as Record<string, unknown>)[k]),
         );
         const candidates = keyIndexedTarget.get(sourceKeyStr);
         if (candidates && candidates.length > 0) {
-          // uncheckedTargetSet에서 O(1) 조회로 아직 남아있는 첫 번째 항목 선택
+          // Select first remaining item using O(1) lookup in uncheckedTargetSet
           sameKeyTarget = candidates.find((c) => uncheckedTargetSet.has(c));
         }
       }
@@ -531,22 +531,22 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
 
     const result: (T | P | (T & P))[] = objClone(this);
 
-    // source 항목의 원본 인덱스를 미리 계산하여 O(n) 검색을 O(1)로 개선
+    // Pre-calculate original index of source items to improve O(n) lookup to O(1)
     const sourceIndexMap = new Map<T, number>();
     for (let i = 0; i < this.length; i++) {
       sourceIndexMap.set(this[i], i);
     }
 
     for (const diff of diffs) {
-      // 변경시
+      // When updating
       if (diff.source !== undefined && diff.target !== undefined) {
         const sourceIndex = sourceIndexMap.get(diff.source);
         if (sourceIndex === undefined) {
-          throw new SdError("예상치 못한 오류: merge에서 source 항목을 찾을 수 없습니다.");
+          throw new SdError("Unexpected error: source item not found in merge.");
         }
         result[sourceIndex] = objMerge(diff.source, diff.target);
       }
-      // 추가시
+      // When adding
       else if (diff.target !== undefined) {
         result.push(diff.target);
       }
@@ -560,7 +560,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     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 은 number 에 대해서만 사용할 수 있습니다.", {
+        throw new ArgumentError("sum can only be used with numbers.", {
           type: typeof item,
         });
       }
@@ -575,7 +575,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     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 은 number/string 에 대해서만 사용할 수 있습니다.", {
+        throw new ArgumentError("min can only be used with numbers/strings.", {
           type: typeof item,
         });
       }
@@ -592,7 +592,7 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     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 은 number/string 에 대해서만 사용할 수 있습니다.", {
+        throw new ArgumentError("max can only be used with numbers/strings.", {
           type: typeof item,
         });
       }
@@ -622,11 +622,11 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
   distinctThis<T>(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
   ): T[] {
-    // 옵션 정규화
+    // Normalize options
     const opts = typeof options === "boolean" ? { matchAddress: options } : (options ?? {});
 
-    // matchAddress: Set 기반 O(n)
-    // 첫 번째 등장한 요소를 유지하기 위해 정방향 순회 후 제거할 인덱스 수집
+    // matchAddress: Set-based O(n)
+    // To preserve first occurrence, collect indices to remove after forward traversal
     if (opts.matchAddress === true) {
       const seen = new Set<T>();
       const toRemove: number[] = [];
@@ -637,15 +637,15 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
           seen.add(this[i]);
         }
       }
-      // 역순으로 제거 (인덱스 변화 방지)
+      // Remove in reverse order (prevent index changes)
       for (let i = toRemove.length - 1; i >= 0; i--) {
         this.splice(toRemove[i], 1);
       }
       return this;
     }
 
-    // keyFn 제공 시: 커스텀 키 기반 O(n)
-    // 첫 번째 등장한 요소를 유지하기 위해 정방향 순회 후 제거할 인덱스 수집
+    // keyFn provided: custom key-based O(n)
+    // To preserve first occurrence, collect indices to remove after forward traversal
     if (opts.keyFn) {
       const seen = new Set<string | number>();
       const toRemove: number[] = [];
@@ -657,14 +657,14 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
           seen.add(key);
         }
       }
-      // 역순으로 제거 (인덱스 변화 방지)
+      // Remove in reverse order (prevent index changes)
       for (let i = toRemove.length - 1; i >= 0; i--) {
         this.splice(toRemove[i], 1);
       }
       return this;
     }
 
-    // 기본: 타입별 처리 (primitive 최적화)
+    // Default: type-based processing (primitive optimization)
     const seen = new Map<string, T>();
     const seenRefs = new Set<symbol | ((...args: unknown[]) => unknown)>();
     const toRemoveSet = new Set<number>();
@@ -672,11 +672,11 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
     for (let i = 0; i < this.length; i++) {
       const item = this[i];
 
-      // primitive 타입은 빠른 경로 O(n)
+      // primitive types take the fast path O(n)
       if (item === null || typeof item !== "object") {
         const type = typeof item;
 
-        // symbol, function은 Set으로 identity 비교
+        // symbol, function use Set for identity comparison
         if (type === "symbol" || type === "function") {
           if (seenRefs.has(item)) {
             toRemoveSet.add(i);
@@ -686,7 +686,7 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
           continue;
         }
 
-        // 나머지 primitive는 타입 prefix + 특수 케이스 처리
+        // Other primitives: type prefix + special case handling
         let key = type + ":";
         if (Object.is(item, -0)) {
           key += "-0";
@@ -702,10 +702,10 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
         continue;
       }
 
-      // 객체는 깊은 비교 O(n²) - 제거되지 않은 이전 항목들과 비교
+      // Objects: deep comparison O(n²) - compare with previous non-removed items
       let hasDuplicateBefore = false;
       for (let j = 0; j < i; j++) {
-        // toRemoveSet에 있는 인덱스는 건너뜀 (O(1) 조회)
+        // Skip indices in toRemoveSet (O(1) lookup)
         if (toRemoveSet.has(j)) continue;
         if (objEqual(this[j], item)) {
           hasDuplicateBefore = true;
@@ -717,7 +717,7 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
       }
     }
 
-    // 역순으로 제거 (인덱스 변화 방지)
+    // Remove in reverse order (prevent index changes)
     const toRemoveArr = Array.from(toRemoveSet).sort((a, b) => b - a);
     for (const idx of toRemoveArr) {
       this.splice(idx, 1);
@@ -757,7 +757,7 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
         ? (itemOrSelector as (item: T, index: number) => boolean)
         : (item: T) => item === itemOrSelector;
 
-    // 역방향 순회로 인덱스 변경 문제 방지 (O(n) 성능)
+    // Reverse traversal to prevent index change issues (O(n) performance)
     for (let i = this.length - 1; i >= 0; i--) {
       if (shouldRemove(this[i], i)) {
         this.splice(i, 1);
@@ -795,7 +795,7 @@ for (const [name, fn] of Object.entries({
 
 //#endregion
 
-//#region 타입 선언
+//#region Type Declarations
 
 declare global {
   interface ReadonlyArray<T> extends ReadonlyArrayExt<T> {}

package/src/extensions/arr-ext.types.ts

@@ -1,5 +1,5 @@
 /**
- * Array 확장 타입 정의
+ * Array extension type definitions
  */
 
 import type { PrimitiveTypeMap, PrimitiveTypeStr, Type } from "../common.types";
@@ -7,71 +7,71 @@ import type { DateTime } from "../types/date-time";
 import type { DateOnly } from "../types/date-only";
 import type { Time } from "../types/time";
 
-//#region 인터페이스
+//#region Interfaces
 
 export interface ReadonlyArrayExt<TItem> {
   /**
-   * 조건에 맞는 단일 요소 반환
-   * @param predicate 필터 조건 (생략 시 배열 전체 대상)
-   * @returns 요소가 없으면 undefined
-   * @throws ArgumentError 조건에 맞는 요소가 2개 이상이면 발생
+   * Return single element matching condition
+   * @param predicate Filter condition (if omitted, entire array is target)
+   * @returns undefined if element does not exist
+   * @throws ArgumentError If 2 or more elements match condition
    */
   single(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
   /**
-   * 첫 번째 요소 반환
-   * @param predicate 필터 조건 (생략 시 첫 번째 요소 반환)
-   * @returns 요소가 없으면 undefined
+   * Return first element
+   * @param predicate Filter condition (if omitted, returns first element)
+   * @returns undefined if element does not exist
    */
   first(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
-  /** 비동기 필터 (순차 실행) */
+  /** Async filter (sequential execution) */
   filterAsync(predicate: (item: TItem, index: number) => Promise<boolean>): Promise<TItem[]>;
 
   /**
-   * 마지막 요소 반환
-   * @param predicate 필터 조건 (생략 시 마지막 요소 반환)
-   * @returns 요소가 없으면 undefined
+   * Return last element
+   * @param predicate Filter condition (if omitted, returns last element)
+   * @returns undefined if element does not exist
    */
   last(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
-  /** null/undefined 제거 */
+  /** Remove null/undefined */
   filterExists(): NonNullable<TItem>[];
 
-  /** 특정 타입의 요소만 필터링 (PrimitiveTypeStr 또는 생성자 타입) */
+  /** Filter only elements of specific type (PrimitiveTypeStr or constructor type) */
   ofType<K extends PrimitiveTypeStr>(type: K): Extract<TItem, PrimitiveTypeMap[K]>[];
   ofType<N extends TItem>(type: Type<N>): N[];
 
-  /** 비동기 매핑 (순차 실행) */
+  /** Async mapping (sequential execution) */
   mapAsync<R>(selector: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
 
-  /** 중첩 배열 평탄화 */
+  /** Flatten nested array */
   mapMany(): TItem extends readonly (infer U)[] ? U[] : TItem;
 
-  /** 매핑 후 평탄화 */
+  /** Map and then flatten */
   mapMany<R>(selector: (item: TItem, index: number) => R[]): R[];
 
-  /** 비동기 매핑 후 평탄화 (순차 실행) */
+  /** Async mapping and then flatten (sequential execution) */
   mapManyAsync<R>(selector: (item: TItem, index: number) => Promise<R[]>): Promise<R[]>;
 
   /**
-   * 비동기 병렬 처리 (Promise.all 사용)
-   * @note 하나라도 reject되면 전체가 fail-fast로 reject됨 (Promise.all 동작)
+   * Async parallel processing (using Promise.all)
+   * @note If any rejects, entire operation fail-fast rejects (Promise.all behavior)
    */
   parallelAsync<R>(fn: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
 
   /**
-   * 키 기준 그룹화
-   * @param keySelector 그룹 키 선택 함수
-   * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
+   * Group by key
+   * @param keySelector Key selection function for group
+   * @note O(n²) complexity (deep comparison for object key support). If only primitive keys are needed, toArrayMap() is more efficient at O(n)
    */
   groupBy<K>(keySelector: (item: TItem, index: number) => K): { key: K; values: TItem[] }[];
 
   /**
-   * 키 기준 그룹화 (값 변환 포함)
-   * @param keySelector 그룹 키 선택 함수
-   * @param valueSelector 값 변환 함수
-   * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
+   * Group by key (with value transformation)
+   * @param keySelector Key selection function for group
+   * @param valueSelector Value transformation function
+   * @note O(n²) complexity (deep comparison for object key support). If only primitive keys are needed, toArrayMap() is more efficient at O(n)
    */
   groupBy<K, V>(
     keySelector: (item: TItem, index: number) => K,
@@ -121,16 +121,16 @@ export interface ReadonlyArrayExt<TItem> {
   ): Record<string, V>;
 
   /**
-   * 평탄한 배열을 트리 구조로 변환한다
+   * Convert flat array to tree structure
    *
-   * @param keyProp 각 항목의 고유 키 속성명
-   * @param parentKey 부모 항목의 키를 참조하는 속성명
-   * @returns 루트 항목들의 배열 (각 항목에 children 속성 추가)
+   * @param keyProp Unique key property name of each item
+   * @param parentKey Property name referencing parent item's key
+   * @returns Array of root items (each item has children property added)
    *
    * @remarks
-   * - parentKey 값이 null/undefined인 항목이 루트가 된다
-   * - 내부적으로 toArrayMap을 사용하여 O(n) 복잡도로 처리한다
-   * - 원본 항목은 복사되어 children 속성이 추가된다
+   * - Items with null/undefined parentKey value become roots
+   * - Internally uses toArrayMap for O(n) complexity
+   * - Original items are copied with children property added
    *
    * @example
    * ```typescript
@@ -162,9 +162,9 @@ export interface ReadonlyArrayExt<TItem> {
   ): TreeArray<TItem>[];
 
   /**
-   * 중복 제거
-   * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
-   * @note 객체 배열에서 keyFn 없이 사용 시 O(n²) 복잡도. 대량 데이터는 keyFn 사용 권장
+   * Remove duplicates
+   * @param options matchAddress: address comparison (true uses Set), keyFn: custom key function (O(n) performance)
+   * @note O(n²) complexity when used without keyFn on object arrays. Using keyFn is recommended for large data
    */
   distinct(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number },
@@ -179,10 +179,10 @@ export interface ReadonlyArrayExt<TItem> {
   ): TItem[];
 
   /**
-   * 두 배열 비교 (INSERT/DELETE/UPDATE)
-   * @param target 비교 대상 배열
-   * @param options keys: 키 비교용, excludes: 비교 제외 속성
-   * @note target에 중복 키가 있으면 첫 번째 매칭만 사용됨
+   * Compare two arrays (INSERT/DELETE/UPDATE)
+   * @param target Array to compare with
+   * @param options keys: for key comparison, excludes: properties to exclude from comparison
+   * @note If target has duplicate keys, only first match is used
    */
   diffs<TOtherItem>(
     target: TOtherItem[],
@@ -205,9 +205,9 @@ export interface ReadonlyArrayExt<TItem> {
   ): (TItem | TOtherItem | (TItem & TOtherItem))[];
 
   /**
-   * 요소의 합계 반환
-   * @param selector 값 선택 함수 (생략 시 요소 자체를 number로 사용)
-   * @returns 빈 배열인 경우 0 반환
+   * Return sum of elements
+   * @param selector Value selection function (if omitted, element itself is used as number)
+   * @returns 0 if array is empty
    */
   sum(selector?: (item: TItem, index: number) => number): number;
 
@@ -223,49 +223,49 @@ export interface ReadonlyArrayExt<TItem> {
 }
 
 /**
- * 원본 배열을 변경하는 확장 메서드
- * @mutates 모든 메서드가 원본 배열을 직접 변경합니다
+ * Extension methods that mutate the original array
+ * @mutates All methods directly modify the original array
  */
 export interface MutableArrayExt<TItem> {
   /**
-   * 원본 배열에서 중복 제거
-   * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
-   * @note 객체 배열에서 keyFn 없이 사용 시 O(n²) 복잡도. 대량 데이터는 keyFn 사용 권장
+   * Remove duplicates from original array
+   * @param options matchAddress: address comparison (true uses Set), keyFn: custom key function (O(n) performance)
+   * @note O(n²) complexity when used without keyFn on object arrays. Using keyFn is recommended for large data
    * @mutates
    */
   distinctThis(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number },
   ): TItem[];
 
-  /** 원본 배열 오름차순 정렬 @mutates */
+  /** Sort original array in ascending order @mutates */
   orderByThis(
     selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined,
   ): TItem[];
 
-  /** 원본 배열 내림차순 정렬 @mutates */
+  /** Sort original array in descending order @mutates */
   orderByDescThis(
     selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined,
   ): TItem[];
 
-  /** 원본 배열에 항목 삽입 @mutates */
+  /** Insert items into original array @mutates */
   insert(index: number, ...items: TItem[]): this;
 
-  /** 원본 배열에서 항목 제거 @mutates */
+  /** Remove item from original array @mutates */
   remove(item: TItem): this;
 
-  /** 원본 배열에서 조건에 맞는 항목 제거 @mutates */
+  /** Remove items matching condition from original array @mutates */
   remove(selector: (item: TItem, index: number) => boolean): this;
 
-  /** 원본 배열에서 항목 토글 (있으면 제거, 없으면 추가) @mutates */
+  /** Toggle item in original array (remove if exists, add if not) @mutates */
   toggle(item: TItem): this;
 
-  /** 원본 배열 비우기 @mutates */
+  /** Clear original array @mutates */
   clear(): this;
 }
 
 //#endregion
 
-//#region 내보내기 타입
+//#region Export Types
 
 export type ArrayDiffsResult<TOriginal, TOther> =
   | { source: undefined; target: TOther } // INSERT
@@ -279,7 +279,7 @@ export type ArrayDiffs2Result<TItem> =
 
 export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
 
-/** 정렬/비교 가능한 타입 */
+/** Type that can be sorted/compared */
 export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
 
 //#endregion