@simplysm/sd-claude 14.0.89 → 14.0.91

package/claude/references/sd-simplysm14/apis/core-common/async-runtime.md

@@ -1,128 +1,86 @@
 # @simplysm/core-common — 비동기 런타임
 
-비동기 실행 흐름·이벤트·캐시·로깅을 다룰 때 함께 읽히는 묶음. `DebounceQueue`/`SerialQueue`(실행 큐)는 `EventEmitter` 를 상속해 `error` 이벤트를 발행하며, `LazyGcMap`(자동 만료 캐시)·`createLogger`(태그 로거)와 함께 쓰인다.
+디바운스/직렬 실행, 타입 안전 이벤트, 조건 대기, 자동 만료 Map 이 필요할 때 함께 읽히는 묶음. 큐 클래스들은 `EventEmitter` 를 상속해 `"error"` 이벤트를 발행함.
 
-## EventEmitter
+## EventEmitter<TEvents>
 
-브라우저/Node 공통의 타입 안전 이벤트 이미터(내부적으로 `EventTarget` 사용).
+`EventTarget` 기반 타입 안전 이벤트 이미터(브라우저·Node 공용). 보통 상속해서 사용. `TEvents` 는 `{ 이벤트명: 데이터타입 }` 맵.
 
-```typescript
-class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
-  on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
-  off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
-  emit<K extends keyof TEvents & string>(type: K, ...args: TEvents[K] extends void ? [] : [data: TEvents[K]]): void;
-  listenerCount<K extends keyof TEvents & string>(type: K): number;
-  dispose(): void;
-}
-```
-
-- `TEvents` — 이벤트명→데이터 타입 맵. `void` 타입 이벤트는 `emit("done")` 처럼 인자 없이 발행.
-- `on` — 같은 (type, listener) 조합 중복 등록은 무시. `off` — 해당 listener 제거.
-- `emit` — 등록 리스너에 데이터 디스패치. `listenerCount(type)` — 현재 리스너 수(없으면 0). `dispose` — 전체 리스너 해제.
+- `on(type, listener)`: → void — 리스너 등록. 같은 (type, listener) 중복 등록은 무시.
+- `off(type, listener)`: → void — 리스너 제거.
+- `emit(type, data)`: → void — 발행. 데이터 타입이 `void` 인 이벤트는 인자 없이 `emit(type)`.
+- `listenerCount(type)`: → number — 해당 이벤트 리스너 수.
+- `dispose()`: → void — 모든 리스너 제거.
 
-```typescript
+```ts
+import { EventEmitter } from "@simplysm/core-common";
 interface MyEvents { data: string; done: void; }
-class My extends EventEmitter<MyEvents> {}
-const e = new My();
-e.on("data", (s) => console.log(s));
-e.emit("data", "hi");
+class MyEmitter extends EventEmitter<MyEvents> {}
+const e = new MyEmitter();
+e.on("data", (d) => console.log(d)); // d: string
+e.emit("data", "hello");
+e.emit("done");
 ```
 
 ## DebounceQueue
 
-짧은 시간 내 여러 호출 중 **마지막만** 실행하는 디바운스 큐. `EventEmitter<{ error: SdError }>` 상속.
+짧은 시간 내 여러 호출 중 **마지막 요청만** 실행. 입력 자동완성·연속 상태 변경 일괄 처리에. `EventEmitter<{ error: SdError }>` 상속.
 
-```typescript
-class DebounceQueue extends EventEmitter<{ error: SdError }> {
-  constructor(delay?: number);                 // 지연 ms (생략 시 다음 이벤트 루프에 즉시)
-  run(fn: () => void | Promise<void>): void;   // 대기 작업 등록(기존 대기 작업 교체)
-  override dispose(): void;                     // 타이머·대기 작업 정리
-}
-```
+- `new DebounceQueue(delay?)` — delay: number(ms). 생략 시 즉시(다음 이벤트 루프).
+- `run(fn)`: → void — `fn: () => void | Promise<void>` 등록. 이전 대기 fn 은 교체됨. delay 후 실행. 실행 중 들어온 요청은 delay 없이 현재 실행 직후 즉시 처리(요청 누락 방지).
+- `dispose()`: → void — 대기 작업·타이머 정리(+ 리스너 제거).
+- fn 에서 throw 시 `"error"` 리스너가 있으면 SdError 로 emit, 없으면 내부 logger.error.
 
-- `constructor(delay)` — 디바운스 지연. 생략하면 0(다음 틱 실행).
-- `run(fn)` — 호출할 때마다 이전 대기 fn 을 교체. 지연 후 마지막 fn 만 실행. **실행 중**에 들어온 추가 요청은 지연 없이 현재 실행 직후 즉시 처리(의도적 설계 — 누락 방지).
-- 에러 처리: fn 이 throw 하면 `SdError` 로 감싸, `error` 리스너가 있으면 `emit("error")`, 없으면 내부 로거로 출력. (문제 발생 = error 심각도)
-
-```typescript
+```ts
+import { DebounceQueue } from "@simplysm/core-common";
 const q = new DebounceQueue(300);
-q.on("error", (e) => console.error(e));
-input.addEventListener("input", () => q.run(() => search(input.value)));
+q.on("error", (err) => console.error(err));
+q.run(() => save(value)); // 300ms 안에 다시 run 하면 이전 건 취소
 ```
 
 ## SerialQueue
 
