@simplysm/core-common 13.0.0-beta.1

package/dist/extensions/arr-ext.types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 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";
+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;
+}
+export type ArrayDiffsResult<T, P> = {
+    source: undefined;
+    target: P;
+} | {
+    source: T;
+    target: undefined;
+} | {
+    source: T;
+    target: P;
+};
+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;
+//# sourceMappingURL=arr-ext.types.d.ts.map

package/dist/extensions/arr-ext.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arr-ext.types.d.ts","sourceRoot":"","sources":["../../src/extensions/arr-ext.types.ts"],"names":[],"mappings":"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"}

package/dist/extensions/arr-ext.types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=arr-ext.types.js.map

package/dist/extensions/arr-ext.types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/extensions/map-ext.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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;
+    }
+}
+export {};
+//# sourceMappingURL=map-ext.d.ts.map

package/dist/extensions/map-ext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-ext.d.ts","sourceRoot":"","sources":["../../src/extensions/map-ext.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,GAAG,CAAC,CAAC,EAAE,CAAC;QAChB;;;;;;;;;;;;;;;;;;;;;;WAsBG;QACH,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;QACpC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;QAE5C;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,IAAI,CAAC;KACzD;CACF;AA6BD,OAAO,EAAE,CAAC"}

package/dist/extensions/map-ext.js

@@ -0,0 +1,26 @@
+Object.defineProperty(Map.prototype, "getOrCreate", {
+  value: function(key, newValue) {
+    if (!this.has(key)) {
+      if (typeof newValue === "function") {
+        this.set(key, newValue());
+      } else {
+        this.set(key, newValue);
+      }
+    }
+    return this.get(key);
+  },
+  enumerable: false,
+  writable: true,
+  configurable: true
+});
+Object.defineProperty(Map.prototype, "update", {
+  value: function(key, updateFn) {
+    const val = this.get(key);
+    const res = updateFn(val);
+    this.set(key, res);
+  },
+  enumerable: false,
+  writable: true,
+  configurable: true
+});
+//# sourceMappingURL=map-ext.js.map

