@simplysm/core-common 13.0.99 → 14.0.1

package/src/utils/obj.ts

@@ -7,26 +7,26 @@ import { ArgumentError } from "../errors/argument-error";
 //#region clone
 
 /**
- * Deep clone
- * - Supports circular references
- * - Supports copying custom types (DateTime, DateOnly, Time, Uuid, Uint8Array)
+ * 깊은 복사
+ * - 순환 참조 지원
+ * - 커스텀 타입 복사 지원 (DateTime, DateOnly, Time, Uuid, Uint8Array)
  *
- * @note Functions and Symbols are not cloned and references are maintained
- * @note WeakMap and WeakSet are not supported (copied as generic objects, resulting in empty objects)
- * @note Prototype chain is maintained (using Object.setPrototypeOf)
- * @note Getters/setters are evaluated as current values and copied (accessor properties themselves are not copied)
+ * @note 함수와 Symbol은 복사되지 않고 참조가 유지됨
+ * @note WeakMap과 WeakSet은 지원되지 않음 (일반 객체로 복사되어 빈 객체가 됨)
+ * @note 프로토타입 체인이 유지됨 (Object.setPrototypeOf 사용)
+ * @note Getter/setter는 현재 값으로 평가되어 복사됨 (접근자 속성 자체는 복사되지 않음)
  */
 export function clone<TObj>(source: TObj): TObj {
   return cloneImpl(source) as TObj;
 }
 
 function cloneImpl(source: unknown, prevClones?: WeakMap<object, unknown>): unknown {
-  // Primitives are returned as-is
+  // 원시 값은 그대로 반환
   if (typeof source !== "object" || source === null) {
     return source;
   }
 
-  // Immutable-like types (no internal object references)
+  // 불변과 유사한 타입 (내부 객체 참조 없음)
   if (source instanceof Date) {
     return new Date(source.getTime());
   }
@@ -52,14 +52,14 @@ function cloneImpl(source: unknown, prevClones?: WeakMap<object, unknown>): unkn
     return new RegExp(source.source, source.flags);
   }
 
-  // Circular reference check (applies to all object types including Error)
+  // 순환 참조 검사 (Error를 포함한 모든 객체 타입에 적용)
   const currPrevClones = prevClones ?? new WeakMap<object, unknown>();
   if (currPrevClones.has(source)) {
     return currPrevClones.get(source);
   }
 