-추가된 작업을 **순차** 실행하는 큐(이전 완료 후 다음 시작). 에러가 나도 후속 작업은 계속 진행. `EventEmitter<{ error: SdError }>` 상속.
+큐에 넣은 작업을 **순차** 실행(앞 작업 완료 후 다음). 에러가 나도 후속 작업은 계속. `EventEmitter<{ error: SdError }>` 상속.
 
-```typescript
-class SerialQueue extends EventEmitter<{ error: SdError }> {
-  constructor(gap?: number);                   // 작업 사이 간격 ms (기본 0)
-  run(fn: () => void | Promise<void>): void;   // 큐에 추가하고 실행 시작
-  override dispose(): void;                     // 대기 큐 비움(실행 중 작업은 완료됨)
-}
-```
+- `new SerialQueue(gap?)` — gap: number(ms, 기본 0). 각 작업 사이 대기 간격.
+- `run(fn)`: → void — `fn: () => void | Promise<void>` 추가 후 처리 시작.
+- `dispose()`: → void — 대기 큐 비움(실행 중 작업은 완료됨)(+ 리스너 제거).
+- fn throw 시 처리: DebounceQueue 와 동일(`"error"` emit 또는 logger.error).
 
-- `constructor(gap)` — 각 작업 사이 대기 간격(ms). 0 이면 연속 실행.
-- `run(fn)` — FIFO 로 순차 실행. 한 작업이 throw 하면 `SdError` 로 감싸 `error` 이벤트 발행(리스너 없으면 로그) 후 다음 작업 진행 — 후속 작업을 막지 않으려는 의도.
-- `dispose` — 아직 시작 안 한 대기분만 제거(실행 중인 건은 완료).
+## wait 네임스페이스
 
-```typescript
-const q = new SerialQueue();
-q.run(async () => save(a)); // 순서 보장
-q.run(async () => save(b));
-```
+- `wait.until(forwarder, milliseconds?, maxCount?)`: → `Promise<void>` — `forwarder()`(boolean | Promise<boolean>) 가 true 될 때까지 대기. 첫 호출에서 true 면 즉시 반환. milliseconds=확인 간격(기본 100). maxCount=최대 시도 횟수(미지정 무제한). 초과 시 **TimeoutError throw**.
+- `wait.time(millisecond)`: → `Promise<void>` — 지정 시간만큼 sleep.
 
