@simplysm/core-common 14.0.51 → 14.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "14.0.51",
+  "version": "14.0.52",
   "description": "심플리즘 패키지 - 코어 (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,8 +14,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": [
     "./src/extensions/arr-ext.ts",

package/README.md

@@ -1,160 +0,0 @@
-# @simplysm/core-common
-
-브라우저와 Node.js 모두에서 사용 가능한 순수 공통 유틸리티 패키지. 다른 `@simplysm/*` 패키지에 대한 내부 의존성이 없는 리프 패키지다.
-
-## Installation
-
-```bash
-npm install @simplysm/core-common
-```
-
-## API Overview
-
-### Errors
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`SdError`](./docs/errors/sd-error.md) | class | 트리 구조 에러 체인 지원. 메시지를 역순으로 결합 (상위 => 하위 => 원인) |
-| [`ArgumentError`](./docs/errors/argument-error.md) | class | 인자 유효성 오류. 인자 객체를 YAML 형식으로 메시지에 포함 |
-| [`NotImplementedError`](./docs/errors/not-implemented-error.md) | class | 미구현 기능 호출 시 발생 |
-| [`TimeoutError`](./docs/errors/timeout-error.md) | class | 대기 시간 초과 시 발생 (시도 횟수 포함) |
-
-### Types (Value Objects)
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`DateTime`](./docs/types/date-time.md) | class | 불변 날짜시간 (밀리초 정밀도, 로컬 타임존) |
-| [`DateOnly`](./docs/types/date-only.md) | class | 불변 날짜 (시간 제외, 주차 계산 지원) |
-| [`Time`](./docs/types/time.md) | class | 불변 시간 (24시간 순환, 날짜 제외) |
-| [`Uuid`](./docs/types/uuid.md) | class | UUID v4 (`crypto.getRandomValues` 기반) |
-| [`LazyGcMap`](./docs/types/lazy-gc-map.md) | class | 자동 만료 기능이 있는 LRU Map |
-
-### Features
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`EventEmitter`](./docs/features/event-emitter.md) | class | 타입 안전 EventEmitter (EventTarget 기반, 브라우저/Node.js 모두 지원) |
-| [`DebounceQueue`](./docs/features/debounce-queue.md) | class | 비동기 디바운스 큐 (짧은 시간 내 다수 호출 시 마지막만 실행) |
-| [`SerialQueue`](./docs/features/serial-queue.md) | class | 비동기 직렬 큐 (순차 실행 보장) |
-
-### Extensions (Prototype)
-
-`@simplysm/core-common`을 import하면 `Array`, `Map`, `Set` 프로토타입 확장이 자동 등록된다.
-
-| Entry | Description |
-|-------|-------------|
-| [`Array Extensions`](./docs/extensions/array.md) | 불변 메서드 (`single`, `groupBy`, `diffs`, `toTree` 등) + 가변 메서드 (`remove`, `insert`, `toggle` 등) |
-| [`Map Extensions`](./docs/extensions/map.md) | `getOrCreate`, `update` |
-| [`Set Extensions`](./docs/extensions/set.md) | `adds`, `toggle` |
-
-### Utils (Namespace Imports)
-
-```typescript
-import { obj, str, num, bytes, path, json, xml, wait, transfer, err, dt, primitive } from "@simplysm/core-common";
-```
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`obj`](./docs/utils/obj.md) | namespace | `clone`, `equal`, `merge`, `merge3`, `omit`, `pick`, `getChainValue`, `setChainValue`, `keys`, `entries`, `map` 등 |
-| [`str`](./docs/utils/str.md) | namespace | `getKoreanSuffix`, `toPascalCase`, `toCamelCase`, `toKebabCase`, `toSnakeCase`, `isNullOrEmpty`, `insert`, `replaceFullWidth` |
-| [`num`](./docs/utils/num.md) | namespace | `parseInt`, `parseFloat`, `parseRoundedInt`, `isNullOrEmpty`, `format` |
-| [`bytes`](./docs/utils/bytes.md) | namespace | `concat`, `toHex`, `fromHex`, `toBase64`, `fromBase64` |
-| [`path`](./docs/utils/path.md) | namespace | `join`, `basename`, `extname` (POSIX 경로만 지원) |
-| [`json`](./docs/utils/json.md) | namespace | `stringify`, `parse` (커스텀 타입 지원) |
-| [`xml`](./docs/utils/xml.md) | namespace | `parse`, `stringify` |
-| [`wait`](./docs/utils/wait.md) | namespace | `until`, `time` |
-| [`transfer`](./docs/utils/transfer.md) | namespace | `encode`, `decode` (Worker 전송용) |
-| [`err`](./docs/utils/err.md) | namespace | `message` (unknown 에러 메시지 추출) |
-| [`dt`](./docs/utils/dt.md) | namespace | `format`, `normalizeMonth`, `convert12To24` |
-| [`primitive`](./docs/utils/primitive.md) | namespace | `typeStr` |
-
-### Utils (Direct Exports)
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`](./docs/utils/template-strings.md) | function | IDE 코드 하이라이팅용 태그드 템플릿 리터럴 |
-| [`ZipArchive`](./docs/utils/zip-archive.md) | class | ZIP 파일 읽기/쓰기/압축/해제 (캐싱, 진행률 콜백 지원) |
-
-### Type Utilities
-
-| Entry | Kind | Description |
-|-------|------|-------------|
-| [`env`, `parseBoolEnv`](./docs/type-utils/env.md) | function | 환경변수 get/set. `process.env`/`import.meta.env` 직접 접근 대신 사용 |
-| [`Bytes`, `PrimitiveTypeMap`, `PrimitiveTypeStr`, `PrimitiveType`, `DeepPartial`, `Type`](./docs/type-utils/common-types.md) | type/interface | 공용 타입 정의 |
-
-## Usage Examples
-
-### 프로토타입 확장 사용
-
-```typescript
-import "@simplysm/core-common";
-
-const users = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }];
-const user = users.single((u) => u.id === 1);
-const grouped = users.groupBy((u) => u.name[0]);
-const sorted = users.orderBy((u) => u.name);
-const diffs = newUsers.diffs(oldUsers, { keys: ["id"] });
-
-const cache = new Map<string, number[]>();
-const arr = cache.getOrCreate("key", []);
-
-const set = new Set<string>();
-set.adds("a", "b", "c");
-```
-
-### 에러 체인 처리
-
-```typescript
-import { SdError } from "@simplysm/core-common";
-
-try {
-  await fetch(url);
-} catch (err) {
-  throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
-  // message: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
-}
-```
-
-### 네임스페이스 유틸리티 사용
-
-```typescript
-import { obj, str, json, DateTime, Uuid } from "@simplysm/core-common";
-
-const copied = obj.clone({ nested: { data: [1, 2, 3] } });
-const isEqual = obj.equal(a, b, { topLevelExcludes: ["updatedAt"] });
-const noId = obj.omit(user, ["id"]);
-
-const suffix = str.getKoreanSuffix("파일", "을"); // "을"
-const camel = str.toCamelCase("HelloWorld");       // "helloWorld"
-
-const serialized = json.stringify({ date: new DateTime(), id: Uuid.generate() });
-const restored = json.parse(serialized); // DateTime, Uuid 타입 복원됨
-```
-
-### 비동기 큐 사용
-
-```typescript
-import { DebounceQueue, SerialQueue } from "@simplysm/core-common";
-
-const dq = new DebounceQueue(300);
-dq.on("error", (err) => console.error(err));
-dq.run(() => saveData());
-
-const sq = new SerialQueue();
-sq.run(async () => await step1());
-sq.run(async () => await step2()); // step1 완료 후 실행
-```
-
-### DateTime 사용
-
-```typescript
-import { DateTime, DateOnly, Time, Uuid } from "@simplysm/core-common";
-
-const now = new DateTime();
-const parsed = DateTime.parse("2025-01-15 10:30:00");
-const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
-const nextMonth = now.addMonths(1);
-
-const today = new DateOnly();
-const id = Uuid.generate();
-```

package/docs/errors/argument-error.md

@@ -1,26 +0,0 @@
-# ArgumentError
-
-인자 유효성 오류. 유효하지 않은 인자를 전달받았을 때 발생하는 에러. 디버깅을 용이하게 하기 위해 인자 객체를 YAML 형식으로 메시지에 포함한다. [`SdError`](./sd-error.md)를 상속한다.
-
-```typescript
-export class ArgumentError extends SdError {
-  /** 기본 메시지("잘못된 인자입니다.")와 함께 인자 객체를 YAML 형식으로 출력 */
-  constructor(argObj: Record<string, unknown>);
-  /** 커스텀 메시지와 함께 인자 객체를 YAML 형식으로 출력 */
-  constructor(message: string, argObj: Record<string, unknown>);
-}
-```
-
-## Usage
-
-```typescript
-import { ArgumentError } from "@simplysm/core-common";
-
-// 인자 객체만 전달
-throw new ArgumentError({ userId: 123, name: null });
-// message: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
-
-// 커스텀 메시지와 인자 객체를 전달
-throw new ArgumentError("잘못된 사용자", { userId: 123 });
-// message: "잘못된 사용자\n\nuserId: 123"
-```

package/docs/errors/not-implemented-error.md

@@ -1,33 +0,0 @@
-# NotImplementedError
-
-미구현 오류. 아직 구현되지 않은 기능이 호출되었을 때 발생하는 에러. 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용된다. [`SdError`](./sd-error.md)를 상속한다.
-
-```typescript
-export class NotImplementedError extends SdError {
-  /**
-   * @param message 추가 설명 메시지
-   */
-  constructor(message?: string);
-}
-```
-
-메시지 형식: `"미구현"` 또는 `"미구현: {message}"`
-
-## Usage
-
-```typescript
-import { NotImplementedError } from "@simplysm/core-common";
-
-// 추상 메서드 구현 전
-class BaseService {
-  process(): void {
-    throw new NotImplementedError("서브클래스에서 구현 필요");
-  }
-}
-
-// 향후 구현 예정인 분기
-switch (type) {
-  case "A": return handleA();
-  case "B": throw new NotImplementedError(`타입 ${type} 처리`);
-}
-```

package/docs/errors/sd-error.md

@@ -1,38 +0,0 @@
-# SdError
-
-트리 구조 조합을 지원하는 에러 클래스. 원인 에러를 감싸서 계층적 메시지를 구성한다. ES2024 `cause` 속성을 활용하며 V8 엔진(Node.js, Chrome)에서는 `captureStackTrace`를 통해 스택 추적을 최적화한다.
-
-```typescript
-export class SdError extends Error {
-  override cause?: Error;
-
-  /** 원인 에러를 감싸서 생성. 메시지는 역순으로 결합됨 (상위 메시지 => 하위 메시지 => 원인 메시지) */
-  constructor(cause: Error, ...messages: string[]);
-  /** 메시지만으로 생성. 메시지는 역순으로 결합됨 (상위 메시지 => 하위 메시지) */
-  constructor(...messages: string[]);
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `cause` | property | `Error \| undefined` | 원인 에러 (override) |
-
-## Usage
-
-```typescript
-import { SdError } from "@simplysm/core-common";
-
-// 원인 에러를 감싸기
-try {
-  await fetch(url);
-} catch (err) {
-  throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
-  // message: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
-}
-
-// 메시지만으로 생성
-throw new SdError("잘못된 상태", "처리 불가");
-// message: "처리 불가 => 잘못된 상태"
-```

package/docs/errors/timeout-error.md

@@ -1,36 +0,0 @@
-# TimeoutError
-
-타임아웃 오류. 대기 시간이 초과되었을 때 발생하는 에러. [`wait.until()`](../utils/wait.md) 같은 비동기 대기 함수에서 최대 시도 횟수를 초과하면 자동으로 발생한다. [`SdError`](./sd-error.md)를 상속한다.
-
-```typescript
-export class TimeoutError extends SdError {
-  /**
-   * @param count 시도 횟수
-   * @param message 추가 메시지
-   */
-  constructor(count?: number, message?: string);
-}
-```
-
-메시지 형식: `"대기 시간 초과"`, `"대기 시간 초과(N회 시도)"`, `"대기 시간 초과: {message}"`, `"대기 시간 초과(N회 시도): {message}"`
-
-## Usage
-
-```typescript
-import { TimeoutError } from "@simplysm/core-common";
-import { wait } from "@simplysm/core-common";
-
-// wait.until에서 자동 발생
-try {
-  await wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회 시도
-} catch (err) {
-  if (err instanceof TimeoutError) {
-    console.log("타임아웃 초과");
-  }
-}
-
-// 직접 발생
-if (elapsed > maxTime) {
-  throw new TimeoutError(undefined, "API 응답 대기 초과");
-}
-```

package/docs/extensions/array.md

@@ -1,125 +0,0 @@
-# Array Extensions
-
-`@simplysm/core-common`을 import하면 `Array.prototype`에 확장 메서드가 자동 등록된다. `ReadonlyArray<T>`와 `Array<T>` 모두에 적용된다.
-
-side-effect import로 활성화:
-
-```typescript
-import "@simplysm/core-common";
-```
-
-## 불변(Immutable) 메서드
-
-원본 배열을 변경하지 않고 새 배열 또는 값을 반환한다.
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `single` | `(predicate?) => T \| undefined` | 조건에 맞는 단일 요소 반환. 2개 이상이면 `ArgumentError` 발생 |
-| `first` | `(predicate?) => T \| undefined` | 첫 번째 요소 반환 |
-| `last` | `(predicate?) => T \| undefined` | 마지막 요소 반환 |
-| `filterExists` | `() => NonNullable<T>[]` | null/undefined 제거 |
-| `ofType` | `(type: PrimitiveTypeStr \| Type<N>) => N[]` | 특정 타입의 요소만 필터 |
-| `filterAsync` | `(predicate) => Promise<T[]>` | 비동기 필터 (순차 실행) |
-| `mapAsync` | `(selector) => Promise<R[]>` | 비동기 매핑 (순차 실행) |
-| `mapMany` | `(selector?) => R[]` | 매핑 후 평탄화 (또는 중첩 배열 평탄화) |
-| `mapManyAsync` | `(selector?) => Promise<R[]>` | 비동기 매핑 후 평탄화 (순차 실행) |
-| `parallelAsync` | `(fn) => Promise<R[]>` | 비동기 병렬 처리 (`Promise.all` 사용). 하나라도 reject되면 전체 reject |
-| `groupBy` | `(keySelector, valueSelector?) => { key, values }[]` | key 기준 그룹화. 객체 key 지원을 위해 O(n²) 복잡도. 원시 key는 O(n) |
-| `toMap` | `(keySelector, valueSelector?) => Map<K, V>` | Map으로 변환. 중복 key이면 `ArgumentError` 발생 |
-| `toMapAsync` | `(keySelector, valueSelector?) => Promise<Map<K, V>>` | 비동기 Map 변환 |
-| `toArrayMap` | `(keySelector, valueSelector?) => Map<K, V[]>` | 배열 값 Map으로 변환 (O(n)) |
-| `toSetMap` | `(keySelector, valueSelector?) => Map<K, Set<V>>` | Set 값 Map으로 변환 |
-| `toMapValues` | `(keySelector, valueSelector) => Map<K, V>` | 그룹별 집계 Map으로 변환 |
-| `toObject` | `(keySelector, valueSelector?) => Record<string, V>` | 객체로 변환. 중복 key이면 `ArgumentError` 발생 |
-| `toTree` | `(keyProp, parentKey) => TreeArray<T>[]` | 평면 배열을 트리 구조로 변환 (O(n)). `parentKey`가 null/undefined인 항목이 루트 |
-| `distinct` | `(options?) => T[]` | 중복 제거. 객체 배열에서 keyFn 없이 사용하면 O(n²) |
-| `orderBy` | `(selector?) => T[]` | 오름차순 정렬 (새 배열 반환) |
-| `orderByDesc` | `(selector?) => T[]` | 내림차순 정렬 (새 배열 반환) |
-| `diffs` | `(target, options?) => ArrayDiffsResult<T, P>[]` | 두 배열 비교 (INSERT/DELETE/UPDATE) |
-| `oneWayDiffs` | `(orgItems, keyPropNameOrGetValFn, options?) => ArrayOneWayDiffResult<T>[]` | 단방향 비교 (create/update/same) |
-| `merge` | `(target, options?) => (T \| P \| T & P)[]` | 두 배열 병합 (`diffs` 기반) |
-| `sum` | `(selector?) => number` | 합계. 빈 배열이면 0 반환 |
-| `min` | `(selector?) => T \| undefined` | 최솟값 |
-| `max` | `(selector?) => T \| undefined` | 최댓값 |
-| `shuffle` | `() => T[]` | 무작위 순서로 섞은 새 배열 반환 |
-
-## 가변(Mutable) 메서드
-
-원본 배열을 직접 수정하고 `this`를 반환한다.
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `remove` | `(item: T) => this` | 항목 제거 |
-| `remove` | `(selector: (item, index) => boolean) => this` | 조건에 맞는 항목 제거 |
-| `insert` | `(index: number, ...items: T[]) => this` | 특정 위치에 항목 삽입 |
-| `toggle` | `(item: T) => this` | 항목 토글 (있으면 제거, 없으면 추가) |
-| `clear` | `() => this` | 배열 비우기 |
-| `distinctThis` | `(options?) => T[]` | 원본 배열에서 중복 제거 |
-| `orderByThis` | `(selector?) => T[]` | 원본 배열 오름차순 정렬 |
-| `orderByDescThis` | `(selector?) => T[]` | 원본 배열 내림차순 정렬 |
-
-## Related Types
-
-### `ArrayDiffsResult<TOriginal, TOther>`
-
-`diffs()` 결과 타입. Discriminated union:
-
-```typescript
-export type ArrayDiffsResult<TOriginal, TOther> =
-  | { source: undefined; target: TOther }         // INSERT (target에만 있음)
-  | { source: TOriginal; target: undefined }       // DELETE (source에만 있음)
-  | { source: TOriginal; target: TOther };         // UPDATE (양쪽에 있고 다름)
-```
-
-### `ArrayOneWayDiffResult<TItem>`
-
-`oneWayDiffs()` 결과 타입. Discriminated union (`type` 필드로 분기):
-
-```typescript
-export type ArrayOneWayDiffResult<TItem> =
-  | { type: "create"; item: TItem; orgItem: undefined }
-  | { type: "update"; item: TItem; orgItem: TItem }
-  | { type: "same";   item: TItem; orgItem: TItem };
-```
-
-### `TreeArray<TNode>`
-
-`toTree()` 결과 타입. 원본 타입에 `children` 속성이 추가된다:
-
-```typescript
-export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
-```
-
-### `ComparableType`
-
-`orderBy`/`orderByDesc` selector의 반환 타입:
-
-```typescript
-export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
-```
-
-## Usage
-
-```typescript
-import "@simplysm/core-common";
-
-const users = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }];
-
-// 불변 메서드
-const alice = users.single((u) => u.id === 1);
-const sorted = users.orderBy((u) => u.name);
-const grouped = users.groupBy((u) => u.name[0]);
-const diffs = newUsers.diffs(oldUsers, { keys: ["id"] });
-
-// toTree
-const items = [
-  { id: 1, parentId: undefined, name: "root" },
-  { id: 2, parentId: 1, name: "child" },
-];
-const tree = items.toTree("id", "parentId");
-
-// 가변 메서드
-const list = [1, 2, 3, 4, 5];
-list.remove((x) => x % 2 === 0); // [1, 3, 5]
-list.insert(1, 10); // [1, 10, 3, 5]
-```

package/docs/extensions/map.md

@@ -1,43 +0,0 @@
-# Map Extensions
-
-`@simplysm/core-common`을 import하면 `Map.prototype`에 확장 메서드가 자동 등록된다.
-
-side-effect import로 활성화:
-
-```typescript
-import "@simplysm/core-common";
-```
-
-## Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getOrCreate` | `(key: K, newValue: V) => V` | key가 없으면 값을 설정하고 반환 |
-| `getOrCreate` | `(key: K, newValueFn: () => V) => V` | key가 없으면 팩토리 함수를 호출하여 값을 설정하고 반환 |
-| `update` | `(key: K, updateFn: (v: V \| undefined) => V) => void` | 현재 값을 받아 새 값으로 업데이트. key가 없으면 `undefined`가 전달됨 |
-
-## Usage
-
-```typescript
-import "@simplysm/core-common";
-
-// getOrCreate — 값으로
-const map = new Map<string, number[]>();
-const arr = map.getOrCreate("key", []);    // 없으면 [] 설정 후 반환
-
-// getOrCreate — 팩토리로 (비용이 큰 연산에 사용)
-const val = map.getOrCreate("key", () => expensiveComputation());
-
-// 함수를 값으로 저장 시 팩토리로 감싸야 함
-const fnMap = new Map<string, () => void>();
-const myFn = () => console.log("hello");
-fnMap.getOrCreate("key", () => myFn);  // 팩토리로 감싸기
-
-// update — 카운터
-const countMap = new Map<string, number>();
-countMap.update("key", (v) => (v ?? 0) + 1);
-
-// update — 배열에 추가
-const arrayMap = new Map<string, string[]>();
-arrayMap.update("key", (v) => [...(v ?? []), "item"]);
-```

package/docs/extensions/set.md

@@ -1,35 +0,0 @@
-# Set Extensions
-
-`@simplysm/core-common`을 import하면 `Set.prototype`에 확장 메서드가 자동 등록된다.
-
-side-effect import로 활성화:
-
-```typescript
-import "@simplysm/core-common";
-```
-
-## Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `adds` | `(...values: T[]) => this` | 여러 값을 한 번에 추가 |
-| `toggle` | `(value: T, addOrDel?: "add" \| "del") => this` | 값 토글 (있으면 제거, 없으면 추가). `addOrDel`로 강제 추가/제거 가능 |
-
-## Usage
-
-```typescript
-import "@simplysm/core-common";
-
-const set = new Set<number>([1, 2, 3]);
-
-// adds — 여러 항목 추가
-set.adds(4, 5, 6); // {1, 2, 3, 4, 5, 6}
-
-// toggle — 자동
-set.toggle(2);  // 2가 있으므로 제거 → {1, 3, 4, 5, 6}
-set.toggle(10); // 10이 없으므로 추가 → {1, 3, 4, 5, 6, 10}
-
-// toggle — 강제
-const isAdmin = true;
-set.toggle(5, isAdmin ? "add" : "del"); // 강제 추가
-```

package/docs/features/debounce-queue.md

@@ -1,48 +0,0 @@
-# DebounceQueue
-
-비동기 디바운스 큐. 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시한다. 입력 필드 자동완성, 연속적인 상태 변경 일괄 처리 등에 유용하다. [`EventEmitter`](./event-emitter.md)를 상속한다.
-
-```typescript
-export class DebounceQueue extends EventEmitter<{ error: SdError }> {
-  /**
-   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
-   */
-  constructor(_delay?: number);
-
-  run(fn: () => void | Promise<void>): void;
-  override dispose(): void;
-}
-```
-
-에러 발생 시 `"error"` 이벤트로 전파되며, 리스너가 없으면 `consola`로 로그 출력된다.
-
-실행 중에 추가된 요청은 디바운스 지연 없이 현재 실행이 완료된 직후 즉시 처리된다. 이는 실행 완료 전에 도착한 요청을 놓치지 않기 위한 의도적인 설계다.
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `run` | method | `(fn: () => void \| Promise<void>) => void` | 큐에 함수 추가. 이전에 추가된 함수가 있으면 교체됨 |
-| `dispose` | method | `() => void` | 대기 중인 작업과 타이머 정리 후 부모 `dispose()` 호출 |
-
-## Usage
-
-```typescript
-import { DebounceQueue } from "@simplysm/core-common";
-
-const queue = new DebounceQueue(300); // 300ms 지연
-
-// 에러 처리
-queue.on("error", (err) => console.error(err));
-
-queue.run(() => console.log("1")); // 무시됨
-queue.run(() => console.log("2")); // 무시됨
-queue.run(() => console.log("3")); // 300ms 후 실행
-
-// 자원 정리
-try {
-  queue.run(() => saveData());
-} finally {
-  queue.dispose();
-}
-```

package/docs/features/event-emitter.md

@@ -1,52 +0,0 @@
-# EventEmitter
-
-타입 안전 EventEmitter. 내부적으로 `EventTarget`을 사용하며 브라우저와 Node.js 모두에서 사용 가능하다. `events`/`eventemitter3` 대신 이 클래스를 사용한다.
-
-```typescript
-export class EventEmitter<
-  TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>,
-> {
-  on<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => void): void;
-  off<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => void): void;
-  emit<TEventName extends keyof TEvents & string>(type: TEventName, ...args: TEvents[TEventName] extends void ? [] : [data: TEvents[TEventName]]): void;
-  listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): number;
-  dispose(): void;
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `on` | method | `(type, listener) => void` | 이벤트 리스너 등록. 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨 |
-| `off` | method | `(type, listener) => void` | 이벤트 리스너 제거 |
-| `emit` | method | `(type, ...args) => void` | 이벤트 발행. `void` 타입 이벤트는 인자 없이 호출 |
-| `listenerCount` | method | `(type) => number` | 특정 이벤트의 등록된 리스너 수 반환 |
-| `dispose` | method | `() => void` | 모든 이벤트 리스너 제거 |
-
-## Usage
-
-```typescript
-import { EventEmitter } from "@simplysm/core-common";
-
-// 이벤트 타입 정의
-interface MyEvents {
-  data: string;
-  error: Error;
-  done: void;
-}
-
-// EventEmitter를 상속하여 사용
-class MyService extends EventEmitter<MyEvents> {
-  async load() {
-    this.emit("data", "Loading...");
-    this.emit("done"); // void 타입은 인자 없이 호출
-  }
-}
-
-const svc = new MyService();
-svc.on("data", (data) => { /* data: string */ });
-svc.on("done", () => { /* ... */ });
-await svc.load();
-svc.dispose(); // 모든 리스너 정리
-```

package/docs/features/serial-queue.md

@@ -1,44 +0,0 @@
-# SerialQueue
-
-비동기 직렬 큐. 큐에 추가된 함수들은 순차적으로 실행된다. 하나의 작업이 완료된 후에야 다음 작업이 시작된다. 에러가 발생해도 후속 작업은 계속 실행된다. [`EventEmitter`](./event-emitter.md)를 상속한다.
-
-```typescript
-export class SerialQueue extends EventEmitter<{ error: SdError }> {
-  /**
-   * @param _gap 각 작업 사이의 간격 (ms). 기본값: 0
-   */
-  constructor(_gap?: number);
-
-  run(fn: () => void | Promise<void>): void;
-  override dispose(): void;
-}
-```
-
-에러 발생 시 `"error"` 이벤트로 전파되며, 리스너가 없으면 `consola`로 로그 출력된다.
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `run` | method | `(fn: () => void \| Promise<void>) => void` | 큐에 함수 추가하고 실행 예약 |
-| `dispose` | method | `() => void` | 대기 중인 큐 비우기 (현재 실행 중인 작업은 완료됨) |
-
-## Usage
-
-```typescript
-import { SerialQueue } from "@simplysm/core-common";
-
-const queue = new SerialQueue();
-
-// 에러 처리
-queue.on("error", (err) => console.error(err));
-
-queue.run(async () => { await fetch("/api/1"); });
-queue.run(async () => { await fetch("/api/2"); }); // 1 완료 후 실행
-queue.run(async () => { await fetch("/api/3"); }); // 2 완료 후 실행
-
-// 간격 있는 큐
-const gapQueue = new SerialQueue(100); // 각 작업 사이 100ms 간격
-gapQueue.run(() => step1());
-gapQueue.run(() => step2()); // step1 완료 후 100ms 뒤에 실행
-```