@simplysm/core-common 14.0.48 → 14.0.50

package/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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 });
+```

package/docs/utils/num.md

@@ -0,0 +1,56 @@
+# num
+
+숫자 유틸리티 네임스페이스.
+
+```typescript
+import { num } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `parseInt` | `(text: unknown) => number \| undefined` | 문자열을 정수로 파싱. 비숫자 문자 제거 후 파싱. 소수점 이하 버림 |
+| `parseFloat` | `(text: unknown) => number \| undefined` | 문자열을 float로 파싱. 비숫자 문자 제거 후 파싱 |
+| `parseRoundedInt` | `(text: unknown) => number \| undefined` | 문자열을 float로 파싱한 후 반올림하여 정수 반환 |
+| `isNullOrEmpty` | `(val: number \| undefined) => val is 0 \| undefined` | 타입 가드: undefined, null, 0이면 true |
+| `format` | `(val: number, digit?) => string` | 천 단위 구분자 포함 문자열로 포맷 |
+| `format` | `(val: number \| undefined, digit?) => string \| undefined` | undefined이면 undefined 반환 |
+
+## `parseInt` / `parseFloat` 동작
+
+- 숫자, `-`, `.` 이외의 문자 제거 후 파싱
+- 선행 `-`만 음수 부호로 유지 (중간 `-`는 제거)
+- 파싱 실패 시 `undefined` 반환
+
+## `format` — `digit` 옵션
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `max` | `number` | 최대 소수점 자릿수 |
+| `min` | `number` | 최소 소수점 자릿수 (부족하면 0으로 채움) |
+
+## Usage
+
+```typescript
+import { num } from "@simplysm/core-common";
+
+num.parseInt("1,234.56");   // 1234
+num.parseInt("-123");       // -123
+num.parseInt("010-1234-5678"); // 1012345678 (중간 - 제거)
+num.parseInt("abc");        // undefined
+
+num.parseFloat("1,234.56"); // 1234.56
+num.parseRoundedInt("1.7"); // 2
+
+// null/zero 검사 (타입 가드)
+const count: number | undefined = getValue();
+if (num.isNullOrEmpty(count)) {
+  // count: 0 | undefined
+} else {
+  // count: number (non-zero)
+}
+
+num.format(1234567.89, { max: 2 }); // "1,234,567.89"
+num.format(1234, { min: 2 });       // "1,234.00"
+```

package/docs/utils/obj.md