package/dist/extensions/map-ext.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/extensions/map-ext.ts"],
+  "sourcesContent": ["/**\n * Map \uD655\uC7A5 \uBA54\uC11C\uB4DC\n */\n\ndeclare global {\n  interface Map<K, V> {\n    /**\n     * \uD0A4\uC5D0 \uD574\uB2F9\uD558\uB294 \uAC12\uC774 \uC5C6\uC73C\uBA74 \uC0C8 \uAC12\uC744 \uC124\uC815\uD558\uACE0 \uBC18\uD658\n     *\n     * @remarks\n     * **\uC8FC\uC758**: V \uD0C0\uC785\uC774 \uD568\uC218\uC778 \uACBD\uC6B0(\uC608: `Map<string, () => void>`),\n     * \uB450 \uBC88\uC9F8 \uC778\uC790\uB85C \uD568\uC218\uB97C \uC9C1\uC811 \uC804\uB2EC\uD558\uBA74 \uD329\uD1A0\uB9AC\uB85C \uC778\uC2DD\uB418\uC5B4 \uD638\uCD9C\uB429\uB2C8\uB2E4.\n     * \uD568\uC218 \uC790\uCCB4\uB97C \uAC12\uC73C\uB85C \uC800\uC7A5\uD558\uB824\uBA74 \uD329\uD1A0\uB9AC\uB85C \uAC10\uC2F8\uC138\uC694.\n     *\n     * @example\n     * ```typescript\n     * // \uC77C\uBC18 \uAC12\n     * map.getOrCreate(\"key\", 0);\n     * map.getOrCreate(\"key\", []);\n     *\n     * // \uD329\uD1A0\uB9AC \uD568\uC218 (\uACC4\uC0B0 \uBE44\uC6A9\uC774 \uD070 \uACBD\uC6B0)\n     * map.getOrCreate(\"key\", () => expensiveComputation());\n     *\n     * // \uD568\uC218\uB97C \uAC12\uC73C\uB85C \uC800\uC7A5\uD558\uB294 \uACBD\uC6B0\n     * const fnMap = new Map<string, () => void>();\n     * const myFn = () => console.log(\"hello\");\n     * fnMap.getOrCreate(\"key\", () => myFn);  // \uD329\uD1A0\uB9AC\uB85C \uAC10\uC2F8\uAE30\n     * ```\n     */\n    getOrCreate(key: K, newValue: V): V;\n    getOrCreate(key: K, newValueFn: () => V): V;\n\n    /**\n     * \uD0A4\uC5D0 \uD574\uB2F9\uD558\uB294 \uAC12\uC744 \uD568\uC218\uB85C \uC5C5\uB370\uC774\uD2B8\uD55C\uB2E4\n     *\n     * @param key \uC5C5\uB370\uC774\uD2B8\uD560 \uD0A4\n     * @param updateFn \uD604\uC7AC \uAC12\uC744 \uBC1B\uC544 \uC0C8 \uAC12\uC744 \uBC18\uD658\uD558\uB294 \uD568\uC218 (\uD0A4\uAC00 \uC5C6\uC73C\uBA74 undefined \uC804\uB2EC)\n     *\n     * @remarks\n     * \uD0A4\uAC00 \uC874\uC7AC\uD558\uC9C0 \uC54A\uC544\uB3C4 updateFn\uC774 \uD638\uCD9C\uB418\uC5B4 \uC0C8 \uAC12\uC774 \uC124\uC815\uB41C\uB2E4.\n     * \uAE30\uC874 \uAC12 \uAE30\uBC18 \uACC4\uC0B0\uC774 \uD544\uC694\uD55C \uACBD\uC6B0 (\uCE74\uC6B4\uD130 \uC99D\uAC00, \uBC30\uC5F4\uC5D0 \uCD94\uAC00 \uB4F1) \uC720\uC6A9\uD558\uB2E4.\n     *\n     * @example\n     * ```typescript\n     * const countMap = new Map<string, number>();\n     *\n     * // \uCE74\uC6B4\uD130 \uC99D\uAC00\n     * countMap.update(\"key\", (v) => (v ?? 0) + 1);\n     *\n     * // \uBC30\uC5F4\uC5D0 \uD56D\uBAA9 \uCD94\uAC00\n     * const arrayMap = new Map<string, string[]>();\n     * arrayMap.update(\"key\", (v) => [...(v ?? []), \"item\"]);\n     * ```\n     */\n    update(key: K, updateFn: (v: V | undefined) => V): void;\n  }\n}\n\nObject.defineProperty(Map.prototype, \"getOrCreate\", {\n  value: function <K, V>(this: Map<K, V>, key: K, newValue: V | (() => V)): V {\n    if (!this.has(key)) {\n      if (typeof newValue === \"function\") {\n        this.set(key, (newValue as () => V)());\n      } else {\n        this.set(key, newValue);\n      }\n    }\n    return this.get(key)!;\n  },\n  enumerable: false,\n  writable: true,\n  configurable: true,\n});\n\nObject.defineProperty(Map.prototype, \"update\", {\n  value: function <K, V>(this: Map<K, V>, key: K, updateFn: (v: V | undefined) => V): void {\n    const val = this.get(key);\n    const res = updateFn(val);\n    this.set(key, res);\n  },\n  enumerable: false,\n  writable: true,\n  configurable: true,\n});\n\nexport {};\n"],
+  "mappings": "AA0DA,OAAO,eAAe,IAAI,WAAW,eAAe;AAAA,EAClD,OAAO,SAAiC,KAAQ,UAA4B;AAC1E,QAAI,CAAC,KAAK,IAAI,GAAG,GAAG;AAClB,UAAI,OAAO,aAAa,YAAY;AAClC,aAAK,IAAI,KAAM,SAAqB,CAAC;AAAA,MACvC,OAAO;AACL,aAAK,IAAI,KAAK,QAAQ;AAAA,MACxB;AAAA,IACF;AACA,WAAO,KAAK,IAAI,GAAG;AAAA,EACrB;AAAA,EACA,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAChB,CAAC;AAED,OAAO,eAAe,IAAI,WAAW,UAAU;AAAA,EAC7C,OAAO,SAAiC,KAAQ,UAAyC;AACvF,UAAM,MAAM,KAAK,IAAI,GAAG;AACxB,UAAM,MAAM,SAAS,GAAG;AACxB,SAAK,IAAI,KAAK,GAAG;AAAA,EACnB;AAAA,EACA,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAChB,CAAC;",
+  "names": []
+}

