@simplysm/core-common 13.0.99 → 14.0.1

package/src/extensions/arr-ext.ts

@@ -1,7 +1,7 @@
 /**
- * Array extension methods
+ * Array 확장 메서드
  *
- * @remarks See type definition file (arr-ext.types.ts) for TSDoc of each method
+ * @remarks 각 메서드의 TSDoc은 타입 정의 파일(arr-ext.types.ts)을 참조
  */
 
 import "./map-ext";
@@ -28,7 +28,7 @@ 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("Multiple results found.", { count: arr.length });
+      throw new ArgumentError("여러 개의 결과가 발견되었습니다.", { 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 case
+    // PrimitiveTypeStr 경우
     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: Compilation error when a new type is added to PrimitiveTypeStr
+            // 완전성 검사: PrimitiveTypeStr에 새 타입이 추가되면 컴파일 에러 발생
             const _exhaustive: never = type;
-            throw new ArgumentError(`Unsupported type: ${_exhaustive}`);
+            throw new ArgumentError(`지원하지 않는 타입: ${_exhaustive}`);
           }
         }
       }) as N[];
     }
 
-    // Type<N> (constructor) case
+    // Type<N> (생성자) 경우
     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));
   },
 
-  // Group array by key
-  // Performance considerations:
-  // - primitive key (string, number, etc.): O(n) - Map-based
-  // - object key: O(n²) - objEqual comparison
+  // key 기준으로 array 그룹화
+  // 성능 고려사항:
+  // - 원시 key (string, number 등): O(n) - Map 기반
+  // - 객체 key: O(n²) - objEqual 비교
   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)[] }[] = [];
 
-    // Map for primitive key optimization (key string -> result index)
+    // 원시 key 최적화를 위한 Map (key 문자열 -> 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 keys are processed in O(n) using Map
+      // 원시 key는 Map을 사용하여 O(n)으로 처리
       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;
       }
 
-      // Object keys use the existing approach O(n²)
+      // 객체 key는 기존 방식 O(n²) 사용
       const existsRecord = result.find((item) => equal(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("Duplicated key.", { duplicatedKey: keyObj });
+        throw new ArgumentError("중복된 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("Duplicated key.", { duplicatedKey: keyObj });
+        throw new ArgumentError("중복된 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 values are treated as "none", allowing overwrite
+      // undefined 값은 "없음"으로 처리하여 덮어쓰기 허용
       if (result[key] !== undefined) {
-        throw new ArgumentError("Duplicated key.", { duplicatedKey: key });
+        throw new ArgumentError("중복된 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) optimization: Map-based indexing
+    // O(n) 최적화: Map 기반 인덱싱
     const childrenMap = this.toArrayMap((item) => item[parentKey]);
 
     const fn = (items: T[]): TreeArray<T>[] => {
@@ -348,8 +348,8 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     const hasKeys = options?.keys !== undefined && options.keys.length > 0;
     const excludeOpts = { topLevelExcludes: options?.excludes };
 
-    // 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
+    // keys 옵션이 제공되면 target을 Map으로 사전 인덱싱하여 O(n×m) → O(n+m)으로 개선
+    // 같은 key 값을 가진 target이 여러 개 존재할 수 있으므로 array로 저장
     const keyIndexedTarget = hasKeys ? new Map<string, P[]>() : undefined;
 
     if (keyIndexedTarget) {
@@ -367,11 +367,11 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
     }
 
     for (const sourceItem of this) {
-      // Prioritize full match (sameTarget), otherwise search for key match (sameKeyTarget)
+      // 전체 일치(sameTarget)를 우선하고, 없으면 key 일치(sameKeyTarget)를 검색
       let sameTarget: P | undefined;
       let sameKeyTarget: P | undefined;
 
-      // Skip already matched items using Set-based skipping (avoid O(n) splice removal)
+      // Set 기반 건너뛰기로 이미 매칭된 항목 스킵 (O(n) splice 제거 방지)
       for (const targetItem of uncheckedTarget) {
         if (!uncheckedTargetSet.has(targetItem)) continue;
         if (equal(targetItem, sourceItem, excludeOpts)) {
@@ -380,14 +380,14 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
         }
       }
 
-      // If no full match and keys option exists, perform O(1) lookup in Map
+      // 전체 일치가 없고 keys 옵션이 있으면 Map에서 O(1) 조회 수행
       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) {
-          // Select first remaining item using O(1) lookup in uncheckedTargetSet
+          // uncheckedTargetSet에서 O(1) 조회로 남은 첫 번째 항목 선택
           sameKeyTarget = candidates.find((c) => uncheckedTargetSet.has(c));
         }
       }
@@ -473,22 +473,22 @@ const arrayReadonlyExtensions: ReadonlyArrayExt<any> & ThisType<any[]> = {
 
     const result: (T | P | (T & P))[] = clone(this);
 
-    // Pre-calculate original index of source items to improve O(n) lookup to O(1)
+    // source 항목의 원래 index를 사전 계산하여 O(n) 조회를 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("Unexpected error: source item not found in merge.");
+          throw new SdError("예상치 못한 오류: merge에서 source 항목을 찾을 수 없습니다.");
         }
         result[sourceIndex] = merge(diff.source, diff.target);
       }
-      // When adding
+      // 추가 시
       else if (diff.target !== undefined) {
         result.push(diff.target);
       }
@@ -502,7 +502,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 can only be used with numbers.", {
+        throw new ArgumentError("sum은 숫자에만 사용할 수 있습니다.", {
           type: typeof item,
         });
       }
@@ -517,7 +517,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 can only be used with numbers/strings.", {
+        throw new ArgumentError("min은 숫자/문자열에만 사용할 수 있습니다.", {
           type: typeof item,
         });
       }
@@ -534,7 +534,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 can only be used with numbers/strings.", {
+        throw new ArgumentError("max는 숫자/문자열에만 사용할 수 있습니다.", {
           type: typeof item,
         });
       }
@@ -571,7 +571,7 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
         indicesToRemove.push(i);
       }
     }
