@simplysm/sd-claude 14.0.50 → 14.0.52

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

@@ -0,0 +1,100 @@
+# Common Types
+
+공유 타입 정의. `Buffer` 대신 사용하는 바이너리 타입, ORM과 공유하는 원시 타입, 범용 유틸리티 타입을 제공한다.
+
+```typescript
+import { Bytes, PrimitiveTypeMap, PrimitiveTypeStr, PrimitiveType, DeepPartial, Type } from "@simplysm/core-common";
+```
+
+## Types
+
+### `Bytes`
+
+```typescript
+export type Bytes = Uint8Array;
+```
+
+`Buffer` 대신 사용하는 바이너리 타입 별칭.
+
+### `PrimitiveTypeMap`
+
+```typescript
+export type PrimitiveTypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  DateTime: DateTime;
+  DateOnly: DateOnly;
+  Time: Time;
+  Uuid: Uuid;
+  Bytes: Bytes;
+};
+```
+
+원시 타입 문자열 key → 실제 타입 매핑. `@simplysm/orm-common`과 공유한다.
+
+### `PrimitiveTypeStr`
+
+```typescript
+export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
+```
+
+원시 타입 문자열 key union.
+
+### `PrimitiveType`
+
+```typescript
+export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+// string | number | boolean | DateTime | DateOnly | Time | Uuid | Bytes | undefined
+```
+
+원시 타입 union.
+
+### `DeepPartial<TObject>`
+
+```typescript
+export type DeepPartial<TObject> = Partial<{
+  [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
+}>;
+```
+
+객체의 모든 속성을 재귀적으로 optional로 변환한다. 원시 타입(`PrimitiveType`)은 그대로 유지하고, object/array 타입에만 재귀적으로 `Partial`을 적용한다.
+
+### `Type<TInstance>`
+
+```typescript
+export interface Type<TInstance> extends Function {
+  new (...args: unknown[]): TInstance;
+}
+```
+
+생성자 타입. 의존성 주입, 팩토리 패턴, instanceof 체크 등에 활용한다.
+
+## Usage
+
+```typescript
+import { Bytes, PrimitiveTypeStr, DeepPartial, Type } from "@simplysm/core-common";
+
+// Bytes
+const data: Bytes = new Uint8Array([1, 2, 3]);
+
+// PrimitiveTypeStr
+const typeStr: PrimitiveTypeStr = "DateTime";
+
+// DeepPartial
+interface Config {
+  server: { host: string; port: number };
+  db: { name: string; user: string };
+}
+const partial: DeepPartial<Config> = {
+  server: { host: "localhost" },  // port 생략 가능
+};
+
+// Type<T>
+function create<T>(ctor: Type<T>): T {
+  return new ctor();
+}
+class MyService {}
+const svc = create(MyService);
+```

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

