@simplysm/core-common 14.0.49 → 14.0.50

package/docs/extensions/array.md

@@ -0,0 +1,125 @@
+# Array Extensions
+
+`@simplysm/core-common`을 import하면 `Array.prototype`에 확장 메서드가 자동 등록된다. `ReadonlyArray<T>`와 `Array<T>` 모두에 적용된다.
+
+side-effect import로 활성화:
+
+```typescript
+import "@simplysm/core-common";
+```
+
+## 불변(Immutable) 메서드
+
+원본 배열을 변경하지 않고 새 배열 또는 값을 반환한다.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `single` | `(predicate?) => T \| undefined` | 조건에 맞는 단일 요소 반환. 2개 이상이면 `ArgumentError` 발생 |
+| `first` | `(predicate?) => T \| undefined` | 첫 번째 요소 반환 |
+| `last` | `(predicate?) => T \| undefined` | 마지막 요소 반환 |
+| `filterExists` | `() => NonNullable<T>[]` | null/undefined 제거 |
+| `ofType` | `(type: PrimitiveTypeStr \| Type<N>) => N[]` | 특정 타입의 요소만 필터 |
+| `filterAsync` | `(predicate) => Promise<T[]>` | 비동기 필터 (순차 실행) |
+| `mapAsync` | `(selector) => Promise<R[]>` | 비동기 매핑 (순차 실행) |
+| `mapMany` | `(selector?) => R[]` | 매핑 후 평탄화 (또는 중첩 배열 평탄화) |
+| `mapManyAsync` | `(selector?) => Promise<R[]>` | 비동기 매핑 후 평탄화 (순차 실행) |
+| `parallelAsync` | `(fn) => Promise<R[]>` | 비동기 병렬 처리 (`Promise.all` 사용). 하나라도 reject되면 전체 reject |
+| `groupBy` | `(keySelector, valueSelector?) => { key, values }[]` | key 기준 그룹화. 객체 key 지원을 위해 O(n²) 복잡도. 원시 key는 O(n) |
+| `toMap` | `(keySelector, valueSelector?) => Map<K, V>` | Map으로 변환. 중복 key이면 `ArgumentError` 발생 |
+| `toMapAsync` | `(keySelector, valueSelector?) => Promise<Map<K, V>>` | 비동기 Map 변환 |
+| `toArrayMap` | `(keySelector, valueSelector?) => Map<K, V[]>` | 배열 값 Map으로 변환 (O(n)) |
+| `toSetMap` | `(keySelector, valueSelector?) => Map<K, Set<V>>` | Set 값 Map으로 변환 |
+| `toMapValues` | `(keySelector, valueSelector) => Map<K, V>` | 그룹별 집계 Map으로 변환 |
+| `toObject` | `(keySelector, valueSelector?) => Record<string, V>` | 객체로 변환. 중복 key이면 `ArgumentError` 발생 |
+| `toTree` | `(keyProp, parentKey) => TreeArray<T>[]` | 평면 배열을 트리 구조로 변환 (O(n)). `parentKey`가 null/undefined인 항목이 루트 |
+| `distinct` | `(options?) => T[]` | 중복 제거. 객체 배열에서 keyFn 없이 사용하면 O(n²) |
+| `orderBy` | `(selector?) => T[]` | 오름차순 정렬 (새 배열 반환) |
+| `orderByDesc` | `(selector?) => T[]` | 내림차순 정렬 (새 배열 반환) |
+| `diffs` | `(target, options?) => ArrayDiffsResult<T, P>[]` | 두 배열 비교 (INSERT/DELETE/UPDATE) |
+| `oneWayDiffs` | `(orgItems, keyPropNameOrGetValFn, options?) => ArrayOneWayDiffResult<T>[]` | 단방향 비교 (create/update/same) |
+| `merge` | `(target, options?) => (T \| P \| T & P)[]` | 두 배열 병합 (`diffs` 기반) |
+| `sum` | `(selector?) => number` | 합계. 빈 배열이면 0 반환 |
+| `min` | `(selector?) => T \| undefined` | 최솟값 |
+| `max` | `(selector?) => T \| undefined` | 최댓값 |
+| `shuffle` | `() => T[]` | 무작위 순서로 섞은 새 배열 반환 |
+
+## 가변(Mutable) 메서드
+
+원본 배열을 직접 수정하고 `this`를 반환한다.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `remove` | `(item: T) => this` | 항목 제거 |
+| `remove` | `(selector: (item, index) => boolean) => this` | 조건에 맞는 항목 제거 |
+| `insert` | `(index: number, ...items: T[]) => this` | 특정 위치에 항목 삽입 |
+| `toggle` | `(item: T) => this` | 항목 토글 (있으면 제거, 없으면 추가) |
+| `clear` | `() => this` | 배열 비우기 |
+| `distinctThis` | `(options?) => T[]` | 원본 배열에서 중복 제거 |
+| `orderByThis` | `(selector?) => T[]` | 원본 배열 오름차순 정렬 |
+| `orderByDescThis` | `(selector?) => T[]` | 원본 배열 내림차순 정렬 |
+
+## Related Types
+
+### `ArrayDiffsResult<TOriginal, TOther>`
+
+`diffs()` 결과 타입. Discriminated union:
+
+```typescript
+export type ArrayDiffsResult<TOriginal, TOther> =
+  | { source: undefined; target: TOther }         // INSERT (target에만 있음)
+  | { source: TOriginal; target: undefined }       // DELETE (source에만 있음)
+  | { source: TOriginal; target: TOther };         // UPDATE (양쪽에 있고 다름)
+```
+
+### `ArrayOneWayDiffResult<TItem>`
+
+`oneWayDiffs()` 결과 타입. Discriminated union (`type` 필드로 분기):
+
+```typescript
+export type ArrayOneWayDiffResult<TItem> =
+  | { type: "create"; item: TItem; orgItem: undefined }
+  | { type: "update"; item: TItem; orgItem: TItem }
+  | { type: "same";   item: TItem; orgItem: TItem };
+```
+
+### `TreeArray<TNode>`
+
+`toTree()` 결과 타입. 원본 타입에 `children` 속성이 추가된다:
+
+```typescript
+export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
+```
+
+### `ComparableType`
+
+`orderBy`/`orderByDesc` selector의 반환 타입:
+
+```typescript
+export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
+```
+
+## Usage
+
+```typescript
+import "@simplysm/core-common";
+
+const users = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }];
+
+// 불변 메서드
+const alice = users.single((u) => u.id === 1);
+const sorted = users.orderBy((u) => u.name);
+const grouped = users.groupBy((u) => u.name[0]);
+const diffs = newUsers.diffs(oldUsers, { keys: ["id"] });
+
+// toTree
+const items = [
+  { id: 1, parentId: undefined, name: "root" },
+  { id: 2, parentId: 1, name: "child" },
+];
+const tree = items.toTree("id", "parentId");
+
+// 가변 메서드
+const list = [1, 2, 3, 4, 5];
+list.remove((x) => x % 2 === 0); // [1, 3, 5]
+list.insert(1, 10); // [1, 10, 3, 5]
+```