package/dist/extensions/set-ext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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;
+    }
+}
+export {};
+//# sourceMappingURL=set-ext.d.ts.map

package/dist/extensions/set-ext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-ext.d.ts","sourceRoot":"","sources":["../../src/extensions/set-ext.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,GAAG,CAAC,CAAC;QACb;;WAEG;QACH,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QAE3B;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;KAClD;CACF;AAgCD,OAAO,EAAE,CAAC"}

package/dist/extensions/set-ext.js

@@ -0,0 +1,29 @@
+Object.defineProperty(Set.prototype, "adds", {
+  value: function(...values) {
+    for (const val of values) {
+      this.add(val);
+    }
+    return this;
+  },
+  enumerable: false,
+  writable: true,
+  configurable: true
+});
+Object.defineProperty(Set.prototype, "toggle", {
+  value: function(value, addOrDel) {
+    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
+});
+//# sourceMappingURL=set-ext.js.map

package/dist/extensions/set-ext.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/extensions/set-ext.ts"],
+  "sourcesContent": ["/**\n * Set \uD655\uC7A5 \uBA54\uC11C\uB4DC\n */\n\ndeclare global {\n  interface Set<T> {\n    /**\n     * \uC5EC\uB7EC \uAC12\uC744 \uD55C \uBC88\uC5D0 \uCD94\uAC00\n     */\n    adds(...values: T[]): this;\n\n    /**\n     * \uAC12\uC744 \uD1A0\uAE00\uD55C\uB2E4 (\uC788\uC73C\uBA74 \uC81C\uAC70, \uC5C6\uC73C\uBA74 \uCD94\uAC00)\n     *\n     * @param value \uD1A0\uAE00\uD560 \uAC12\n     * @param addOrDel \uAC15\uC81C\uB85C \uCD94\uAC00(\"add\") \uB610\uB294 \uC81C\uAC70(\"del\") \uC9C0\uC815 (\uC0DD\uB7B5 \uC2DC \uC790\uB3D9 \uD1A0\uAE00)\n     * @returns this (\uBA54\uC11C\uB4DC \uCCB4\uC774\uB2DD \uAC00\uB2A5)\n     *\n     * @remarks\n     * addOrDel \uD30C\uB77C\uBBF8\uD130\uB85C \uC870\uAC74\uBD80 \uCD94\uAC00/\uC81C\uAC70\uB97C \uAC04\uACB0\uD558\uAC8C \uD45C\uD604\uD560 \uC218 \uC788\uB2E4.\n     *\n     * @example\n     * ```typescript\n     * const set = new Set<number>([1, 2, 3]);\n     *\n     * set.toggle(2);  // 2\uAC00 \uC788\uC73C\uBBC0\uB85C \uC81C\uAC70 \u2192 {1, 3}\n     * set.toggle(4);  // 4\uAC00 \uC5C6\uC73C\uBBC0\uB85C \uCD94\uAC00 \u2192 {1, 3, 4}\n     *\n     * // \uC870\uAC74\uBD80 \uD1A0\uAE00\n     * const isAdmin = true;\n     * set.toggle(5, isAdmin ? \"add\" : \"del\");  // \uAC15\uC81C \uCD94\uAC00\n     * ```\n     */\n    toggle(value: T, addOrDel?: \"add\" | \"del\"): this;\n  }\n}\n\nObject.defineProperty(Set.prototype, \"adds\", {\n  value: function <T>(this: Set<T>, ...values: T[]): Set<T> {\n    for (const val of values) {\n      this.add(val);\n    }\n    return this;\n  },\n  enumerable: false,\n  writable: true,\n  configurable: true,\n});\n\nObject.defineProperty(Set.prototype, \"toggle\", {\n  value: function <T>(this: Set<T>, value: T, addOrDel?: \"add\" | \"del\"): Set<T> {\n    if (addOrDel === \"add\") {\n      this.add(value);\n    } else if (addOrDel === \"del\") {\n      this.delete(value);\n    } else if (this.has(value)) {\n      this.delete(value);\n    } else {\n      this.add(value);\n    }\n    return this;\n  },\n  enumerable: false,\n  writable: true,\n  configurable: true,\n});\n\nexport {};\n"],
+  "mappings": "AAqCA,OAAO,eAAe,IAAI,WAAW,QAAQ;AAAA,EAC3C,OAAO,YAA8B,QAAqB;AACxD,eAAW,OAAO,QAAQ;AACxB,WAAK,IAAI,GAAG;AAAA,IACd;AACA,WAAO;AAAA,EACT;AAAA,EACA,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAChB,CAAC;AAED,OAAO,eAAe,IAAI,WAAW,UAAU;AAAA,EAC7C,OAAO,SAA2B,OAAU,UAAkC;AAC5E,QAAI,aAAa,OAAO;AACtB,WAAK,IAAI,KAAK;AAAA,IAChB,WAAW,aAAa,OAAO;AAC7B,WAAK,OAAO,KAAK;AAAA,IACnB,WAAW,KAAK,IAAI,KAAK,GAAG;AAC1B,WAAK,OAAO,KAAK;AAAA,IACnB,OAAO;AACL,WAAK,IAAI,KAAK;AAAA,IAChB;AACA,WAAO;AAAA,EACT;AAAA,EACA,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAChB,CAAC;",
+  "names": []
+}

