@simplysm/sd-claude 14.0.53 → 14.0.55

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

@@ -1,6 +1,6 @@
 # @simplysm/core-common
 
-브라우저와 Node.js 모두에서 사용 가능한 순수 공통 유틸리티 패키지. 다른 `@simplysm/*` 패키지에 대한 내부 의존성이 없는 리프 패키지다.
+> 브라우저와 Node.js 모두에서 사용 가능한 순수 공통 유틸리티 패키지. 다른 `@simplysm/*` 패키지에 대한 내부 의존성이 없는 리프 패키지다. 에러 클래스, 값 타입(`DateTime`, `Uuid` 등), 프로토타입 확장(`Array`, `Map`, `Set`), 비동기 큐, 네임스페이스 유틸리티 함수를 제공한다.
 
 ## Installation
 
@@ -8,172 +8,90 @@
 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");
-```
+### 날짜·시간 다루기
 
-### 에러 체인 처리
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 날짜+시간을 불변 객체로 다루기 (파싱, 포맷, 산술 연산) | [date-time.md](./types/date-time.md) |
+| 시간 없이 날짜만 다루기 (주차 계산 포함) | [date-only.md](./types/date-only.md) |
+| 날짜 없이 시간만 다루기 (24시간 순환) | [time.md](./types/time.md) |
+| 날짜/시간 포맷 문자열 변환, 월 정규화 | [dt.md](./utils/dt.md) |
 
-```typescript
-import { SdError } from "@simplysm/core-common";
+### 컬렉션 조작
 
-try {
-  await fetch(url);
-} catch (err) {
-  throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
-  // message: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
-}
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 배열 필터/정렬/그룹화/비교/변환 | [array.md](./extensions/array.md) |
+| Map에서 기본값 생성(`getOrCreate`) 또는 값 업데이트(`update`) | [map.md](./extensions/map.md) |
+| Set에 여러 값 일괄 추가(`adds`) 또는 토글(`toggle`) | [set.md](./extensions/set.md) |
 
-### 네임스페이스 유틸리티 사용
+### 객체 조작
 
-```typescript
-import { obj, str, json, DateTime, Uuid } from "@simplysm/core-common";
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 객체 깊은 복사/비교/병합, 3-way 병합, key 조작, 체인 경로 접근 | [obj.md](./utils/obj.md) |
 
-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"
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DateTime/Uuid 등 커스텀 타입을 포함한 JSON 직렬화/역직렬화 | [json.md](./utils/json.md) |
+| Worker 간 커스텀 타입 데이터 전송 (직렬화/역직렬화) | [transfer.md](./utils/transfer.md) |
+| XML 파싱/직렬화 | [xml.md](./utils/xml.md) |
+| ZIP 파일 읽기/쓰기/압축/해제 | [zip-archive.md](./utils/zip-archive.md) |
+| Uint8Array ↔ hex/base64 변환, 결합 | [bytes.md](./utils/bytes.md) |
 
-const serialized = json.stringify({ date: new DateTime(), id: Uuid.generate() });
-const restored = json.parse(serialized); // DateTime, Uuid 타입 복원됨
-```
+### 에러 처리
 
-### 비동기 큐 사용
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 원인 에러를 감싸 트리 구조 에러 체인을 구성 | [sd-error.md](./errors/sd-error.md) |
+| 인자 유효성 오류를 YAML 형식 메시지로 표시 | [argument-error.md](./errors/argument-error.md) |
+| 미구현 기능 호출 표시 | [not-implemented-error.md](./errors/not-implemented-error.md) |
+| 대기 시간 초과 표시 | [timeout-error.md](./errors/timeout-error.md) |
+| catch 블록의 unknown 에러에서 메시지 추출 | [err.md](./utils/err.md) |
 
-```typescript
-import { DebounceQueue, SerialQueue } from "@simplysm/core-common";
+### 이벤트·비동기 제어
 
-const dq = new DebounceQueue(300);
-dq.on("error", (err) => console.error(err));
-dq.run(() => saveData());
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 타입 안전한 이벤트 기반 통신 (`events`/`eventemitter3` 대체) | [event-emitter.md](./features/event-emitter.md) |
+| 짧은 시간 내 다수 호출을 마지막 하나로 축약 | [debounce-queue.md](./features/debounce-queue.md) |
+| 비동기 작업의 순차 실행 보장 | [serial-queue.md](./features/serial-queue.md) |
 
-const sq = new SerialQueue();
-sq.run(async () => await step1());
-sq.run(async () => await step2()); // step1 완료 후 실행
-```
+### 식별자·캐시
 