package/docs/extensions/map.md

@@ -0,0 +1,43 @@
+# Map Extensions
+
+`@simplysm/core-common`을 import하면 `Map.prototype`에 확장 메서드가 자동 등록된다.
+
+side-effect import로 활성화:
+
+```typescript
+import "@simplysm/core-common";
+```
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getOrCreate` | `(key: K, newValue: V) => V` | key가 없으면 값을 설정하고 반환 |
+| `getOrCreate` | `(key: K, newValueFn: () => V) => V` | key가 없으면 팩토리 함수를 호출하여 값을 설정하고 반환 |
+| `update` | `(key: K, updateFn: (v: V \| undefined) => V) => void` | 현재 값을 받아 새 값으로 업데이트. key가 없으면 `undefined`가 전달됨 |
+
+## Usage
+
+```typescript
+import "@simplysm/core-common";
+
+// getOrCreate — 값으로
+const map = new Map<string, number[]>();
+const arr = map.getOrCreate("key", []);    // 없으면 [] 설정 후 반환
+
+// getOrCreate — 팩토리로 (비용이 큰 연산에 사용)
+const val = map.getOrCreate("key", () => expensiveComputation());
+
+// 함수를 값으로 저장 시 팩토리로 감싸야 함
+const fnMap = new Map<string, () => void>();
+const myFn = () => console.log("hello");
+fnMap.getOrCreate("key", () => myFn);  // 팩토리로 감싸기
+
+// update — 카운터
+const countMap = new Map<string, number>();
+countMap.update("key", (v) => (v ?? 0) + 1);
+
+// update — 배열에 추가
+const arrayMap = new Map<string, string[]>();
+arrayMap.update("key", (v) => [...(v ?? []), "item"]);
+```

package/docs/extensions/set.md

@@ -0,0 +1,35 @@
+# Set Extensions
+
+`@simplysm/core-common`을 import하면 `Set.prototype`에 확장 메서드가 자동 등록된다.
+
+side-effect import로 활성화:
+
+```typescript
+import "@simplysm/core-common";
+```
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `adds` | `(...values: T[]) => this` | 여러 값을 한 번에 추가 |
+| `toggle` | `(value: T, addOrDel?: "add" \| "del") => this` | 값 토글 (있으면 제거, 없으면 추가). `addOrDel`로 강제 추가/제거 가능 |
+
+## Usage
+
+```typescript
+import "@simplysm/core-common";
+
+const set = new Set<number>([1, 2, 3]);
+
+// adds — 여러 항목 추가
+set.adds(4, 5, 6); // {1, 2, 3, 4, 5, 6}
+
+// toggle — 자동
+set.toggle(2);  // 2가 있으므로 제거 → {1, 3, 4, 5, 6}
+set.toggle(10); // 10이 없으므로 추가 → {1, 3, 4, 5, 6, 10}
+
+// toggle — 강제
+const isAdmin = true;
+set.toggle(5, isAdmin ? "add" : "del"); // 강제 추가
+```

package/docs/features/debounce-queue.md

@@ -0,0 +1,48 @@
+# DebounceQueue
+
+비동기 디바운스 큐. 짧은 시간 내에 여러 번 호출되면 마지막 요청만 실행하고 이전 요청은 무시한다. 입력 필드 자동완성, 연속적인 상태 변경 일괄 처리 등에 유용하다. [`EventEmitter`](./event-emitter.md)를 상속한다.
+
+```typescript
+export class DebounceQueue extends EventEmitter<{ error: SdError }> {
+  /**
+   * @param _delay 디바운스 지연 시간 (밀리초). 생략 시 즉시 실행 (다음 이벤트 루프)
+   */
+  constructor(_delay?: number);
+
+  run(fn: () => void | Promise<void>): void;
+  override dispose(): void;
+}
+```
+
+에러 발생 시 `"error"` 이벤트로 전파되며, 리스너가 없으면 `consola`로 로그 출력된다.
+
+실행 중에 추가된 요청은 디바운스 지연 없이 현재 실행이 완료된 직후 즉시 처리된다. 이는 실행 완료 전에 도착한 요청을 놓치지 않기 위한 의도적인 설계다.
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `run` | method | `(fn: () => void \| Promise<void>) => void` | 큐에 함수 추가. 이전에 추가된 함수가 있으면 교체됨 |
+| `dispose` | method | `() => void` | 대기 중인 작업과 타이머 정리 후 부모 `dispose()` 호출 |
+
+## Usage
+
+```typescript
+import { DebounceQueue } from "@simplysm/core-common";
+
+const queue = new DebounceQueue(300); // 300ms 지연
+
+// 에러 처리
+queue.on("error", (err) => console.error(err));
+
+queue.run(() => console.log("1")); // 무시됨
+queue.run(() => console.log("2")); // 무시됨
+queue.run(() => console.log("3")); // 300ms 후 실행
+
+// 자원 정리
+try {
+  queue.run(() => saveData());
+} finally {
+  queue.dispose();
+}
+```

package/docs/features/event-emitter.md

@@ -0,0 +1,52 @@
+# EventEmitter
+
+타입 안전 EventEmitter. 내부적으로 `EventTarget`을 사용하며 브라우저와 Node.js 모두에서 사용 가능하다. `events`/`eventemitter3` 대신 이 클래스를 사용한다.
+
+```typescript
+export class EventEmitter<
+  TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>,
+> {
+  on<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => void): void;
+  off<TEventName extends keyof TEvents & string>(type: TEventName, listener: (data: TEvents[TEventName]) => void): void;
+  emit<TEventName extends keyof TEvents & string>(type: TEventName, ...args: TEvents[TEventName] extends void ? [] : [data: TEvents[TEventName]]): void;
+  listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): number;
+  dispose(): void;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `on` | method | `(type, listener) => void` | 이벤트 리스너 등록. 같은 리스너를 같은 이벤트에 중복 등록하면 무시됨 |
+| `off` | method | `(type, listener) => void` | 이벤트 리스너 제거 |
+| `emit` | method | `(type, ...args) => void` | 이벤트 발행. `void` 타입 이벤트는 인자 없이 호출 |
+| `listenerCount` | method | `(type) => number` | 특정 이벤트의 등록된 리스너 수 반환 |
+| `dispose` | method | `() => void` | 모든 이벤트 리스너 제거 |
+
+## Usage
+
+```typescript
+import { EventEmitter } from "@simplysm/core-common";
+
+// 이벤트 타입 정의
+interface MyEvents {
+  data: string;
+  error: Error;
+  done: void;
+}
+
+// EventEmitter를 상속하여 사용
+class MyService extends EventEmitter<MyEvents> {
+  async load() {
+    this.emit("data", "Loading...");
+    this.emit("done"); // void 타입은 인자 없이 호출
+  }
+}
+
+const svc = new MyService();
+svc.on("data", (data) => { /* data: string */ });
+svc.on("done", () => { /* ... */ });
+await svc.load();
+svc.dispose(); // 모든 리스너 정리
+```

