@simplysm/sd-claude 14.0.76 → 14.0.77

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

@@ -1,123 +1,88 @@
 # @simplysm/core-common — extensions
 
-`index.ts` 가 import 되면 자동으로 `Array.prototype`, `Set.prototype`, `Map.prototype` 에 메서드를 정의 (`enumerable: false`).
-
-## Array (Readonly — 새 배열/값 반환)
-
-### 조회
-
-```typescript
-arr.single(pred?)              // 0 or 1개. 2개 이상이면 ArgumentError. 없으면 undefined.
-arr.first(pred?)               // pred 면 find, 없으면 [0]
-arr.last(pred?)                // pred 면 역방향 find, 없으면 [length-1]
-arr.filterExists()             // null/undefined 제거 → NonNullable<T>[]
-arr.ofType("string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes")
-arr.ofType(SomeClass)          // instanceof 또는 constructor 일치
-```
-
-### 비동기
-
-```typescript
-await arr.filterAsync(asyncPred)        // 순차
-await arr.mapAsync(asyncSelector)       // 순차
-await arr.mapManyAsync(asyncSelector)   // 순차 + 평탄화
-await arr.parallelAsync(fn)             // Promise.all (하나 reject 시 전체 reject)
-```
-
-### 매핑·평탄화
-
-```typescript
-arr.mapMany()                  // 중첩 배열 1단계 flatten + filterExists
-arr.mapMany(selector)          // 매핑 후 flatten
+`@simplysm/core-common` import 시 자동 적용. 글로벌 `Array`/`ReadonlyArray`/`Map`/`Set` 인터페이스에 ambient declare.
+
+## ReadonlyArray<T> (비파괴)
+
+```ts
+single(predicate?): T | undefined            // 0~1개만 통과. 2개+ → ArgumentError
+first(predicate?): T | undefined             // 첫 요소 (predicate 시 find와 동일)
+last(predicate?): T | undefined              // 마지막 요소
+filterAsync(predicate: async): Promise<T[]>  // 비동기 필터 (순차)
+filterExists(): NonNullable<T>[]             // null/undefined 제거 + 타입 좁힘
+ofType(type: PrimitiveTypeStr | Type<N>): N[]   // 원시 타입명 또는 생성자로 필터
+mapAsync(selector: async): Promise<R[]>      // 비동기 매핑 (순차)
+mapMany(selector?): R[]                      // flat + filterExists
+mapManyAsync(selector?: async): Promise<R[]>
+parallelAsync(fn: async): Promise<R[]>       // Promise.all (하나 reject 시 전체 reject)
+
+groupBy(keySelector, valueSelector?): { key, values }[]
+  // 원시 key: O(n) Map 최적화. 객체 key: equal() 비교로 O(n²)
+toMap(keySelector, valueSelector?): Map<K, V>          // 중복 key → ArgumentError
+toMapAsync(keySelector: async, valueSelector?: async): Promise<Map>
+toArrayMap(keySelector, valueSelector?): Map<K, V[]>   // 중복 허용, array로 누적 (O(n))
+toSetMap(keySelector, valueSelector?): Map<K, Set<V>>
+toMapValues(keySelector, valueSelector(items)): Map<K, V>   // value는 그룹 전체로 계산
+toObject(keySelector: → string, valueSelector?): Record<string, V>
+toTree(keyProp, parentKey): TreeArray<T>[]   // 평면 → 트리 (parentKey null이면 root)
+
+distinct(options?: bool | { matchAddress?, keyFn? }): T[]
+  // matchAddress=true: Set 참조 비교. keyFn: 커스텀 키 O(n). 둘 다 없이 객체: O(n²) equal
+orderBy(selector?): T[]                      // 오름차순 (불변, 새 array)
+orderByDesc(selector?): T[]
+
+diffs(target, options?: { keys?, excludes? }): ArrayDiffsResult<T, P>[]
+  // 전체 일치 우선, 없으면 keys 일치(update 후보). 결과: INSERT|DELETE|UPDATE
+oneWayDiffs(orgItems: T[] | Map<TKey, T>, keyPropNameOrGetValFn, options?):
+  ArrayOneWayDiffResult<T>[]                 // type: 'create'|'update'|'same'
+merge(target, options?): (T | P | T&P)[]     // diffs 후 update는 obj.merge, insert는 append
+
+sum(selector?): number                       // 숫자 아니면 ArgumentError
+min(selector?): number | string | undefined  // 숫자/문자열만
+max(selector?): number | string | undefined
+shuffle(): T[]                               // Fisher-Yates, 새 array
 ```
 
-### 변환
+## Array<T> (파괴, @mutates)
 
-```typescript
-arr.groupBy(keyFn)                              // [{ key, values }, ...] (객체 key 시 O(n²), 원시 key 는 O(n))
-arr.groupBy(keyFn, valueFn)
-arr.toMap(keyFn) / toMap(keyFn, valFn)          // 중복 key 시 ArgumentError
-await arr.toMapAsync(...)
-arr.toArrayMap(keyFn[, valFn])                  // Map<K, V[]>  (원시 key 권장 — O(n))
-arr.toSetMap(keyFn[, valFn])                    // Map<K, Set<V>>
-arr.toMapValues(keyFn, (items) => aggregated)
-arr.toObject(strKeyFn[, valFn])                 // 중복 key 시 ArgumentError
-arr.toTree("id", "parentId")                    // 평면 → 트리 ({...item, children: []}), O(n).
-                                                //   parentKey 가 null/undefined 면 루트.
+```ts
+distinctThis(options?)                       // distinct를 in-place로
+orderByThis(selector?)                       // Array.prototype.sort 위임 (in-place)
+orderByDescThis(selector?)
+insert(index, ...items)                      // splice 삽입, this 반환
+remove(item | selector)                      // 역순 순회 splice 제거
+toggle(item)                                 // 있으면 remove, 없으면 push
+clear()                                      // 전체 비우기
 ```
 