-### DateTime 사용
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| UUID v4 생성 또는 검증 | [uuid.md](./types/uuid.md) |
+| 일정 시간 미접근 항목을 자동 삭제하는 캐시 | [lazy-gc-map.md](./types/lazy-gc-map.md) |
 
-```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);
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 한국어 조사 처리, 케이스 변환, 전각→반각 변환 | [str.md](./utils/str.md) |
+| 문자열→숫자 파싱, 숫자 포맷 | [num.md](./utils/num.md) |
+| IDE 코드 하이라이팅이 필요한 태그드 템플릿 리터럴 | [template-strings.md](./utils/template-strings.md) |
 
-const today = new DateOnly();
-const id = Uuid.generate();
-```
+### 환경·경로·타입
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 환경변수 읽기/쓰기 (`process.env`/`import.meta.env` 직접 접근 대신) | [env.md](./type-utils/env.md) |
+| POSIX 경로 결합/파일명 추출 (브라우저 환경용) | [path.md](./utils/path.md) |
+| 조건 대기(`until`) 또는 시간 대기(`time`) | [wait.md](./utils/wait.md) |
+| 런타임에 값의 PrimitiveTypeStr 추론 | [primitive.md](./utils/primitive.md) |
+| 공용 타입 정의 (`Bytes`, `PrimitiveType`, `DeepPartial`, `Type`) | [common-types.md](./type-utils/common-types.md) |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 브라우저 전용 API (DOM, `window` 등) → `@simplysm/core-browser`
+- Node.js 전용 파일 시스템/프로세스 → `@simplysm/core-node`
+- 서버/클라이언트 통신 → `@simplysm/service-server`, `@simplysm/service-client`
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

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

package/claude/references/sd-simplysm-v14/core-common/errors/argument-error.md

@@ -1,4 +1,6 @@
-# ArgumentError
+# `ArgumentError`
+
+> **읽어야 하는 상황**: 유효하지 않은 인자를 전달받았을 때 인자 객체를 YAML 형식으로 메시지에 포함하여 디버깅을 용이하게 할 때.
 
 인자 유효성 오류. 유효하지 않은 인자를 전달받았을 때 발생하는 에러. 디버깅을 용이하게 하기 위해 인자 객체를 YAML 형식으로 메시지에 포함한다. [`SdError`](./sd-error.md)를 상속한다.
 

package/claude/references/sd-simplysm-v14/core-common/errors/not-implemented-error.md

@@ -1,4 +1,6 @@
-# NotImplementedError
+# `NotImplementedError`
+
+> **읽어야 하는 상황**: 아직 구현되지 않은 기능이 호출되었음을 표시할 때. 추상 메서드 스텁, 향후 구현 예정인 분기에 사용.
 
 미구현 오류. 아직 구현되지 않은 기능이 호출되었을 때 발생하는 에러. 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용된다. [`SdError`](./sd-error.md)를 상속한다.
 

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

@@ -1,4 +1,6 @@
-# SdError
+# `SdError`
+
+> **읽어야 하는 상황**: 원인 에러를 감싸 트리 구조 에러 체인을 구성해야 할 때. 인자 오류는 [`ArgumentError`](./argument-error.md), 타임아웃은 [`TimeoutError`](./timeout-error.md) 참조.
 
 트리 구조 조합을 지원하는 에러 클래스. 원인 에러를 감싸서 계층적 메시지를 구성한다. ES2024 `cause` 속성을 활용하며 V8 엔진(Node.js, Chrome)에서는 `captureStackTrace`를 통해 스택 추적을 최적화한다.
 

package/claude/references/sd-simplysm-v14/core-common/errors/timeout-error.md

@@ -1,4 +1,6 @@
-# TimeoutError
+# `TimeoutError`
+
+> **읽어야 하는 상황**: 대기 시간이 초과되었을 때. [`wait.until()`](../utils/wait.md)에서 자동 발생하거나 직접 throw할 때.
 
 타임아웃 오류. 대기 시간이 초과되었을 때 발생하는 에러. [`wait.until()`](../utils/wait.md) 같은 비동기 대기 함수에서 최대 시도 횟수를 초과하면 자동으로 발생한다. [`SdError`](./sd-error.md)를 상속한다.
 

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

@@ -1,5 +1,7 @@
 # Array Extensions
 
+> **읽어야 하는 상황**: 배열 필터/정렬/그룹화/비교/변환이 필요할 때. Map 확장은 [map.md](./map.md), Set 확장은 [set.md](./set.md) 참조.
+
 `@simplysm/core-common`을 import하면 `Array.prototype`에 확장 메서드가 자동 등록된다. `ReadonlyArray<T>`와 `Array<T>` 모두에 적용된다.
 
 side-effect import로 활성화:

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