@@ -0,0 +1,107 @@
+# obj
+
+객체 유틸리티 네임스페이스. 깊은 복사, 비교, 병합, key 조작 등을 제공한다.
+
+```typescript
+import { obj } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `clone` | `<T>(source: T) => T` | 깊은 복사. 순환 참조, 커스텀 타입(`DateTime`, `DateOnly`, `Time`, `Uuid`, `Uint8Array`) 지원 |
+| `equal` | `(source, target, options?) => boolean` | 깊은 동등성 비교 |
+| `merge` | `<S, T>(source: S, target: T, opt?) => S & T` | 깊은 병합. source를 기반으로 target을 병합하여 새 객체 반환 |
+| `merge3` | `(source, origin, target, optionsObj?) => { conflict, result }` | 3-way 병합 |
+| `omit` | `<T, K>(item: T, omitKeys: K[]) => Omit<T, K>` | 특정 key 제외 |
+| `omitByFilter` | `<T>(item: T, omitKeyFn) => T` | 조건에 맞는 key 제외 |
+| `pick` | `<T, K>(item: T, pickKeys: K[]) => Pick<T, K>` | 특정 key만 선택 |
+| `getChainValue` | `(obj, chain, optional?) => unknown` | 체인 경로로 값 조회 (예: `"a.b[0].c"`) |
+| `getChainValueByDepth` | `(obj, key, depth, optional?) => TObject[TKey]` | 같은 key로 지정된 깊이만큼 하강 |
+| `setChainValue` | `(obj, chain, value) => void` | 체인 경로로 값 설정 |
+| `deleteChainValue` | `(obj, chain) => void` | 체인 경로로 값 삭제 |
+| `clearUndefined` | `<T>(obj: T) => T` | 객체에서 undefined/null 값을 가진 key 삭제 (원본 수정) |
+| `clear` | `<T>(obj: T) => Record<string, never>` | 객체의 모든 key 삭제 (원본 수정) |
+| `nullToUndefined` | `<T>(obj: T) => T \| undefined` | null을 undefined로 변환 (재귀, 원본 수정) |
+| `unflatten` | `(flatObj) => Record<string, unknown>` | 평탄화된 객체를 중첩 객체로 변환 (`"a.b.c": 1` → `{ a: { b: { c: 1 } } }`) |
+| `keys` | `<T>(obj: T) => (keyof T)[]` | 타입 안전한 `Object.keys` |
+| `entries` | `<T>(obj: T) => Entries<T>` | 타입 안전한 `Object.entries` |
+| `fromEntries` | `<T>(entryPairs: T[]) => { [K in T[0]]: T[1] }` | 타입 안전한 `Object.fromEntries` |
+| `map` | `(obj, fn) => Record<string, TNewValue>` | 각 엔트리를 변환하여 새 객체 반환 |
+
+## Related Types
+
+### `EqualOptions`
+
+`equal()` 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `topLevelIncludes` | `string[]` | 비교할 key 목록 (최상위 레벨에만 적용) |
+| `topLevelExcludes` | `string[]` | 비교에서 제외할 key 목록 (최상위 레벨에만 적용) |
+| `ignoreArrayIndex` | `boolean` | 배열 순서를 무시할지 여부. `true`면 O(n²) 복잡도 |
+| `shallow` | `boolean` | 얕은 비교 여부. `true`면 1단계만 비교 (참조 비교) |
+
+### `MergeOptions`
+
+`merge()` 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `arrayProcess` | `"replace" \| "concat"` | 배열 처리 방식. `"replace"`: target으로 교체 (기본값), `"concat"`: 병합 (중복 제거) |
+| `useDelTargetNull` | `boolean` | target이 null일 때 해당 key를 삭제할지 여부 |
+
+### `Merge3KeyOptions`
+
+`merge3()` key별 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `keys` | `string[]` | 비교할 하위 key 목록 |
+| `excludes` | `string[]` | 비교에서 제외할 하위 key 목록 |
+| `ignoreArrayIndex` | `boolean` | 배열 순서를 무시할지 여부 |
+
+### `UndefToOptional<T>`
+
+`undefined` 타입을 가진 속성을 optional로 변환:
+
+```typescript
+// { a: string; b: string | undefined } → { a: string; b?: string | undefined }
+export type UndefToOptional<TObject> = ...
+```
+
+### `OptionalToUndef<T>`
+
+optional 속성을 필수 + `undefined` 유니온으로 변환:
+
+```typescript
+// { a: string; b?: string } → { a: string; b: string | undefined }
+export type OptionalToUndef<TObject> = ...
+```
+
+## Usage
+
+```typescript
+import { obj } from "@simplysm/core-common";
+
+// 깊은 복사
+const copied = obj.clone({ nested: { data: [1, 2, 3] } });
+
+// 깊은 비교
+const isEqual = obj.equal(a, b, { topLevelExcludes: ["updatedAt"] });
+
+// 깊은 병합
+const merged = obj.merge(defaults, overrides);
+
+// omit / pick
+const noId = obj.omit(user, ["id"]);
+const onlyName = obj.pick(user, ["name", "email"]);
+
+// 체인 경로
+const val = obj.getChainValue(data, "user.address[0].city");
+obj.setChainValue(data, "user.name", "Alice");
+
+// 객체 변환
+const mapped = obj.map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
+```

package/docs/utils/path.md

@@ -0,0 +1,30 @@
+# path
+
+경로 유틸리티 네임스페이스. Node.js `path` 모듈 대체 (브라우저 환경 지원). POSIX 스타일 경로(슬래시 `/`)만 지원한다. Windows 백슬래시(`\`)는 지원하지 않는다.
+
+```typescript
+import { path } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `join` | `(...segments: string[]) => string` | 경로 결합 (`path.join` 대체) |
+| `basename` | `(filePath: string, ext?: string) => string` | 파일명 추출 (`path.basename` 대체). ext 지정 시 해당 확장자 제거 |
+| `extname` | `(filePath: string) => string` | 파일 확장자 추출 (`path.extname` 대체). 숨김 파일(`.gitignore`)은 빈 문자열 반환 |
+
+## Usage
+
+```typescript
+import { path } from "@simplysm/core-common";
+
+path.join("/foo", "bar", "baz");  // "/foo/bar/baz"
+path.join("/foo/", "/bar/");      // "/foo/bar"
+
+path.basename("/foo/bar/file.txt");         // "file.txt"
+path.basename("/foo/bar/file.txt", ".txt"); // "file"
+
+path.extname("/foo/bar/file.txt");  // ".txt"
+path.extname("/foo/.gitignore");    // ""
+```

package/docs/utils/primitive.md

@@ -0,0 +1,28 @@
+# primitive
+
+원시 타입 변환 유틸리티 네임스페이스.
+
+```typescript
+import { primitive } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `typeStr` | `(value: PrimitiveTypeMap[PrimitiveTypeStr]) => PrimitiveTypeStr` | 값으로부터 `PrimitiveTypeStr` 추론. 지원하지 않는 타입이면 `ArgumentError` 발생 |
+
+## Usage
+
+```typescript
+import { primitive } from "@simplysm/core-common";
+
+primitive.typeStr("hello");          // "string"
+primitive.typeStr(123);              // "number"
+primitive.typeStr(true);             // "boolean"
+primitive.typeStr(new DateTime());   // "DateTime"
+primitive.typeStr(new DateOnly());   // "DateOnly"
+primitive.typeStr(new Time());       // "Time"
+primitive.typeStr(Uuid.generate()); // "Uuid"
+primitive.typeStr(new Uint8Array()); // "Bytes"
+```