-### 중복·정렬
-
-```typescript
-arr.distinct()                                  // 깊은 equal 비교 (객체 array 는 O(n²))
-arr.distinct(true)                              // matchAddress: 참조 비교 (Set 기반, O(n))
-arr.distinct({ matchAddress?, keyFn? })         // keyFn 권장 — O(n)
-arr.orderBy(selector?)                          // 오름차순. string/number/DateTime/DateOnly/Time/undefined 지원
-arr.orderByDesc(selector?)
-arr.shuffle()                                   // Fisher-Yates
+## 익스포트 타입
+
+```ts
+type ArrayDiffsResult<TOrig, TOther> =
+  | { source: undefined; target: TOther }     // INSERT
+  | { source: TOrig; target: undefined }      // DELETE
+  | { source: TOrig; target: TOther }         // UPDATE
+type ArrayOneWayDiffResult<T> =
+  | { type: 'create'; item: T; orgItem: undefined }
+  | { type: 'update'; item: T; orgItem: T }
+  | { type: 'same'; item: T; orgItem: T }
+type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] }
+type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined
 ```
 
-### 비교·병합
-
-```typescript
-arr.diffs(target)                               // INSERT/DELETE/UPDATE 결과
-arr.diffs(target, { keys: ["id"], excludes? })  // key 기반 매칭 (Map 인덱싱 O(n+m))
-arr.diffs(target, { excludes: [...] })
-   // 결과 타입:
-   //   { source: undefined, target: T }  // INSERT
-   //   { source: T, target: undefined }  // DELETE
-   //   { source: T, target: T }          // UPDATE
+## Map<K, V>
 
-arr.oneWayDiffs(orgItems | Map, keyPropOrFn, {
-  includeSame?, excludes?, includes?,
-})
-   // 결과: { type: "create"|"update"|"same", item, orgItem }
-
-arr.merge(target[, { keys?, excludes? }])       // diffs 후 source 기반에 target 병합·신규 push
+```ts
+getOrCreate(key, newValue: V): V
+getOrCreate(key, newValueFn: () => V): V     // 함수면 팩토리로 호출하여 lazy 생성
+update(key, updateFn: (v: V | undefined) => V): void   // key 없어도 fn 호출
 ```
+- **주의**: `Map<K, () => void>` 같이 V가 함수 타입이면 두 번째 인자가 팩토리로 인식됨. 함수 값을 저장하려면 `getOrCreate(k, () => myFn)`.
 
-### 집계
+## Set<T>
 