-## LazyGcMap
-
-마지막 접근 이후 일정 시간이 지나면 항목을 자동 삭제하는 Map(LRU 접근 시간 갱신). 타이머를 쓰므로 사용 후 `dispose()` 필수.
-
-```typescript
-class LazyGcMap<TKey, TValue> {
-  constructor(options: {
-    gcInterval?: number;   // GC 주기 ms (기본: expireTime/10, 최소 1000)
-    expireTime: number;    // 만료 시간 ms (마지막 접근 이후)
-    onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
-  });
-  get size: number;
-  has(key): boolean;       // 접근 시간 갱신 안 함
-  get(key): TValue | undefined; // 접근 시간 갱신(LRU)
-  set(key, value): void;        // 저장 + GC 타이머 시작
-  delete(key): boolean;         // 비면 타이머 중지
-  getOrCreate(key, factory: () => TValue): TValue; // dispose 후 호출 시 throw
-  clear(): void;                // 항목만 비움(재사용 가능)
-  dispose(): void;              // 타이머 중지 + 비움(이후 set/get 무력화)
-  values(): IterableIterator<TValue>;
-  keys(): IterableIterator<TKey>;
-  entries(): IterableIterator<[TKey, TValue]>;
-}
+```ts
+import { wait } from "@simplysm/core-common";
+await wait.until(() => isReady, 100, 50); // 100ms 간격 최대 50회, 초과 시 TimeoutError
+await wait.time(500);
 ```
 
-- `expireTime` — 필수. 마지막 접근 후 이 시간이 지나면 만료. `gcInterval` — 만료 스캔 주기(미지정 시 `expireTime/10`, 최소 1000ms).
-- `onExpire(key, value)` — 만료 직전 호출(비동기 가능). 콜백이 throw 해도 로그만 남기고 GC 계속. 콜백 도중 같은 key 가 재등록되면 새 항목은 삭제하지 않음.
-- `get` 은 접근 시간을 갱신(LRU), `has` 는 갱신하지 않음. `set` 이 호출돼야 GC 타이머가 시작되고, 항목이 모두 비면 타이머가 자동 중지.
-- `getOrCreate` 는 dispose 이후 호출하면 throw(silent 동작 금지). `dispose` 미호출 시 타이머가 계속 돌아 메모리 누수.
-
-```typescript
-const cache = new LazyGcMap<string, Session>({ expireTime: 60000 });
+## LazyGcMap<TKey, TValue>
+
+마지막 접근 이후 일정 시간 지나면 항목을 자동 삭제하는 Map(LRU 접근 시간 갱신). GC 는 항목이 있을 때만 타이머로 동작. 사용 후 **반드시 `dispose()`** — 안 하면 타이머가 남아 메모리 누수.
+
+- `new LazyGcMap({ expireTime, gcInterval?, onExpire? })`
+  - expireTime: number(ms) — 마지막 접근 후 이 시간 지나면 만료. (필수)
+  - gcInterval?: number(ms) — GC 점검 주기. 기본 `max(expireTime/10, 1000)`.
+  - onExpire?: `(key, value) => void | Promise<void>` — 만료 시 콜백(비동기 가능). 콜백 throw 는 logger.error 후 계속 진행. 만료 항목 정리·리소스 해제에.
+- `get(key)`: → `V | undefined` — 조회(접근 시간 갱신=만료 연장).
+- `has(key)`: → boolean — 존재 확인(접근 시간 갱신 안 함).
+- `set(key, value)`: → void — 저장(GC 타이머 시작).
+- `getOrCreate(key, factory)`: → V — 없으면 factory()로 생성·저장 후 반환(있으면 접근 시간 갱신). dispose 후 호출 시 throw.
+- `delete(key)`: → boolean / `clear()`: → void(인스턴스 재사용 가능) / `dispose()`: → void(타이머 중지+정리, 이후 사용 불가).
+- `values()` / `keys()` / `entries()`: → Iterator — 순회.
+- `size`: → number — 항목 수.
+
+```ts
+import { LazyGcMap } from "@simplysm/core-common";
+const cache = new LazyGcMap<string, Conn>({ expireTime: 60000, onExpire: (k, c) => c.close() });
 try {
-  const s = cache.getOrCreate(id, () => loadSession(id));
+  const conn = cache.getOrCreate(key, () => createConn());
 } finally {
+  // 앱/모듈 종료 시
   cache.dispose();
 }
 ```
-
-## createLogger
-
-`consola` 기반 태그 로거를 지연 생성하는 팩토리. 모듈 최상위에서 호출해도 안전(첫 메서드 접근 시점까지 `consola.withTag` 생성을 미뤄, 이후 `setupConsola()` 의 level/reporter 변경이 반영됨).
-
-```typescript
-createLogger(tag: string): ConsolaInstance;
-```
-
-- `tag` — 로그에 붙는 태그(클래스/모듈명 등). 반환값은 `consola` 인스턴스라 `.info`/`.warn`/`.error`/`.success` 등을 그대로 사용.
-- 즉시 `consola.withTag()` 를 부르면 호출 시점 옵션이 고정되는 문제를 피하기 위한 Proxy 래퍼. 테스트의 `vi.spyOn` 과도 호환.
-
-```typescript
-const logger = createLogger("MyService");
-logger.error("처리 실패", err);
-```

package/claude/references/sd-simplysm14/apis/core-common/datetime.md

@@ -1,129 +1,86 @@
-# @simplysm/core-common — 날짜·시간
+# @simplysm/core-common — 날짜·시간 값 타입
 
-불변 날짜/시간 값 `DateTime`(날짜+시간)·`DateOnly`(날짜)·`Time`(시간)과 포맷 문자열을 처리하는 `dt` 네임스페이스. 세 클래스 모두 로컬 타임존 기준이며, 모든 set/add 메서드는 원본을 변경하지 않고 새 인스턴스를 반환한다. 파싱 실패 시 `ArgumentError` throw.
+날짜·시간을 **불변(immutable)** 값으로 다룰 때 함께 읽히는 묶음. JS `Date` 대신 사용. `set*`·`add*` 메서드는 모두 새 인스턴스를 반환하고 원본을 바꾸지 않음. 모두 로컬 타임존 기준으로 동작. ORM 컬럼 타입(`DateTime`/`DateOnly`/`Time`)·JSON/Worker 직렬화에서 1급 지원됨.
 