package/docs/features/serial-queue.md

@@ -0,0 +1,44 @@
+# SerialQueue
+
+비동기 직렬 큐. 큐에 추가된 함수들은 순차적으로 실행된다. 하나의 작업이 완료된 후에야 다음 작업이 시작된다. 에러가 발생해도 후속 작업은 계속 실행된다. [`EventEmitter`](./event-emitter.md)를 상속한다.
+
+```typescript
+export class SerialQueue extends EventEmitter<{ error: SdError }> {
+  /**
+   * @param _gap 각 작업 사이의 간격 (ms). 기본값: 0
+   */
+  constructor(_gap?: number);
+
+  run(fn: () => void | Promise<void>): void;
+  override dispose(): void;
+}
+```
+
+에러 발생 시 `"error"` 이벤트로 전파되며, 리스너가 없으면 `consola`로 로그 출력된다.
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `run` | method | `(fn: () => void \| Promise<void>) => void` | 큐에 함수 추가하고 실행 예약 |
+| `dispose` | method | `() => void` | 대기 중인 큐 비우기 (현재 실행 중인 작업은 완료됨) |
+
+## Usage
+
+```typescript
+import { SerialQueue } from "@simplysm/core-common";
+
+const queue = new SerialQueue();
+
+// 에러 처리
+queue.on("error", (err) => console.error(err));
+
+queue.run(async () => { await fetch("/api/1"); });
+queue.run(async () => { await fetch("/api/2"); }); // 1 완료 후 실행
+queue.run(async () => { await fetch("/api/3"); }); // 2 완료 후 실행
+
+// 간격 있는 큐
+const gapQueue = new SerialQueue(100); // 각 작업 사이 100ms 간격
+gapQueue.run(() => step1());
+gapQueue.run(() => step2()); // step1 완료 후 100ms 뒤에 실행
+```

package/docs/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/docs/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/docs/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 (월요일)
+```