package/dist/features/debounce-queue.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 비동기 함수 디바운스 큐
+ *
+ * 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시합니다.
+ * 입력 필드 자동완성, 연속적인 상태 변경 배치 처리 등에 유용합니다.
+ *
+ * @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";
+interface DebounceQueueEvents {
+    error: SdError;
+}
+export declare class DebounceQueue extends EventEmitter<DebounceQueueEvents> {
+    private readonly _delay?;
+    private static readonly _logger;
+    private _pendingFn;
+    private _isRunning;
+    private _isDisposed;
+    private _timer;
+    /**
+     * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
+     */
+    constructor(_delay?: number | undefined);
+    /**
+     * 대기 중인 작업과 타이머 정리
+     */
+    dispose(): void;
+    /**
+     * using 문 지원
+     */
+    [Symbol.dispose](): void;
+    /**
+     * 함수를 큐에 추가
+     * 이전에 추가된 함수가 있으면 대체됨
+     */
+    run(fn: () => void | Promise<void>): void;
+    private _processLast;
+}
+export {};
+//# sourceMappingURL=debounce-queue.d.ts.map

package/dist/features/debounce-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce-queue.d.ts","sourceRoot":"","sources":["../../src/features/debounce-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,UAAU,mBAAmB;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,aAAc,SAAQ,YAAY,CAAC,mBAAmB,CAAC;IAWtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAVpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAA4C;IAE3E,OAAO,CAAC,UAAU,CAA2C;IAC7D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAA4C;IAE1D;;OAEG;gBAC0B,MAAM,CAAC,EAAE,MAAM,YAAA;IAI5C;;OAEG;IACM,OAAO,IAAI,IAAI;IAUxB;;OAEG;IACM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIjC;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;YAiB3B,YAAY;CA+B3B"}

package/dist/features/debounce-queue.js