-공통 포맷 토큰(`toFormatString` 인자): `yyyy`/`yy`(연), `MM`/`M`(월), `ddd`(요일 한글: 일~토)/`dd`/`d`(일), `tt`(AM/PM), `hh`/`h`(12시간), `HH`/`H`(24시간), `mm`/`m`(분), `ss`/`s`(초), `fff`/`ff`/`f`(밀리초), `zzz`/`zz`/`z`(타임존 오프셋, DateTime 만). 긴 토큰이 먼저 치환됨.
+세 클래스 공통:
+- `parse(str)` 정적 메서드로 문자열 파싱(미지원 형식이면 ArgumentError).
+- `tick` getter — 내부 밀리초 값. `equal`·정렬·복제의 동등성 기준.
+- `isValid` getter — 유효 값 여부.
+- `toFormatString(formatStr)` / `toString()` — 포맷 문자열 변환(아래 `dt` 네임스페이스의 포맷 토큰 사용).
 
 ## DateTime
 
-날짜+시간을 ms 정밀도로 담는 불변 클래스. 내부에 `readonly date: Date` 보유.
-
-```typescript
-class DateTime {
-  constructor();                                   // 현재 시각
-  constructor(year, month, day, hour?, minute?, second?, millisecond?); // month 는 1~12
-  constructor(tick: number);                       // epoch ms
-  constructor(date: Date);
-  static parse(str: string): DateTime;
-
-  readonly date: Date;
-  get year/month/day/hour/minute/second/millisecond/tick: number;
-  get dayOfWeek: number;             // 0(일)~6(토)
-  get timezoneOffsetMinutes: number; // UTC 대비 분 (KST = +540)
-  get isValid: boolean;
-
-  setYear/setMonth/setDay/setHour/setMinute/setSecond/setMillisecond(v: number): DateTime;
-  addYears/addMonths/addDays/addHours/addMinutes/addSeconds/addMilliseconds(n: number): DateTime;
-  toFormatString(formatStr: string): string;
-  toString(): string;                // "yyyy-MM-ddTHH:mm:ss.fffzzz"
-}
-```
+날짜+시간(밀리초 정밀도) 불변 클래스.
+
+생성자 오버로드:
+- `new DateTime()` — 현재 시각.
+- `new DateTime(year, month, day, hour?, minute?, second?, millisecond?)` — month 는 1~12(내부에서 0-base 변환). 시·분·초·밀리초 생략 시 0.
+- `new DateTime(tick)` — 밀리초 tick.
+- `new DateTime(date)` — JS Date 복제.
+
+- `DateTime.parse(str)`: → DateTime — 지원 형식: `yyyy-MM-dd HH:mm:ss[.fff]`, `yyyyMMddHHmmss`, `yyyy-MM-dd AM/PM HH:mm:ss`, 한국어 `yyyy-MM-dd 오전/오후 HH:mm:ss`, ISO 8601.
+
+getter: `year`·`month`(1~12)·`day`·`hour`·`minute`·`second`·`millisecond`·`tick`·`dayOfWeek`(일~토=0~6)·`timezoneOffsetMinutes`(UTC 대비 분, KST=+540)·`isValid`·`date`(내부 Date, 읽기 전용).
 
-- 생성자 `month` 인자는 1~12(내부에서 `month-1` 로 Date 에 전달). `tick`/`Date` 오버로드는 단일 숫자/Date 로 구분.
-- `parse` 지원 형식: `yyyy-MM-dd HH:mm:ss[.fff]`, `yyyyMMddHHmmss`, `yyyy-MM-dd AM/PM HH:mm:ss`, 한국어 `yyyy-MM-dd 오전/오후 HH:mm:ss`, ISO 8601. 먼저 `Date.parse` 를 시도.
-- `setMonth(month)` — 1~12 밖이면 연도로 흡수, 대상 월 일수보다 현재 일이 크면 말일로 보정(1/31 → setMonth(2) → 2/28). `setYear` 도 윤년 말일 보정.
-- `addMonths`/`addDays` 는 각각 `setMonth`/`setDay` 기반이라 월말 보정/오버플로 규칙을 따름. `addHours` 이하는 tick 가산이라 타임존 전환 영향 없음.
-- `isValid` — 내부 Date 가 NaN 이 아닌지. `parse` 가 아닌 잘못된 tick/Date 로 만든 경우 점검용.
+불변 변환(새 인스턴스): `setYear`·`setMonth`·`setDay`·`setHour`·`setMinute`·`setSecond`·`setMillisecond`. 산술(새 인스턴스): `addYears`·`addMonths`·`addDays`·`addHours`·`addMinutes`·`addSeconds`·`addMilliseconds`.
 
