@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/core-common/README.md

@@ -0,0 +1,179 @@
+# @simplysm/core-common
+
+브라우저와 Node.js 모두에서 사용 가능한 순수 공통 유틸리티 패키지. 다른 `@simplysm/*` 패키지에 대한 내부 의존성이 없는 리프 패키지다.
+
+## Installation
+
+```bash
+npm install @simplysm/core-common
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 날짜/시간 연산 | [DateTime](./types/date-time.md), [DateOnly](./types/date-only.md), [Time](./types/time.md) |
+| 배열 필터/정렬/그룹화/비교 | [Array Extensions](./extensions/array.md) |
+| 객체 복사/비교/병합 | [obj](./utils/obj.md) |
+| JSON 직렬화 (커스텀 타입 포함) | [json](./utils/json.md) |
+| 에러 체인 구성 | [SdError](./errors/sd-error.md) |
+| 이벤트 기반 통신 | [EventEmitter](./features/event-emitter.md) |
+| 비동기 제어 (디바운스/직렬) | [DebounceQueue](./features/debounce-queue.md), [SerialQueue](./features/serial-queue.md) |
+| UUID 생성 | [Uuid](./types/uuid.md) |
+| 환경변수 접근 | [env](./type-utils/env.md) |
+| Worker 간 데이터 전송 | [transfer](./utils/transfer.md) |
+| ZIP 파일 처리 | [ZipArchive](./utils/zip-archive.md) |
+| 바이너리 변환 (hex/base64) | [bytes](./utils/bytes.md) |
+| 문자열 케이스 변환/한국어 조사 | [str](./utils/str.md) |
+| 자동 만료 캐시 | [LazyGcMap](./types/lazy-gc-map.md) |
+
+## API Overview
+
+### Errors
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`SdError`](./errors/sd-error.md) | class | 원인 에러를 감싸 트리 구조 에러 체인을 구성할 때 |
+| [`ArgumentError`](./errors/argument-error.md) | class | 인자 유효성 오류를 YAML 형식 메시지로 표시할 때 |
+| [`NotImplementedError`](./errors/not-implemented-error.md) | class | 미구현 기능이 호출되었음을 표시할 때 |
+| [`TimeoutError`](./errors/timeout-error.md) | class | 대기 시간 초과를 시도 횟수와 함께 표시할 때 |
+
+### Types (Value Objects)
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`DateTime`](./types/date-time.md) | class | 날짜+시간을 불변 객체로 다룰 때 (밀리초 정밀도, 로컬 타임존) |
+| [`DateOnly`](./types/date-only.md) | class | 시간 없이 날짜만 다룰 때 (주차 계산 지원) |
+| [`Time`](./types/time.md) | class | 날짜 없이 시간만 다룰 때 (24시간 순환) |
+| [`Uuid`](./types/uuid.md) | class | UUID v4를 생성하거나 검증할 때 |
+| [`LazyGcMap`](./types/lazy-gc-map.md) | class | 일정 시간 미접근 항목을 자동 삭제하는 캐시가 필요할 때 |
+
+### Features
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`EventEmitter`](./features/event-emitter.md) | class | 타입 안전한 이벤트 기반 통신이 필요할 때 (`events`/`eventemitter3` 대체) |
+| [`DebounceQueue`](./features/debounce-queue.md) | class | 짧은 시간 내 다수 호출을 마지막 하나로 축약할 때 |
+| [`SerialQueue`](./features/serial-queue.md) | class | 비동기 작업의 순차 실행을 보장할 때 |
+
+### Extensions (Prototype)
+
+`@simplysm/core-common`을 import하면 `Array`, `Map`, `Set` 프로토타입 확장이 자동 등록된다.
+
+| Entry | 언제 쓰나 |
+|-------|-----------|
+| [`Array Extensions`](./extensions/array.md) | 배열 필터/정렬/그룹화/비교/변환이 필요할 때 |
+| [`Map Extensions`](./extensions/map.md) | Map에서 기본값 생성(`getOrCreate`) 또는 값 업데이트(`update`)가 필요할 때 |
+| [`Set Extensions`](./extensions/set.md) | Set에 여러 값 일괄 추가(`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 | 언제 쓰나 |
+|-------|------|-----------|
+| [`obj`](./utils/obj.md) | namespace | 객체 깊은 복사/비교/병합, key 조작, 체인 경로 접근이 필요할 때 |
+| [`str`](./utils/str.md) | namespace | 한국어 조사 처리, 케이스 변환, 전각→반각 변환이 필요할 때 |
+| [`num`](./utils/num.md) | namespace | 문자열→숫자 파싱, 숫자 포맷이 필요할 때 |
+| [`bytes`](./utils/bytes.md) | namespace | Uint8Array ↔ hex/base64 변환, 결합이 필요할 때 |
+| [`path`](./utils/path.md) | namespace | POSIX 경로 결합/파일명 추출이 필요할 때 (브라우저 환경용) |
+| [`json`](./utils/json.md) | namespace | DateTime/Uuid 등 커스텀 타입을 포함한 JSON 직렬화/역직렬화가 필요할 때 |
+| [`xml`](./utils/xml.md) | namespace | XML 파싱/직렬화가 필요할 때 |
+| [`wait`](./utils/wait.md) | namespace | 조건 대기(`until`) 또는 시간 대기(`time`)가 필요할 때 |
+| [`transfer`](./utils/transfer.md) | namespace | Worker 간 커스텀 타입 데이터 전송이 필요할 때 |
+| [`err`](./utils/err.md) | namespace | catch 블록의 unknown 에러에서 메시지를 추출할 때 |
+| [`dt`](./utils/dt.md) | namespace | 날짜/시간 포맷 문자열 변환, 월 정규화가 필요할 때 |
+| [`primitive`](./utils/primitive.md) | namespace | 런타임에 값의 PrimitiveTypeStr을 추론할 때 |
+
+### Utils (Direct Exports)
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`](./utils/template-strings.md) | function | IDE 코드 하이라이팅이 필요한 태그드 템플릿 리터럴을 작성할 때 |
+| [`ZipArchive`](./utils/zip-archive.md) | class | ZIP 파일 읽기/쓰기/압축/해제가 필요할 때 |
+
+### Type Utilities
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`env`, `parseBoolEnv`](./type-utils/env.md) | function | 환경변수를 읽거나 쓸 때 (`process.env`/`import.meta.env` 직접 접근 대신) |
+| [`Bytes`, `PrimitiveTypeMap`, `PrimitiveTypeStr`, `PrimitiveType`, `DeepPartial`, `Type`](./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/claude/references/sd-simplysm-v14/core-common/errors/argument-error.md

@@ -0,0 +1,26 @@
+# 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/claude/references/sd-simplysm-v14/core-common/errors/not-implemented-error.md

@@ -0,0 +1,33 @@
+# 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/claude/references/sd-simplysm-v14/core-common/errors/sd-error.md

@@ -0,0 +1,38 @@
+# 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/claude/references/sd-simplysm-v14/core-common/errors/timeout-error.md

@@ -0,0 +1,36 @@
+# 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/claude/references/sd-simplysm-v14/core-common/extensions/array.md

@@ -0,0 +1,125 @@
+# 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/claude/references/sd-simplysm-v14/core-common/extensions/map.md

@@ -0,0 +1,43 @@
+# 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/claude/references/sd-simplysm-v14/core-common/extensions/set.md

@@ -0,0 +1,35 @@
+# 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/claude/references/sd-simplysm-v14/core-common/features/debounce-queue.md

@@ -0,0 +1,48 @@
+# 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/claude/references/sd-simplysm-v14/core-common/features/event-emitter.md

@@ -0,0 +1,52 @@
+# 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/claude/references/sd-simplysm-v14/core-common/features/serial-queue.md

@@ -0,0 +1,44 @@
+# 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 뒤에 실행
+```