@@ -1,5 +1,7 @@
 # Map Extensions
 
+> **읽어야 하는 상황**: Map에서 기본값 생성(`getOrCreate`) 또는 기존 값 기반 업데이트(`update`)가 필요할 때.
+
 `@simplysm/core-common`을 import하면 `Map.prototype`에 확장 메서드가 자동 등록된다.
 
 side-effect import로 활성화:

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

@@ -1,5 +1,7 @@
 # Set Extensions
 
+> **읽어야 하는 상황**: Set에 여러 값을 한 번에 추가(`adds`) 또는 값 토글(`toggle`)이 필요할 때.
+
 `@simplysm/core-common`을 import하면 `Set.prototype`에 확장 메서드가 자동 등록된다.
 
 side-effect import로 활성화:

package/claude/references/sd-simplysm-v14/core-common/features/debounce-queue.md

@@ -1,4 +1,6 @@
-# DebounceQueue
+# `DebounceQueue`
+
+> **읽어야 하는 상황**: 짧은 시간 내 다수 호출을 마지막 하나로 축약해야 할 때 (입력 필드 자동완성, 연속 상태 변경 일괄 처리 등). 순차 실행이 필요하면 [`SerialQueue`](./serial-queue.md) 참조.
 
 비동기 디바운스 큐. 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시한다. 입력 필드 자동완성, 연속적인 상태 변경 일괄 처리 등에 유용하다. [`EventEmitter`](./event-emitter.md)를 상속한다.
 

package/claude/references/sd-simplysm-v14/core-common/features/event-emitter.md

@@ -1,4 +1,6 @@
-# EventEmitter
+# `EventEmitter`
+
+> **읽어야 하는 상황**: 타입 안전한 이벤트 기반 통신이 필요할 때. `events`/`eventemitter3` 대신 사용. 디바운스가 필요하면 [`DebounceQueue`](./debounce-queue.md), 순차 실행이 필요하면 [`SerialQueue`](./serial-queue.md) 참조.
 
 타입 안전 EventEmitter. 내부적으로 `EventTarget`을 사용하며 브라우저와 Node.js 모두에서 사용 가능하다. `events`/`eventemitter3` 대신 이 클래스를 사용한다.
 

package/claude/references/sd-simplysm-v14/core-common/features/serial-queue.md

@@ -1,4 +1,6 @@
-# SerialQueue
+# `SerialQueue`
+
+> **읽어야 하는 상황**: 비동기 작업의 순차 실행을 보장해야 할 때 (하나 완료 후 다음 시작). 디바운스가 필요하면 [`DebounceQueue`](./debounce-queue.md) 참조.
 
 비동기 직렬 큐. 큐에 추가된 함수들은 순차적으로 실행된다. 하나의 작업이 완료된 후에야 다음 작업이 시작된다. 에러가 발생해도 후속 작업은 계속 실행된다. [`EventEmitter`](./event-emitter.md)를 상속한다.
 

package/claude/references/sd-simplysm-v14/core-common/type-utils/common-types.md

@@ -1,5 +1,7 @@
 # Common Types
 
+> **읽어야 하는 상황**: `Bytes`(Uint8Array 별칭), `PrimitiveTypeMap`/`PrimitiveTypeStr`/`PrimitiveType`(원시 타입 매핑), `DeepPartial`, `Type<T>`(생성자 타입) 등 공용 타입이 필요할 때.
+
 공유 타입 정의. `Buffer` 대신 사용하는 바이너리 타입, ORM과 공유하는 원시 타입, 범용 유틸리티 타입을 제공한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/core-common/type-utils/env.md

@@ -1,4 +1,6 @@
-# env / parseBoolEnv
+# `env` / `parseBoolEnv`
+
+> **읽어야 하는 상황**: 환경변수를 읽거나 쓸 때. `process.env`/`import.meta.env` 직접 접근 대신 반드시 이 함수를 사용해야 한다.
 
 환경변수 접근 유틸리티 함수. `process.env`/`import.meta.env` 직접 접근 대신 이 함수를 사용해야 한다.
 

package/claude/references/sd-simplysm-v14/core-common/types/date-only.md