@@ -0,0 +1,80 @@
+import { SdError } from "../errors/sd-error";
+import { EventEmitter } from "./event-emitter";
+import { createConsola } from "consola";
+class DebounceQueue extends EventEmitter {
+  /**
+   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
+   */
+  constructor(_delay) {
+    super();
+    this._delay = _delay;
+  }
+  static _logger = createConsola().withTag("DebounceQueue");
+  _pendingFn;
+  _isRunning = false;
+  _isDisposed = false;
+  _timer;
+  /**
+   * 대기 중인 작업과 타이머 정리
+   */
+  dispose() {
+    this._isDisposed = true;
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+    this._pendingFn = void 0;
+    super.dispose();
+  }
+  /**
+   * using 문 지원
+   */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * 함수를 큐에 추가
+   * 이전에 추가된 함수가 있으면 대체됨
+   */
+  run(fn) {
+    if (this._isDisposed) return;
+    this._pendingFn = fn;
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+    if (!this._isRunning) {
+      this._timer = setTimeout(() => {
+        void this._processLast();
+      }, this._delay);
+    }
+  }
+  async _processLast() {
+    if (this._isDisposed || this._isRunning || !this._pendingFn) return;
+    this._isRunning = true;
+    this._timer = void 0;
+    try {
+      while (this._pendingFn) {
+        const currentFn = this._pendingFn;
+        this._pendingFn = void 0;
+        try {
+          await currentFn();
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          const sdError = new SdError(error, "\uC791\uC5C5 \uC2E4\uD589 \uC911 \uC624\uB958 \uBC1C\uC0DD");
+          if (this.listenerCount("error") > 0) {
+            this.emit("error", sdError);
+          } else {
+            DebounceQueue._logger.error(sdError);
+          }
+        }
+      }
+    } finally {
+      this._isRunning = false;
+    }
+  }
+}
+export {
+  DebounceQueue
+};
+//# sourceMappingURL=debounce-queue.js.map

