@simplysm/core-common 13.0.0-beta.2 → 13.0.0-beta.21

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

@@ -1,258 +0,0 @@
-/**
- * Array 확장 타입 정의
- */
-
-import type { PrimitiveTypeMap, PrimitiveTypeStr, Type } from "../common.types";
-import type { DateTime } from "../types/date-time";
-import type { DateOnly } from "../types/date-only";
-import type { Time } from "../types/time";
-
-//#region 인터페이스
-
-export interface ReadonlyArrayExt<T> {
-  /**
-   * 조건에 맞는 단일 요소 반환
-   * @param predicate 필터 조건 (생략 시 배열 전체 대상)
-   * @returns 요소가 없으면 undefined
-   * @throws ArgumentError 조건에 맞는 요소가 2개 이상이면 발생
-   */
-  single(predicate?: (item: T, index: number) => boolean): T | undefined;
-
-  /**
-   * 첫 번째 요소 반환
-   * @param predicate 필터 조건 (생략 시 첫 번째 요소 반환)
-   * @returns 요소가 없으면 undefined
-   */
-  first(predicate?: (item: T, index: number) => boolean): T | undefined;
-
-  /** 비동기 필터 (순차 실행) */
-  filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
-
-  /**
-   * 마지막 요소 반환
-   * @param predicate 필터 조건 (생략 시 마지막 요소 반환)
-   * @returns 요소가 없으면 undefined
-   */
-  last(predicate?: (item: T, index: number) => boolean): T | undefined;
-
-  /** null/undefined 제거 */
-  filterExists(): NonNullable<T>[];
-
-  /** 특정 타입의 요소만 필터링 (PrimitiveTypeStr 또는 생성자 타입) */
-  ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
-  ofType<N extends T>(type: Type<N>): N[];
-
-  /** 비동기 매핑 (순차 실행) */
-  mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
-
-  /** 중첩 배열 평탄화 */
-  mapMany(): T extends readonly (infer U)[] ? U[] : T;
-
-  /** 매핑 후 평탄화 */
-  mapMany<R>(selector: (item: T, index: number) => R[]): R[];
-
-  /** 비동기 매핑 후 평탄화 (순차 실행) */
-  mapManyAsync<R>(selector: (item: T, 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[]>;
-
-  /**
-   * 키 기준 그룹화
-   * @param keySelector 그룹 키 선택 함수
-   * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
-   */
-  groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
-
-  /**
-   * 키 기준 그룹화 (값 변환 포함)
-   * @param keySelector 그룹 키 선택 함수
-   * @param valueSelector 값 변환 함수
-   * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
-   */
-  groupBy<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
-  ): {
-    key: K;
-    values: V[];
-  }[];
-
-  toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
-
-  toMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V>;
-
-  toMapAsync<K>(keySelector: (item: T, index: number) => Promise<K>): Promise<Map<K, T>>;
-
-  toMapAsync<K, V>(
-    keySelector: (item: T, index: number) => Promise<K> | K,
-    valueSelector: (item: T, index: number) => Promise<V> | V,
-  ): Promise<Map<K, V>>;
-
-  toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
-
-  toArrayMap<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
-  ): Map<K, V[]>;
-
-  toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
-  toSetMap<K, V>(
-    keySelector: (item: T, index: number) => K,
-    valueSelector: (item: T, index: number) => V,
-  ): Map<K, Set<V>>;
-
-  toMapValues<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (items: T[]) => V): Map<K, V>;
-
-  toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
-
-  toObject<V>(
-    keySelector: (item: T, index: number) => string,
-    valueSelector: (item: T, index: number) => V,
-  ): Record<string, V>;
-
-  /**
-   * 평탄한 배열을 트리 구조로 변환한다
-   *
-   * @param keyProp 각 항목의 고유 키 속성명
-   * @param parentKey 부모 항목의 키를 참조하는 속성명
-   * @returns 루트 항목들의 배열 (각 항목에 children 속성 추가)
-   *
-   * @remarks
-   * - parentKey 값이 null/undefined인 항목이 루트가 된다
-   * - 내부적으로 toArrayMap을 사용하여 O(n) 복잡도로 처리한다
-   * - 원본 항목은 복사되어 children 속성이 추가된다
-   *
-   * @example
-   * ```typescript
-   * interface Item {
-   *   id: number;
-   *   parentId?: number;
-   *   name: string;
-   * }
-   *
-   * const items: Item[] = [
-   *   { id: 1, name: "root" },
-   *   { id: 2, parentId: 1, name: "child1" },
-   *   { id: 3, parentId: 1, name: "child2" },
-   *   { id: 4, parentId: 2, name: "grandchild" },
-   * ];
-   *
-   * const tree = items.toTree("id", "parentId");
-   * // [{ id: 1, name: "root", children: [
-   * //   { id: 2, name: "child1", children: [
-   * //     { id: 4, name: "grandchild", children: [] }
-   * //   ]},
-   * //   { id: 3, name: "child2", children: [] }
-   * // ]}]
-   * ```
-   */
-  toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
-
-  /**
-   * 중복 제거
-   * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
-   * @note 객체 배열에서 keyFn 없이 사용 시 O(n²) 복잡도. 대량 데이터는 keyFn 사용 권장
-   */
-  distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
-
-  orderBy(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
-
-  orderByDesc(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
-
-  /**
-   * 두 배열 비교 (INSERT/DELETE/UPDATE)
-   * @param target 비교 대상 배열
-   * @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),
-    options?: {
-      includeSame?: boolean;
-      excludes?: string[];
-      includes?: string[];
-    },
-  ): ArrayDiffs2Result<T>[];
-
-  merge<P>(target: P[], options?: { keys?: string[]; excludes?: string[] }): (T | P | (T & P))[];
-
-  /**
-   * 요소의 합계 반환
-   * @param selector 값 선택 함수 (생략 시 요소 자체를 number로 사용)
-   * @returns 빈 배열인 경우 0 반환
-   */
-  sum(selector?: (item: T, index: number) => number): number;
-
-  min(): T extends number | string ? T | undefined : never;
-
-  min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-
-  max(): T extends number | string ? T | undefined : never;
-
-  max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-
-  shuffle(): T[];
-}
-
-/**
- * 원본 배열을 변경하는 확장 메서드
- * @mutates 모든 메서드가 원본 배열을 직접 변경합니다
- */
-export interface MutableArrayExt<T> {
-  /**
-   * 원본 배열에서 중복 제거
-   * @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[];
-
-  /** 원본 배열 오름차순 정렬 @mutates */
-  orderByThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
-
-  /** 원본 배열 내림차순 정렬 @mutates */
-  orderByDescThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
-
-  /** 원본 배열에 항목 삽입 @mutates */
-  insert(index: number, ...items: T[]): this;
-
-  /** 원본 배열에서 항목 제거 @mutates */
-  remove(item: T): this;
-
-  /** 원본 배열에서 조건에 맞는 항목 제거 @mutates */
-  remove(selector: (item: T, index: number) => boolean): this;
-
-  /** 원본 배열에서 항목 토글 (있으면 제거, 없으면 추가) @mutates */
-  toggle(item: T): this;
-
-  /** 원본 배열 비우기 @mutates */
-  clear(): this;
-}
-
-//#endregion
-
-//#region 내보내기 타입
-
-export type ArrayDiffsResult<T, P> =
-  | { source: undefined; target: P } // INSERT
-  | { source: T; target: undefined } // DELETE
-  | { source: T; target: P }; // 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 TreeArray<T> = T & { children: TreeArray<T>[] };
-
-/** 정렬/비교 가능한 타입 */
-export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
-
-//#endregion

package/src/extensions/map-ext.ts

@@ -1,86 +0,0 @@
-/**
- * Map 확장 메서드
- */
-
-declare global {
-  interface Map<K, V> {
-    /**
-     * 키에 해당하는 값이 없으면 새 값을 설정하고 반환
-     *
-     * @remarks
-     * **주의**: V 타입이 함수인 경우(예: `Map<string, () => void>`),
-     * 두 번째 인자로 함수를 직접 전달하면 팩토리로 인식되어 호출됩니다.
-     * 함수 자체를 값으로 저장하려면 팩토리로 감싸세요.
-     *
-     * @example
-     * ```typescript
-     * // 일반 값
-     * map.getOrCreate("key", 0);
-     * map.getOrCreate("key", []);
-     *
-     * // 팩토리 함수 (계산 비용이 큰 경우)
-     * map.getOrCreate("key", () => expensiveComputation());
-     *
-     * // 함수를 값으로 저장하는 경우
-     * const fnMap = new Map<string, () => void>();
-     * const myFn = () => console.log("hello");
-     * fnMap.getOrCreate("key", () => myFn);  // 팩토리로 감싸기
-     * ```
-     */
-    getOrCreate(key: K, newValue: V): V;
-    getOrCreate(key: K, newValueFn: () => V): V;
-
-    /**
-     * 키에 해당하는 값을 함수로 업데이트한다
-     *
-     * @param key 업데이트할 키
-     * @param updateFn 현재 값을 받아 새 값을 반환하는 함수 (키가 없으면 undefined 전달)
-     *
-     * @remarks
-     * 키가 존재하지 않아도 updateFn이 호출되어 새 값이 설정된다.
-     * 기존 값 기반 계산이 필요한 경우 (카운터 증가, 배열에 추가 등) 유용하다.
-     *
-     * @example
-     * ```typescript
-     * const countMap = new Map<string, number>();
-     *
-     * // 카운터 증가
-     * countMap.update("key", (v) => (v ?? 0) + 1);
-     *
-     * // 배열에 항목 추가
-     * const arrayMap = new Map<string, string[]>();
-     * arrayMap.update("key", (v) => [...(v ?? []), "item"]);
-     * ```
-     */
-    update(key: K, updateFn: (v: V | undefined) => V): void;
-  }
-}
-
-Object.defineProperty(Map.prototype, "getOrCreate", {
-  value: function <K, V>(this: Map<K, V>, key: K, newValue: V | (() => V)): V {
-    if (!this.has(key)) {
-      if (typeof newValue === "function") {
-        this.set(key, (newValue as () => V)());
-      } else {
-        this.set(key, newValue);
-      }
-    }
-    return this.get(key)!;
-  },
-  enumerable: false,
-  writable: true,
-  configurable: true,
-});
-
-Object.defineProperty(Map.prototype, "update", {
-  value: function <K, V>(this: Map<K, V>, key: K, updateFn: (v: V | undefined) => V): void {
-    const val = this.get(key);
-    const res = updateFn(val);
-    this.set(key, res);
-  },
-  enumerable: false,
-  writable: true,
-  configurable: true,
-});
-
-export {};

package/src/extensions/set-ext.ts

@@ -1,68 +0,0 @@
-/**
- * Set 확장 메서드
- */
-
-declare global {
-  interface Set<T> {
-    /**
-     * 여러 값을 한 번에 추가
-     */
-    adds(...values: T[]): this;
-
-    /**
-     * 값을 토글한다 (있으면 제거, 없으면 추가)
-     *
-     * @param value 토글할 값
-     * @param addOrDel 강제로 추가("add") 또는 제거("del") 지정 (생략 시 자동 토글)
-     * @returns this (메서드 체이닝 가능)
-     *
-     * @remarks
-     * addOrDel 파라미터로 조건부 추가/제거를 간결하게 표현할 수 있다.
-     *
-     * @example
-     * ```typescript
-     * const set = new Set<number>([1, 2, 3]);
-     *
-     * set.toggle(2);  // 2가 있으므로 제거 → {1, 3}
-     * set.toggle(4);  // 4가 없으므로 추가 → {1, 3, 4}
-     *
-     * // 조건부 토글
-     * const isAdmin = true;
-     * set.toggle(5, isAdmin ? "add" : "del");  // 강제 추가
-     * ```
-     */
-    toggle(value: T, addOrDel?: "add" | "del"): this;
-  }
-}
-
-Object.defineProperty(Set.prototype, "adds", {
-  value: function <T>(this: Set<T>, ...values: T[]): Set<T> {
-    for (const val of values) {
-      this.add(val);
-    }
-    return this;
-  },
-  enumerable: false,
-  writable: true,
-  configurable: true,
-});
-
-Object.defineProperty(Set.prototype, "toggle", {
-  value: function <T>(this: Set<T>, value: T, addOrDel?: "add" | "del"): Set<T> {
-    if (addOrDel === "add") {
-      this.add(value);
-    } else if (addOrDel === "del") {
-      this.delete(value);
-    } else if (this.has(value)) {
-      this.delete(value);
-    } else {
-      this.add(value);
-    }
-    return this;
-  },
-  enumerable: false,
-  writable: true,
-  configurable: true,
-});
-
-export {};

package/src/features/debounce-queue.ts

@@ -1,116 +0,0 @@
-/**
- * 비동기 함수 디바운스 큐
- *
- * 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시합니다.
- * 입력 필드 자동완성, 연속적인 상태 변경 배치 처리 등에 유용합니다.
- *
- * @remarks
- * 실행 중에 추가된 요청은 디바운스 지연 없이 현재 실행이 완료된 직후 처리됩니다.
- * 이는 실행 완료 전에 들어온 요청이 누락되지 않도록 하기 위한 의도적 설계입니다.
- *
- * @example
- * const queue = new DebounceQueue(300); // 300ms 딜레이
- * queue.run(() => console.log("1")); // 무시됨
- * queue.run(() => console.log("2")); // 무시됨
- * queue.run(() => console.log("3")); // 300ms 후 실행됨
- *
- * @example
- * // 에러 처리
- * queue.on("error", (err) => console.error(err));
- */
-import { SdError } from "../errors/sd-error";
-import { EventEmitter } from "./event-emitter";
-import { createConsola } from "consola";
-
-interface DebounceQueueEvents {
-  error: SdError;
-}
-
-export class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
-  private static readonly _logger = createConsola().withTag("DebounceQueue");
-
-  private _pendingFn: (() => void | Promise<void>) | undefined;
-  private _isRunning = false;
-  private _isDisposed = false;
-  private _timer: ReturnType<typeof setTimeout> | undefined;
-
-  /**
-   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
-   */
-  constructor(private readonly _delay?: number) {
-    super();
-  }
-
-  /**
-   * 대기 중인 작업과 타이머 정리
-   */
-  override dispose(): void {
-    this._isDisposed = true;
-    if (this._timer) {
-      clearTimeout(this._timer);
-      this._timer = undefined;
-    }
-    this._pendingFn = undefined;
-    super.dispose();
-  }
-
-  /**
-   * using 문 지원
-   */
-  override [Symbol.dispose](): void {
-    this.dispose();
-  }
-
-  /**
-   * 함수를 큐에 추가
-   * 이전에 추가된 함수가 있으면 대체됨
-   */
-  run(fn: () => void | Promise<void>): void {
-    if (this._isDisposed) return;
-
-    this._pendingFn = fn;
-
-    if (this._timer) {
-      clearTimeout(this._timer);
-      this._timer = undefined;
-    }
-
-    if (!this._isRunning) {
-      this._timer = setTimeout(() => {
-        void this._processLast();
-      }, this._delay);
-    }
-  }
-
-  private async _processLast(): Promise<void> {
-    if (this._isDisposed || this._isRunning || !this._pendingFn) return;
-
-    this._isRunning = true;
-    this._timer = undefined;
-
-    try {
-      // 실행 중에 새 요청이 들어오면 디바운스 지연 없이 즉시 처리
-      // 이는 "실행 완료 전에 들어온 요청은 실행 직후 바로 처리"하는 의도적 설계
-      while (this._pendingFn) {
-        const currentFn = this._pendingFn;
-        this._pendingFn = undefined;
-
-        try {
-          await currentFn();
-        } catch (err) {
-          const error = err instanceof Error ? err : new Error(String(err));
-          const sdError = new SdError(error, "작업 실행 중 오류 발생");
-
-          // 리스너가 있으면 이벤트로 전달, 없으면 로깅
-          if (this.listenerCount("error") > 0) {
-            this.emit("error", sdError);
-          } else {
-            DebounceQueue._logger.error(sdError);
-          }
-        }
-      }
-    } finally {
-      this._isRunning = false;
-    }
-  }
-}

