@simplysm/core-common 13.0.15 → 13.0.18

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

@@ -9,63 +9,63 @@ import type { Time } from "../types/time";
 
 //#region 인터페이스
 
-export interface ReadonlyArrayExt<T> {
+export interface ReadonlyArrayExt<TItem> {
   /**
    * 조건에 맞는 단일 요소 반환
    * @param predicate 필터 조건 (생략 시 배열 전체 대상)
    * @returns 요소가 없으면 undefined
    * @throws ArgumentError 조건에 맞는 요소가 2개 이상이면 발생
    */
-  single(predicate?: (item: T, index: number) => boolean): T | undefined;
+  single(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
   /**
    * 첫 번째 요소 반환
    * @param predicate 필터 조건 (생략 시 첫 번째 요소 반환)
    * @returns 요소가 없으면 undefined
    */
-  first(predicate?: (item: T, index: number) => boolean): T | undefined;
+  first(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
   /** 비동기 필터 (순차 실행) */
-  filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+  filterAsync(predicate: (item: TItem, index: number) => Promise<boolean>): Promise<TItem[]>;
 
   /**
    * 마지막 요소 반환
    * @param predicate 필터 조건 (생략 시 마지막 요소 반환)
    * @returns 요소가 없으면 undefined
    */
-  last(predicate?: (item: T, index: number) => boolean): T | undefined;
+  last(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
 
   /** null/undefined 제거 */
-  filterExists(): NonNullable<T>[];
+  filterExists(): NonNullable<TItem>[];
 
   /** 특정 타입의 요소만 필터링 (PrimitiveTypeStr 또는 생성자 타입) */
-  ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
-  ofType<N extends T>(type: Type<N>): N[];
+  ofType<K extends PrimitiveTypeStr>(type: K): Extract<TItem, PrimitiveTypeMap[K]>[];
+  ofType<N extends TItem>(type: Type<N>): N[];
 
   /** 비동기 매핑 (순차 실행) */
-  mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+  mapAsync<R>(selector: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
 
   /** 중첩 배열 평탄화 */
-  mapMany(): T extends readonly (infer U)[] ? U[] : T;
+  mapMany(): TItem extends readonly (infer U)[] ? U[] : TItem;
 
   /** 매핑 후 평탄화 */
-  mapMany<R>(selector: (item: T, index: number) => R[]): R[];
+  mapMany<R>(selector: (item: TItem, index: number) => R[]): R[];
 
   /** 비동기 매핑 후 평탄화 (순차 실행) */
-  mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+  mapManyAsync<R>(selector: (item: TItem, index: number) => Promise<R[]>): Promise<R[]>;
 
   /**
    * 비동기 병렬 처리 (Promise.all 사용)
    * @note 하나라도 reject되면 전체가 fail-fast로 reject됨 (Promise.all 동작)
    */
-  parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+  parallelAsync<R>(fn: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
 
   /**
    * 키 기준 그룹화
    * @param keySelector 그룹 키 선택 함수
    * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
    */
-  groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
+  groupBy<K>(keySelector: (item: TItem, index: number) => K): { key: K; values: TItem[] }[];
 
   /**
    * 키 기준 그룹화 (값 변환 포함)
@@ -74,44 +74,47 @@ export interface ReadonlyArrayExt<T> {
    * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
    */
   groupBy<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
+    keySelector: (item: TItem, index: number) => K,
+    valueSelector: (item: TItem, index: number) => V,
   ): {
     key: K;
     values: V[];
   }[];
 
-  toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
+  toMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, TItem>;
 
-  toMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V>;
+  toMap<K, V>(
+    keySelector: (item: TItem, index: number) => K,
+    valueSelector: (item: TItem, index: number) => V,
+  ): Map<K, V>;
 
-  toMapAsync<K>(keySelector: (item: T, index: number) => Promise<K>): Promise<Map<K, T>>;
+  toMapAsync<K>(keySelector: (item: TItem, index: number) => Promise<K>): Promise<Map<K, TItem>>;
 
   toMapAsync<K, V>(
-    keySelector: (item: T, index: number) => Promise<K> | K,
-    valueSelector: (item: T, index: number) => Promise<V> | V,
+    keySelector: (item: TItem, index: number) => Promise<K> | K,
+    valueSelector: (item: TItem, index: number) => Promise<V> | V,
   ): Promise<Map<K, V>>;
 
-  toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
+  toArrayMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, TItem[]>;
 
   toArrayMap<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
+    keySelector: (item: TItem, index: number) => K,
+    valueSelector: (item: TItem, index: number) => V,
   ): Map<K, V[]>;
 
-  toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
+  toSetMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, Set<TItem>>;
   toSetMap<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
+    keySelector: (item: TItem, index: number) => K,
+    valueSelector: (item: TItem, index: number) => V,
   ): Map<K, Set<V>>;
 
-  toMapValues<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (items: T[]) => V): Map<K, V>;
+  toMapValues<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (items: TItem[]) => V): Map<K, V>;
 
-  toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
+  toObject(keySelector: (item: TItem, index: number) => string): Record<string, TItem>;
 
   toObject<V>(
-    keySelector: (item: T, index: number) => string,
-    valueSelector: (item: T, index: number) => V,
+    keySelector: (item: TItem, index: number) => string,
+    valueSelector: (item: TItem, index: number) => V,
   ): Record<string, V>;
 
   /**
@@ -150,18 +153,18 @@ export interface ReadonlyArrayExt<T> {
    * // ]}]
    * ```
    */
-  toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
+  toTree<K extends keyof TItem, P extends keyof TItem>(keyProp: K, parentKey: P): TreeArray<TItem>[];
 
   /**
    * 중복 제거
    * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
    * @note 객체 배열에서 keyFn 없이 사용 시 O(n²) 복잡도. 대량 데이터는 keyFn 사용 권장
    */
-  distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
+  distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number }): TItem[];
 