-```typescript
-new DateTime(2025, 1, 31).setMonth(2).toFormatString("yyyy-MM-dd"); // "2025-02-28"
-DateTime.parse("2025-01-15 오후 2:30:00").hour;                     // 14
+- `setMonth(month)` / `addMonths` — 대상 월의 일수가 현재 일보다 적으면 그 달 마지막 일로 보정(1/31 → setMonth(2) → 2/28|29). 범위 밖 월은 연도로 캐리.
+- `setDay(day)` — 범위 밖 일은 JS Date 규칙대로 다음/이전 월로 넘어감.
+
+```ts
+import { DateTime } from "@simplysm/core-common";
+const at = DateTime.parse("2025-01-15 10:30:00");
+at.addDays(3).toFormatString("yyyy-MM-dd HH:mm"); // "2025-01-18 10:30"
 ```
 
 ## DateOnly
 
-시간 정보 없이 날짜만 담는 불변 클래스(`readonly date: Date`, 자정 고정). 주차 계산 API 포함.
-
-```typescript
-class DateOnly {
-  constructor();                       // 오늘
-  constructor(year, month, day);        // month 1~12
-  constructor(tick: number);
-  constructor(date: Date);
-  static parse(str: string): DateOnly;
-  static getDateByYearWeekSeq(arg: { year: number; month?: number; weekSeq: number }, weekStartDay?: number, minDaysInFirstWeek?: number): DateOnly;
-
-  readonly date: Date;
-  get year/month/day/tick/dayOfWeek: number; // dayOfWeek 0(일)~6(토)
-  get isValid: boolean;
-  setYear/setMonth/setDay(v: number): DateOnly;
-  addYears/addMonths/addDays(n: number): DateOnly;
-
-  getBaseYearMonthSeqForWeekSeq(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number };
-  getWeekSeqStartDate(weekStartDay?: number, minDaysInFirstWeek?: number): DateOnly;
-  getWeekSeqOfYear(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; weekSeq: number };
-  getWeekSeqOfMonth(weekStartDay?: number, minDaysInFirstWeek?: number): { year: number; monthSeq: number; weekSeq: number };
-
-  toFormatString(formatStr: string): string;
-  toString(): string;                  // "yyyy-MM-dd"
-}
-```
+시간 없는 날짜(yyyy-MM-dd) 불변 클래스.
+
+생성자: `new DateOnly()`(오늘) / `(year, month, day)` / `(tick)` / `(date)`.
 
-- `parse` 형식: `yyyy-MM-dd`·`yyyyMMdd`(둘 다 타임존 무관, 문자열에서 직접 추출), ISO 8601(UTC 해석 후 로컬 변환). 서버/클라 타임존이 다르면 `yyyy-MM-dd` 권장.
-- 주차 계산 공통 인자: `weekStartDay` 주 시작 요일(0=일~6=토, 기본 1=월), `minDaysInFirstWeek` 첫 주로 인정할 최소 일수(1~7, 기본 4=ISO 8601). 미국식은 `(0, 1)`.
-- `getWeekSeqOfYear` — 연 기준 몇 째 주인지. `getWeekSeqOfMonth` — 월 기준 주차(+기준 연·월). `getWeekSeqStartDate` — 이 날짜가 속한 주의 시작일. `getBaseYearMonthSeqForWeekSeq` — 주차 귀속 기준 연·월(월 경계 조정).
-- `getDateByYearWeekSeq(arg, ...)` — 정적. `{ year, weekSeq }`(연 주차) 또는 `{ year, month, weekSeq }`(월 주차)로 해당 주 시작일 역산.
+- `DateOnly.parse(str)`: → DateOnly — `yyyy-MM-dd`·`yyyyMMdd`(타임존 무관, 문자열에서 직접 추출)·ISO 8601(UTC 해석 후 로컬 변환). 서버/클라 타임존이 다르면 `yyyy-MM-dd` 형식 권장.
 
-```typescript
-new DateOnly(2025, 1, 6).getWeekSeqOfYear();           // { year: 2025, weekSeq: 2 }
-DateOnly.getDateByYearWeekSeq({ year: 2025, weekSeq: 2 }); // 2025-01-06 (월)
+getter: `year`·`month`·`day`·`tick`·`dayOfWeek`·`isValid`·`date`. 불변 변환: `setYear`·`setMonth`·`setDay`(DateTime 과 동일한 월말/캐리 보정). 산술: `addYears`·`addMonths`·`addDays`.
+
+주차 계산(ISO 8601 기본: weekStartDay=1 월요일, minDaysInFirstWeek=4):
+- `getWeekSeqOfYear(weekStartDay?, minDaysInFirstWeek?)`: → `{ year, weekSeq }` — 해당 연도 내 주차 번호.
+- `getWeekSeqOfMonth(weekStartDay?, minDaysInFirstWeek?)`: → `{ year, monthSeq, weekSeq }` — 해당 월 내 주차 번호.
+- `getWeekSeqStartDate(weekStartDay?, minDaysInFirstWeek?)`: → DateOnly — 이 날짜가 속한 주의 시작일.
+- `getBaseYearMonthSeqForWeekSeq(weekStartDay?, minDaysInFirstWeek?)`: → `{ year, monthSeq }` — 주차 귀속 기준 연·월(주가 걸친 경우 어느 달로 셈할지).
+- `DateOnly.getDateByYearWeekSeq(arg, weekStartDay?, minDaysInFirstWeek?)`: → DateOnly — `arg = { year, month?, weekSeq }` 로 그 주의 시작일을 역산.
+
+옵션 풀이:
+- weekStartDay: 0~6 — 주 시작 요일. 0=일요일(미국식), 1=월요일(ISO, 기본). 달력 표시 기준에 맞춤.
+- minDaysInFirstWeek: 1~7 — 첫 주로 인정할 최소 일수. 4=ISO(주의 과반), 1=시작일 포함 즉시 1주차(미국식).
+
+```ts
+import { DateOnly } from "@simplysm/core-common";
+new DateOnly(2025, 1, 6).getWeekSeqOfYear(); // { year: 2025, weekSeq: 2 }
 ```
 
 ## Time
 