package/src/features/event-emitter.ts

@@ -1,112 +0,0 @@
-/**
- * EventTarget 래퍼 - EventEmitter와 유사한 API 제공
- *
- * 브라우저와 Node.js 모두에서 사용 가능한 타입 안전한 이벤트 에미터이다.
- * 내부적으로 EventTarget을 사용하여 구현되어 있다.
- *
- * @typeParam T 이벤트 타입 맵. 키는 이벤트 이름, 값은 이벤트 데이터 타입
- *
- * @example
- * interface MyEvents {
- *   data: string;
- *   error: Error;
- *   done: void;
- * }
- *
- * class MyEmitter extends EventEmitter<MyEvents> {}
- *
- * const emitter = new MyEmitter();
- * emitter.on("data", (data) => console.log(data)); // data: string
- * emitter.emit("data", "hello");
- * emitter.emit("done"); // void 타입은 인자 없이 호출
- */
-export class EventEmitter<T extends { [K in keyof T]: unknown } = Record<string, unknown>> {
-  private readonly _target = new EventTarget();
-  // 이벤트 타입별로 리스너 맵 관리 (같은 리스너를 다른 이벤트에 등록 가능)
-  // 다형적 리스너 관리를 위해 Function 타입 사용
-  private readonly _listenerMap = new Map<string, Map<Function, (e: Event) => void>>();
-
-  /**
-   * 이벤트 리스너 등록
-   *
-   * @param type 이벤트 타입
-   * @param listener 이벤트 핸들러
-   * @note 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨
-   */
-  on<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void {
-    // 이벤트 타입별 맵 가져오거나 생성
-    let typeMap = this._listenerMap.get(type);
-    if (!typeMap) {
-      typeMap = new Map();
-      this._listenerMap.set(type, typeMap);
-    }
-
-    // 이미 해당 이벤트에 등록된 리스너면 무시 (중복 등록 방지)
-    if (typeMap.has(listener)) return;
-
-    const wrappedListener = (e: Event) => listener((e as CustomEvent).detail);
-    typeMap.set(listener, wrappedListener);
-    this._target.addEventListener(type, wrappedListener);
-  }
-
-  /**
-   * 이벤트 리스너 제거
-   *
-   * @param type 이벤트 타입
-   * @param listener 제거할 이벤트 핸들러
-   */
-  off<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void {
-    const typeMap = this._listenerMap.get(type);
-    if (!typeMap) return;
-
-    const wrappedListener = typeMap.get(listener);
-    if (wrappedListener) {
-      this._target.removeEventListener(type, wrappedListener);
-      typeMap.delete(listener);
-
-      // 빈 맵 정리
-      if (typeMap.size === 0) {
-        this._listenerMap.delete(type);
-      }
-    }
-  }
-
-  /**
-   * 이벤트 발생
-   *
-   * @param type 이벤트 타입
-   * @param args 이벤트 데이터 (void 타입이면 생략)
-   */
-  emit<K extends keyof T & string>(type: K, ...args: T[K] extends void ? [] : [data: T[K]]): void {
-    this._target.dispatchEvent(new CustomEvent(type, { detail: args[0] }));
-  }
-
-  /**
-   * 특정 이벤트의 리스너 수 반환
-   *
-   * @param type 이벤트 타입
-   * @returns 등록된 리스너 수
-   */
-  listenerCount<K extends keyof T & string>(type: K): number {
-    return this._listenerMap.get(type)?.size ?? 0;
-  }
-
-  /**
-   * 모든 이벤트 리스너를 제거한다.
-   */
-  dispose(): void {
-    for (const [type, typeMap] of this._listenerMap) {
-      for (const wrappedListener of typeMap.values()) {
-        this._target.removeEventListener(type, wrappedListener);
-      }
-    }
-    this._listenerMap.clear();
-  }
-
-  /**
-   * using 문 지원
-   */
-  [Symbol.dispose](): void {
-    this.dispose();
-  }
-}