package/dist/features/debounce-queue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/features/debounce-queue.ts"],
+  "sourcesContent": ["/**\n * \uBE44\uB3D9\uAE30 \uD568\uC218 \uB514\uBC14\uC6B4\uC2A4 \uD050\n *\n * \uC9E7\uC740 \uC2DC\uAC04 \uB0B4\uC5D0 \uC5EC\uB7EC \uBC88 \uD638\uCD9C\uB418\uBA74 \uB9C8\uC9C0\uB9C9 \uC694\uCCAD\uB9CC \uC2E4\uD589\uD558\uACE0 \uC774\uC804 \uC694\uCCAD\uC740 \uBB34\uC2DC\uD569\uB2C8\uB2E4.\n * \uC785\uB825 \uD544\uB4DC \uC790\uB3D9\uC644\uC131, \uC5F0\uC18D\uC801\uC778 \uC0C1\uD0DC \uBCC0\uACBD \uBC30\uCE58 \uCC98\uB9AC \uB4F1\uC5D0 \uC720\uC6A9\uD569\uB2C8\uB2E4.\n *\n * @remarks\n * \uC2E4\uD589 \uC911\uC5D0 \uCD94\uAC00\uB41C \uC694\uCCAD\uC740 \uB514\uBC14\uC6B4\uC2A4 \uC9C0\uC5F0 \uC5C6\uC774 \uD604\uC7AC \uC2E4\uD589\uC774 \uC644\uB8CC\uB41C \uC9C1\uD6C4 \uCC98\uB9AC\uB429\uB2C8\uB2E4.\n * \uC774\uB294 \uC2E4\uD589 \uC644\uB8CC \uC804\uC5D0 \uB4E4\uC5B4\uC628 \uC694\uCCAD\uC774 \uB204\uB77D\uB418\uC9C0 \uC54A\uB3C4\uB85D \uD558\uAE30 \uC704\uD55C \uC758\uB3C4\uC801 \uC124\uACC4\uC785\uB2C8\uB2E4.\n *\n * @example\n * const queue = new DebounceQueue(300); // 300ms \uB51C\uB808\uC774\n * queue.run(() => console.log(\"1\")); // \uBB34\uC2DC\uB428\n * queue.run(() => console.log(\"2\")); // \uBB34\uC2DC\uB428\n * queue.run(() => console.log(\"3\")); // 300ms \uD6C4 \uC2E4\uD589\uB428\n *\n * @example\n * // \uC5D0\uB7EC \uCC98\uB9AC\n * queue.on(\"error\", (err) => console.error(err));\n */\nimport { SdError } from \"../errors/sd-error\";\nimport { EventEmitter } from \"./event-emitter\";\nimport { createConsola } from \"consola\";\n\ninterface DebounceQueueEvents {\n  error: SdError;\n}\n\nexport class DebounceQueue extends EventEmitter<DebounceQueueEvents> {\n  private static readonly _logger = createConsola().withTag(\"DebounceQueue\");\n\n  private _pendingFn: (() => void | Promise<void>) | undefined;\n  private _isRunning = false;\n  private _isDisposed = false;\n  private _timer: ReturnType<typeof setTimeout> | undefined;\n\n  /**\n   * @param _delay \uB514\uBC14\uC6B4\uC2A4 \uC9C0\uC5F0 \uC2DC\uAC04 (\uBC00\uB9AC\uCD08). \uC0DD\uB7B5 \uC2DC \uC989\uC2DC \uC2E4\uD589 (\uB2E4\uC74C \uC774\uBCA4\uD2B8 \uB8E8\uD504)\n   */\n  constructor(private readonly _delay?: number) {\n    super();\n  }\n\n  /**\n   * \uB300\uAE30 \uC911\uC778 \uC791\uC5C5\uACFC \uD0C0\uC774\uBA38 \uC815\uB9AC\n   */\n  override dispose(): void {\n    this._isDisposed = true;\n    if (this._timer) {\n      clearTimeout(this._timer);\n      this._timer = undefined;\n    }\n    this._pendingFn = undefined;\n    super.dispose();\n  }\n\n  /**\n   * using \uBB38 \uC9C0\uC6D0\n   */\n  override [Symbol.dispose](): void {\n    this.dispose();\n  }\n\n  /**\n   * \uD568\uC218\uB97C \uD050\uC5D0 \uCD94\uAC00\n   * \uC774\uC804\uC5D0 \uCD94\uAC00\uB41C \uD568\uC218\uAC00 \uC788\uC73C\uBA74 \uB300\uCCB4\uB428\n   */\n  run(fn: () => void | Promise<void>): void {\n    if (this._isDisposed) return;\n\n    this._pendingFn = fn;\n\n    if (this._timer) {\n      clearTimeout(this._timer);\n      this._timer = undefined;\n    }\n\n    if (!this._isRunning) {\n      this._timer = setTimeout(() => {\n        void this._processLast();\n      }, this._delay);\n    }\n  }\n\n  private async _processLast(): Promise<void> {\n    if (this._isDisposed || this._isRunning || !this._pendingFn) return;\n\n    this._isRunning = true;\n    this._timer = undefined;\n\n    try {\n      // \uC2E4\uD589 \uC911\uC5D0 \uC0C8 \uC694\uCCAD\uC774 \uB4E4\uC5B4\uC624\uBA74 \uB514\uBC14\uC6B4\uC2A4 \uC9C0\uC5F0 \uC5C6\uC774 \uC989\uC2DC \uCC98\uB9AC\n      // \uC774\uB294 \"\uC2E4\uD589 \uC644\uB8CC \uC804\uC5D0 \uB4E4\uC5B4\uC628 \uC694\uCCAD\uC740 \uC2E4\uD589 \uC9C1\uD6C4 \uBC14\uB85C \uCC98\uB9AC\"\uD558\uB294 \uC758\uB3C4\uC801 \uC124\uACC4\n      while (this._pendingFn) {\n        const currentFn = this._pendingFn;\n        this._pendingFn = undefined;\n\n        try {\n          await currentFn();\n        } catch (err) {\n          const error = err instanceof Error ? err : new Error(String(err));\n          const sdError = new SdError(error, \"\uC791\uC5C5 \uC2E4\uD589 \uC911 \uC624\uB958 \uBC1C\uC0DD\");\n\n          // \uB9AC\uC2A4\uB108\uAC00 \uC788\uC73C\uBA74 \uC774\uBCA4\uD2B8\uB85C \uC804\uB2EC, \uC5C6\uC73C\uBA74 \uB85C\uAE45\n          if (this.listenerCount(\"error\") > 0) {\n            this.emit(\"error\", sdError);\n          } else {\n            DebounceQueue._logger.error(sdError);\n          }\n        }\n      }\n    } finally {\n      this._isRunning = false;\n    }\n  }\n}\n"],
+  "mappings": "AAoBA,SAAS,eAAe;AACxB,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAMvB,MAAM,sBAAsB,aAAkC;AAAA;AAAA;AAAA;AAAA,EAWnE,YAA6B,QAAiB;AAC5C,UAAM;AADqB;AAAA,EAE7B;AAAA,EAZA,OAAwB,UAAU,cAAc,EAAE,QAAQ,eAAe;AAAA,EAEjE;AAAA,EACA,aAAa;AAAA,EACb,cAAc;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAYC,UAAgB;AACvB,SAAK,cAAc;AACnB,QAAI,KAAK,QAAQ;AACf,mBAAa,KAAK,MAAM;AACxB,WAAK,SAAS;AAAA,IAChB;AACA,SAAK,aAAa;AAClB,UAAM,QAAQ;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,CAAU,OAAO,OAAO,IAAU;AAChC,SAAK,QAAQ;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,IAAsC;AACxC,QAAI,KAAK,YAAa;AAEtB,SAAK,aAAa;AAElB,QAAI,KAAK,QAAQ;AACf,mBAAa,KAAK,MAAM;AACxB,WAAK,SAAS;AAAA,IAChB;AAEA,QAAI,CAAC,KAAK,YAAY;AACpB,WAAK,SAAS,WAAW,MAAM;AAC7B,aAAK,KAAK,aAAa;AAAA,MACzB,GAAG,KAAK,MAAM;AAAA,IAChB;AAAA,EACF;AAAA,EAEA,MAAc,eAA8B;AAC1C,QAAI,KAAK,eAAe,KAAK,cAAc,CAAC,KAAK,WAAY;AAE7D,SAAK,aAAa;AAClB,SAAK,SAAS;AAEd,QAAI;AAGF,aAAO,KAAK,YAAY;AACtB,cAAM,YAAY,KAAK;AACvB,aAAK,aAAa;AAElB,YAAI;AACF,gBAAM,UAAU;AAAA,QAClB,SAAS,KAAK;AACZ,gBAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAChE,gBAAM,UAAU,IAAI,QAAQ,OAAO,4DAAe;AAGlD,cAAI,KAAK,cAAc,OAAO,IAAI,GAAG;AACnC,iBAAK,KAAK,SAAS,OAAO;AAAA,UAC5B,OAAO;AACL,0BAAc,QAAQ,MAAM,OAAO;AAAA,UACrC;AAAA,QACF;AAAA,MACF;AAAA,IACF,UAAE;AACA,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/features/event-emitter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare class EventEmitter<T extends {
+    [K in keyof T]: unknown;
+} = Record<string, unknown>> {
+    private readonly _target;
+    private readonly _listenerMap;
+    /**
+     * 이벤트 리스너 등록
+     *
+     * @param type 이벤트 타입
+     * @param listener 이벤트 핸들러
+     * @note 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨
+     */
+    on<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void;
+    /**
+     * 이벤트 리스너 제거
+     *
+     * @param type 이벤트 타입
+     * @param listener 제거할 이벤트 핸들러
+     */
+    off<K extends keyof T & string>(type: K, listener: (data: T[K]) => void): void;
+    /**
+     * 이벤트 발생
+     *
+     * @param type 이벤트 타입
+     * @param args 이벤트 데이터 (void 타입이면 생략)
+     */
+    emit<K extends keyof T & string>(type: K, ...args: T[K] extends void ? [] : [data: T[K]]): void;
+    /**
+     * 특정 이벤트의 리스너 수 반환
+     *
+     * @param type 이벤트 타입
+     * @returns 등록된 리스너 수
+     */
+    listenerCount<K extends keyof T & string>(type: K): number;
+    /**
+     * 모든 이벤트 리스너를 제거한다.
+     */
+    dispose(): void;
+    /**
+     * using 문 지원
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=event-emitter.d.ts.map