-날짜 없이 시각(HH:mm:ss.fff)만 담는 불변 클래스. 24시간을 넘거나 음수인 tick 은 24시간 순환으로 정규화된다.
-
-```typescript
-class Time {
-  constructor();                                  // 현재 시각의 시간 부분
-  constructor(hour, minute, second?, millisecond?);
-  constructor(tick: number);                       // 자정 기준 ms
-  constructor(date: Date);                          // Date 의 시간 부분만
-  static parse(str: string): Time;
-
-  get hour/minute/second/millisecond/tick: number;
-  get isValid: boolean;
-  setHour/setMinute/setSecond/setMillisecond(v: number): Time;
-  addHours/addMinutes/addSeconds/addMilliseconds(n: number): Time; // 24시간 순환
-  toFormatString(formatStr: string): string;
-  toString(): string;                              // "HH:mm:ss.fff"
-}
-```
+날짜 없는 시간(HH:mm:ss.fff) 불변 클래스. 24시간 초과·음수 tick 은 자동으로 0~24h 범위로 순환 정규화됨.
 
-- 생성자 다중 인자(`hour, minute, ...`)와 단일 `tick`/`Date` 오버로드. 결과 tick 은 항상 `[0, 24h)` 범위로 wrap.
-- `parse` 형식: `HH:mm:ss[.fff]`, `AM/PM HH:mm:ss[.fff]`, ISO 8601(시간 부분만 추출, 타임존 변환은 Date 위임).
-- `addHours` 등 산술은 24시간을 넘으면 다시 0시부터(`23:00` + 2h → `01:00`). 날짜 개념이 없으므로 일자 carry 는 버려짐.
+생성자: `new Time()`(현재 시각) / `(hour, minute, second?, millisecond?)` / `(tick)` / `(date)`(Date 의 시간부만).
 
-```typescript
-Time.parse("AM 10:30:00").addHours(15).toString(); // "01:30:00.000"
-```
+- `Time.parse(str)`: → Time — `HH:mm:ss[.fff]`·`AM/PM HH:mm:ss`·ISO 8601(시간부만 추출).
 
-## dt 네임스페이스
+getter: `hour`·`minute`·`second`·`millisecond`·`tick`·`isValid`. 불변 변환: `setHour`·`setMinute`·`setSecond`·`setMillisecond`. 산술: `addHours`·`addMinutes`·`addSeconds`·`addMilliseconds` (모두 24시간 순환 — 23:30 에 +1h → 00:30).
 
-`import { dt } from "@simplysm/core-common"`. 위 클래스들이 내부에서 쓰는 포맷/정규화 함수를 직접 노출.
+## dt 네임스페이스 (날짜/시간 포맷)
 
-```typescript
-dt.format(formatString: string, args: { year?; month?; day?; hour?; minute?; second?; millisecond?; timezoneOffsetMinutes?: number }): string;
-dt.normalizeMonth(year: number, month: number, day: number): { year: number; month: number; day: number };
-dt.convert12To24(rawHour: number, isPM: boolean): number;
-interface DtNormalizedMonth { year: number; month: number; day: number; }
-```
+`toFormatString` 이 내부적으로 쓰는 포맷 토큰 정의. 직접 호출도 가능.
+
+- `dt.format(formatString, args)`: → string — `args = { year?, month?, day?, hour?, minute?, second?, millisecond?, timezoneOffsetMinutes? }` 중 주어진 구성요소만 치환. C# 스타일 토큰 사용.
+- `dt.normalizeMonth(year, month, day)`: → `{ year, month, day }` — 범위 밖 월을 연도로 캐리하고 일을 월말로 보정. `set*Month` 구현 기반.
+- `dt.convert12To24(rawHour, isPM)`: → number — 12시간제(1~12)+오전/오후 → 24시간제(0~23). 12 AM=0, 12 PM=12.
+- 타입 `dt.DtNormalizedMonth` = `{ year; month; day }`.
 