-```typescript
-arr.sum(selector?)             // 숫자 아니면 ArgumentError. 빈 배열 → 0.
-arr.min(selector?) / max(selector?)   // string|number. 빈 배열 → undefined
+```ts
+adds(...values: T[]): this                   // 다중 add
+toggle(value, addOrDel?: "add" | "del"): this
+  // 인자 없으면 자동 토글, "add"=강제 추가, "del"=강제 삭제
 ```
-
-### TreeArray 타입
-
-```typescript
-type TreeArray<T> = T & { children: TreeArray<T>[] };
-```
-
-## Array (Mutable — 원본 변경, `@mutates`)
-
-```typescript
-arr.distinctThis(options?)             // 원본에서 중복 제거 (역순 splice, O(n))
-arr.orderByThis(selector?) / orderByDescThis(selector?)
-arr.insert(index, ...items)
-arr.remove(itemOrSelector)             // 일치 항목 모두 제거. 역순 순회.
-arr.toggle(item)                       // 있으면 remove, 없으면 push
-arr.clear()
-```
-
-모두 `this` 반환 (체이닝 가능, `clear/distinctThis/orderBy*This` 는 변경된 자기 자신).
-
-## Set
-
-```typescript
-set.adds(...values)                            // 다중 add, this 반환
-set.toggle(value)                              // 자동 토글
-set.toggle(value, "add" | "del")               // 강제 추가/제거
-```
-
-## Map
-
-```typescript
-map.getOrCreate(key, defaultValue)             // 없으면 set 후 반환
-map.getOrCreate(key, () => expensiveCompute()) // 팩토리 (값이 함수이면 항상 호출됨 — 함수 값을 저장하려면 `() => fn` 으로 한 번 더 감쌀 것)
-map.update(key, (v|undefined) => newV)         // 없는 key 도 호출됨 (카운터·배열 push 패턴)
-```
-
-## ComparableType
-
-`orderBy*` 의 selector 반환 타입: `string | number | boolean | DateTime | DateOnly | Time | undefined`.

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

@@ -1,46 +1,51 @@
 # @simplysm/core-common — features
 
-비동기 큐와 타입 안전 이벤트 이미터.
-
-## EventEmitter\<TEvents\>
-
-브라우저·Node 공용 (내부 `EventTarget`). 타입 안전.
-
-```typescript
-interface MyEvents { data: string; error: Error; done: void; }
-class MyEmitter extends EventEmitter<MyEvents> {}
-
-const e = new MyEmitter();
-e.on("data", (d) => ...);       // d: string
-e.emit("data", "hello");
-e.emit("done");                 // void 이벤트는 인자 없이
-e.off("data", handler);
-e.listenerCount("data");        // 등록된 수
-e.dispose();                    // 모든 리스너 제거
+## EventEmitter<TEvents>
+
+EventTarget 기반의 타입 안전 이벤트 이미터. 브라우저·Node 공통.
+
+```ts
+class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
+  on<E extends keyof TEvents & string>(type: E, listener: (data: TEvents[E]) => void): void
+  off<E>(type: E, listener: ...): void
+  emit<E>(type: E, ...args: TEvents[E] extends void ? [] : [data: TEvents[E]]): void
+  listenerCount(type): number
+  dispose(): void                            // 모든 리스너 제거
+}
+```
+- `TEvents`: `{ eventName: dataType }` 맵. `void` 타입이면 `emit("done")` 인자 생략.
+- 같은 `(type, listener)` 쌍 중복 등록 시 무시.
+- 내부적으로 `CustomEvent.detail`로 데이터 전송. listener는 wrapper로 감싸져 등록되며, listenerMap이 원본 ↔ wrapper 매핑 보관.
+
+```ts
+interface MyEvents { data: string; done: void }
+class M extends EventEmitter<MyEvents> {}
+const m = new M();
+m.on("data", s => ...);
+m.emit("data", "hi");
+m.emit("done");
 ```
 
-같은 이벤트에 같은 리스너 중복 등록은 무시.
-
-## DebounceQueue extends EventEmitter\<{ error: SdError }\>
+## DebounceQueue extends EventEmitter<{ error: SdError }>
 
-연속 호출 중 마지막 작업만 실행.
+마지막 요청만 실행. 짧은 시간 내 다중 호출 → 마지막 1건만 처리.
 
