@simplysm/sd-claude 14.0.88 → 14.0.90

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

@@ -1,138 +1,130 @@
 # @simplysm/core-common
 
-브라우저·Node 공용 유틸리티 패키지. 에러 계층, 불변 날짜/시간 값, 큐·이벤트·로거, 컬렉션 프로토타입 확장, 객체·문자열·숫자·바이트·경로·직렬화 네임스페이스, 타입 유틸리티를 제공한다. 패키지를 import 하면 부수효과로 `Array`/`Set`/`Map` 프로토타입 확장이 주입된다.
+브라우저·Node 공용 유틸리티 패키지. 날짜/시간 값 타입, 에러 클래스, 배열/객체 조작, 직렬화, 비동기 큐, 로거, 환경변수 접근을 제공. 워크스페이스 거의 모든 패키지의 기반.
+
+> 부수효과 주의: 이 패키지를 import 하면 `Array.prototype`·`Set.prototype`·`Map.prototype` 에 확장 메서드가 설치됨(전역 prototype 변경). 확장 메서드는 `array.toMap(...)` 처럼 메서드로 직접 호출.
 
 ## 사용 트리거 인덱스
 
-- **날짜·시간** — `DateTime`/`DateOnly`/`Time` 불변 값과 포맷(`dt`). 날짜 계산·주차·포맷이 필요할 때. 자세히: [datetime.md](./datetime.md)
-- **컬렉션 확장** — `Array`/`Set`/`Map` 프로토타입 메서드(groupBy·distinct·orderBy·diffs·toTree·getOrCreate 등). 배열·맵·셋 가공 시. 자세히: [array-ext.md](./array-ext.md)
-- **obj 네임스페이스** — 깊은 clone·equal·merge·merge3, 경로 접근, pick/omit, 키 변환. 객체 비교·병합·정리 시. 자세히: [obj.md](./obj.md)
-- **직렬화 (json/xml/transfer)** — 커스텀 타입 보존 JSON·XML·Worker 전송. 영속화·통신·워커 전달 시. 자세히: [json-transfer.md](./json-transfer.md)
-- **에러** — `SdError`/`ArgumentError`/`NotImplementedError`/`TimeoutError`. throw 시 메시지 체인·인자 덤프가 필요할 때. (아래 인라인)
-- **env** — `env`/`parseBoolEnv`. 환경변수 read/write·불리언 파싱 시. (아래 인라인)
-- **값 타입** — `Uuid`, `LazyGcMap`. UUID 생성·검증, 자동 만료 캐시 맵. (아래 인라인)
-- **큐·이벤트·로거** — `DebounceQueue`/`SerialQueue`/`EventEmitter`/`createLogger`. 디바운스·직렬 실행·이벤트·태그 로깅 시. (아래 인라인)
-- **문자열·숫자·바이트·경로 (str/num/bytes/path/wait/err/primitive)** — 케이스 변환·조사·파싱·포맷·hex/base64·POSIX 경로·대기. (아래 인라인)
-- **코드 템플릿 태그·ZIP** — `js`/`ts`/`html`/`tsql`/`mysql`/`pgsql` 하이라이팅 태그, `ZipArchive`. (아래 인라인)
-- **타입 유틸리티** — `Bytes`/`PrimitiveType*`/`DeepPartial`/`Type`. 원시 타입 매핑·생성자 타입이 필요할 때. (아래 인라인)
-
-## 에러
-
-`SdError` 를 루트로 한 계층. 메시지는 상위→하위→원인 순서로 `" => "` 결합되어 출력된다.
-
-- `new SdError(cause: Error, ...messages)` / `new SdError(...messages)` — ES2024 `cause` 활용. `cause` 가 있으면 stack 에 원인 stack 을 이어 붙임. `messages` 는 역순 결합(뒤 인자가 더 하위).
-- `new ArgumentError(argObj)` / `new ArgumentError(message, argObj)` — 유효하지 않은 인자용. `argObj` 를 YAML 로 메시지에 포함(기본 메시지 "잘못된 인자입니다.").
-- `new NotImplementedError(message?)` — 미구현 분기·추상 스텁용. 메시지 "미구현(: message)".
-- `new TimeoutError(count?, message?)` — 대기 초과용. `count` 는 시도 횟수. `wait.until` 이 최대 시도 초과 시 자동 throw.
-
-```typescript
-throw new SdError(err, "API 호출 실패");          // "API 호출 실패 => <원인 메시지>"
-throw new ArgumentError("잘못된 사용자", { userId }); // YAML 인자 덤프 포함
+- **에러 클래스** — `throw` 할 때, 에러 원인 체인을 만들 때, catch 에서 분기할 때. SdError/ArgumentError/NotImplementedError/TimeoutError. 자세히: [errors.md](./errors.md)
+- **날짜/시간 값 타입** — 날짜·시간을 불변 값으로 다루거나 파싱·포맷·산술할 때. DateTime/DateOnly/Time + `dt` 포맷 네임스페이스. 자세히: [datetime.md](./datetime.md)
+- **배열 확장 메서드** — 배열을 그룹화·정렬·중복제거·Map변환·트리화·diff/merge 할 때. `Array.prototype` 확장. 자세히: [array-ext.md](./array-ext.md)
+- **객체 유틸 (`obj` 네임스페이스)** — 깊은 복사/비교/병합, 체인 경로 접근, key 변환을 할 때. 자세히: [obj.md](./obj.md)
+- **직렬화/Worker 전송** — 커스텀 타입(DateTime·Uuid·Map·Set·Error 등) 포함 데이터를 JSON·XML·바이트·Worker 메시지로 주고받을 때. `json`/`xml`/`bytes`/`transfer` 네임스페이스. 자세히: [serialization.md](./serialization.md)
+- **비동기 큐·이벤트·대기** — 디바운스/직렬 실행, 타입 안전 이벤트, 조건 대기, 자동 만료 Map 이 필요할 때. DebounceQueue/SerialQueue/EventEmitter/wait/LazyGcMap. 자세히: [async-runtime.md](./async-runtime.md)
+- **로거** — 모듈 어디서든 로그를 찍을 때 (아래 인라인).
+- **환경변수** — 환경변수를 읽고/쓰고/boolean 파싱할 때 (아래 인라인).
+- **문자열/숫자/경로 유틸** — 한국어 조사, 케이스 변환, 숫자 파싱·포맷, POSIX 경로 조작 (아래 인라인).
+- **UUID·ZIP·템플릿 태그·Set/Map 확장·공용 타입** — 그 외 단발성 유틸 (아래 인라인).
+
+## 로거
+
+`createLogger(tag)` — consola 기반 lazy logger 인스턴스 생성. 모듈 레벨에서 호출해도 안전(첫 메서드 접근 시점까지 `consola.withTag` 생성을 지연하므로 이후 `setupConsola()` 의 level/reporters 변경이 반영됨).
+
+- tag: string — 로그 prefix 로 표시되는 태그. 형식은 `<도메인>:<역할>` 또는 단일 토큰 권장. 메시지 본문에 `[패키지명]` 수동 prefix 를 넣지 말 것 — 그 역할은 tag 가 담당.
+
+```ts
+import { createLogger } from "@simplysm/core-common";
+const logger = createLogger("capacitor:auto-update");
+logger.info("최신 버전 확인 중");
+logger.error("checkPermissions 실패", err);
 ```
 
-## env
+`console.*` 직접 호출·`consola.withTag()` 직접 호출 금지 — 항상 `createLogger` 사용.
 
-- `env(key): string | undefined` — 환경변수 읽기(`process.env` 우선, 없으면 `import.meta.env`).
-- `env(key, value): void` — `process.env` 에 쓰기(process 가 있을 때만).
-- `parseBoolEnv(value): boolean` — `"true"`/`"1"`/`"yes"`/`"on"`(대소문자 무시) → `true`, 그 외 → `false`.
+## 환경변수
 
-## 값 타입
+- `env(key)`: → `string | undefined` — 환경변수 읽기. `process.env[key]` 우선, 없으면 `import.meta.env[key]` fallback. Node·브라우저(Vite) 양쪽에서 동작.
+- `env(key, value)`: → `void` — `process.env[key]` 에 값 쓰기 (Node 환경에서만 적용, 브라우저에선 무동작).
+- `parseBoolEnv(value)`: → `boolean` — 환경변수 문자열을 boolean 으로 해석. `"true"|"1"|"yes"|"on"` (대소문자 무시) 이면 true, 그 외(빈 값·undefined 포함) false. 플래그성 env 판정에 사용.
 
-### Uuid
+```ts
+import { env, parseBoolEnv } from "@simplysm/core-common";
+if (parseBoolEnv(env("DEV"))) { /* 개발 모드 분기 */ }
+```
+
+## 문자열 유틸 (`str` 네임스페이스)
 
-암호학적으로 안전한 UUID v4(`crypto.getRandomValues` 기반) 불변 값 객체.
-- `Uuid.generate(): Uuid` — 새 v4 생성.
-- `Uuid.fromBytes(bytes): Uuid` — 16바이트 `Uint8Array` 로 생성(길이≠16 이면 `ArgumentError`).
-- `new Uuid(uuidStr)` — 형식(`8-4-4-4-12` hex) 검증, 불일치 시 `ArgumentError`.
-- `toString(): string` / `toBytes(): Uint8Array` — 문자열·16바이트 변환.
+- `str.getKoreanSuffix(text, type)`: → string — 받침 유무로 한국어 조사 선택. type: `"을"`(을/를)·`"은"`(은/는)·`"이"`(이/가)·`"와"`(과/와)·`"랑"`(이랑/랑)·`"로"`(으로/로, 받침 ㄹ 은 "로")·`"라"`(이라/라). 빈 문자열·한글 아님이면 받침 없음 조사 반환. 동적 메시지 조립에 사용.
+- `str.replaceFullWidth(s)`: → string — 전각 영문/숫자/공백/괄호를 반각으로 변환. OCR·외부 입력 정규화에 사용.
+- `str.toPascalCase(s)` / `toCamelCase(s)` / `toKebabCase(s)` / `toSnakeCase(s)`: → string — 케이스 변환. `-`·`_`·`.` 구분자와 대문자 경계를 인식. 코드 생성·식별자 정규화에 사용.
+- `str.isNullOrEmpty(s)`: → `s is "" | undefined` — null/undefined/빈 문자열 판정(타입 가드). false 분기에서 non-empty string 으로 좁혀짐.
+- `str.insert(s, index, insertString)`: → string — index 위치에 문자열 삽입한 새 문자열.
 
-### LazyGcMap
+```ts
+import { str } from "@simplysm/core-common";
+`${name}${str.getKoreanSuffix(name, "을")} 저장했습니다`;
+```
 
-LRU 접근시간 기반 자동 만료 Map. **반드시 `dispose()` 호출** 해야 GC 타이머가 정리됨(아니면 메모리 누수).
-- `new LazyGcMap({ gcInterval?, expireTime, onExpire? })` — `expireTime`(ms): 마지막 접근 후 이 시간 지나면 삭제. `gcInterval`(ms): GC 주기, 기본 `expireTime/10`(최소 1000). `onExpire(key, value)`: 만료 시 콜백(async 가능, 에러 시 로그 후 계속).
-- `get(key)` — 조회(접근시간 갱신). `has(key)` — 존재 확인(갱신 안 함). `set(key, value)` — 저장(첫 set 에 GC 타이머 시작). `delete(key)` / `clear()`(인스턴스 재사용 가능) / `dispose()`(이후 사용 불가).
-- `getOrCreate(key, factory)` — 없으면 `factory()` 로 생성·저장(dispose 후 호출 시 throw).
-- `size` getter, `keys()`/`values()`/`entries()` 이터레이터.
+## 숫자 유틸 (`num` 네임스페이스)
 
-## 큐·이벤트·로거
+- `num.parseInt(text)`: → `number | undefined` — 비숫자 문자 제거 후 정수 파싱. 소수점은 버림(`"12.34"`→12). 선행 `-` 만 음수 부호로 유지, 중간 `-` 제거(`"010-1234"`→101234). 파싱 불가면 undefined.
+- `num.parseFloat(text)`: → `number | undefined` — 위와 동일 규칙으로 실수 파싱.
+- `num.parseRoundedInt(text)`: → `number | undefined` — float 파싱 후 반올림한 정수. 소수 입력을 반올림 정수로 받을 때.
+- `num.isNullOrEmpty(val)`: → `val is 0 | undefined` — null/undefined/0 판정(타입 가드). false 분기에서 0 아닌 숫자로 좁혀짐.
+- `num.format(val, digit?)`: → string(또는 입력이 undefined 면 undefined) — 천 단위 구분자 포함 포맷. `digit.max`=최대 소수 자릿수, `digit.min`=최소 소수 자릿수(부족분 0 채움). `format(1234.567, { max: 2 })`→`"1,234.57"`.
 
-### EventEmitter\<TEvents\>
+## 경로 유틸 (`path` 네임스페이스)
 
-`EventTarget` 래퍼. `TEvents` 는 `{ 이벤트명: 데이터타입 }` 맵. 보통 상속해 사용.
-- `on(type, listener)` / `off(type, listener)` — 등록/해제(같은 리스너 중복 등록은 무시).
-- `emit(type, data?)` — 발행(데이터 타입이 `void` 면 인자 생략).
-- `listenerCount(type): number` — 리스너 수.
-- `dispose()` — 모든 리스너 제거.
+POSIX 스타일(슬래시 `/`)만 지원. 브라우저·Capacitor 환경용. Windows 백슬래시 경로 미지원.
 
-### DebounceQueue (extends EventEmitter\<{ error: SdError }\>)
+- `path.join(...segments)`: → string — 세그먼트를 `/` 로 결합. 중간 중복 슬래시·빈 세그먼트 정리.
+- `path.basename(filePath, ext?)`: → string — 파일명 추출. ext 가 주어지고 끝나면 그 확장자 제거.
+- `path.extname(filePath)`: → string — 확장자 추출(`.` 포함). 숨김 파일(`.gitignore`)은 빈 문자열(Node 와 동일).
 
-연속 호출 시 마지막만 실행하는 디바운스 큐. 실행 중 들어온 요청은 지연 없이 직후 즉시 처리.
-- `new DebounceQueue(delay?)` — `delay`(ms) 생략 시 다음 이벤트 루프에 즉시.
-- `run(fn)` — 대기 함수 교체(이전 대기 폐기). `dispose()` — 타이머·대기 정리.
-- 작업 에러는 `"error"` 리스너가 있으면 emit, 없으면 내부 로거로 출력.
+## UUID (`Uuid` 클래스)
 
-### SerialQueue (extends EventEmitter\<{ error: SdError }\>)
+- `Uuid.generate()`: → Uuid — `crypto.getRandomValues` 기반 암호학적 안전 UUID v4 생성.
+- `new Uuid(uuidStr)` — 문자열로 생성. 형식 불일치면 ArgumentError throw.
+- `Uuid.fromBytes(bytes)`: → Uuid — 16바이트 Uint8Array 로 생성. 길이≠16 이면 ArgumentError.
+- 인스턴스: `toString()` → 문자열, `toBytes()` → 16바이트 Uint8Array.
 
-추가된 함수를 순차 실행. 한 작업이 실패해도 후속은 계속.
-- `new SerialQueue(gap?)` — `gap`(ms) 작업 사이 간격(기본 0).
-- `run(fn)` — 큐에 추가·실행. `dispose()` — 대기분 비움(실행 중 작업은 완료).
-- 에러 처리는 DebounceQueue 와 동일.
+## ZIP (`ZipArchive` 클래스)
 
-### createLogger
+ZIP 읽기/쓰기/압축/해제. 동일 파일 중복 해제 방지용 내부 캐시 사용. 사용 후 `close()` 필수.
 
-- `createLogger(tag): ConsolaInstance` — `consola.withTag` 를 지연 생성하는 lazy 로거. 모듈 레벨에서 선언해도 이후 `setupConsola` 변경(level/reporters)이 반영됨. `vi.spyOn` 호환.
+- `new ZipArchive(data?)` — data(`Blob | Uint8Array`) 주면 읽기용, 생략하면 새 아카이브.
+- `extractAll(progressCallback?)`: → `Promise<Map<string, Bytes | undefined>>` — 모든 파일 추출. 콜백은 `{ fileName, totalSize, extractedSize }` 진행률 수신.
+- `get(fileName)`: → `Promise<Bytes | undefined>` — 단일 파일 추출(없으면 undefined).
+- `exists(fileName)`: → `Promise<boolean>` — 파일 존재 여부.
+- `write(fileName, bytes)`: → void — 파일을 캐시에 등록(아직 압축 전).
+- `compress()`: → `Promise<Bytes>` — 캐시된 전체 파일을 ZIP 바이트로 압축. 내부적으로 `extractAll()` 호출(대용량 시 메모리 주의).
+- `close()`: → `Promise<void>` — 리더 닫고 캐시 비움.
 
-## 문자열·숫자·바이트·경로·대기
+## 템플릿 태그 (코드 하이라이팅용)
 
-### str 네임스페이스
-- `str.getKoreanSuffix(text, type)` — 받침에 따라 한국어 조사 반환. `type`: `"을"`(을/를)·`"은"`(은/는)·`"이"`(이/가)·`"와"`(과/와)·`"랑"`(이랑/랑)·`"로"`(으로/로, ㄹ받침 예외)·`"라"`(이라/라).
-- `str.replaceFullWidth(s)` — 전각 영문·숫자·공백·괄호 → 반각.
-- `str.toPascalCase`/`toCamelCase`/`toKebabCase`/`toSnakeCase(s)` — 케이스 변환(연속 대문자 분리, 기존 구분자 유지).
-- `str.isNullOrEmpty(s): s is "" | undefined` — null/undefined/빈 문자열 타입 가드.
-- `str.insert(s, index, insertString)` — 지정 위치에 문자열 삽입.
+`js` / `ts` / `html` / `tsql` / `mysql` / `pgsql` — 모두 동일 동작: 템플릿 리터럴을 문자열로 결합하고 공통 들여쓰기를 제거(앞뒤 빈 줄 제거). IDE 하이라이팅·가독성 목적이며 SQL 이스케이프 등 기능 차이는 없음.
 
-### num 네임스페이스
-- `num.parseInt(text)` / `num.parseFloat(text)` — 비숫자 문자 제거 후 파싱(선행 `-` 만 음수 부호 유지). 실패 시 `undefined`. parseInt 는 소수부 버림.
-- `num.parseRoundedInt(text)` — float 파싱 후 반올림 정수.
-- `num.isNullOrEmpty(val): val is 0 | undefined` — null/undefined/0 타입 가드.
-- `num.format(val, digit?)` — 천 단위 구분 문자열. `digit: { max?, min? }` 소수 자릿수(min 부족분 0 채움). val 이 undefined 면 undefined.
+```ts
+import { ts } from "@simplysm/core-common";
+const code = ts`
+  interface User { name: string; }
+`; // 들여쓰기 정규화된 문자열
+```
 
-### bytes 네임스페이스 (`Bytes` = `Uint8Array`)
-- `bytes.concat(arrays)` — 여러 Uint8Array 결합.
-- `bytes.toHex(bytes)` / `bytes.fromHex(hex)` — hex 왕복(소문자 출력. fromHex 는 홀수 길이·비hex 문자 시 `ArgumentError`).
-- `bytes.toBase64(bytes)` / `bytes.fromBase64(base64)` — base64 왕복(fromBase64 는 공백·패딩 정규화, 잘못된 문자·길이 시 `ArgumentError`).
+## Set 확장 메서드 (`Set.prototype`)
 
-### path 네임스페이스 (POSIX `/` 전용, 브라우저·Capacitor용)
-- `path.join(...segments)` — 슬래시 결합(중복 슬래시 정리). `path.basename(filePath, ext?)` — 파일명(ext 일치 시 제거). `path.extname(filePath)` — 확장자(숨김 파일은 빈 문자열).
+- `set.adds(...values)`: → this — 여러 값을 한 번에 add. 체이닝 가능.
+- `set.toggle(value, addOrDel?)`: → this — 값 토글. `addOrDel` 생략 시 있으면 제거/없으면 추가, `"add"`=강제 추가, `"del"`=강제 제거. 조건부 추가/제거를 한 줄로.
 
-### wait 네임스페이스
-- `wait.until(forwarder, milliseconds?, maxCount?)` — 조건이 true 될 때까지 대기. `milliseconds` 확인 간격(기본 100), `maxCount` 최대 시도(초과 시 `TimeoutError`, undefined 면 무제한).
-- `wait.time(millisecond)` — 지정 ms 대기 Promise.
+## Map 확장 메서드 (`Map.prototype`)
 
-### err 네임스페이스
-- `err.message(error): string` — `unknown` 에러에서 메시지 추출(`Error` 면 `.message`, 아니면 `String()`). catch 블록용.
+- `map.getOrCreate(key, newValue)` / `getOrCreate(key, newValueFn)`: → V — key 없으면 값(또는 팩토리 호출 결과) 설정 후 반환, 있으면 기존 값. 주의: V 가 함수 타입이면 두 번째 인자 함수가 팩토리로 인식되어 호출됨 — 함수를 값으로 저장하려면 `() => myFn` 으로 감쌀 것.
+- `map.update(key, updateFn)`: → void — `updateFn(현재값 | undefined)` 결과로 값 설정. key 가 없어도 호출됨. 카운터 증가·배열 누적에 사용. 예: `m.update(k, v => (v ?? 0) + 1)`.
 
-### primitive 네임스페이스
-- `primitive.typeStr(value): PrimitiveTypeStr` — 런타임 값 → 원시 타입 문자열(`"string"`|`"number"`|`"boolean"`|`"DateTime"`|`"DateOnly"`|`"Time"`|`"Uuid"`|`"Bytes"`). 미지원 타입은 `ArgumentError`.
+## 공용 타입 (`common.types`)
 
-## 코드 템플릿 태그·ZIP
+- `Bytes` = `Uint8Array` — 바이너리 데이터 별칭. Buffer 대신 사용.
+- `PrimitiveTypeMap` — 원시 타입 문자열 → 실제 타입 매핑(`string`/`number`/`boolean`/`DateTime`/`DateOnly`/`Time`/`Uuid`/`Bytes`). orm-common 과 공유.
+- `PrimitiveTypeStr` = `keyof PrimitiveTypeMap` — 원시 타입 문자열 key union.
+- `PrimitiveType` — 모든 원시 타입 값의 union(+ undefined).
+- `DeepPartial<T>` — 모든 속성을 재귀적으로 optional 화. 원시/날짜 타입은 그대로 두고 object/array 만 재귀.
+- `Type<TInstance>` — 클래스 생성자 타입(`new (...args) => TInstance`). DI·팩토리·instanceof 체크에 사용.
 
-코드 하이라이팅용 태그 함수(동작은 문자열 결합 + 공통 들여쓰기 정규화로 동일):
-- `js`/`ts`/`html`/`tsql`/`mysql`/`pgsql` — 각각 JS·TS·HTML·MSSQL·MySQL·PostgreSQL 하이라이팅 의도. `` js`...` `` 형태로 사용.
+## 원시 타입 추론 (`primitive` 네임스페이스)
 
-### ZipArchive
-ZIP 읽기/쓰기/압축/해제 클래스. 내부 캐시로 중복 해제 방지. **사용 후 `close()` 필수**.
-- `new ZipArchive(data?)` — `data`(`Blob | Bytes`) 생략 시 새 아카이브.
-- `get(fileName): Promise<Bytes | undefined>` — 특정 파일 추출. `exists(fileName): Promise<boolean>` — 존재 확인.
-- `extractAll(progressCallback?): Promise<Map<string, Bytes | undefined>>` — 전체 추출. `progressCallback(progress)` 의 `progress: ZipArchiveProgress { fileName, totalSize, extractedSize }`.
-- `write(fileName, bytes)` — 캐시에 파일 추가. `compress(): Promise<Bytes>` — 캐시 내용을 ZIP 으로 압축(내부에서 extractAll 호출, 대용량 메모리 주의). `close()` — 리더 닫고 캐시 비움.
+- `primitive.typeStr(value)`: → PrimitiveTypeStr — 런타임 값에서 원시 타입 문자열 추론(`"hello"`→`"string"`, `new DateTime()`→`"DateTime"`, `Uint8Array`→`"Bytes"`). 지원 안 되는 타입이면 ArgumentError. ORM 컬럼 타입 판정 등에 사용.
 
-## 타입 유틸리티
+## 에러 메시지 추출 (`err` 네임스페이스)
 
-`common.types` 의 타입(네임스페이스 아닌 직접 export):
-- `Bytes` = `Uint8Array` — 바이너리 타입 별칭.
-- `PrimitiveTypeMap` — `{ string, number, boolean, DateTime, DateOnly, Time, Uuid, Bytes }` 원시 타입 매핑(orm-common 과 공유).
-- `PrimitiveTypeStr` = `keyof PrimitiveTypeMap` — 원시 타입 문자열 key.
-- `PrimitiveType` = `PrimitiveTypeMap[PrimitiveTypeStr] | undefined` — 원시 타입 union.
-- `DeepPartial<TObject>` — 모든 속성을 재귀적으로 optional 로(원시 타입은 그대로, object/array 에만 재귀).
-- `Type<TInstance>` — 클래스 생성자 타입(`new (...args) => TInstance`). DI·팩토리·`instanceof` 체크용.
+- `err.message(e)`: → string — `unknown` 에러에서 메시지 추출. Error 면 `.message`, 아니면 `String(e)`. catch 블록의 `unknown` 을 안전하게 문자열화할 때.

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

@@ -1,72 +1,77 @@
-# @simplysm/core-common — 컬렉션 프로토타입 확장
+# @simplysm/core-common — 배열 확장 메서드
 
-`import "@simplysm/core-common"`(또는 패키지의 다른 심볼 import) 시 부수효과로 `Array`/`Set`/`Map` 프로토타입에 메서드가 주입된다. 별도 함수 호출이 아니라 인스턴스 메서드로 바로 쓴다. 메서드들은 `enumerable: false` 로 정의되어 `for...in` 에 노출되지 않음. 컬렉션을 그룹화·중복제거·정렬·diff 할 때 함께 읽힌다.
+`@simplysm/core-common` import 시 `Array.prototype` 에 설치되는 확장 메서드. 배열을 조회·그룹화·정렬·중복제거·Map/객체/트리 변환·diff/merge·집계할 때 함께 읽힘. 모두 `array.method(...)` 로 직접 호출. enumerable=false 로 설치되어 `for...in`·`Object.keys` 에 노출되지 않음.
 
-## Array — 조회 (ReadonlyArrayExt)
+표기: **읽기 전용**(원본 불변, 새 배열/값 반환) vs **@mutates**(원본 직접 수정). 정렬/중복제거는 두 버전(예: `orderBy` vs `orderByThis`)이 있음.
 
-- `single(predicate?)` — 조건에 맞는 단일 요소. 없으면 `undefined`, 2개 이상이면 `ArgumentError` throw. "있다면 하나뿐" 을 단언할 때.
-- `first(predicate?)` / `last(predicate?)` — 첫/마지막 요소(predicate 생략 시 인덱스 끝). 없으면 `undefined`.
-- `filterExists()` — `null`/`undefined` 제거. 반환 타입 `NonNullable<T>[]`.
-- `ofType(type)` — 특정 타입 요소만. `type` 은 `PrimitiveTypeStr`("string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes") 또는 생성자(`Type<N>`). 문자열은 typeof/instanceof, 생성자는 `instanceof` + `constructor` 일치로 판정.
-- `sum(selector?)` — 합계. 비어 있으면 0. 숫자가 아니면 `ArgumentError`.
-- `min(selector?)` / `max(selector?)` — 최소/최대(문자열·숫자). 비어 있으면 `undefined`. 그 외 타입은 `ArgumentError`.
-- `shuffle()` — Fisher-Yates 셔플한 새 배열.
+## 조회 / 필터
 
-비동기:
-- `filterAsync(predicate)` / `mapAsync(selector)` — 순차 실행(await 보장). 호출 순서가 중요할 때.
-- `parallelAsync(fn)` — `Promise.all` 병렬. 하나라도 reject 면 전체 즉시 reject.
-- `mapMany(selector?)` — 매핑 후 1단계 평탄화 + `filterExists`. selector 생략 시 자기 자신 평탄화.
-- `mapManyAsync(selector?)` — `mapMany` 의 비동기(순차) 버전.
+- `single(predicate?)`: → `T | undefined` — 조건에 맞는 단 하나 반환. **2개 이상이면 ArgumentError throw**. 0개면 undefined. "유일해야 한다"는 불변식 검증에 사용.
+- `first(predicate?)`: → `T | undefined` — 첫 요소(predicate 있으면 첫 매칭). 없으면 undefined.
+- `last(predicate?)`: → `T | undefined` — 마지막 요소(predicate 있으면 뒤에서 첫 매칭).
+- `filterExists()`: → `NonNullable<T>[]` — null/undefined 제거(타입도 좁혀짐).
+- `ofType(type)`: → 좁혀진 배열 — PrimitiveTypeStr(`"string"`·`"number"`·`"boolean"`·`"DateTime"`·`"DateOnly"`·`"Time"`·`"Uuid"`·`"Bytes"`) 또는 생성자(`Type<N>`)로 필터. 문자열이면 typeof/instanceof, 생성자면 `instanceof` 또는 `constructor` 일치. 혼합 배열에서 특정 타입만 뽑을 때.
+- `filterAsync(predicate)`: → `Promise<T[]>` — 비동기 조건 필터(**순차** 실행).
 
-## Array — 그룹화·변환
+## 비동기 매핑
 
-- `groupBy(keySelector, valueSelector?)` — key 별 `{ key, values }[]`. 원시 key 는 O(n)(Map), 객체 key 는 O(n²)(깊은 비교). 객체 key 가 필요 없으면 `toArrayMap` 권장.
-- `toMap(keySelector, valueSelector?)` — `Map<K,V>`. key 중복 시 `ArgumentError`.
-- `toMapAsync(...)` — `toMap` 의 비동기(순차) 버전. selector 가 Promise 반환 가능.
-- `toArrayMap(keySelector, valueSelector?)` — `Map<K, V[]>`. 같은 key 값들을 배열로 누적.
-- `toSetMap(keySelector, valueSelector?)` — `Map<K, Set<V>>`. 값 중복 자동 제거.
-- `toMapValues(keySelector, valueSelector)` — key 별로 모은 `items[]` 를 `valueSelector(items)` 로 집계해 `Map<K,V>`.
-- `toObject(keySelector, valueSelector?)` — `Record<string,V>`. key(문자열) 중복 시 `ArgumentError`(단 기존 값이 null 이면 덮어쓰기 허용).
-- `toTree(keyProp, parentKey)` — 평면 배열 → 트리. `parentKey` 가 null/undefined 인 항목이 루트, 각 노드에 `children` 추가(원본은 clone). 반환 `TreeArray<T>[]`.
+- `mapAsync(selector)`: → `Promise<R[]>` — 비동기 매핑(**순차** 실행, 순서 보존).
+- `parallelAsync(fn)`: → `Promise<R[]>` — `Promise.all` 기반 **병렬** 실행. 하나라도 reject 면 전체 reject. 독립 IO 를 동시에 돌릴 때.
+- `mapMany(selector?)`: → 평탄화 배열 — selector 매핑 후 1단계 flat + `filterExists`. selector 없으면 자신을 flat. 중첩 배열 펼칠 때.
+- `mapManyAsync(selector?)`: → `Promise<...>` — 비동기 매핑 후 평탄화(순차).
 
-## Array — 중복제거·정렬·diff
+## 그룹화 / Map·객체 변환
 
-- `distinct(options?)` — 중복 제거(새 배열). `options`: `boolean`(=`{matchAddress}`) 또는 `{ matchAddress?, keyFn? }`. `matchAddress:true` 면 참조 비교(O(n)), `keyFn` 이면 key 비교(O(n)), 둘 다 없으면 객체는 깊은 비교(O(n²)).
-- `orderBy(selector?)` / `orderByDesc(selector?)` — 오름/내림차순 새 배열. selector 는 string|number|DateTime|DateOnly|Time|undefined 반환. null/undefined 는 오름차순에서 앞.
-- `diffs(target, options?)` — 두 배열 비교 결과 `ArrayDiffsResult<T,P>[]`. `options.keys`(key 비교 속성)·`options.excludes`(비교 제외 속성). 전체 일치 우선, 없으면 key 일치를 UPDATE 로. target 잔여는 INSERT, source 잔여는 DELETE.
-- `oneWayDiffs(orgItems, keyPropNameOrGetValFn, options?)` — source(this) 를 기준으로 원본 대비 변경 분류. `keyPropNameOrGetValFn`: 키 속성명 또는 `(item) => 키값`. key 값이 없거나 원본에 없으면 `create`, 다르면 `update`, 같으면 `same`(옵션 `includeSame:true` 일 때만 포함). `options.excludes`/`options.includes` 로 비교 범위 조정. 반환 `ArrayOneWayDiffResult<T>[]`.
-- `merge(target, options?)` — `diffs` 결과를 적용해 병합한 새 배열. UPDATE 는 `obj.merge` 로 깊은 병합, INSERT 는 추가. `options` 는 `diffs` 와 동일.
+- `groupBy(keySelector, valueSelector?)`: → `{ key, values }[]` — key 별 그룹. 원시 key 는 O(n), 객체 key 는 깊은 비교 O(n²). 객체 key 가 불필요하면 `toArrayMap` 권장.
+- `toMap(keySelector, valueSelector?)`: → `Map<K, V|T>` — key→단일값. **중복 key 면 ArgumentError**. 1:1 인덱싱에 사용.
+- `toMapAsync(keySelector, valueSelector?)`: → `Promise<Map>` — 위의 비동기(순차) 버전(selector 가 Promise 반환 허용).
+- `toArrayMap(keySelector, valueSelector?)`: → `Map<K, (V|T)[]>` — key→값 배열(중복 허용). O(n) 그룹화의 기본 선택지.
+- `toSetMap(keySelector, valueSelector?)`: → `Map<K, Set<V|T>>` — key→Set(중복 자동 제거).
+- `toMapValues(keySelector, valueSelector)`: → `Map<K, V>` — key 별로 모은 **항목 배열 전체**를 valueSelector(items)→집계값으로 변환. 그룹별 합계 등.
+- `toObject(keySelector, valueSelector?)`: → `Record<string, V|T>` — key(string)→값 객체. 중복 key(둘 다 non-null)면 ArgumentError.
 
-## Array — 원본 변경 (MutableArrayExt, @mutates)
+## 트리화
 
-원본 배열을 직접 수정하고 보통 `this` 를 반환(체이닝).
-- `distinctThis(options?)` — 원본에서 중복 제거(역순 splice).
-- `orderByThis(selector?)` / `orderByDescThis(selector?)` — 원본 in-place 정렬.
-- `insert(index, ...items)` — 지정 위치 삽입.
-- `remove(itemOrSelector)` — 값 일치 또는 조건 함수에 맞는 항목 전부 제거(역순 순회).
-- `toggle(item)` — 있으면 제거, 없으면 push.
-- `clear()` — 전부 비움.
+- `toTree(keyProp, parentKey)`: → `TreeArray<T>[]` — 평면 배열을 트리로. `parentKey` 값이 null/undefined 인 항목이 루트, 각 노드에 `children` 추가(항목은 clone 됨). 내부 `toArrayMap` 으로 O(n). `TreeArray<T> = T & { children: TreeArray<T>[] }`.
 
-## Set 확장
+```ts
+items.toTree("id", "parentId");
+// [{ id: 1, name: "root", children: [{ id: 2, ..., children: [] }] }]
+```
+
+## 정렬 / 중복제거
+
+- `orderBy(selector?)` / `orderByDesc(selector?)`: → `T[]` (새 배열) — selector 가 반환한 string/number/boolean/DateTime/DateOnly/Time/undefined 로 정렬. null/undefined 는 오름차순 앞·내림차순 뒤. 날짜타입은 tick 비교, 문자열은 `localeCompare`. selector 없으면 요소 자체.
+- `orderByThis(selector?)` / `orderByDescThis(selector?)`: → `T[]` @mutates — 원본을 in-place 정렬.
+- `distinct(options?)`: → `T[]` (새 배열) — 중복 제거. options: `true`/`{ matchAddress: true }`=참조 비교 O(n), `{ keyFn }`=커스텀 key O(n), 미지정=원시는 값·객체는 깊은 비교 O(n²). 대량 객체 배열엔 `keyFn` 권장.
+- `distinctThis(options?)`: → `T[]` @mutates — 원본에서 중복 제거(첫 등장만 유지).
+
+## diff / merge
+
+- `diffs(target, options?)`: → `ArrayDiffsResult<T,P>[]` — 두 배열 비교. 결과 항목은 `{ source: undefined, target }`(INSERT) / `{ source, target: undefined }`(DELETE) / `{ source, target }`(UPDATE). options: `keys`=동일성 판정 key(없으면 전체 깊은 비교), `excludes`=비교 제외 속성. target 에 중복 key 면 첫 매칭만.
+- `oneWayDiffs(orgItems, keyPropNameOrGetValFn, options?)`: → `ArrayOneWayDiffResult<T>[]` — 현재 배열을 원본(배열 또는 `Map<key, item>`) 대비 분류. 결과 type: `"create"`(key 값 없거나 원본에 없음)·`"update"`(값 다름)·`"same"`(같음, `includeSame: true` 일 때만 포함). keyPropNameOrGetValFn 은 key 속성명 또는 `(item)=>키값` 함수. options.excludes/includes 로 비교 범위 조정. 저장 시 INSERT/UPDATE 판정에 사용.
+- `merge(target, options?)`: → `(T|P|(T&P))[]` (새 배열) — `diffs` 결과로 source 를 기준 삼아 병합. UPDATE 는 `obj.merge` 로 깊은 병합, INSERT 는 추가, DELETE 는 유지(원본 보존). options 는 `diffs` 와 동일.
+
+`ArrayDiffsResult`·`ArrayOneWayDiffResult`·`TreeArray`·`ComparableType`(=`string | number | boolean | DateTime | DateOnly | Time | undefined`) 타입이 함께 export 됨.
+
+## 집계
 
-- `adds(...values)` — 여러 값 일괄 추가, `this` 반환.
-- `toggle(value, addOrDel?)` — `addOrDel` 생략 시 자동 토글(있으면 제거/없으면 추가), `"add"`=강제 추가, `"del"`=강제 제거. 조건부 추가/제거를 한 줄로. `this` 반환.
+- `sum(selector?)`: → number — 합계(빈 배열 0). 숫자 아닌 값이면 ArgumentError.
+- `min(selector?)` / `max(selector?)`: → `string | number | undefined` — 최소/최대. 숫자·문자열만 허용(아니면 ArgumentError). 빈 배열 undefined.
 
-## Map 확장
+## 그 외 @mutates
 
-- `getOrCreate(key, newValueOrFactory)` — key 가 없으면 값을 설정 후 반환, 있으면 기존 값. 두 번째 인자가 함수면 팩토리로 인식해 호출됨 — 함수 자체를 값으로 저장하려면 `() => fn` 처럼 팩토리로 감쌀 것.
-- `update(key, updateFn)` — 현재 값(`v | undefined`)을 받아 새 값을 설정. key 가 없어도 `updateFn(undefined)` 호출됨. 카운터 증가·배열 누적 등에.
+- `insert(index, ...items)`: → this — index 위치에 삽입.
+- `remove(item)` / `remove(selector)`: → this — 일치 항목(또는 조건 매칭) 모두 제거(역순 순회 O(n)).
+- `toggle(item)`: → this — 있으면 제거·없으면 push.
+- `clear()`: → this — 전체 비움.
 
-## 내보낸 타입
+## shuffle
 
-- `ArrayDiffsResult<TOriginal, TOther>` — `{ source: undefined, target }`(INSERT) | `{ source, target: undefined }`(DELETE) | `{ source, target }`(UPDATE).
-- `ArrayOneWayDiffResult<TItem>` — `{ type: "create"|"update"|"same", item, orgItem }` (create 는 `orgItem: undefined`).
-- `TreeArray<TNode>` — `TNode & { children: TreeArray<TNode>[] }`.
-- `ComparableType` — `string | number | boolean | DateTime | DateOnly | Time | undefined`. 정렬/비교 가능 타입.
+- `shuffle()`: → `T[]` (새 배열) — Fisher–Yates 무작위 섞기. 원본 불변.
 
-```typescript
-const orders = items.toArrayMap((it) => it.customerId);          // Map<id, item[]>
-const sorted = items.orderBy((it) => it.createdAt).distinct({ keyFn: (it) => it.id });
-const tree = rows.toTree("id", "parentId");
-const changes = current.oneWayDiffs(original, "id");             // create/update 분류
+```ts
+const grouped = users.toArrayMap((u) => u.teamId);     // Map<teamId, User[]>
+const sorted = items.orderBy((x) => x.createdAt);       // DateTime 기준 오름차순
+const diff = next.oneWayDiffs(prev, "id");              // create/update/same 분류
 ```

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