@@ -0,0 +1,42 @@
+# env / parseBoolEnv
+
+환경변수 접근 유틸리티 함수. `process.env`/`import.meta.env` 직접 접근 대신 이 함수를 사용해야 한다.
+
+```typescript
+export function env(key: string): string | undefined;
+export function env(key: string, value: string): void;
+
+export function parseBoolEnv(value: unknown): boolean;
+```
+
+직접 named import로 사용한다:
+
+```typescript
+import { env, parseBoolEnv } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `env` | `(key: string) => string \| undefined` | 환경변수 값 읽기. `process.env` 우선, fallback `import.meta.env` |
+| `env` | `(key: string, value: string) => void` | 환경변수 값 쓰기 (`process.env`에 저장) |
+| `parseBoolEnv` | `(value: unknown) => boolean` | 환경변수 값을 boolean으로 파싱. `"true"`, `"1"`, `"yes"`, `"on"` (대소문자 무시) → `true`, 그 외 → `false` |
+
+## Usage
+
+```typescript
+import { env, parseBoolEnv } from "@simplysm/core-common";
+
+// 읽기
+const apiUrl = env("API_URL"); // string | undefined
+
+// 쓰기
+env("DEBUG", "true");
+
+// boolean 파싱
+parseBoolEnv(env("DEBUG")); // true
+parseBoolEnv("yes");        // true
+parseBoolEnv("false");      // false
+parseBoolEnv("0");          // false
+```

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

@@ -0,0 +1,86 @@
+# DateOnly
+
+불변 날짜 클래스 (시간 제외: `yyyy-MM-dd`). 시간 정보 없이 날짜만 저장하며 로컬 타임존 기준으로 동작한다. 주차 계산을 지원한다. 수정 메서드는 모두 새 인스턴스를 반환한다.
+
+```typescript
+export class DateOnly {
+  readonly date: Date;
+
+  constructor();
+  constructor(year: number, month: number, day: number);
+  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;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `date` | property | `Date` | 내부 Date 객체 (시간 부분은 항상 00:00:00) |
+| `year` | getter | `number` | 연도 |
+| `month` | getter | `number` | 월 (1-12) |
+| `day` | getter | `number` | 일 (1-31) |
+| `tick` | getter | `number` | Unix 타임스탬프 (밀리초) |
+| `dayOfWeek` | getter | `number` | 요일 (일요일=0 ~ 토요일=6) |
+| `isValid` | getter | `boolean` | 날짜가 올바르게 설정되었는지 여부 |
+| `parse` | static | `(str: string) => DateOnly` | 문자열을 파싱하여 DateOnly 생성 |
+| `getDateByYearWeekSeq` | static | `(arg, weekStartDay?, minDaysInFirstWeek?) => DateOnly` | 연도·(월)·주차로 해당 주의 시작 날짜 반환 |
+| `setYear` | method | `(year: number) => DateOnly` | 지정된 연도로 새 인스턴스 반환 |
+| `setMonth` | method | `(month: number) => DateOnly` | 지정된 월로 새 인스턴스 반환. 현재 일이 대상 월의 일수보다 크면 마지막 일로 조정됨 |
+| `setDay` | method | `(day: number) => DateOnly` | 지정된 일로 새 인스턴스 반환 |
+| `addYears` | method | `(years: number) => DateOnly` | 지정된 연수를 더한 새 인스턴스 반환 |
+| `addMonths` | method | `(months: number) => DateOnly` | 지정된 월수를 더한 새 인스턴스 반환 |
+| `addDays` | method | `(days: number) => DateOnly` | 지정된 일수를 더한 새 인스턴스 반환 |
+| `getBaseYearMonthSeqForWeekSeq` | method | `(weekStartDay?, minDaysInFirstWeek?) => { year: number; monthSeq: number }` | 이 날짜가 포함된 주의 기준 연도와 월 반환 |
+| `getWeekSeqStartDate` | method | `(weekStartDay?, minDaysInFirstWeek?) => DateOnly` | 이 날짜가 포함된 주의 시작 날짜 반환 |
+| `getWeekSeqOfYear` | method | `(weekStartDay?, minDaysInFirstWeek?) => { year: number; weekSeq: number }` | 연도와 주차 번호 반환 |
+| `getWeekSeqOfMonth` | method | `(weekStartDay?, minDaysInFirstWeek?) => { year: number; monthSeq: number; weekSeq: number }` | 연도, 월, 해당 월 내의 주차 번호 반환 |
+| `toFormatString` | method | `(formatStr: string) => string` | 지정된 형식 문자열로 변환 (형식 토큰은 [`DateTime`](./date-time.md) 참조) |
+| `toString` | method | `() => string` | `"yyyy-MM-dd"` 형식 문자열 반환 |
+
+## `parse` — 지원 형식
+
+| 형식 | 예시 | 타임존 |
+|------|------|--------|
+| `yyyy-MM-dd` | `"2025-01-15"` | 타임존 무관 (직접 추출) |
+| `yyyyMMdd` | `"20250115"` | 타임존 무관 (직접 추출) |
+| ISO 8601 | `"2025-01-15T00:00:00Z"` | UTC로 해석 후 로컬 타임존 변환 |
+
+서버/클라이언트 타임존이 다른 경우 `yyyy-MM-dd` 형식 권장.
+
+## 주차 계산 파라미터
+
+| 파라미터 | 기본값 | 설명 |
+|----------|--------|------|
+| `weekStartDay` | `1` (월요일) | 주 시작 요일 (0=일요일, 1=월요일, ..., 6=토요일) |
+| `minDaysInFirstWeek` | `4` | 첫 번째 주로 간주되기 위한 최소 일수 (ISO 8601 표준) |
+
+## Usage
+
+```typescript
+import { DateOnly } from "@simplysm/core-common";
+
+const today = new DateOnly();
+const specific = new DateOnly(2025, 1, 15);
+const parsed = DateOnly.parse("2025-01-15");
+
+// 불변 수정
+const nextWeek = today.addDays(7);
+const firstDayOfMonth = today.setDay(1);
+
+// 주차 계산 (ISO 8601 기본값: 월요일 시작, 첫 주 최소 4일)
+const { year, weekSeq } = new DateOnly(2025, 1, 6).getWeekSeqOfYear();
+// { year: 2025, weekSeq: 2 }
+
+// 주차로 날짜 계산
+const weekStart = DateOnly.getDateByYearWeekSeq({ year: 2025, weekSeq: 2 });
+// 2025-01-06 (월요일)
+```

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

@@ -0,0 +1,106 @@
+# DateTime
+
+불변 날짜시간 클래스 (밀리초 정밀도, 로컬 타임존). JavaScript `Date` 객체를 래핑하여 불변성과 편리한 API를 제공한다. 수정 메서드는 모두 새 인스턴스를 반환한다.
+
+```typescript
+export class DateTime {
+  readonly date: Date;
+
+  constructor();
+  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): DateTime;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `date` | property | `Date` | 내부 Date 객체 |
+| `year` | getter | `number` | 연도 |
+| `month` | getter | `number` | 월 (1-12) |
+| `day` | getter | `number` | 일 (1-31) |
+| `hour` | getter | `number` | 시 (0-23) |
+| `minute` | getter | `number` | 분 (0-59) |
+| `second` | getter | `number` | 초 (0-59) |
+| `millisecond` | getter | `number` | 밀리초 (0-999) |
+| `tick` | getter | `number` | Unix 타임스탬프 (밀리초) |
+| `dayOfWeek` | getter | `number` | 요일 (일요일=0 ~ 토요일=6) |
+| `timezoneOffsetMinutes` | getter | `number` | 타임존 오프셋 (분) |
+| `isValid` | getter | `boolean` | 날짜시간이 올바르게 설정되었는지 여부 |
+| `parse` | static | `(str: string) => DateTime` | 문자열을 파싱하여 DateTime 생성 |
+| `setYear` | method | `(year: number) => DateTime` | 지정된 연도로 새 인스턴스 반환 |
+| `setMonth` | method | `(month: number) => DateTime` | 지정된 월로 새 인스턴스 반환. 현재 일이 대상 월의 일수보다 크면 마지막 일로 조정됨 |
+| `setDay` | method | `(day: number) => DateTime` | 지정된 일로 새 인스턴스 반환 |
+| `setHour` | method | `(hour: number) => DateTime` | 지정된 시로 새 인스턴스 반환 |
+| `setMinute` | method | `(minute: number) => DateTime` | 지정된 분으로 새 인스턴스 반환 |
+| `setSecond` | method | `(second: number) => DateTime` | 지정된 초로 새 인스턴스 반환 |
+| `setMillisecond` | method | `(millisecond: number) => DateTime` | 지정된 밀리초로 새 인스턴스 반환 |
+| `addYears` | method | `(years: number) => DateTime` | 지정된 연수를 더한 새 인스턴스 반환 |
+| `addMonths` | method | `(months: number) => DateTime` | 지정된 월수를 더한 새 인스턴스 반환 |
+| `addDays` | method | `(days: number) => DateTime` | 지정된 일수를 더한 새 인스턴스 반환 |
+| `addHours` | method | `(hours: number) => DateTime` | 지정된 시간을 더한 새 인스턴스 반환 |
+| `addMinutes` | method | `(minutes: number) => DateTime` | 지정된 분을 더한 새 인스턴스 반환 |
+| `addSeconds` | method | `(seconds: number) => DateTime` | 지정된 초를 더한 새 인스턴스 반환 |
+| `addMilliseconds` | method | `(milliseconds: number) => DateTime` | 지정된 밀리초를 더한 새 인스턴스 반환 |
+| `toFormatString` | method | `(formatStr: string) => string` | 지정된 형식 문자열로 변환 |
+| `toString` | method | `() => string` | ISO 형식 문자열 반환 (`yyyy-MM-ddTHH:mm:ss.fffzzz`) |
+
+## `parse` — 지원 형식
+
+| 형식 | 예시 |
+|------|------|
+| `yyyy-MM-dd HH:mm:ss` | `"2025-01-15 10:30:00"` |
+| `yyyy-MM-dd HH:mm:ss.fff` | `"2025-01-15 10:30:00.123"` |
+| `yyyyMMddHHmmss` | `"20250115103000"` |
+| `yyyy-MM-dd AM/PM HH:mm:ss` | `"2025-01-15 AM 10:30:00"` |
+| `yyyy-MM-dd 오전/오후 HH:mm:ss` | `"2025-01-15 오전 10:30:00"` |
+| ISO 8601 | `"2025-01-15T10:30:00Z"` |
+
+## `toFormatString` — 형식 문자열 토큰
+
+| 토큰 | 설명 | 예시 |
+|------|------|------|
+| `yyyy` | 4자리 연도 | `2025` |
+| `yy` | 2자리 연도 | `25` |
+| `MM` | 0 채움 월 | `01`~`12` |
+| `M` | 월 | `1`~`12` |
+| `ddd` | 요일 | `일`, `월`, `화`, `수`, `목`, `금`, `토` |
+| `dd` | 0 채움 일 | `01`~`31` |
+| `d` | 일 | `1`~`31` |
+| `tt` | 오전/오후 | `AM`, `PM` |
+| `HH` | 0 채움 24시간 | `00`~`23` |
+| `H` | 24시간 | `0`~`23` |
+| `hh` | 0 채움 12시간 | `01`~`12` |
+| `h` | 12시간 | `1`~`12` |
+| `mm` | 0 채움 분 | `00`~`59` |
+| `m` | 분 | `0`~`59` |
+| `ss` | 0 채움 초 | `00`~`59` |
+| `s` | 초 | `0`~`59` |
+| `fff` | 밀리초 (3자리) | `000`~`999` |
+| `ff` | 밀리초 (2자리) | `00`~`99` |
+| `f` | 밀리초 (1자리) | `0`~`9` |
+| `zzz` | 타임존 오프셋 (`±HH:mm`) | `+09:00` |
+| `zz` | 타임존 오프셋 (`±HH`) | `+09` |
+| `z` | 타임존 오프셋 (`±H`) | `+9` |
+
+## Usage
+
+```typescript
+import { DateTime } from "@simplysm/core-common";
+
+const now = new DateTime();
+const specific = new DateTime(2025, 1, 15, 10, 30, 0);
+const fromTick = new DateTime(Date.now());
+const parsed = DateTime.parse("2025-01-15 10:30:00");
+
+const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
+const iso = now.toString(); // "2025-01-15T10:30:00.000+09:00"
+
+// 불변 수정
+const nextMonth = now.addMonths(1);
+const endOfYear = now.setMonth(12).setDay(31);
+```

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

@@ -0,0 +1,59 @@
+# LazyGcMap
+
+자동 만료 기능이 있는 Map. LRU 방식으로 접근 시간을 갱신하고, 지정된 시간 동안 접근하지 않으면 자동 삭제한다. 사용 후 반드시 `dispose()`를 호출해야 GC 타이머가 정리된다.
+
+```typescript
+export class LazyGcMap<TKey, TValue> {
+  constructor(options: {
+    gcInterval?: number;
+    expireTime: number;
+    onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
+  });
+}
+```
+
+## Constructor Options
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `expireTime` | `number` | 필수 | 만료 시간 (밀리초). 마지막 접근 이후 이 시간이 지나면 삭제됨 |
+| `gcInterval` | `number` | 선택 | GC 간격 (밀리초). 생략 시 `expireTime / 10` (최소 1000ms) |
+| `onExpire` | `(key: TKey, value: TValue) => void \| Promise<void>` | 선택 | 만료 시 호출되는 콜백. 에러 발생 시 로그 출력 후 계속 실행 |
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `size` | getter | `number` | 저장된 항목 수 |
+| `has` | method | `(key: TKey) => boolean` | key 존재 여부 확인 (접근 시간 갱신하지 않음) |
+| `get` | method | `(key: TKey) => TValue \| undefined` | 값 조회 (접근 시간 갱신) |
+| `set` | method | `(key: TKey, value: TValue) => void` | 값 저장 (접근 시간 설정 및 GC 타이머 시작) |
+| `delete` | method | `(key: TKey) => boolean` | 항목 삭제 |
+| `getOrCreate` | method | `(key: TKey, factory: () => TValue) => TValue` | key가 없으면 팩토리로 생성하여 저장 후 반환 |
+| `clear` | method | `() => void` | 모든 항목 삭제 (인스턴스는 계속 사용 가능) |
+| `dispose` | method | `() => void` | 인스턴스 정리 (GC 타이머 중지 및 데이터 삭제). 이후 모든 작업 무시됨 |
+| `values` | method | `() => IterableIterator<TValue>` | 값 순회 |
+| `keys` | method | `() => IterableIterator<TKey>` | key 순회 |
+| `entries` | method | `() => IterableIterator<[TKey, TValue]>` | 엔트리 순회 |
+
+## Usage
+
+```typescript
+import { LazyGcMap } from "@simplysm/core-common";
+
+const cache = new LazyGcMap<string, Data>({
+  expireTime: 60_000,       // 60초 미접근 시 삭제
+  gcInterval: 10_000,       // 10초마다 GC 실행 (생략 시 6000ms)
+  onExpire: async (key, value) => {
+    await value.cleanup();  // 정리 작업
+  },
+});
+
+try {
+  cache.set("key", data);
+  const val = cache.get("key"); // 접근 시간 갱신
+  const created = cache.getOrCreate("other", () => createData());
+} finally {
+  cache.dispose(); // 반드시 호출
+}
+```

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

@@ -0,0 +1,62 @@
+# Time
+
+불변 시간 클래스 (날짜 제외: `HH:mm:ss.fff`). 날짜 정보 없이 시간만 저장하며 24시간을 초과하거나 음수인 값은 자동으로 정규화된다. 수정 및 산술 메서드는 새 인스턴스를 반환하며 모두 24시간 순환한다.
+
+```typescript
+export class Time {
+  constructor();
+  constructor(hour: number, minute: number, second?: number, millisecond?: number);
+  constructor(tick: number);
+  constructor(date: Date);
+
+  static parse(str: string): Time;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `hour` | getter | `number` | 시 (0-23) |
+| `minute` | getter | `number` | 분 (0-59) |
+| `second` | getter | `number` | 초 (0-59) |
+| `millisecond` | getter | `number` | 밀리초 (0-999) |
+| `tick` | getter | `number` | 자정(00:00:00.000) 기준 밀리초 |
+| `isValid` | getter | `boolean` | 시간이 올바르게 설정되었는지 여부 |
+| `parse` | static | `(str: string) => Time` | 문자열을 파싱하여 Time 생성 |
+| `setHour` | method | `(hour: number) => Time` | 지정된 시로 새 인스턴스 반환 |
+| `setMinute` | method | `(minute: number) => Time` | 지정된 분으로 새 인스턴스 반환 |
+| `setSecond` | method | `(second: number) => Time` | 지정된 초로 새 인스턴스 반환 |
+| `setMillisecond` | method | `(millisecond: number) => Time` | 지정된 밀리초로 새 인스턴스 반환 |
+| `addHours` | method | `(hours: number) => Time` | 지정된 시간을 더한 새 인스턴스 반환 (24시간 순환) |
+| `addMinutes` | method | `(minutes: number) => Time` | 지정된 분을 더한 새 인스턴스 반환 (24시간 순환) |
+| `addSeconds` | method | `(seconds: number) => Time` | 지정된 초를 더한 새 인스턴스 반환 (24시간 순환) |
+| `addMilliseconds` | method | `(milliseconds: number) => Time` | 지정된 밀리초를 더한 새 인스턴스 반환 (24시간 순환) |
+| `toFormatString` | method | `(formatStr: string) => string` | 지정된 형식 문자열로 변환 (형식 토큰은 [`DateTime`](./date-time.md) 참조, 날짜 관련 토큰 제외) |
+| `toString` | method | `() => string` | `"HH:mm:ss.fff"` 형식 문자열 반환 |
+
+## `parse` — 지원 형식
+
+| 형식 | 예시 |
+|------|------|
+| `HH:mm:ss` | `"10:30:00"` |
+| `HH:mm:ss.fff` | `"10:30:00.123"` |
+| `AM/PM HH:mm:ss` | `"AM 10:30:00"`, `"PM 02:15:00"` |
+| ISO 8601 | `"2025-01-15T10:30:00Z"` (시간 부분만 추출, 타임존 변환 적용) |
+
+## Usage
+
+```typescript
+import { Time } from "@simplysm/core-common";
+
+const now = new Time();
+const specific = new Time(10, 30, 0);
+const parsed = Time.parse("10:30:00");
+
+// 불변 수정
+const later = specific.addHours(2).addMinutes(30);
+// 24시간 순환
+const midnight = new Time(23, 0, 0).addHours(2); // 01:00:00
+
+const formatted = specific.toFormatString("HH:mm:ss");
+```

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

@@ -0,0 +1,41 @@
+# Uuid
+
+UUID v4 클래스. `crypto.getRandomValues` 기반으로 암호학적으로 안전한 UUID를 생성한다 (Chrome 37+, Node.js 호환).
+
+```typescript
+export class Uuid {
+  constructor(uuid: string);
+
+  static generate(): Uuid;
+  static fromBytes(bytes: Bytes): Uuid;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `generate` | static | `() => Uuid` | 새 UUID v4 인스턴스 생성 |
+| `fromBytes` | static | `(bytes: Bytes) => Uuid` | 16바이트 `Uint8Array`로 UUID 생성. 바이트 크기가 16이 아니면 `ArgumentError` 발생 |
+| `toString` | method | `() => string` | UUID 문자열 반환 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) |
+| `toBytes` | method | `() => Bytes` | UUID를 16바이트 `Uint8Array`로 변환 |
+
+## Related Types
+
+### `Bytes`
+
+`Uint8Array` 별칭. [`Bytes`](../type-utils/common-types.md) 참조.
+
+## Usage
+
+```typescript
+import { Uuid } from "@simplysm/core-common";
+
+const id = Uuid.generate();
+const fromStr = new Uuid("550e8400-e29b-41d4-a716-446655440000");
+
+console.log(id.toString()); // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+
+const bytes = id.toBytes(); // Uint8Array(16)
+const restored = Uuid.fromBytes(bytes);
+```

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

@@ -0,0 +1,36 @@
+# bytes
+
+`Uint8Array` 유틸리티 네임스페이스. 복잡한 변환 연산을 제공한다.
+
+```typescript
+import { bytes } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `concat` | `(arrays: Bytes[]) => Bytes` | 여러 `Uint8Array` 결합 |
+| `toHex` | `(bytes: Bytes) => string` | `Uint8Array`를 소문자 hex 문자열로 변환 |
+| `fromHex` | `(hex: string) => Bytes` | hex 문자열을 `Uint8Array`로 변환. 홀수 길이이거나 유효하지 않은 문자가 있으면 `ArgumentError` |
+| `toBase64` | `(bytes: Bytes) => string` | `Uint8Array`를 Base64 문자열로 변환 |
+| `fromBase64` | `(base64: string) => Bytes` | Base64 문자열을 `Uint8Array`로 변환. 유효하지 않은 문자/길이이면 `ArgumentError` |
+
+## Usage
+
+```typescript
+import { bytes } from "@simplysm/core-common";
+
+// concat
+const a = new Uint8Array([1, 2]);
+const b = new Uint8Array([3, 4]);
+bytes.concat([a, b]); // Uint8Array([1, 2, 3, 4])
+
+// hex 변환
+bytes.toHex(new Uint8Array([255, 0, 127])); // "ff007f"
+bytes.fromHex("ff007f"); // Uint8Array([255, 0, 127])
+
+// base64 변환
+bytes.toBase64(new Uint8Array([72, 101, 108, 108, 111])); // "SGVsbG8="
+bytes.fromBase64("SGVsbG8="); // Uint8Array([72, 101, 108, 108, 111])
+```

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

@@ -0,0 +1,60 @@
+# dt
+
+날짜 포맷 유틸리티 네임스페이스. `DateTime`, `DateOnly`, `Time` 클래스 내부에서 사용되는 저수준 포맷/변환 함수를 제공한다.
+
+```typescript
+import { dt } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `format` | `(formatString, args) => string` | 형식 문자열에 따라 날짜/시간을 문자열로 변환 |
+| `normalizeMonth` | `(year, month, day) => DtNormalizedMonth` | 월 설정 시 연/월/일 정규화 (범위 벗어난 월 처리, 마지막 일 초과 처리) |
+| `convert12To24` | `(rawHour, isPM) => number` | 12시간 형식을 24시간 형식으로 변환 |
+
+## `format` — args
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `year` | `number` | 연도 |
+| `month` | `number` | 월 |
+| `day` | `number` | 일 |
+| `hour` | `number` | 시 |
+| `minute` | `number` | 분 |
+| `second` | `number` | 초 |
+| `millisecond` | `number` | 밀리초 |
+| `timezoneOffsetMinutes` | `number` | 타임존 오프셋 (분) |
+
+형식 문자열 토큰은 [`DateTime.toFormatString`](../types/date-time.md)과 동일하다.
+
+## Related Types
+
+### `DtNormalizedMonth`
+
+`normalizeMonth()` 결과 타입:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `year` | `number` | 정규화된 연도 |
+| `month` | `number` | 정규화된 월 (1-12) |
+| `day` | `number` | 정규화된 일 |
+
+## Usage
+
+```typescript
+import { dt } from "@simplysm/core-common";
+
+// 포맷
+dt.format("yyyy-MM-dd", { year: 2025, month: 1, day: 15 }); // "2025-01-15"
+
+// 월 정규화
+dt.normalizeMonth(2025, 13, 15);  // { year: 2026, month: 1, day: 15 }
+dt.normalizeMonth(2025, 2, 31);   // { year: 2025, month: 2, day: 28 }
+
+// 12시간 → 24시간
+dt.convert12To24(12, false); // 0  (12:00 AM = 0:00)
+dt.convert12To24(12, true);  // 12 (12:00 PM = 12:00)
+dt.convert12To24(3, true);   // 15 (3:00 PM = 15:00)
+```

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

@@ -0,0 +1,26 @@
+# err
+
+에러 메시지 추출 유틸리티 네임스페이스.
+
+```typescript
+import { err } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `message` | `(err: unknown) => string` | `catch` 블록의 `unknown` 에러에서 메시지 추출. `Error` 인스턴스이면 `message` 속성 반환, 그렇지 않으면 `String()` 변환 결과 반환 |
+
+## Usage
+
+```typescript
+import { err } from "@simplysm/core-common";
+
+try {
+  await doSomething();
+} catch (e) {
+  const msg = err.message(e); // string
+  console.log(msg);
+}
+```

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

@@ -0,0 +1,58 @@
+# json
+
+JSON 변환 유틸리티 네임스페이스. `DateTime`, `DateOnly`, `Time`, `Uuid`, `Set`, `Map`, `Error`, `Uint8Array` 등 커스텀 타입을 지원하는 직렬화/역직렬화를 제공한다.
+
+```typescript
+import { json } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `stringify` | `(obj, options?) => string` | 객체를 JSON 문자열로 직렬화 |
+| `parse` | `<TResult = unknown>(json: string) => TResult` | JSON 문자열을 객체로 역직렬화. null 값은 undefined로 변환 |
+
+## `stringify` — options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `space` | `string \| number` | JSON 들여쓰기 |
+| `replacer` | `(key, value) => unknown` | 커스텀 replacer. 기본 타입 변환 전에 호출됨 |
+| `redactBytes` | `boolean` | `true`이면 `Uint8Array` 내용을 `"__hidden__"`으로 대체 (로깅용). 이 옵션으로 직렬화된 결과는 `parse()`로 복원 불가 |
+
+## 지원 타입
+
+| 타입 | 직렬화 형식 |
+|------|-------------|
+| `DateTime` | `{ __type__: "DateTime", data: "yyyy-MM-ddTHH:mm:ss.fffzzz" }` |
+| `DateOnly` | `{ __type__: "DateOnly", data: "yyyy-MM-dd" }` |
+| `Time` | `{ __type__: "Time", data: "HH:mm:ss.fff" }` |
+| `Uuid` | `{ __type__: "Uuid", data: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }` |
+| `Date` | `{ __type__: "Date", data: ISO8601 }` |
+| `Set` | `{ __type__: "Set", data: [...] }` |
+| `Map` | `{ __type__: "Map", data: [[k, v], ...] }` |
+| `Error` | `{ __type__: "Error", data: { name, message, stack, ... } }` |
+| `Uint8Array` | `{ __type__: "Uint8Array", data: "hex문자열" }` |
+
+`parse()`는 JSON null 값을 undefined로 변환한다. 이는 simplysm 프레임워크의 null-free 규칙을 위한 의도적인 동작이다.
+
+## Usage
+
+```typescript
+import { json, DateTime, Uuid } from "@simplysm/core-common";
+
+// 커스텀 타입 지원 직렬화
+const serialized = json.stringify({
+  date: new DateTime(),
+  id: Uuid.generate(),
+  data: new Uint8Array([1, 2, 3]),
+});
+
+// 커스텀 타입 복원
+const restored = json.parse<{ date: DateTime; id: Uuid }>(serialized);
+// restored.date는 DateTime 인스턴스
+
+// 로깅용 (바이너리 숨김)
+const logStr = json.stringify({ data: sensitiveBytes }, { redactBytes: true });
+```