-```typescript
-const q = new DebounceQueue(300);   // 300ms 지연 (생략 시 다음 이벤트 루프)
-q.run(fn);                          // 이전 대기 함수 교체
-q.on("error", (e) => ...);          // 작업 throw 시. 리스너 없으면 logger.error
-q.dispose();                        // 타이머·대기 함수 정리
+```ts
+new DebounceQueue(delay?: number)            // ms. 생략 시 다음 이벤트 루프 (setTimeout(_, undefined))
+run(fn: () => void | Promise<void>): void
+dispose(): void                              // 타이머·pending 정리
 ```
+- `delay` ms 지난 뒤 가장 최근 `fn` 실행. 실행 중 도착한 추가 `run()`은 디바운스 지연 없이 현재 실행 직후 즉시 처리 (요청 누락 방지).
+- fn throw 시 `SdError`로 감싸 `"error"` 이벤트 발행. 리스너 없으면 `consola` 로그.
 
-실행 도중 들어온 새 요청은 지연 없이 실행 완료 직후 즉시 처리 (놓침 방지).
-
-## SerialQueue extends EventEmitter\<{ error: SdError }\>
+## SerialQueue extends EventEmitter<{ error: SdError }>
 
-순차 실행, 작업 사이 간격 옵션.
+큐에 추가된 함수들을 순차 실행.
 
-```typescript
-const q = new SerialQueue(0);       // gap ms (기본 0)
-q.run(asyncFn);                     // 큐에 추가, 자동 실행
-q.on("error", ...);                 // 에러는 다음 작업에 영향 X (계속 실행)
-q.dispose();                        // 대기 큐 비움 (현재 작업은 완료됨)
+```ts
+new SerialQueue(gap: number = 0)             // 각 작업 사이 ms 간격
+run(fn: () => void | Promise<void>): void
+dispose(): void                              // 대기 큐 비우기 (실행 중은 완료됨)
 ```
+- 하나 완료 후 다음 시작. 에러 발생해도 후속 작업 계속 실행. throw는 `SdError` 감싸서 `"error"` 이벤트 (리스너 없으면 `consola.error`).
+- `gap>0` 이면 작업 간 `wait.time(gap)` 대기.

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

@@ -1,114 +1,88 @@
 # @simplysm/core-common — types
 
-날짜·시간·UUID·만료 캐시 타입.
-
-## DateTime (불변)
-
-밀리초 정밀도, 로컬 타임존. 모든 변환/산술 메서드는 새 인스턴스 반환.
+## Uuid
 
-```typescript
-new DateTime()                                    // 현재
-new DateTime(year, month, day, h?, m?, s?, ms?)   // month 는 1-12
-new DateTime(tick)                                // ms epoch
-new DateTime(date)                                // Date 복사
-DateTime.parse(str)                               // "yyyy-MM-dd HH:mm:ss" / "yyyyMMddHHmmss" /
-                                                  //   "yyyy-MM-dd AM|PM HH:mm:ss" / "오전|오후" / ISO 8601
-                                                  //   실패 시 ArgumentError
+```ts
+class Uuid {
+  static generate(): Uuid                  // crypto.getRandomValues 기반 UUID v4
+  static fromBytes(bytes: Bytes): Uuid     // 16바이트 Uint8Array → Uuid (길이≠16이면 ArgumentError)
+  constructor(uuid: string)                // 형식 검증 (실패 시 ArgumentError)
+  toString(): string
+  toBytes(): Bytes
+}
 ```
-
-Getters: `year/month/day/hour/minute/second/millisecond/tick/dayOfWeek/timezoneOffsetMinutes/isValid` (month 는 1-12, dayOfWeek 는 0-6 일~토).
-
-변환: `setYear/setMonth/setDay/setHour/setMinute/setSecond/setMillisecond` — 새 인스턴스. `setMonth` 는 대상 월 일수 초과 시 마지막 일로 클램프. `setDay` 는 JS Date 동작에 따라 월 경계 자동 조정.
-
-산술: `addYears/addMonths/addDays/addHours/addMinutes/addSeconds/addMilliseconds`.
-
-포맷: `toFormatString(formatStr)` ([date-format 토큰](#date-format-토큰)). `toString()` = `"yyyy-MM-ddTHH:mm:ss.fffzzz"`.
-
-## DateOnly (불변)
-
-날짜만(yyyy-MM-dd), 로컬 타임존.
-
-```typescript
-new DateOnly()                       // 오늘
-new DateOnly(year, month, day)
-new DateOnly(tick) / new DateOnly(date)
-DateOnly.parse(str)                  // "yyyy-MM-dd" / "yyyyMMdd" (타임존 무관) /
-                                     //   ISO 8601 (UTC → 로컬 변환). 실패 시 ArgumentError
+- 정규식 `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i` 로 검증.
+- v4 비트: byte[6]은 0x40 마스크, byte[8]은 0x80 마스크 적용.
+
+## DateTime (불변, 로컬 타임존, ms 정밀도)
+
+```ts
+new DateTime()                              // 현재
+new DateTime(year, month, day, h?, m?, s?, ms?)
+new DateTime(tick: number)
+new DateTime(date: Date)
+static parse(str): DateTime                 // 'yyyy-MM-dd HH:mm:ss[.fff]', 'yyyyMMddHHmmss',
+                                            // 'yyyy-MM-dd AM/PM HH:mm:ss', '오전/오후', ISO 8601
 ```