@@ -1,4 +1,6 @@
-# DateOnly
+# `DateOnly`
+
+> **읽어야 하는 상황**: 시간 없이 날짜만 다뤄야 할 때 (주차 계산 지원). 시간이 포함된 날짜시간은 [`DateTime`](./date-time.md), 시간만 필요하면 [`Time`](./time.md) 참조.
 
 불변 날짜 클래스 (시간 제외: `yyyy-MM-dd`). 시간 정보 없이 날짜만 저장하며 로컬 타임존 기준으로 동작한다. 주차 계산을 지원한다. 수정 메서드는 모두 새 인스턴스를 반환한다.
 

package/claude/references/sd-simplysm-v14/core-common/types/date-time.md

@@ -1,4 +1,12 @@
-# DateTime
+# `DateTime`
+
+> **읽어야 하는 상황**: 날짜+시간을 불변 객체로 다뤄야 할 때 (파싱, 포맷, 산술 연산 포함). 시간 없이 날짜만 필요하면 [`DateOnly`](./date-only.md), 날짜 없이 시간만 필요하면 [`Time`](./time.md) 참조.
+
+## When to use
+
+- 날짜+시간을 불변 객체로 다뤄야 할 때 (밀리초 정밀도, 로컬 타임존)
+- 다양한 형식의 날짜시간 문자열을 파싱해야 할 때
+- 날짜시간 산술 연산(addMonths, addDays 등)이 필요할 때
 
 불변 날짜시간 클래스 (밀리초 정밀도, 로컬 타임존). JavaScript `Date` 객체를 래핑하여 불변성과 편리한 API를 제공한다. 수정 메서드는 모두 새 인스턴스를 반환한다.
 

package/claude/references/sd-simplysm-v14/core-common/types/lazy-gc-map.md

@@ -1,4 +1,6 @@
-# LazyGcMap
+# `LazyGcMap`
+
+> **읽어야 하는 상황**: 일정 시간 미접근 항목을 자동 삭제하는 LRU 캐시가 필요할 때. 단순 Map이면 표준 `Map`을 사용.
 
 자동 만료 기능이 있는 Map. LRU 방식으로 접근 시간을 갱신하고, 지정된 시간 동안 접근하지 않으면 자동 삭제한다. 사용 후 반드시 `dispose()`를 호출해야 GC 타이머가 정리된다.
 

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

@@ -1,4 +1,6 @@
-# Time
+# `Time`
+
+> **읽어야 하는 상황**: 날짜 없이 시간만 다뤄야 할 때 (24시간 순환). 날짜+시간이 필요하면 [`DateTime`](./date-time.md) 참조.
 
 불변 시간 클래스 (날짜 제외: `HH:mm:ss.fff`). 날짜 정보 없이 시간만 저장하며 24시간을 초과하거나 음수인 값은 자동으로 정규화된다. 수정 및 산술 메서드는 새 인스턴스를 반환하며 모두 24시간 순환한다.
 

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

@@ -1,4 +1,6 @@
-# Uuid
+# `Uuid`
+
+> **읽어야 하는 상황**: UUID v4를 생성하거나 문자열/바이트에서 UUID를 복원할 때.
 
 UUID v4 클래스. `crypto.getRandomValues` 기반으로 암호학적으로 안전한 UUID를 생성한다 (Chrome 37+, Node.js 호환).
 

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

@@ -1,4 +1,6 @@
-# bytes
+# `bytes`
+
+> **읽어야 하는 상황**: Uint8Array ↔ hex/base64 변환, 여러 Uint8Array 결합이 필요할 때.
 
 `Uint8Array` 유틸리티 네임스페이스. 복잡한 변환 연산을 제공한다.
 

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

@@ -1,4 +1,6 @@
-# dt
+# `dt`
+
+> **읽어야 하는 상황**: 날짜/시간 포맷 문자열 변환(`format`), 월 정규화(`normalizeMonth`), 12→24시간 변환이 필요할 때. 일반적으로 `DateTime`/`DateOnly`/`Time`의 `toFormatString`을 사용하고, 저수준 포맷이 필요할 때만 직접 사용.
 
 날짜 포맷 유틸리티 네임스페이스. `DateTime`, `DateOnly`, `Time` 클래스 내부에서 사용되는 저수준 포맷/변환 함수를 제공한다.
 

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

@@ -1,4 +1,6 @@
-# err
+# `err`
+
+> **읽어야 하는 상황**: catch 블록의 `unknown` 타입 에러에서 메시지 문자열을 추출할 때.
 
 에러 메시지 추출 유틸리티 네임스페이스.
 

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