@@ -0,0 +1,86 @@
+# @simplysm/core-common — 비동기 런타임
+
+디바운스/직렬 실행, 타입 안전 이벤트, 조건 대기, 자동 만료 Map 이 필요할 때 함께 읽히는 묶음. 큐 클래스들은 `EventEmitter` 를 상속해 `"error"` 이벤트를 발행함.
+
+## EventEmitter<TEvents>
+
+`EventTarget` 기반 타입 안전 이벤트 이미터(브라우저·Node 공용). 보통 상속해서 사용. `TEvents` 는 `{ 이벤트명: 데이터타입 }` 맵.
+
+- `on(type, listener)`: → void — 리스너 등록. 같은 (type, listener) 중복 등록은 무시.
+- `off(type, listener)`: → void — 리스너 제거.
+- `emit(type, data)`: → void — 발행. 데이터 타입이 `void` 인 이벤트는 인자 없이 `emit(type)`.
+- `listenerCount(type)`: → number — 해당 이벤트 리스너 수.
+- `dispose()`: → void — 모든 리스너 제거.
+
+```ts
+import { EventEmitter } from "@simplysm/core-common";
+interface MyEvents { data: string; done: void; }
+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 }>` 상속.
+
+- `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.
+
+```ts
+import { DebounceQueue } from "@simplysm/core-common";
+const q = new DebounceQueue(300);
+q.on("error", (err) => console.error(err));
+q.run(() => save(value)); // 300ms 안에 다시 run 하면 이전 건 취소
+```
+
+## SerialQueue
+
+큐에 넣은 작업을 **순차** 실행(앞 작업 완료 후 다음). 에러가 나도 후속 작업은 계속. `EventEmitter<{ error: SdError }>` 상속.
+
+- `new SerialQueue(gap?)` — gap: number(ms, 기본 0). 각 작업 사이 대기 간격.
+- `run(fn)`: → void — `fn: () => void | Promise<void>` 추가 후 처리 시작.
+- `dispose()`: → void — 대기 큐 비움(실행 중 작업은 완료됨)(+ 리스너 제거).
+- fn throw 시 처리: DebounceQueue 와 동일(`"error"` emit 또는 logger.error).
+
+## wait 네임스페이스
+
+- `wait.until(forwarder, milliseconds?, maxCount?)`: → `Promise<void>` — `forwarder()`(boolean | Promise<boolean>) 가 true 될 때까지 대기. 첫 호출에서 true 면 즉시 반환. milliseconds=확인 간격(기본 100). maxCount=최대 시도 횟수(미지정 무제한). 초과 시 **TimeoutError throw**.
+- `wait.time(millisecond)`: → `Promise<void>` — 지정 시간만큼 sleep.
+
+```ts
+import { wait } from "@simplysm/core-common";
+await wait.until(() => isReady, 100, 50); // 100ms 간격 최대 50회, 초과 시 TimeoutError
+await wait.time(500);
+```
+
+## 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 conn = cache.getOrCreate(key, () => createConn());
+} finally {
+  // 앱/모듈 종료 시
+  cache.dispose();
+}
+```