-    // Remove in reverse order to prevent index shifts
+    // index 변동을 방지하기 위해 역순으로 제거
     for (let i = indicesToRemove.length - 1; i >= 0; i--) {
       this.splice(indicesToRemove[i], 1);
     }
@@ -609,7 +609,7 @@ const arrayMutableExtensions: MutableArrayExt<any> & ThisType<any[]> = {
         ? (itemOrSelector as (item: T, index: number) => boolean)
         : (item: T) => item === itemOrSelector;
 
-    // Reverse traversal to prevent index change issues (O(n) performance)
+    // index 변경 문제를 방지하기 위한 역순 순회 (O(n) 성능)
     for (let i = this.length - 1; i >= 0; i--) {
       if (shouldRemove(this[i], i)) {
         this.splice(i, 1);
@@ -647,7 +647,7 @@ for (const [name, fn] of Object.entries({
 
 //#endregion
 
-//#region Type Declarations
+//#region 타입 선언
 
 declare global {
   interface ReadonlyArray<T> extends ReadonlyArrayExt<T> {}

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

@@ -1,5 +1,5 @@
 /**
- * Array extension type definitions
+ * Array 확장 타입 정의
  */
 
 import type { PrimitiveTypeMap, PrimitiveTypeStr, Type } from "../common.types";
@@ -11,67 +11,67 @@ import type { Time } from "../types/time";
 
 export interface ReadonlyArrayExt<TItem> {
   /**
-   * 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
+   * 조건에 맞는 단일 요소 반환
+   * @param predicate 필터 조건 (생략 시 전체 array 대상)
+   * @returns 요소가 없으면 undefined
+   * @throws ArgumentError 2개 이상의 요소가 조건에 맞을 경우
    */
   single(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
   /**
-   * Return first element
-   * @param predicate Filter condition (if omitted, returns first element)
-   * @returns undefined if element does not exist
+   * 첫 번째 요소 반환
+   * @param predicate 필터 조건 (생략 시 첫 번째 요소 반환)
+   * @returns 요소가 없으면 undefined
    */
   first(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
-  /** Async filter (sequential execution) */
+  /** 비동기 필터 (순차 실행) */
   filterAsync(predicate: (item: TItem, index: number) => Promise<boolean>): Promise<TItem[]>;
 
   /**
-   * Return last element
-   * @param predicate Filter condition (if omitted, returns last element)
-   * @returns undefined if element does not exist
+   * 마지막 요소 반환
+   * @param predicate 필터 조건 (생략 시 마지막 요소 반환)
+   * @returns 요소가 없으면 undefined
    */
   last(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
-  /** Remove null/undefined */
+  /** null/undefined 제거 */
   filterExists(): NonNullable<TItem>[];
 
-  /** Filter only elements of specific type (PrimitiveTypeStr or constructor type) */
+  /** 특정 타입의 요소만 필터 (PrimitiveTypeStr 또는 생성자 타입) */
   ofType<TKey extends PrimitiveTypeStr>(type: TKey): Extract<TItem, PrimitiveTypeMap[TKey]>[];
   ofType<TNarrow extends TItem>(type: Type<TNarrow>): TNarrow[];
 
-  /** Async mapping (sequential execution) */
+  /** 비동기 매핑 (순차 실행) */
   mapAsync<TResult>(selector: (item: TItem, index: number) => Promise<TResult>): Promise<TResult[]>;
 
-  /** Flatten nested array */
+  /** 중첩 array 평탄화 */
   mapMany(): TItem extends readonly (infer U)[] ? U[] : TItem;
 
-  /** Map and then flatten */
+  /** 매핑 후 평탄화 */
   mapMany<TResult>(selector: (item: TItem, index: number) => TResult[]): TResult[];
 
-  /** Async mapping and then flatten (sequential execution) */
+  /** 비동기 매핑 후 평탄화 (순차 실행) */
   mapManyAsync<TResult>(selector: (item: TItem, index: number) => Promise<TResult[]>): Promise<TResult[]>;
 
   /**
-   * Async parallel processing (using Promise.all)
-   * @note If any rejects, entire operation fail-fast rejects (Promise.all behavior)
+   * 비동기 병렬 처리 (Promise.all 사용)
+   * @note 하나라도 reject되면 전체가 즉시 reject됨 (Promise.all 동작)
    */
   parallelAsync<TResult>(fn: (item: TItem, index: number) => Promise<TResult>): Promise<TResult[]>;
 
   /**
-   * 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)
+   * key 기준 그룹화
+   * @param keySelector 그룹의 key 선택 함수
+   * @note O(n²) 복잡도 (객체 key 지원을 위한 깊은 비교). 원시 key만 필요하면 toArrayMap()이 O(n)으로 더 효율적
    */
   groupBy<TKey>(keySelector: (item: TItem, index: number) => TKey): { key: TKey; values: TItem[] }[];
 
   /**
-   * 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)
+   * key 기준 그룹화 (value 변환 포함)
+   * @param keySelector 그룹의 key 선택 함수
+   * @param valueSelector value 변환 함수
+   * @note O(n²) 복잡도 (객체 key 지원을 위한 깊은 비교). 원시 key만 필요하면 toArrayMap()이 O(n)으로 더 효율적
    */
   groupBy<TKey, TValue>(
     keySelector: (item: TItem, index: number) => TKey,
@@ -121,16 +121,16 @@ export interface ReadonlyArrayExt<TItem> {
   ): Record<string, TValue>;
 
   /**
-   * Convert flat array to tree structure
+   * 평면 array를 트리 구조로 변환
    *
-   * @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)
+   * @param keyProp 각 항목의 고유 key 속성명
+   * @param parentKey 부모 항목의 key를 참조하는 속성명
+   * @returns 루트 항목 array (각 항목에 children 속성이 추가됨)
    *
    * @remarks
-   * - Items with null/undefined parentKey value become roots
-   * - Internally uses toArrayMap for O(n) complexity
-   * - Original items are copied with children property added
+   * - parentKey 값이 null/undefined인 항목이 루트가 됨
+   * - 내부적으로 toArrayMap을 사용하여 O(n) 복잡도
+   * - 원본 항목은 복사되고 children 속성이 추가됨
    *
    * @example
    * ```typescript
@@ -162,9 +162,9 @@ export interface ReadonlyArrayExt<TItem> {
   ): TreeArray<TItem>[];
 
   /**
-   * 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
+   * 중복 제거
+   * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 key 함수 (O(n) 성능)
+   * @note 객체 array에서 keyFn 없이 사용하면 O(n²) 복잡도. 대량 데이터에는 keyFn 사용 권장
    */
   distinct(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number },
@@ -179,10 +179,10 @@ export interface ReadonlyArrayExt<TItem> {
   ): TItem[];
 
   /**
-   * 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
+   * 두 array 비교 (INSERT/DELETE/UPDATE)
+   * @param target 비교할 array
+   * @param options keys: key 비교용, excludes: 비교에서 제외할 속성
+   * @note target에 중복 key가 있으면 첫 번째 매칭만 사용됨
    */
   diffs<TOtherItem>(
     target: TOtherItem[],
@@ -233,9 +233,9 @@ export interface ReadonlyArrayExt<TItem> {
   ): (TItem | TOtherItem | (TItem & TOtherItem))[];
 
   /**
-   * Return sum of elements
-   * @param selector Value selection function (if omitted, element itself is used as number)
-   * @returns 0 if array is empty
+   * 요소의 합계 반환
+   * @param selector value 선택 함수 (생략 시 요소 자체를 숫자로 사용)
+   * @returns array가 비어 있으면 0
    */
   sum(selector?: (item: TItem, index: number) => number): number;
 
@@ -251,43 +251,43 @@ export interface ReadonlyArrayExt<TItem> {
 }
 
 /**
- * Extension methods that mutate the original array
- * @mutates All methods directly modify the original array
+ * 원본 array를 변경하는 확장 메서드
+ * @mutates 모든 메서드가 원본 array를 직접 수정함
  */
 export interface MutableArrayExt<TItem> {
   /**
-   * 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
+   * 원본 array에서 중복 제거
+   * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 key 함수 (O(n) 성능)
+   * @note 객체 array에서 keyFn 없이 사용하면 O(n²) 복잡도. 대량 데이터에는 keyFn 사용 권장
    * @mutates
    */
   distinctThis(
     options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number },
   ): TItem[];
 
-  /** Sort original array in ascending order @mutates */
+  /** 원본 array를 오름차순 정렬 @mutates */
   orderByThis(
     selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined,
   ): TItem[];
 
-  /** Sort original array in descending order @mutates */
+  /** 원본 array를 내림차순 정렬 @mutates */
   orderByDescThis(
     selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined,
   ): TItem[];
 
-  /** Insert items into original array @mutates */
+  /** 원본 array에 항목 삽입 @mutates */
   insert(index: number, ...items: TItem[]): this;
 
-  /** Remove item from original array @mutates */
+  /** 원본 array에서 항목 제거 @mutates */
   remove(item: TItem): this;
 
-  /** Remove items matching condition from original array @mutates */
+  /** 원본 array에서 조건에 맞는 항목 제거 @mutates */
   remove(selector: (item: TItem, index: number) => boolean): this;
 
-  /** Toggle item in original array (remove if exists, add if not) @mutates */
+  /** 원본 array에서 항목 토글 (있으면 제거, 없으면 추가) @mutates */
   toggle(item: TItem): this;
 
-  /** Clear original array @mutates */
+  /** 원본 array 비우기 @mutates */
   clear(): this;
 }
 
@@ -307,7 +307,7 @@ export type ArrayOneWayDiffResult<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

package/src/extensions/map-ext.ts

@@ -1,53 +1,53 @@
 /**
- * Map extension methods
+ * Map 확장 메서드
  */
 
 declare global {
   interface Map<K, V> {
     /**
-     * If no value exists for key, set new value and return it
+     * key에 해당하는 값이 없으면 새 값을 설정하고 반환
      *
      * @remarks
-     * **Caution**: If V type is a function (e.g., `Map<string, () => void>`),
-     * passing the function directly as the second argument will be recognized as a factory and called.
-     * To store the function itself as a value, wrap it in a factory.
+     * **주의**: V 타입이 함수인 경우 (예: `Map<string, () => void>`),
+     * 함수를 두 번째 인자로 직접 전달하면 팩토리로 인식되어 호출됨.
+     * 함수 자체를 값으로 저장하려면 팩토리로 감싸야 함.
      *
      * @example
      * ```typescript
-     * // Regular values
+     * // 일반 값
      * map.getOrCreate("key", 0);
      * map.getOrCreate("key", []);
      *
-     * // Factory function (for expensive computations)
+     * // 팩토리 함수 (비용이 큰 연산에 사용)
      * map.getOrCreate("key", () => expensiveComputation());
      *
-     * // Storing function as value
+     * // 함수를 값으로 저장
      * const fnMap = new Map<string, () => void>();
      * const myFn = () => console.log("hello");
-     * fnMap.getOrCreate("key", () => myFn);  // Wrap in factory
+     * fnMap.getOrCreate("key", () => myFn);  // 팩토리로 감싸기
      * ```
      */
     getOrCreate(key: K, newValue: V): V;
     getOrCreate(key: K, newValueFn: () => V): V;
 
     /**
-     * Update value for key using function
+     * 함수를 사용하여 key의 값을 업데이트
      *
-     * @param key Key to update
-     * @param updateFn Function that receives current value and returns new value (undefined if key doesn't exist)
+     * @param key 업데이트할 key
+     * @param updateFn 현재 값을 받아 새 값을 반환하는 함수 (key가 없으면 undefined)
      *
      * @remarks
-     * updateFn is called even if key doesn't exist, setting new value.
-     * Useful for calculations based on existing value (counter increment, add to array, etc).
+     * key가 존재하지 않아도 updateFn이 호출되어 새 값이 설정됨.
+     * 기존 값 기반 계산(카운터 증가, array에 추가 등)에 유용함.
      *
      * @example
      * ```typescript
      * const countMap = new Map<string, number>();
      *
-     * // Increment counter
+     * // 카운터 증가
      * countMap.update("key", (v) => (v ?? 0) + 1);
      *
-     * // Add item to array
+     * // array에 항목 추가
      * const arrayMap = new Map<string, string[]>();
      * arrayMap.update("key", (v) => [...(v ?? []), "item"]);
      * ```

package/src/extensions/set-ext.ts

@@ -1,34 +1,34 @@
 /**
- * Set extension methods
+ * Set 확장 메서드
  */
 
 declare global {
   interface Set<T> {
     /**
-     * Add multiple values at once
+     * 여러 값을 한 번에 추가
      */
     adds(...values: T[]): this;
 
     /**
-     * Toggle value (remove if exists, add if not)
+     * 값 토글 (있으면 제거, 없으면 추가)
      *
-     * @param value Value to toggle
-     * @param addOrDel Force add ("add") or remove ("del") (if omitted, toggle automatically)
-     * @returns this (method chaining available)
+     * @param value 토글할 값
+     * @param addOrDel 강제 추가("add") 또는 제거("del") (생략 시 자동 토글)
+     * @returns this (메서드 체이닝 가능)
      *
      * @remarks
-     * addOrDel parameter allows concise expression of conditional add/remove.
+     * addOrDel 매개변수로 조건부 추가/제거를 간결하게 표현할 수 있음.
      *
      * @example
      * ```typescript
      * const set = new Set<number>([1, 2, 3]);
      *
-     * set.toggle(2);  // 2 exists, so remove → {1, 3}
-     * set.toggle(4);  // 4 doesn't exist, so add → {1, 3, 4}
+     * set.toggle(2);  // 2가 있으므로 제거 → {1, 3}
+     * set.toggle(4);  // 4가 없으므로 추가 → {1, 3, 4}
      *
-     * // Conditional toggle
+     * // 조건부 토글
      * const isAdmin = true;
-     * set.toggle(5, isAdmin ? "add" : "del");  // Force add
+     * set.toggle(5, isAdmin ? "add" : "del");  // 강제 추가
      * ```
      */
     toggle(value: T, addOrDel?: "add" | "del"): this;