@@ -1,4 +1,6 @@
-# json
+# `json`
+
+> **읽어야 하는 상황**: DateTime/Uuid/Set/Map/Error/Uint8Array 등 커스텀 타입을 포함한 JSON 직렬화/역직렬화가 필요할 때. Worker 간 전송은 [`transfer`](./transfer.md) 참조.
 
 JSON 변환 유틸리티 네임스페이스. `DateTime`, `DateOnly`, `Time`, `Uuid`, `Set`, `Map`, `Error`, `Uint8Array` 등 커스텀 타입을 지원하는 직렬화/역직렬화를 제공한다.
 

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

@@ -1,4 +1,6 @@
-# num
+# `num`
+
+> **읽어야 하는 상황**: 문자열→숫자 파싱(비숫자 문자 자동 제거), 숫자 포맷(천 단위 구분자), 0/null/undefined 검사가 필요할 때.
 
 숫자 유틸리티 네임스페이스.
 

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

@@ -1,4 +1,6 @@
-# obj
+# `obj`
+
+> **읽어야 하는 상황**: 객체 깊은 복사/비교/병합, 3-way 병합, key 조작(omit/pick), 체인 경로 접근이 필요할 때.
 
 객체 유틸리티 네임스페이스. 깊은 복사, 비교, 병합, key 조작 등을 제공한다.
 

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

@@ -1,4 +1,6 @@
-# path
+# `path`
+
+> **읽어야 하는 상황**: 브라우저 환경에서 POSIX 경로 결합/파일명 추출/확장자 추출이 필요할 때. Node.js `path` 모듈 대체.
 
 경로 유틸리티 네임스페이스. Node.js `path` 모듈 대체 (브라우저 환경 지원). POSIX 스타일 경로(슬래시 `/`)만 지원한다. Windows 백슬래시(`\`)는 지원하지 않는다.
 

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

@@ -1,4 +1,6 @@
-# primitive
+# `primitive`
+
+> **읽어야 하는 상황**: 런타임에 값의 `PrimitiveTypeStr`을 추론해야 할 때 (예: string→"string", DateTime→"DateTime").
 
 원시 타입 변환 유틸리티 네임스페이스.
 

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

@@ -1,4 +1,6 @@
-# str
+# `str`
+
+> **읽어야 하는 상황**: 한국어 조사 처리, 케이스 변환(PascalCase/camelCase/kebab-case/snake_case), 전각→반각 변환, 문자열 삽입이 필요할 때.
 
 문자열 유틸리티 네임스페이스.
 

package/claude/references/sd-simplysm-v14/core-common/utils/template-strings.md

@@ -1,5 +1,7 @@
 # Template Strings
 
+> **읽어야 하는 상황**: IDE에서 JavaScript/TypeScript/HTML/SQL 코드 하이라이팅이 필요한 태그드 템플릿 리터럴을 작성할 때.
+
 IDE 코드 하이라이팅 지원용 태그드 템플릿 리터럴 함수. 실제 동작은 문자열 결합 + 들여쓰기 정규화(앞뒤 빈 줄 제거, 공통 들여쓰기 제거)이다.
 
 ```typescript

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

@@ -1,4 +1,6 @@
-# transfer
+# `transfer`
+
+> **읽어야 하는 상황**: Worker 간에 DateTime/Uuid 등 커스텀 타입을 포함한 데이터를 전송할 때. JSON 문자열 직렬화는 [`json`](./json.md) 참조.
 
 Worker 간 전송 가능한 객체 변환 유틸리티 네임스페이스. `structuredClone`이 지원하지 않는 커스텀 타입을 처리한다.
 

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

@@ -1,4 +1,6 @@
-# wait
+# `wait`
+
+> **읽어야 하는 상황**: 조건이 true가 될 때까지 폴링 대기(`until`) 또는 지정 시간만큼 대기(`time`)가 필요할 때.
 
 비동기 대기 유틸리티 네임스페이스.
 

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

@@ -1,4 +1,6 @@
-# xml
+# `xml`
+
+> **읽어야 하는 상황**: XML 문자열을 객체로 파싱하거나 객체를 XML 문자열로 직렬화할 때.
 
 XML 변환 유틸리티 네임스페이스. `fast-xml-parser` 기반.
 

package/claude/references/sd-simplysm-v14/core-common/utils/zip-archive.md

@@ -1,4 +1,6 @@
-# ZipArchive
+# `ZipArchive`
+
+> **읽어야 하는 상황**: ZIP 파일 읽기/쓰기/압축/해제가 필요할 때. 사용 후 반드시 `close()`를 호출해야 한다.
 
 ZIP 파일 처리 클래스. ZIP 파일의 읽기, 쓰기, 압축, 해제를 처리한다. 동일 파일의 중복 해제를 방지하기 위해 내부 캐싱을 사용한다. `@zip.js/zip.js` 기반.