-- `dt.format(fmt, args)` — 위 공통 토큰 표를 따르는 저수준 포맷터. 누락한 구성요소(예: `hour` 만)는 해당 토큰만 치환하고 나머지는 원문 유지. `DateTime`/`DateOnly`/`Time` 의 `toFormatString` 이 이 함수를 호출.
-- `dt.normalizeMonth(year, month, day)` — 월이 1~12 밖이면 연도로 흡수, 일이 대상 월 일수 초과면 말일로 보정한 `{year, month, day}`. `setMonth` 의 보정 규칙 그대로.
-- `dt.convert12To24(rawHour, isPM)` — 12시간(1~12)+AM/PM 을 0~23 으로. `12 AM`→0, `12 PM`→12.
+포맷 토큰: `yyyy`/`yy`(연), `MM`/`M`(월), `ddd`(요일 일~토)/`dd`/`d`(일), `tt`(AM/PM), `hh`/`h`(12시간), `HH`/`H`(24시간), `mm`/`m`(분), `ss`/`s`(초), `fff`/`ff`/`f`(밀리초), `zzz`(±HH:mm)/`zz`(±HH)/`z`(±H, 타임존 오프셋).
 
-```typescript
+```ts
+import { dt } from "@simplysm/core-common";
 dt.format("yyyy-MM-dd (ddd)", { year: 2024, month: 3, day: 15 }); // "2024-03-15 (금)"
-dt.normalizeMonth(2025, 13, 15);                                  // { year: 2026, month: 1, day: 15 }
 ```

package/claude/references/sd-simplysm14/apis/core-common/errors.md

@@ -1,91 +1,86 @@
 # @simplysm/core-common — 에러 클래스
 
-원인 체인(`cause`)을 가진 에러를 throw 하거나 타입별로 분기할 때 함께 읽히는 묶음. 모두 `SdError` 를 베이스로 하며 각 클래스는 `name` 을 자기 클래스명으로 설정해 `instanceof`·`name` 양쪽으로 식별 가능.
+`throw` 를 던지거나, 에러 원인을 체인으로 감싸거나, catch 에서 `instanceof` 로 분기할 때 함께 읽히는 묶음. 모두 `SdError` 를 상속하므로 `instanceof SdError` 로 한꺼번에 잡을 수 있음.
 
 ## SdError
 
-ES2024 `cause` 를 활용해 에러를 트리로 감싸는 베이스 클래스. 메시지는 **역순으로 결합**되어 상위(가장 바깥) 메시지가 앞에 온다.
-
-```typescript
+```ts
 class SdError extends Error {
   override cause?: Error;
-  constructor(cause: Error, ...messages: string[]); // 원인 에러 + 상위 메시지들
-  constructor(...messages: string[]);               // 메시지들만
+  constructor(cause: Error, ...messages: string[]); // 원인 에러를 감싸기
+  constructor(...messages: string[]);                // 메시지만으로 생성
 }
 ```
 
-- `cause: Error` — 첫 인자가 `Error` 면 원인으로 저장되고 그 stack 이 현재 stack 뒤에 `---- cause stack ----` 로 이어붙음. 첫 인자가 문자열/기타면 일반 메시지로 취급.
-- `...messages` — 추가 설명 메시지들. 결합 시 `messages` 가 먼저 reverse 되어 `상위 => 하위 => 원인` 순으로 `" => "` 결합. null/undefined 메시지는 제외.
+ES2024 `cause` 를 활용한 트리형 에러. 메시지는 **역순으로** `" => "` 로 결합됨(상위 메시지가 앞).
 
-```typescript
-throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
-// message: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
+- cause: Error — 첫 인자가 Error 면 원인 에러로 보존(`this.cause`). 원인 에러의 stack 이 현재 stack 뒤에 `---- cause stack ----` 로 이어 붙음. 하위 호출에서 받은 에러를 상위 문맥으로 감쌀 때.
+- ...messages: string[] — 문맥 메시지들. `new SdError(err, "API 호출 실패", "사용자 로드 실패")` → `"사용자 로드 실패 => API 호출 실패 => 원본 메시지"`. null/undefined 메시지는 제외됨.
+- `name` 은 `"SdError"`. V8(Node·Chrome)에서 `captureStackTrace` 로 생성자 프레임 제거.
 
-throw new SdError("잘못된 상태", "처리 불가");
-// message: "처리 불가 => 잘못된 상태"
+```ts
+import { SdError } from "@simplysm/core-common";
+try {
+  await fetch(url);
+} catch (err) {
+  throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
+}
 ```
 
-주의: 하위 에러를 잡아 컨텍스트를 덧붙여 다시 throw 할 때 사용. 원본 에러를 삼키지 말고 첫 인자로 넘겨 체인을 보존.
+주의: 첫 인자가 Error 가 아니면(문자열·기타) cause 없이 메시지로만 취급됨. `new SdError("잘못된 상태", "처리 불가")` → `"처리 불가 => 잘못된 상태"`.
 
 ## ArgumentError
 
-유효하지 않은 인자를 받았을 때 throw. 인자 객체를 YAML 로 직렬화해 메시지에 포함(디버깅용). `SdError` 상속.
-
-```typescript
+```ts
 class ArgumentError extends SdError {
-  constructor(argObj: Record<string, unknown>);             // 기본 메시지 + 인자
-  constructor(message: string, argObj: Record<string, unknown>); // 커스텀 메시지 + 인자
+  constructor(argObj: Record<string, unknown>);
+  constructor(message: string, argObj: Record<string, unknown>);
 }
 ```
 