-
-Getters: `year/month/day/tick/dayOfWeek/isValid`.
-변환·산술: `setYear/setMonth/setDay`, `addYears/addMonths/addDays`.
-포맷: `toFormatString`, `toString()` = `"yyyy-MM-dd"`.
-
-주차 API (ISO 8601 기본: 월요일 시작, 첫 주 최소 4일):
-
-```typescript
-d.getWeekSeqOfYear(weekStartDay=1, minDaysInFirstWeek=4)  // { year, weekSeq }
-d.getWeekSeqOfMonth(...)                                  // { year, monthSeq, weekSeq }
-d.getWeekSeqStartDate(...)                                // DateOnly
-d.getBaseYearMonthSeqForWeekSeq(...)                      // { year, monthSeq }
-DateOnly.getDateByYearWeekSeq({ year, month?, weekSeq }, ...) // 해당 주 시작일
+- 읽기 getter: `year`, `month` (1-12), `day`, `hour`, `minute`, `second`, `millisecond`, `tick`, `dayOfWeek` (0=일~6=토), `timezoneOffsetMinutes`, `isValid`, `date` (내부 Date 복사 X — readonly 참조).
+- 변환: `setYear/Month/Day/Hour/Minute/Second/Millisecond(n)` → 새 인스턴스. `setMonth`는 일수 초과 시 해당 월 말일로 보정 (예: 1월 31일 → 2월 28/29일).
+- 산술: `addYears/Months/Days` (캘린더 기반), `addHours/Minutes/Seconds/Milliseconds` (tick 가산).
+- 포맷: `toFormatString(fmt)` — `dt.format` 형식 문자열. `toString()` = `"yyyy-MM-ddTHH:mm:ss.fffzzz"`.
+- 파싱 실패 시 `ArgumentError`.
+
+## DateOnly (불변, 시간 제외)
+
+```ts
+new DateOnly() | new DateOnly(y,m,d) | new DateOnly(tick) | new DateOnly(date)
+static parse(str): DateOnly                 // 'yyyy-MM-dd', 'yyyyMMdd' (타임존 무관),
+                                            // ISO 8601 (UTC→로컬 변환)
+static getDateByYearWeekSeq(
+  { year, month?, weekSeq },
+  weekStartDay = 1, minDaysInFirstWeek = 4,
+): DateOnly                                 // 지정 주차의 시작 날짜
 ```
-
-## Time (불변)
-
-시간만(HH:mm:ss.fff). 24h 순환 — 음수/24h+ 자동 정규화.
-
-```typescript
-new Time()                              // 현재 시각의 시간 부분
-new Time(hour, minute, second?, ms?)
-new Time(tick) / new Time(date)
-Time.parse(str)                         // "HH:mm:ss[.fff]" / "AM|PM HH:mm:ss[.fff]" / ISO 8601 시간 부분
+- getter: `year`, `month`, `day`, `tick`, `dayOfWeek`, `isValid`.
+- `setYear/Month/Day`, `addYears/Months/Days` 동일 패턴 (월 보정 동일).
+- 주차 API (인스턴스):
+  - `getBaseYearMonthSeqForWeekSeq(weekStartDay=1, minDaysInFirstWeek=4)`: 이 날짜가 속한 주의 기준 연/월.
+  - `getWeekSeqStartDate(...)`: 이 날짜가 속한 주의 시작 날짜.
+  - `getWeekSeqOfYear(...)`: `{ year, weekSeq }`.
+  - `getWeekSeqOfMonth(...)`: `{ year, monthSeq, weekSeq }`.
+- `weekStartDay`: 주 시작 요일 (0=일~6=토). 기본 1=월.
+- `minDaysInFirstWeek`: 첫 주 최소 일수 (1~7). 4=ISO 8601, 1=미국식.
+- `toFormatString(fmt)` / `toString()` = `"yyyy-MM-dd"`.
+
+## Time (불변, 24시간 순환)
+
+```ts
+new Time() | new Time(h, m, s?, ms?) | new Time(tick) | new Time(date)
+static parse(str): Time                     // 'HH:mm:ss[.fff]', 'AM/PM HH:mm:ss', ISO 8601
 ```