-  // Error (including cause)
-  // Prototype-based copying instead of constructor call - ensures custom Error class compatibility
+  // Error (cause 포함)
+  // 생성자 호출 대신 프로토타입 기반 복사 - 커스텀 Error 클래스 호환성 보장
   if (source instanceof Error) {
     const cloned = Object.create(Object.getPrototypeOf(source)) as Error;
     currPrevClones.set(source, cloned);
@@ -69,7 +69,7 @@ function cloneImpl(source: unknown, prevClones?: WeakMap<object, unknown>): unkn
     if (source.cause !== undefined) {
       cloned.cause = cloneImpl(source.cause, currPrevClones);
     }
-    // Copy custom Error properties
+    // 커스텀 Error 속성 복사
     for (const key of Object.keys(source)) {
       if (!["message", "name", "stack", "cause"].includes(key)) {
         const desc = Object.getOwnPropertyDescriptor(source, key);
@@ -117,7 +117,7 @@ function cloneImpl(source: unknown, prevClones?: WeakMap<object, unknown>): unkn
     return result;
   }
 
-  // Other Object types
+  // 기타 Object 타입
   const result: Record<string, unknown> = {};
   Object.setPrototypeOf(result, Object.getPrototypeOf(source));
   currPrevClones.set(source, result);
@@ -134,40 +134,40 @@ function cloneImpl(source: unknown, prevClones?: WeakMap<object, unknown>): unkn
 
 //#region equal
 
-/** equal options type */
+/** equal 옵션 타입 */
 export interface EqualOptions {
-  /** List of keys to compare. When specified, only those keys are compared (applies only to top level) */
+  /** 비교할 key 목록. 지정 시 해당 key만 비교 (최상위 레벨에만 적용) */
   topLevelIncludes?: string[];
-  /** List of keys to exclude from comparison (applies only to top level) */
+  /** 비교에서 제외할 key 목록 (최상위 레벨에만 적용) */
   topLevelExcludes?: string[];
-  /** Whether to ignore array order. O(n²) complexity when true */
+  /** array 순서를 무시할지 여부. true면 O(n²) 복잡도 */
   ignoreArrayIndex?: boolean;
-  /** Whether to do shallow comparison. Only compare 1 level (reference comparison) when true */
+  /** 얕은 비교 여부. true면 1단계만 비교 (참조 비교) */
   shallow?: boolean;
 }
 
 /**
- * Deep equality comparison
+ * 깊은 동등성 비교
  *
- * @param source Comparison target 1
- * @param target Comparison target 2
- * @param options Comparison options
- * @param options.topLevelIncludes List of keys to compare. When specified, only those keys are compared (applies only to top level)
- *   @example `{ topLevelIncludes: ["id", "name"] }` - Compare only id and name keys
- * @param options.topLevelExcludes List of keys to exclude from comparison (applies only to top level)
- *   @example `{ topLevelExcludes: ["updatedAt"] }` - Compare excluding updatedAt key
- * @param options.ignoreArrayIndex Whether to ignore array order. O(n²) complexity when true
- * @param options.shallow Whether to do shallow comparison. Only compare 1 level (reference comparison) when true
+ * @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 options apply only to object property keys.
- *       All keys in Map are always included in comparison.
- * @note Performance considerations:
- * - Basic array comparison: O(n) time complexity
- * - When using `ignoreArrayIndex: true`: O(n²) time complexity
- *   (possible performance degradation on large arrays)
- * @note `ignoreArrayIndex: true` behavior characteristics:
- * - Ignore array order and check if elements are permutations of the same set
- * - Example: `[1,2,3]` and `[3,2,1]` → true, `[1,1,1]` and `[1,2,3]` → false
+ * @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: unknown, target: unknown, options?: EqualOptions): boolean {
   if (source === target) return true;
@@ -235,7 +235,7 @@ function equalArray(source: unknown[], target: unknown[], options?: EqualOptions
         return false;
       });
     } else {
-      // On recursive calls, topLevelIncludes/topLevelExcludes options apply only to top level, so exclude them
+      // 재귀 호출 시 topLevelIncludes/topLevelExcludes 옵션은 최상위 레벨에만 적용되므로 제외
       const recursiveOptions = {
         ignoreArrayIndex: options.ignoreArrayIndex,
         shallow: options.shallow,
@@ -259,7 +259,7 @@ function equalArray(source: unknown[], target: unknown[], options?: EqualOptions
         }
       }
     } else {
-      // On recursive calls, topLevelIncludes/topLevelExcludes options apply only to top level, so exclude them
+      // 재귀 호출 시 topLevelIncludes/topLevelExcludes 옵션은 최상위 레벨에만 적용되므로 제외
       for (let i = 0; i < source.length; i++) {
         if (
           !equal(source[i], target[i], {
@@ -277,16 +277,16 @@ function equalArray(source: unknown[], target: unknown[], options?: EqualOptions
 }
 
 /**
- * Map object comparison
- * @note O(n²) complexity when handling non-string keys (objects, arrays, etc.)
- * @note Recommended to use shallow: true option for large datasets (improves to O(n) with reference comparison)
+ * Map 객체 비교
+ * @note 비문자열 key(객체, array 등) 처리 시 O(n²) 복잡도
+ * @note 대용량 데이터에는 shallow: true 옵션 사용 권장 (참조 비교로 O(n)으로 개선)
  */
 function equalMap(
   source: Map<unknown, unknown>,
   target: Map<unknown, unknown>,
   options?: EqualOptions,
 ): boolean {
-  // When comparing Maps, topLevelIncludes/topLevelExcludes options are ignored (apply only to object property keys)
+  // 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);
 
@@ -296,7 +296,7 @@ function equalMap(
 
   const usedTargetKeys = new Set<number>();
   for (const sourceKey of sourceKeys) {
-    // String keys: compare directly
+    // 문자열 key: 직접 비교
     if (typeof sourceKey === "string") {
       const sourceValue = source.get(sourceKey);
       const targetValue = target.get(sourceKey);
@@ -313,7 +313,7 @@ function equalMap(
         }
       }
     } else {
-      // Non-string keys: find equivalent key in targetKeys
+      // 비문자열 key: targetKeys에서 동등한 key 검색
       let found = false;
       for (let i = 0; i < targetKeys.length; i++) {
         const targetKey = targetKeys[i];
@@ -387,9 +387,9 @@ function equalObject(
 }
 
 /**
- * Set deep equality comparison
- * @note Deep equal comparison (`shallow: false`) has O(n²) time complexity.
- *   Recommended to use `shallow: true` for primitive Sets or when performance is critical
+ * Set 깊은 동등성 비교
+ * @note 깊은 비교(`shallow: false`)는 O(n²) 시간 복잡도.
+ *   원시 타입 Set이거나 성능이 중요한 경우 `shallow: true` 사용 권장
  */
 function equalSet(source: Set<unknown>, target: Set<unknown>, options?: EqualOptions): boolean {
   if (source.size !== target.size) {
@@ -403,8 +403,8 @@ function equalSet(source: Set<unknown>, target: Set<unknown>, options?: EqualOpt
       }
     }
   } else {
-    // Deep equal: create target array only once outside loop
-    // Track matched indices to prevent duplicate matching
+    // 깊은 비교: 루프 외부에서 target array를 한 번만 생성
+    // 중복 매칭 방지를 위해 매칭된 인덱스 추적
     const targetArr = [...target];
     const matchedIndices = new Set<number>();
     for (const sourceItem of source) {
@@ -425,31 +425,31 @@ function equalSet(source: Set<unknown>, target: Set<unknown>, options?: EqualOpt
 
 //#region merge
 
-/** merge options type */
+/** merge 옵션 타입 */
 export interface MergeOptions {
-  /** Array processing method. "replace": replace with target (default), "concat": merge (deduplicate) */
+  /** Array 처리 방식. "replace": target으로 교체 (기본값), "concat": 병합 (중복 제거) */
   arrayProcess?: "replace" | "concat";
-  /** Whether to delete the key when target is null */
+  /** target이 null일 때 해당 key를 삭제할지 여부 */
   useDelTargetNull?: boolean;
 }
 
 /**
- * Deep merge (merge target into source as base)
+ * 깊은 병합 (source를 기반으로 target을 병합)
  *
- * @param source Base object
- * @param target Object to merge
- * @param opt Merge options
- * @param opt.arrayProcess Array processing method
- *   - `"replace"`: Replace with target array (default)
- *   - `"concat"`: Merge source and target arrays (deduplicate with Set)
- * @param opt.useDelTargetNull Whether to delete the key when target value is null
- *   - `true`: Delete the key from result if target is null
- *   - `false` or not specified: Keep source value
+ * @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 Returns a new object without modifying original objects (guarantees immutability)
- * @note When using arrayProcess="concat", deduplication is done with Set,
- *       and for object arrays, deduplication is determined by reference (address) comparison
- * @note If types are different, overwrite with target value
+ * @note 원본 객체를 수정하지 않고 새 객체를 반환 (불변성 보장)
+ * @note arrayProcess="concat" 사용 시 Set으로 중복 제거되며,
+ *       객체 array의 경우 참조(주소) 비교로 중복 여부 판단
+ * @note 타입이 다르면 target 값으로 덮어씀
  */
 export function merge<TSource, TMergeTarget>(
   source: TSource,
@@ -486,7 +486,7 @@ export function merge<TSource, TMergeTarget>(
     return clone(target) as TSource & TMergeTarget;
   }
 
-  // If source is not an object or source and target are different types of objects, overwrite with target
+  // source가 객체가 아니거나 source와 target이 다른 타입의 객체이면 target으로 덮어씀
   if (typeof source !== "object" || source.constructor !== target.constructor) {
     return clone(target) as TSource & TMergeTarget;
   }
@@ -524,33 +524,33 @@ export function merge<TSource, TMergeTarget>(
   return resultRec as TSource & TMergeTarget;
 }
 
-/** merge3 options type */
+/** merge3 옵션 타입 */
 export interface Merge3KeyOptions {
-  /** List of sub-keys to compare (same as equal's topLevelIncludes) */
+  /** 비교할 하위 key 목록 (equal의 topLevelIncludes와 동일) */
   keys?: string[];
-  /** List of sub-keys to exclude from comparison */
+  /** 비교에서 제외할 하위 key 목록 */
   excludes?: string[];
-  /** Whether to ignore array order */
+  /** array 순서를 무시할지 여부 */
   ignoreArrayIndex?: boolean;
 }
 
 /**
- * 3-way merge
+ * 3-way 병합
  *
- * Merge by comparing three objects: source, origin, and target.
- * - If source and origin are equal and target differs → use target value
- * - If target and origin are equal and source differs → use source value
- * - If source and target are equal → use that value
- * - If all three values differ → conflict occurs (maintain origin value)
+ * source, origin, target 세 객체를 비교하여 병합.
+ * - source와 origin이 같고 target이 다르면 → target 값 사용
+ * - target과 origin이 같고 source가 다르면 → source 값 사용
+ * - source와 target이 같으면 → 해당 값 사용
+ * - 세 값이 모두 다르면 → 충돌 발생 (origin 값 유지)
  *
- * @param source Changed version 1
- * @param origin Base version (common ancestor)
- * @param target Changed version 2
- * @param optionsObj Comparison options per key. Specify equal() comparison options individually for each key
- *   - `keys`: List of sub-keys to compare (same as equal's topLevelIncludes)
- *   - `excludes`: List of sub-keys to exclude from comparison
- *   - `ignoreArrayIndex`: Whether to ignore array order
- * @returns conflict: Whether conflict occurred, result: Merge result
+ * @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(
@@ -599,10 +599,10 @@ export function merge3<
 //#region omit / pick
 
 /**
- * Exclude specific keys from object
- * @param item Source object
- * @param omitKeys Array of keys to exclude
- * @returns New object with specified keys excluded
+ * 객체에서 특정 key 제외
+ * @param item 원본 객체
+ * @param omitKeys 제외할 key 배열
+ * @returns 지정된 key가 제외된 새 객체
  * @example
  * const user = { name: "Alice", age: 30, email: "alice@example.com" };
  * omit(user, ["email"]);
@@ -622,11 +622,11 @@ export function omit<T extends Record<string, unknown>, K extends keyof T>(
 }
 
 /**
- * Exclude keys matching condition
+ * 조건에 맞는 key 제외
  * @internal
- * @param item Source object
- * @param omitKeyFn Function that receives key and returns whether to exclude (true to exclude)
- * @returns New object with keys matching condition excluded
+ * @param item 원본 객체
+ * @param omitKeyFn key를 받아 제외 여부를 반환하는 함수 (true면 제외)
+ * @returns 조건에 맞는 key가 제외된 새 객체
  * @example
  * const data = { name: "Alice", _internal: "secret", age: 30 };
  * omitByFilter(data, (key) => key.startsWith("_"));
@@ -646,10 +646,10 @@ export function omitByFilter<T extends Record<string, unknown>>(
 }
 
 /**
- * Select specific keys from object
- * @param item Source object
- * @param keys Array of keys to select
- * @returns New object containing only specified keys
+ * 객체에서 특정 key만 선택
+ * @param item 원본 객체
+ * @param keys 선택할 key 배열
+ * @returns 지정된 key만 포함된 새 객체
  * @example
  * const user = { name: "Alice", age: 30, email: "alice@example.com" };
  * pick(user, ["name", "age"]);
@@ -670,7 +670,7 @@ export function pick<T extends Record<string, unknown>, K extends keyof T>(
 
 //#region getChainValue / setChainValue / deleteChainValue
 
-// Regex caching (created once at module load)
+// 정규식 캐싱 (모듈 로드 시 한 번만 생성)
 const chainSplitRegex = /[.[\]]/g;
 const chainCleanRegex = /[?!'"]/g;
 const chainNumericRegex = /^[0-9]*$/;
@@ -693,7 +693,7 @@ function getChainSplits(chain: string): (string | number)[] {
 }
 
 /**
- * Get value by chain path
+ * 체인 경로로 값 조회
  * @example getChainValue(obj, "a.b[0].c")
  */
 export function getChainValue(obj: unknown, chain: string, optional: true): unknown | undefined;
@@ -716,13 +716,13 @@ export function getChainValue(
 }
 
 /**
- * Descend by the same key for depth levels
+ * 같은 key로 지정된 깊이만큼 하강
  * @internal
- * @param obj Target object
- * @param key Key to descend by
- * @param depth Depth to descend (1 or more)
- * @param optional If true, return undefined without error if null/undefined found in the middle
- * @throws ArgumentError If depth is less than 1
+ * @param obj 대상 객체
+ * @param key 하강에 사용할 key
+ * @param depth 하강 깊이 (1 이상)
+ * @param optional true이면 중간에 null/undefined를 만나도 에러 없이 undefined 반환
+ * @throws ArgumentError depth가 1 미만인 경우
  * @example getChainValueByDepth({ parent: { parent: { name: 'a' } } }, 'parent', 2) => { name: 'a' }
  */
 export function getChainValueByDepth<TObject, TKey extends keyof TObject>(
@@ -743,7 +743,7 @@ export function getChainValueByDepth<TObject, TKey extends keyof TObject>(
   optional?: true,
 ): TObject[TKey] | undefined {
   if (depth < 1) {
-    throw new ArgumentError("depth must be 1 or greater", { depth });
+    throw new ArgumentError("depth는 1 이상이어야 합니다", { depth });
   }
   let result: unknown = obj;
   for (let i = 0; i < depth; i++) {
@@ -757,13 +757,13 @@ export function getChainValueByDepth<TObject, TKey extends keyof TObject>(
 }
 
 /**
- * Set value by chain path
+ * 체인 경로로 값 설정
  * @example setChainValue(obj, "a.b[0].c", value)
  */
 export function setChainValue(obj: unknown, chain: string, value: unknown): void {
   const splits = getChainSplits(chain);
   if (splits.length === 0) {
-    throw new ArgumentError("Chain is empty", { chain });
+    throw new ArgumentError("chain이 비어있습니다", { chain });
   }
 
   let curr: Record<string | number, unknown> = obj as Record<string | number, unknown>;
@@ -777,19 +777,19 @@ export function setChainValue(obj: unknown, chain: string, value: unknown): void
 }
 
 /**
- * Delete value by chain path
+ * 체인 경로로 값 삭제
  * @example deleteChainValue(obj, "a.b[0].c")
  */
 export function deleteChainValue(obj: unknown, chain: string): void {
   const splits = getChainSplits(chain);
   if (splits.length === 0) {
-    throw new ArgumentError("Chain is empty", { chain });
+    throw new ArgumentError("chain이 비어있습니다", { chain });
   }
 
   let curr: Record<string | number, unknown> = obj as Record<string | number, unknown>;
   for (const splitItem of splits.slice(0, -1)) {
     const next = curr[splitItem];
-    // Silently return if middle path doesn't exist (nothing to delete)
+    // 중간 경로가 존재하지 않으면 조용히 반환 (삭제할 것이 없음)
     if (next == null || typeof next !== "object") {
       return;
     }
@@ -805,10 +805,10 @@ export function deleteChainValue(obj: unknown, chain: string): void {
 //#region clearUndefined / clear / nullToUndefined / unflatten
 
 /**
- * Delete keys with undefined values from object
+ * 객체에서 undefined 값을 가진 key 삭제
  * @internal
  *
- * @mutates Modifies the original object directly
+ * @mutates 원본 객체를 직접 수정
  */
 export function clearUndefined<T extends object>(obj: T): T {
   const record = obj as Record<string, unknown>;
@@ -821,10 +821,10 @@ export function clearUndefined<T extends object>(obj: T): T {
 }
 
 /**
- * Delete all keys from object
+ * 객체의 모든 key 삭제
  * @internal
  *
- * @mutates Modifies the original object directly
+ * @mutates 원본 객체를 직접 수정
  */
 export function clear<T extends Record<string, unknown>>(obj: T): Record<string, never> {
   for (const key of Object.keys(obj)) {
@@ -834,10 +834,10 @@ export function clear<T extends Record<string, unknown>>(obj: T): Record<string,
 }
 
 /**
- * Convert null to undefined (recursive)
+ * null을 undefined로 변환 (재귀)
  * @internal
  *
- * @mutates Modifies the original array/object directly
+ * @mutates 원본 array/객체를 직접 수정
  */
 export function nullToUndefined<TObject>(obj: TObject): TObject | undefined {
   return nullToUndefinedImpl(obj, new WeakSet());
@@ -882,7 +882,7 @@ function nullToUndefinedImpl<TObject>(obj: TObject, seen: WeakSet<object>): TObj
 }
 
 /**
- * Convert flattened object to nested object
+ * 평탄화된 객체를 중첩 객체로 변환
  * @internal
  * @example unflatten({ "a.b.c": 1 }) => { a: { b: { c: 1 } } }
  */
@@ -912,10 +912,10 @@ export function unflatten(flatObj: Record<string, unknown>): Record<string, unkn
 
 //#endregion
 
-//#region Type utilities
+//#region 타입 유틸리티
 
 /**
- * Convert properties with undefined to optional
+ * undefined를 가진 속성을 optional로 변환
  * @example { a: string; b: string | undefined } → { a: string; b?: string | undefined }
  */
 export type UndefToOptional<TObject> = {
@@ -923,7 +923,7 @@ export type UndefToOptional<TObject> = {
 } & { [K in keyof TObject as undefined extends TObject[K] ? never : K]: TObject[K] };
 
 /**
- * Convert optional properties to required + undefined union
+ * optional 속성을 필수 + undefined 유니온으로 변환
  * @example { a: string; b?: string } → { a: string; b: string | undefined }
  */
 export type OptionalToUndef<TObject> = {
@@ -933,27 +933,27 @@ export type OptionalToUndef<TObject> = {
 //#endregion
 
 /**
- * Type-safe version of Object.keys
- * @param obj Object to extract keys from
- * @returns Array of object keys
+ * 타입 안전한 Object.keys
+ * @param obj key를 추출할 객체
+ * @returns 객체 key 배열
  */
 export function keys<T extends object>(obj: T): (keyof T)[] {
   return Object.keys(obj) as (keyof T)[];
 }
 
 /**
- * Type-safe version of Object.entries
- * @param obj Object to extract entries from
- * @returns Array of [key, value] tuples
+ * 타입 안전한 Object.entries
+ * @param obj 엔트리를 추출할 객체
+ * @returns [key, value] 튜플 배열
  */
 export function entries<T extends object>(obj: T): Entries<T> {
   return Object.entries(obj) as Entries<T>;
 }
 
 /**
- * Type-safe version of Object.fromEntries
- * @param entries Array of [key, value] tuples
- * @returns Created object
+ * 타입 안전한 Object.fromEntries
+ * @param entries [key, value] 튜플 배열
+ * @returns 생성된 객체
  */
 export function fromEntries<T extends [string, unknown]>(entryPairs: T[]): { [K in T[0]]: T[1] } {
   return Object.fromEntries(entryPairs) as { [K in T[0]]: T[1] };
@@ -962,18 +962,18 @@ export function fromEntries<T extends [string, unknown]>(entryPairs: T[]): { [K
 type Entries<TObject> = { [K in keyof TObject]: [K, TObject[K]] }[keyof TObject][];
 
 /**
- * Transform each entry of object and return new object
- * @param obj Object to transform
- * @param fn Transform function (key, value) => [newKey, newValue]
- * @returns New object with transformed keys and values
+ * 객체의 각 엔트리를 변환하여 새 객체 반환
+ * @param obj 변환할 객체
+ * @param fn 변환 함수 (key, value) => [newKey, newValue]
+ * @returns key와 value가 변환된 새 객체
  * @example
  * const colors = { primary: "255, 0, 0", secondary: "0, 255, 0" };
  *
- * // Transform only values
+ * // 값만 변환
  * map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
  * // { primary: "rgb(255, 0, 0)", secondary: "rgb(0, 255, 0)" }
  *
- * // Transform both keys and values
+ * // key와 값 모두 변환
  * map(colors, (key, rgb) => [`${key}Light`, `rgb(${rgb})`]);
  * // { primaryLight: "rgb(255, 0, 0)", secondaryLight: "rgb(0, 255, 0)" }
  */

package/src/utils/path.ts

@@ -1,15 +1,15 @@
 /**
- * Path utility functions
- * Replacement for Node.js path module (supports browser environments)
+ * 경로 유틸리티 함수
+ * Node.js path 모듈 대체 (브라우저 환경 지원)
  *
- * @note This utility supports POSIX style paths (slash `/`) only.
- *       Windows backslash (`\`) paths are not supported.
- *       Designed for browser environments and Capacitor plugins.
+ * @note 이 유틸리티는 POSIX 스타일 경로(슬래시 `/`)만 지원.
+ *       Windows 백슬래시(`\`) 경로는 지원하지 않음.
+ *       브라우저 환경 및 Capacitor 플러그인용으로 설계됨.
  */
 
 /**
- * Combine paths (path.join replacement)
- * @note Supports POSIX style paths only (slash `/`)
+ * 경로 결합 (path.join 대체)
+ * @note POSIX 스타일 경로(슬래시 `/`)만 지원
  */
 export function join(...segments: string[]): string {
   return segments
@@ -19,7 +19,7 @@ export function join(...segments: string[]): string {
 }
 
 /**
- * Extract filename (path.basename replacement)
+ * 파일명 추출 (path.basename 대체)
  */
 export function basename(filePath: string, ext?: string): string {
   const name = filePath.split("/").pop() ?? "";
@@ -30,8 +30,8 @@ export function basename(filePath: string, ext?: string): string {
 }
 
 /**
- * Extract file extension (path.extname replacement)
- * @note Hidden files (e.g., `.gitignore`) return empty string (same as Node.js path.extname)
+ * 파일 확장자 추출 (path.extname 대체)
+ * @note 숨김 파일(예: `.gitignore`)은 빈 문자열 반환 (Node.js path.extname과 동일)
  */
 export function extname(filePath: string): string {
   const name = filePath.split("/").pop() ?? "";