-- `argObj` — 문제가 된 인자들을 담은 객체. `YAML.stringify` 결과가 메시지 본문 뒤에 두 줄 띄고 붙음. 어떤 값이 잘못됐는지 그대로 노출하려는 의도.
-- `message` — 생략 시 `"잘못된 인자입니다."` 가 기본값.
+유효하지 않은 인자를 받았을 때 던지는 에러. 디버깅을 위해 인자 객체를 **YAML 형식**으로 메시지에 붙임. `name` 은 `"ArgumentError"`.
+
+- argObj: Record<string, unknown> — 메시지에 YAML 로 직렬화해 포함할 인자값들. 어떤 입력이 문제였는지 드러낼 때.
+- message: string — 커스텀 머리말. 생략 시 `"잘못된 인자입니다."` 사용.
 
-```typescript
-throw new ArgumentError("잘못된 사용자", { userId: 123, name: null });
-// "잘못된 사용자\n\nuserId: 123\nname: null"
+```ts
+import { ArgumentError } from "@simplysm/core-common";
+throw new ArgumentError("유효하지 않은 UUID 형식입니다.", { uuid });
+// 메시지: "유효하지 않은 UUID 형식입니다.\n\nuuid: ..."
 ```
 
-이 패키지 내부(`Uuid`, `bytes`, `num` 파싱, `obj` 체인 함수 등)에서 입력 검증 실패 시 광범위하게 사용된다.
+이 패키지 내부 검증(Uuid·bytes·obj 체인 등)에서 이미 광범위하게 throw 하므로, 유효성 위반은 직접 처리하지 말고 그대로 전파하는 편이 일관적.
 
 ## NotImplementedError
 
-아직 구현되지 않은 코드 경로가 호출됐을 때 throw. `SdError` 상속.
-
-```typescript
+```ts
 class NotImplementedError extends SdError {
-  constructor(message?: string); // "미구현" 또는 "미구현: <message>"
+  constructor(message?: string);
 }
 ```
 
-- `message` — 어떤 기능이 미구현인지 보조 설명. 생략 시 메시지는 `"미구현"`.
+아직 구현되지 않은 기능이 호출됐을 때. 메시지는 `"미구현"` 또는 `"미구현: <message>"`. `name` 은 `"NotImplementedError"`. 추상 메서드 스텁, 미구현 분기에 사용.
 
-```typescript
-switch (type) {
-  case "A": return handleA();
-  case "B": throw new NotImplementedError(`타입 ${type} 처리`); // "미구현: 타입 B 처리"
-}
-```
-
-추상 메서드 스텁이나 미완성 분기에 의도적 throw 로 두어 silent skip 을 막는 용도.
+- message?: string — 무엇이 미구현인지 추가 설명. 예: `throw new NotImplementedError(\`타입 ${type} 처리\`)`.
 
 ## TimeoutError
 
-대기 시간이 초과됐을 때 throw. `wait.until()` 이 `maxCount` 초과 시 자동으로 발생시킨다. `SdError` 상속.
-
-```typescript
+```ts
 class TimeoutError extends SdError {
-  constructor(count?: number, message?: string); // "대기 시간 초과(<count>회 시도): <message>"
+  constructor(count?: number, message?: string);
 }
 ```
 
-- `count` — 시도 횟수. 지정 시 `(N회 시도)` 가 메시지에 삽입됨.
-- `message` — 무엇을 대기하다 실패했는지 보조 설명.
+대기 시간 초과 에러. 메시지는 `"대기 시간 초과"` + (count 있으면 `(N회 시도)`) + (message 있으면 `: <message>`). `name` 은 `"TimeoutError"`.
+
+- count?: number — 시도 횟수. `wait.until(...)` 이 최대 시도 초과 시 자동으로 이 에러를 throw(시도 횟수를 넣어).
+- message?: string — 무엇을 기다리다 초과했는지 추가 설명.
 
-```typescript
+```ts
+import { TimeoutError, wait } from "@simplysm/core-common";
 try {
   await wait.until(() => isReady, 100, 50);
-} catch (e) {
-  if (e instanceof TimeoutError) { /* 타임아웃 분기 */ }
+} catch (err) {
+  if (err instanceof TimeoutError) { /* 타임아웃 처리 */ }
 }
 ```