-  orderBy(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+  orderBy(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
 
-  orderByDesc(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+  orderByDesc(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
 
   /**
    * 두 배열 비교 (INSERT/DELETE/UPDATE)
@@ -169,68 +172,74 @@ export interface ReadonlyArrayExt<T> {
    * @param options keys: 키 비교용, excludes: 비교 제외 속성
    * @note target에 중복 키가 있으면 첫 번째 매칭만 사용됨
    */
-  diffs<P>(target: P[], options?: { keys?: string[]; excludes?: string[] }): ArrayDiffsResult<T, P>[];
-
-  oneWayDiffs<K extends keyof T>(
-    orgItems: T[] | Map<T[K], T>,
-    keyPropNameOrFn: K | ((item: T) => K),
+  diffs<TOtherItem>(
+    target: TOtherItem[],
+    options?: { keys?: string[]; excludes?: string[] },
+  ): ArrayDiffsResult<TItem, TOtherItem>[];
+
+  oneWayDiffs<K extends keyof TItem>(
+    orgItems: TItem[] | Map<TItem[K], TItem>,
+    keyPropNameOrFn: K | ((item: TItem) => K),
     options?: {
       includeSame?: boolean;
       excludes?: string[];
       includes?: string[];
     },
-  ): ArrayDiffs2Result<T>[];
+  ): ArrayDiffs2Result<TItem>[];
 
-  merge<P>(target: P[], options?: { keys?: string[]; excludes?: string[] }): (T | P | (T & P))[];
+  merge<TOtherItem>(
+    target: TOtherItem[],
+    options?: { keys?: string[]; excludes?: string[] },
+  ): (TItem | TOtherItem | (TItem & TOtherItem))[];
 
   /**
    * 요소의 합계 반환
    * @param selector 값 선택 함수 (생략 시 요소 자체를 number로 사용)
    * @returns 빈 배열인 경우 0 반환
    */
-  sum(selector?: (item: T, index: number) => number): number;
+  sum(selector?: (item: TItem, index: number) => number): number;
 
-  min(): T extends number | string ? T | undefined : never;
+  min(): TItem extends number | string ? TItem | undefined : never;
 
-  min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
+  min<P extends number | string>(selector?: (item: TItem, index: number) => P): P | undefined;
 
-  max(): T extends number | string ? T | undefined : never;
+  max(): TItem extends number | string ? TItem | undefined : never;
 
-  max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
+  max<P extends number | string>(selector?: (item: TItem, index: number) => P): P | undefined;
 
-  shuffle(): T[];
+  shuffle(): TItem[];
 }
 
 /**
  * 원본 배열을 변경하는 확장 메서드
  * @mutates 모든 메서드가 원본 배열을 직접 변경합니다
  */
-export interface MutableArrayExt<T> {
+export interface MutableArrayExt<TItem> {
   /**
    * 원본 배열에서 중복 제거
    * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
    * @note 객체 배열에서 keyFn 없이 사용 시 O(n²) 복잡도. 대량 데이터는 keyFn 사용 권장
    * @mutates
    */
-  distinctThis(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
+  distinctThis(options?: boolean | { matchAddress?: boolean; keyFn?: (item: TItem) => string | number }): TItem[];
 
   /** 원본 배열 오름차순 정렬 @mutates */
-  orderByThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+  orderByThis(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
 
   /** 원본 배열 내림차순 정렬 @mutates */
-  orderByDescThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+  orderByDescThis(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
 
   /** 원본 배열에 항목 삽입 @mutates */
-  insert(index: number, ...items: T[]): this;
+  insert(index: number, ...items: TItem[]): this;
 
   /** 원본 배열에서 항목 제거 @mutates */
-  remove(item: T): this;
+  remove(item: TItem): this;
 
   /** 원본 배열에서 조건에 맞는 항목 제거 @mutates */
-  remove(selector: (item: T, index: number) => boolean): this;
+  remove(selector: (item: TItem, index: number) => boolean): this;
 
   /** 원본 배열에서 항목 토글 (있으면 제거, 없으면 추가) @mutates */
-  toggle(item: T): this;
+  toggle(item: TItem): this;
 
   /** 원본 배열 비우기 @mutates */
   clear(): this;
@@ -240,17 +249,17 @@ export interface MutableArrayExt<T> {
 
 //#region 내보내기 타입
 
-export type ArrayDiffsResult<T, P> =
-  | { source: undefined; target: P } // INSERT
-  | { source: T; target: undefined } // DELETE
-  | { source: T; target: P }; // UPDATE
+export type ArrayDiffsResult<TOriginal, TOther> =
+  | { source: undefined; target: TOther } // INSERT
+  | { source: TOriginal; target: undefined } // DELETE
+  | { source: TOriginal; target: TOther }; // UPDATE
 
-export type ArrayDiffs2Result<T> =
-  | { type: "create"; item: T; orgItem: undefined }
-  | { type: "update"; item: T; orgItem: T }
-  | { type: "same"; item: T; orgItem: T };
+export type ArrayDiffs2Result<TItem> =
+  | { type: "create"; item: TItem; orgItem: undefined }
+  | { type: "update"; item: TItem; orgItem: TItem }
+  | { type: "same"; item: TItem; orgItem: TItem };
 
-export type TreeArray<T> = T & { children: TreeArray<T>[] };
+export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
 
 /** 정렬/비교 가능한 타입 */
 export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;

package/src/features/event-emitter.ts

@@ -4,7 +4,7 @@
  * 브라우저와 Node.js 모두에서 사용 가능한 타입 안전한 이벤트 에미터이다.
  * 내부적으로 EventTarget을 사용하여 구현되어 있다.
  *
- * @typeParam T 이벤트 타입 맵. 키는 이벤트 이름, 값은 이벤트 데이터 타입
+ * @typeParam TEvents 이벤트 타입 맵. 키는 이벤트 이름, 값은 이벤트 데이터 타입
  *
  * @example
  * interface MyEvents {
@@ -20,7 +20,7 @@
  * emitter.emit("data", "hello");
  * emitter.emit("done"); // void 타입은 인자 없이 호출
  */
-export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string, unknown>> {
+export class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
   private readonly _target = new EventTarget();
   // 이벤트 타입별로 리스너 맵 관리 (같은 리스너를 다른 이벤트에 등록 가능)
   // 다형적 리스너 관리를 위해 Function 타입 사용
@@ -33,7 +33,7 @@ export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string,
    * @param listener 이벤트 핸들러
    * @note 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨
    */
-  on<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void {
+  on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void {
     // 이벤트 타입별 맵 가져오거나 생성
     let typeMap = this._listenerMap.get(type);
     if (!typeMap) {
@@ -55,7 +55,7 @@ export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string,
    * @param type 이벤트 타입
    * @param listener 제거할 이벤트 핸들러
    */
-  off<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void {
+  off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void {
     const typeMap = this._listenerMap.get(type);
     if (!typeMap) return;
 
@@ -77,7 +77,7 @@ export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string,
    * @param type 이벤트 타입
    * @param args 이벤트 데이터 (void 타입이면 생략)
    */
-  emit<K extends keyof T & string>(type: K, ...args: T[K] extends void ? [] : [data: T[K]]): void {
+  emit<K extends keyof TEvents & string>(type: K, ...args: TEvents[K] extends void ? [] : [data: TEvents[K]]): void {
     this._target.dispatchEvent(new CustomEvent(type, { detail: args[0] }));
   }
 
@@ -87,7 +87,7 @@ export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string,
    * @param type 이벤트 타입
    * @returns 등록된 리스너 수
    */
-  listenerCount<K extends keyof T & string>(type: K): number {
+  listenerCount<K extends keyof TEvents & string>(type: K): number {
     return this._listenerMap.get(type)?.size ?? 0;
   }
 

package/src/index.ts

@@ -7,8 +7,8 @@ import "./extensions/map-ext";
 
 export * from "./env";
 
-// arr-extension에서 타입만 re-export
-export type { ArrayDiffsResult, ArrayDiffs2Result, TreeArray } from "./extensions/arr-ext";
+// arr-extension re-export
+export * from "./extensions/arr-ext";
 
 //#region errors
 export * from "./errors/sd-error";

package/src/types/lazy-gc-map.ts

@@ -19,23 +19,11 @@ import consola from "consola";
  *   map.dispose();
  * }
  */
-export class LazyGcMap<K, V> {
+export class LazyGcMap<TKey, TValue> {
   private static readonly _logger = consola.withTag("LazyGcMap");
 
-  /**
-   * dispose() 미호출 감지용 registry
-   * @note FinalizationRegistry는 Chrome 84+, Node 14.6+ 지원
-   *       미지원 환경에서는 경고 없이 동작하지만, dispose() 미호출 시 메모리 누수 가능
-   */
-  private static readonly _registry =
-    typeof FinalizationRegistry !== "undefined"
-      ? new FinalizationRegistry<string>((id) => {
-          LazyGcMap._logger.warn(`LazyGcMap(${id})이 dispose() 없이 가비지 수집됨. 메모리 누수 가능성 있음.`);
-        })
-      : undefined;
-
   // 실제 데이터와 마지막 접근 시간을 함께 저장
-  private readonly _map = new Map<K, { value: V; lastAccess: number }>();
+  private readonly _map = new Map<TKey, { value: TValue; lastAccess: number }>();
 
   // GC 타이머
   private _gcTimer?: ReturnType<typeof setInterval>;
@@ -43,8 +31,6 @@ export class LazyGcMap<K, V> {
   private _isGcRunning = false;
   // destroy 호출 여부
   private _isDestroyed = false;
-  // 인스턴스 식별자 (경고 메시지용)
-  private readonly _instanceId = Math.random().toString(36).slice(2);
 
   /**
    * @param _options 설정 옵션
@@ -56,11 +42,9 @@ export class LazyGcMap<K, V> {
     private readonly _options: {
       gcInterval?: number;
       expireTime: number;
-      onExpire?: (key: K, value: V) => void | Promise<void>;
+      onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
     },
-  ) {
-    LazyGcMap._registry?.register(this, this._instanceId);
-  }
+  ) {}
 
   /** 저장된 항목 수 */
   get size(): number {
@@ -68,13 +52,13 @@ export class LazyGcMap<K, V> {
   }
 
   /** 키 존재 여부 확인 (접근 시간 갱신 안함) */
-  has(key: K): boolean {
+  has(key: TKey): boolean {
     if (this._isDestroyed) return false;
     return this._map.has(key);
   }
 
   /** 값 조회 (접근 시간 갱신됨) */
-  get(key: K): V | undefined {
+  get(key: TKey): TValue | undefined {
     if (this._isDestroyed) return undefined;
     const item = this._map.get(key);
     if (item == null) return undefined;
@@ -85,7 +69,7 @@ export class LazyGcMap<K, V> {
   }
 
   /** 값 저장 (접근 시간 설정 및 GC 타이머 시작) */
-  set(key: K, value: V): void {
+  set(key: TKey, value: TValue): void {
     if (this._isDestroyed) return;
     this._map.set(key, { value, lastAccess: Date.now() });
     // 데이터가 들어왔으므로 GC 타이머 가동
@@ -93,7 +77,7 @@ export class LazyGcMap<K, V> {
   }
 
   /** 항목 삭제 (비었으면 GC 타이머 중지) */
-  delete(key: K): boolean {
+  delete(key: TKey): boolean {
     if (this._isDestroyed) return false;
     const result = this._map.delete(key);
     // 비었으면 타이머 중지
@@ -107,8 +91,6 @@ export class LazyGcMap<K, V> {
   dispose(): void {
     if (this._isDestroyed) return;
     this._isDestroyed = true;
-    LazyGcMap._registry?.unregister(this);
-
     this._map.clear();
     this._stopGc();
   }
@@ -133,7 +115,7 @@ export class LazyGcMap<K, V> {
    * @param factory 키가 없을 때 값을 생성하는 함수
    * @returns 기존 값 또는 새로 생성된 값
    */
-  getOrCreate(key: K, factory: () => V): V {
+  getOrCreate(key: TKey, factory: () => TValue): TValue {
     if (this._isDestroyed) {
       throw new Error("LazyGcMap이 이미 dispose되었습니다.");
     }
@@ -149,7 +131,7 @@ export class LazyGcMap<K, V> {
   }
 
   /** 값들만 순회 (Iterator) */
-  *values(): IterableIterator<V> {
+  *values(): IterableIterator<TValue> {
     if (this._isDestroyed) return;
     for (const item of this._map.values()) {
       yield item.value;
@@ -157,13 +139,13 @@ export class LazyGcMap<K, V> {
   }
 
   /** 키들만 순회 (Iterator) */
-  *keys(): IterableIterator<K> {
+  *keys(): IterableIterator<TKey> {
     if (this._isDestroyed) return;
     yield* this._map.keys();
   }
 
   /** 엔트리 순회 (Iterator) */
-  *entries(): IterableIterator<[K, V]> {
+  *entries(): IterableIterator<[TKey, TValue]> {
     if (this._isDestroyed) return;
     for (const [key, item] of this._map.entries()) {
       yield [key, item.value];
@@ -191,7 +173,7 @@ export class LazyGcMap<K, V> {
       const now = Date.now();
 
       // 1. 만료된 항목 수집 (삭제 전)
-      const expiredEntries: { key: K; item: { value: V; lastAccess: number } }[] = [];
+      const expiredEntries: { key: TKey; item: { value: TValue; lastAccess: number } }[] = [];
       for (const [key, item] of this._map) {
         if (now - item.lastAccess > this._options.expireTime) {
           expiredEntries.push({ key, item });

package/src/utils/json.ts

@@ -172,7 +172,7 @@ export function jsonStringify(
  * @security 개발 모드(`__DEV__`)에서만 에러 메시지에 JSON 문자열 전체가 포함된다.
  * 프로덕션 모드에서는 JSON 길이만 포함된다.
  */
-export function jsonParse<T = unknown>(json: string): T {
+export function jsonParse<TResult = unknown>(json: string): TResult {
   try {
     return objNullToUndefined(
       JSON.parse(json, (_key, value: unknown) => {
@@ -218,7 +218,7 @@ export function jsonParse<T = unknown>(json: string): T {
 
         return value;
       }),
-    ) as T;
+    ) as TResult;
   } catch (err) {
     if (env.DEV) {
       throw new SdError(err, "JSON 파싱 에러: \n" + json);