-
-Getters/Setters/Add 메서드는 DateTime 시간부와 유사. `addHours/Minutes/Seconds/Milliseconds` 는 24h 순환.
-
-## Uuid
-
-UUID v4, `crypto.getRandomValues` 기반.
-
-```typescript
-Uuid.generate()                  // 새 v4
-new Uuid("xxxxxxxx-...")         // 형식 검증, 실패 시 ArgumentError
-Uuid.fromBytes(bytes16)          // 16바이트 → Uuid (길이 ≠ 16 시 ArgumentError)
-u.toString()                     // "xxxxxxxx-xxxx-..."
-u.toBytes()                      // 16바이트 Uint8Array
+- 24시간을 초과/음수인 tick 입력은 자동으로 `% MS_PER_DAY` 정규화.
+- getter: `hour`, `minute`, `second`, `millisecond`, `tick`, `isValid`.
+- `setHour/Minute/Second/Millisecond`, `addHours/Minutes/Seconds/Milliseconds` (24시간 순환).
+- `toFormatString(fmt)` / `toString()` = `"HH:mm:ss.fff"`.
+
+## LazyGcMap<TKey, TValue>
+
+LRU 접근 시간 갱신 + 주기 GC 로 자동 만료되는 `Map`.
+
+```ts
+new LazyGcMap({
+  expireTime: number,                       // 만료 ms (필수). 마지막 접근부터 경과 시 삭제
+  gcInterval?: number,                      // GC 주기 ms. 기본 = max(expireTime/10, 1000)
+  onExpire?: (key, value) => void|Promise<void>,   // 만료 시 콜백. 비동기 가능, throw하면 로그만
+})
+
+has(key)       // 접근 시간 갱신 X
+get(key)       // 접근 시간 갱신 O
+set(key, val)  // GC 타이머 시작
+delete(key)    // 비면 GC 중지
+clear()        // 전체 삭제 + GC 중지 (인스턴스 재사용 가능)
+dispose()      // 영구 정리 (이후 모든 작업 no-op, getOrCreate만 throw)
+getOrCreate(key, factory)
+size, keys(), values(), entries()
 ```
-
-## LazyGcMap
-
-LRU 자동 만료 Map. **사용 후 반드시 `dispose()` 호출** — 안 하면 GC 타이머가 살아 메모리 누수.
-
-```typescript
-const m = new LazyGcMap<K, V>({
-  expireTime: 60_000,           // 마지막 접근 이후 ms
-  gcInterval?: 6_000,           // 기본: expireTime/10, 최소 1000ms
-  onExpire?: (k, v) => ... ,    // 비동기 가능, 에러는 로그
-});
-
-m.size; m.has(k); m.get(k); m.set(k, v); m.delete(k); m.clear(); m.dispose();
-m.getOrCreate(k, factory);                 // dispose 후 호출 시 throw
-m.keys() / m.values() / m.entries();       // Iterator
-```
-
-`get`/`getOrCreate` 만 접근시간 갱신(LRU). `has` 는 갱신 X. GC 실행 중 같은 key 재등록 시 새 항목 보존.
-
-## date-format 토큰
-
-`DateTime/DateOnly/Time#toFormatString(formatStr)` 에서 사용. C# 호환.
-
-| 토큰 | 의미 | 예 |
-|------|------|----|
-| `yyyy`/`yy` | 연도 4/2자리 | 2024 / 24 |
-| `MM`/`M` | 월 패딩/미패딩 | 01 / 1 |
-| `ddd` | 한글 요일 | 일~토 |
-| `dd`/`d` | 일 패딩/미패딩 | 01 / 1 |
-| `tt` | AM/PM | AM |
-| `hh`/`h` | 12시간 패딩/미패딩 | 01 / 1 |
-| `HH`/`H` | 24시간 패딩/미패딩 | 14 / 14 |
-| `mm`/`m` | 분 | 30 / 30 |
-| `ss`/`s` | 초 | 45 / 45 |
-| `fff`/`ff`/`f` | 밀리초 3/2/1자리 | 123 / 12 / 1 |
-| `zzz`/`zz`/`z` | 타임존 ±HH:mm / ±HH / ±H | +09:00 |
-
-긴 토큰이 먼저 매칭 → 부분 매칭 방지.
+- **반드시 `dispose()` 호출 필요** — 안 하면 GC 타이머 leak.
+- GC 중복 실행 방지(`_isGcRunning`). `onExpire` 실행 도중 같은 key로 `set()`되면 새 값은 보존(참조 동일성 비교).
+- 비어있으면 자동 GC 중지 → 재 `set()` 시 자동 재시작.