@simplysm/core-common 13.0.96 → 13.0.97

package/dist/env.d.ts

@@ -1,3 +1,8 @@
+declare global {
+    interface ImportMeta {
+        env?: Record<string, unknown>;
+    }
+}
 export declare const env: {
     DEV: boolean;
     VER?: string;

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B;CACF;AAMD,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}

package/dist/env.js

@@ -1,7 +1,10 @@
+const _metaEnv = import.meta.env ?? {};
+const _processEnv = typeof process !== "undefined" ? process.env : {};
+const _raw = { ..._metaEnv, ..._processEnv };
 const env = {
-  ...process.env,
-  DEV: JSON.parse(process.env.DEV != null && process.env.DEV !== "" ? process.env.DEV : "false"),
-  VER: process.env.VER
+  ..._raw,
+  DEV: JSON.parse(String(_raw["DEV"] != null && String(_raw["DEV"]) !== "" ? _raw["DEV"] : false)),
+  VER: _raw["VER"]
 };
 export {
   env

package/dist/env.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/env.ts"],
-  "mappings": "AAEO,MAAM,MAIT;AAAA,EACF,GAAG,QAAQ;AAAA,EACX,KAAK,KAAK,MAAM,QAAQ,IAAI,OAAO,QAAQ,QAAQ,IAAI,QAAQ,KAAK,QAAQ,IAAI,MAAM,OAAO;AAAA,EAC7F,KAAK,QAAQ,IAAI;AACnB;",
+  "mappings": "AAQA,MAAM,WAAoC,YAAY,OAAO,CAAC;AAC9D,MAAM,cAAuC,OAAO,YAAY,cAAc,QAAQ,MAAM,CAAC;AAC7F,MAAM,OAAgC,EAAE,GAAG,UAAU,GAAG,YAAY;AAE7D,MAAM,MAIT;AAAA,EACF,GAAG;AAAA,EACH,KAAK,KAAK,MAAM,OAAO,KAAK,KAAK,KAAK,QAAQ,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,KAAK,KAAK,IAAI,KAAK,CAAC;AAAA,EAC/F,KAAK,KAAK,KAAK;AACjB;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "13.0.96",
+  "version": "13.0.97",
   "description": "Simplysm package - Core module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
   "dependencies": {
     "@zip.js/zip.js": "^2.8.23",
     "consola": "^3.4.2",
-    "fast-xml-parser": "^5.5.5",
+    "fast-xml-parser": "^5.5.8",
     "yaml": "^2.8.2"
   }
 }

package/src/env.ts

@@ -1,11 +1,21 @@
 declare const process: { env: { DEV?: string; VER?: string; [key: string]: string | undefined } };
 
+declare global {
+  interface ImportMeta {
+    env?: Record<string, unknown>;
+  }
+}
+
+const _metaEnv: Record<string, unknown> = import.meta.env ?? {};
+const _processEnv: Record<string, unknown> = typeof process !== "undefined" ? process.env : {};
+const _raw: Record<string, unknown> = { ..._metaEnv, ..._processEnv };
+
 export const env: {
   DEV: boolean;
   VER?: string;
   [key: string]: unknown;
 } = {
-  ...process.env,
-  DEV: JSON.parse(process.env.DEV != null && process.env.DEV !== "" ? process.env.DEV : "false"),
-  VER: process.env.VER,
+  ..._raw,
+  DEV: JSON.parse(String(_raw["DEV"] != null && String(_raw["DEV"]) !== "" ? _raw["DEV"] : false)),
+  VER: _raw["VER"] as string | undefined,
 };

package/README.md

@@ -1,113 +0,0 @@
-# @simplysm/core-common
-
-Simplysm 프레임워크의 기반 유틸리티 패키지. 플랫폼 중립적인 타입, 유틸리티 함수, 에러 클래스, 확장 메서드를 제공한다.
-
-## 설치
-
-```bash
-npm install @simplysm/core-common
-```
-
-## 의존성
-
-- `@zip.js/zip.js` -- ZIP 파일 처리
-- `consola` -- 로깅
-- `fast-xml-parser` -- XML 파싱/직렬화
-- `yaml` -- YAML 직렬화 (ArgumentError 메시지용)
-
-## 문서
-
-| 카테고리 | 설명 |
-|---------|------|
-| [타입](docs/types.md) | DateTime, DateOnly, Time, Uuid, LazyGcMap 등 불변 타입 |
-| [유틸리티](docs/utilities.md) | obj, str, num, bytes, json, xml, zip 등 네임스페이스 유틸리티 |
-| [기능](docs/features.md) | EventEmitter, DebounceQueue, SerialQueue, 에러 클래스, 확장 메서드, env |
-
-## 빠른 시작
-
-### 날짜/시간 타입
-
-```typescript
-import { DateTime, DateOnly, Time } from "@simplysm/core-common";
-
-const now = new DateTime();
-const tomorrow = now.addDays(1);
-const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
-
-const today = new DateOnly();
-const weekInfo = today.getWeekSeqOfYear(); // { year, weekSeq }
-
-const time = Time.parse("14:30:00");
-const later = time.addHours(2); // 24시간 래핑
-```
-
-### 유틸리티 함수
-
-```typescript
-import { obj, str, json, bytes } from "@simplysm/core-common";
-
-// 객체 딥 클론/비교/병합
-const cloned = obj.clone(source);
-const isEqual = obj.equal(a, b);
-const merged = obj.merge(source, target);
-
-// 문자열 변환
-str.toPascalCase("hello-world"); // "HelloWorld"
-str.toKebabCase("HelloWorld");   // "hello-world"
-
-// JSON (커스텀 타입 지원)
-const serialized = json.stringify({ date: new DateTime() });
-const parsed = json.parse<{ date: DateTime }>(serialized);
-
-// 바이너리
-const hex = bytes.toHex(data);
-const b64 = bytes.toBase64(data);
-```
-
-### 이벤트 에미터
-
-```typescript
-import { EventEmitter } from "@simplysm/core-common";
-
-const emitter = new EventEmitter<{ change: string; error: Error }>();
-emitter.on("change", (data) => { /* ... */ });
-emitter.emit("change", "updated");
-```
-
-### 배열 확장 메서드
-
-```typescript
-import "@simplysm/core-common"; // side-effect import
-
-const items = [1, 2, 3, 4, 5];
-items.first();                    // 1
-items.last();                     // 5
-items.distinct();                 // 중복 제거
-items.orderBy((x) => x);         // 정렬
-items.groupBy((x) => x % 2);     // 그룹화
-items.sum();                      // 15
-```
-
-### ZIP 처리
-
-```typescript
-import { ZipArchive } from "@simplysm/core-common";
-
-await using zip = new ZipArchive(data);
-const content = await zip.get("file.txt");
-zip.write("new-file.txt", bytes);
-const compressed = await zip.compress();
-```
-
-### 에러 클래스
-
-```typescript
-import { SdError, ArgumentError, TimeoutError } from "@simplysm/core-common";
-
-// 에러 체인 (=> 구분자로 조인)
-throw new SdError(originalError, "추가 컨텍스트");
-// 메시지: "추가 컨텍스트 => 원본 에러 메시지"
-
-// 인자 에러 (YAML 형식)
-throw new ArgumentError({ userId: -1, name: "" });
-```

package/docs/features.md

@@ -1,343 +0,0 @@
-# 기능
-
-## EventEmitter
-
-타입 안전한 이벤트 에미터. `EventTarget` 기반으로 브라우저와 Node.js 모두에서 사용 가능하다.
-
-```typescript
-import { EventEmitter } from "@simplysm/core-common";
-
-const emitter = new EventEmitter<{
-  change: string;
-  error: Error;
-  ready: void;
-}>();
-
-// 리스너 등록 (동일 리스너 중복 등록 무시)
-emitter.on("change", (data) => { /* data: string */ });
-
-// 리스너 제거
-emitter.off("change", listener);
-
-// 이벤트 발생 (void 타입은 인자 없이 호출)
-emitter.emit("change", "updated");
-emitter.emit("ready");
-
-// 리스너 수 확인
-emitter.listenerCount("change");
-
-// 정리 (Disposable 지원)
-emitter.dispose();
-// 또는
-using emitter2 = new EventEmitter<{ tick: number }>();
-```
-
-### 상속 패턴
-
-```typescript
-interface MyEvents {
-  data: string;
-  error: Error;
-}
-
-class MyService extends EventEmitter<MyEvents> {
-  process(): void {
-    this.emit("data", "result");
-  }
-}
-```
-
----
-
-## DebounceQueue
-
-디바운스된 비동기 작업 실행. delay 내 마지막 요청만 실행된다.
-
-```typescript
-import { DebounceQueue } from "@simplysm/core-common";
-
-const queue = new DebounceQueue(300); // 300ms 디바운스 (생략 시 즉시 실행)
-
-queue.on("error", (err) => { /* SdError */ });
-
-// 300ms 내 마지막 호출만 실행
-queue.run(async () => {
-  await saveData();
-});
-
-queue.dispose();
-// 또는
-using queue2 = new DebounceQueue(100);
-```
-
-동작 방식:
-- delay 내 새 요청이 들어오면 이전 요청을 취소하고 새 요청만 실행
-- 실행 중 새 요청이 들어오면 실행 완료 후 **즉시** 새 요청 처리 (디바운스 delay 없이)
-- 에러 발생 시 "error" 이벤트 리스너가 있으면 이벤트 발생, 없으면 consola로 로깅
-
----
-
-## SerialQueue
-
-순차 비동기 작업 실행. 작업 간 선택적 간격(gap) 설정 가능. 에러가 발생해도 후속 작업은 계속 실행된다.
-
-```typescript
-import { SerialQueue } from "@simplysm/core-common";
-
-const queue = new SerialQueue(100); // 작업 간 100ms 간격 (기본값: 0)
-
-queue.on("error", (err) => { /* SdError */ });
-
-queue.run(async () => await task1());
-queue.run(async () => await task2()); // task1 완료 + 100ms 후 실행
-
-queue.dispose(); // 대기 중인 큐 비우기 (현재 실행 중인 작업은 완료)
-// 또는
-using queue2 = new SerialQueue();
-```
-
----
-
-## 에러 클래스
-
-### SdError
-
-에러 체인을 지원하는 기본 에러 클래스. ES2024 `cause` 속성을 활용한다. 메시지는 역순으로 `=>` 구분자로 조인된다.
-
-```typescript
-import { SdError } from "@simplysm/core-common";
-
-// 메시지만
-throw new SdError("작업 실패");
-
-// 여러 메시지 (역순 조인)
-throw new SdError("하위 메시지", "상위 메시지");
-// 메시지: "상위 메시지 => 하위 메시지"
-
-// 원인 에러 래핑
-throw new SdError(originalError, "추가 컨텍스트");
-// 메시지: "추가 컨텍스트 => 원본 에러 메시지"
-// cause 속성에 originalError 저장
-// stack에 원인 에러 스택도 포함 (---- cause stack ---- 구분자)
-```
-
-### ArgumentError
-
-잘못된 인자를 YAML 형식으로 표시하는 에러. `SdError`를 상속한다.
-
-```typescript
-import { ArgumentError } from "@simplysm/core-common";
-
-throw new ArgumentError({ userId: -1, name: "" });
-// 메시지: "Invalid arguments.\n\nuserId: -1\nname: ''"
-
-throw new ArgumentError("유효하지 않은 입력", { userId: -1 });
-// 메시지: "유효하지 않은 입력\n\nuserId: -1"
-```
-
-### NotImplementedError
-
-미구현 기능을 표시하는 에러. `SdError`를 상속한다.
-
-```typescript
-import { NotImplementedError } from "@simplysm/core-common";
-
-throw new NotImplementedError();
-// 메시지: "Not implemented"
-
-throw new NotImplementedError("이 기능은 아직 구현되지 않았습니다");
-// 메시지: "Not implemented: 이 기능은 아직 구현되지 않았습니다"
-```
-
-### TimeoutError
-
-타임아웃 에러. `SdError`를 상속한다.
-
-```typescript
-import { TimeoutError } from "@simplysm/core-common";
-
-throw new TimeoutError();
-// 메시지: "Waiting time exceeded"
-
-throw new TimeoutError(3);
-// 메시지: "Waiting time exceeded(3 attempts)"
-
-throw new TimeoutError(3, "API 응답 대기 초과");
-// 메시지: "Waiting time exceeded(3 attempts): API 응답 대기 초과"
-```
-
----
-
-## 배열 확장 메서드
-
-`import "@simplysm/core-common"` (side-effect import) 시 `Array.prototype`에 추가되는 메서드.
-
-### 요소 접근
-
-```typescript
-[1, 2, 3].first();                          // 1
-[1, 2, 3].first((x) => x > 1);             // 2
-[1, 2, 3].last();                           // 3
-[1, 2, 3].last((x) => x < 3);              // 2
-[1, 2, 3].single((x) => x === 2);           // 2 (복수 매칭 시 ArgumentError)
-```
-
-### 필터링
-
-```typescript
-[1, null, 2, undefined].filterExists();      // [1, 2]
-items.ofType("string");                      // string 타입만 필터
-items.ofType(MyClass);                       // MyClass 인스턴스만 필터
-await items.filterAsync(async (x) => check(x)); // 순차 비동기 필터
-```
-
-### 변환
-
-```typescript
-items.mapMany();                             // 2차원 -> 1차원 평탄화 (null 제거)
-items.mapMany((x) => x.children);           // 매핑 후 평탄화
-await items.mapAsync(async (x) => transform(x));       // 순차 비동기 매핑
-await items.mapManyAsync(async (x) => getChildren(x)); // 순차 비동기 매핑 후 평탄화
-await items.parallelAsync(async (x) => process(x));    // Promise.all 병렬 처리
-```
-
-### 그룹화/매핑
-
-```typescript
-items.groupBy((x) => x.category);           // { key, values }[]
-items.groupBy((x) => x.cat, (x) => x.name); // 값 변환 포함
-
-items.toMap((x) => x.id);                   // Map<id, item> (중복 키 시 ArgumentError)
-items.toMap((x) => x.id, (x) => x.name);   // Map<id, name>
-await items.toMapAsync(async (x) => x.id);  // 비동기 키 매핑
-
-items.toArrayMap((x) => x.category);        // Map<category, item[]>
-items.toArrayMap((x) => x.cat, (x) => x.name); // Map<category, name[]>
-
-items.toSetMap((x) => x.category);           // Map<category, Set<item>>
-items.toMapValues((x) => x.cat, (arr) => arr.length); // Map<cat, count>
-
-items.toObject((x) => x.id);                // Record<string, item>
-items.toObject((x) => x.id, (x) => x.name); // Record<string, name>
-
-items.toTree("id", "parentId");              // TreeArray<T>[] (parentId가 null인 항목이 루트)
-```
-
-### 정렬/고유
-
-```typescript
-items.distinct();                            // 고유 요소 (객체: 딥 비교 O(n^2))
-items.distinct({ matchAddress: true });      // 참조 비교 (Set 기반 O(n))
-items.distinct({ keyFn: (x) => x.id });     // 커스텀 키 (O(n))
-
-items.orderBy((x) => x.name);               // 오름차순 (null/undefined 우선)
-items.orderByDesc((x) => x.score);          // 내림차순
-
-items.shuffle();                             // 랜덤 셔플 (Fisher-Yates)
-```
-
-### 집계
-
-```typescript
-items.sum((x) => x.price);                  // 합계 (빈 배열이면 0)
-items.min((x) => x.date);                   // 최솟값 (number | string)
-items.max((x) => x.date);                   // 최댓값 (number | string)
-```
-
-### 비교/병합
-
-```typescript
-// 배열 diff (INSERT/DELETE/UPDATE)
-items.diffs(target);
-// 반환: { source, target }[]
-// source만 있으면 DELETE, target만 있으면 INSERT, 둘 다 있으면 UPDATE
-
-items.diffs(target, { keys: ["id"] });           // 키 기준 매칭
-items.diffs(target, { excludes: ["updatedAt"] }); // 비교 제외 키
-
-// 단방향 diff
-items.oneWayDiffs(orgItems, "id");
-items.oneWayDiffs(orgItems, (x) => x.id, { includeSame: true });
-// 반환: { type: "create"|"update"|"same", item, orgItem }[]
-
-// 배열 병합
-items.merge(target);
-items.merge(target, { keys: ["id"], excludes: ["updatedAt"] });
-```
-
-### 원본 변경 메서드 (@mutates)
-
-```typescript
-items.distinctThis();                        // 원본 배열에서 중복 제거
-items.orderByThis((x) => x.name);           // 원본 배열 오름차순 정렬
-items.orderByDescThis((x) => x.score);      // 원본 배열 내림차순 정렬
-items.insert(2, newItem1, newItem2);         // 인덱스 2에 삽입
-items.remove(item);                          // 참조 일치 항목 제거
-items.remove((x) => x.expired);             // 조건 일치 항목 제거
-items.toggle(item);                          // 있으면 제거, 없으면 추가
-items.clear();                               // 전체 제거
-```
-
-### 내보내는 타입
-
-```typescript
-import type {
-  ArrayDiffsResult,       // { source, target } 유니온
-  ArrayOneWayDiffResult,  // { type, item, orgItem } 유니온
-  TreeArray,              // T & { children: TreeArray<T>[] }
-  ComparableType,         // string | number | boolean | DateTime | DateOnly | Time | undefined
-} from "@simplysm/core-common";
-```
-
----
-
-## Map 확장 메서드
-
-```typescript
-const map = new Map<string, number[]>();
-
-// 없으면 생성 (값 또는 팩토리 함수)
-map.getOrCreate("key", []);                  // 직접 값
-map.getOrCreate("key", () => []);            // 팩토리 함수
-// 주의: V 타입이 함수이면 팩토리로 인식되므로 () => myFn 형태로 래핑 필요
-
-// 값 갱신 (키가 없으면 prev는 undefined)
-map.update("key", (prev) => [...(prev ?? []), 1]);
-```
-
----
-
-## Set 확장 메서드
-
-```typescript
-const set = new Set<string>();
-
-set.adds("a", "b", "c");                    // 다수 추가 (체이닝)
-
-set.toggle("a");                             // 있으면 제거, 없으면 추가
-set.toggle("b", "add");                     // 강제 추가
-set.toggle("b", "del");                     // 강제 제거
-```
-
----
-
-## 환경 변수
-
-```typescript
-import { env } from "@simplysm/core-common";
-
-env.DEV;    // boolean -- 개발 모드 여부 (process.env.DEV를 JSON.parse)
-env.VER;    // string | undefined -- 버전 문자열 (process.env.VER)
-```
-
-### `__DEV__` 글로벌 상수
-
-빌드 시점에 치환되는 글로벌 상수. 라이브러리 빌드에서는 치환되지 않고, 클라이언트/서버 빌드에서 `define: { '__DEV__': 'true/false' }`로 치환된다.
-
-```typescript
-declare const __DEV__: boolean;
-
-if (__DEV__) {
-  // 개발 모드 전용 로직
-}
-```

package/docs/types.md

@@ -1,341 +0,0 @@
-# 타입
-
-## DateTime
-
-불변(immutable) 날짜/시간 타입. 모든 변경 메서드는 새 인스턴스를 반환한다.
-
-### 생성
-
-```typescript
-import { DateTime } from "@simplysm/core-common";
-
-new DateTime();                                    // 현재 시각
-new DateTime(2024, 1, 15);                         // 2024-01-15 00:00:00
-new DateTime(2024, 1, 15, 14, 30, 0);              // 2024-01-15 14:30:00
-new DateTime(2024, 1, 15, 14, 30, 0, 500);         // 밀리초 포함
-new DateTime(tick);                                // tick(밀리초)으로 생성
-new DateTime(new Date());                          // Date 객체에서 생성
-```
-
-### 파싱
-
-```typescript
-DateTime.parse("2024-01-15T14:30:00.000Z");        // ISO 8601
-DateTime.parse("2024-01-15 14:30:00");              // yyyy-MM-dd HH:mm:ss
-DateTime.parse("2024-01-15 14:30:00.123");          // yyyy-MM-dd HH:mm:ss.fff
-DateTime.parse("20240115143000");                   // yyyyMMddHHmmss
-DateTime.parse("2024-01-15 AM 10:30:00");           // yyyy-MM-dd AM/PM HH:mm:ss
-DateTime.parse("2024-01-15 오전 10:30:00");          // yyyy-MM-dd 오전/오후 HH:mm:ss
-```
-
-### 속성
-
-| 속성 | 타입 | 설명 |
-|------|------|------|
-| `year` | `number` | 연도 |
-| `month` | `number` | 월 (1~12) |
-| `day` | `number` | 일 |
-| `hour` | `number` | 시 (0~23) |
-| `minute` | `number` | 분 |
-| `second` | `number` | 초 |
-| `millisecond` | `number` | 밀리초 |
-| `tick` | `number` | epoch 밀리초 |
-| `dayOfWeek` | `number` | 요일 (0=일요일) |
-| `timezoneOffsetMinutes` | `number` | 타임존 오프셋(분) |
-| `isValid` | `boolean` | 유효성 |
-| `date` | `Date` | 내부 Date 객체 (readonly) |
-
-### 변경 (새 인스턴스 반환)
-
-```typescript
-const dt = new DateTime(2024, 1, 15, 14, 30, 0);
-
-dt.setYear(2025);          // 2025-01-15 14:30:00
-dt.setMonth(6);            // 2024-06-15 14:30:00
-dt.setDay(20);             // 2024-01-20 14:30:00
-dt.setHour(10);            // 2024-01-15 10:30:00
-dt.setMinute(45);          // 2024-01-15 14:45:00
-dt.setSecond(30);          // 2024-01-15 14:30:30
-dt.setMillisecond(500);    // 2024-01-15 14:30:00.500
-
-dt.addYears(1);            // 2025-01-15 14:30:00
-dt.addMonths(3);           // 2024-04-15 14:30:00
-dt.addDays(10);            // 2024-01-25 14:30:00
-dt.addHours(-2);           // 2024-01-15 12:30:00
-dt.addMinutes(15);         // 2024-01-15 14:45:00
-dt.addSeconds(30);         // 2024-01-15 14:30:30
-dt.addMilliseconds(500);   // 2024-01-15 14:30:00.500
-```
-
-### 포맷
-
-```typescript
-dt.toFormatString("yyyy-MM-dd HH:mm:ss");   // "2024-01-15 14:30:00"
-dt.toFormatString("yy/M/d tt h:mm");        // "24/1/15 PM 2:30"
-dt.toString();                                // ISO 8601 형식 "2024-01-15T14:30:00.000+09:00"
-```
-
-포맷 패턴:
-
-| 패턴 | 설명 | 예시 |
-|------|------|------|
-| `yyyy` | 4자리 연도 | 2024 |
-| `yy` | 2자리 연도 | 24 |
-| `MM` | 0패딩 월 | 01~12 |
-| `M` | 월 | 1~12 |
-| `ddd` | 요일 | 일, 월, 화, 수, 목, 금, 토 |
-| `dd` | 0패딩 일 | 01~31 |
-| `d` | 일 | 1~31 |
-| `tt` | 오전/오후 | AM, PM |
-| `hh` | 0패딩 12시간 | 01~12 |
-| `h` | 12시간 | 1~12 |
-| `HH` | 0패딩 24시간 | 00~23 |
-| `H` | 24시간 | 0~23 |
-| `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 |
-
----
-
-## DateOnly
-
-불변 날짜 전용 타입 (시간 정보 없음).
-
-### 생성/파싱
-
-```typescript
-import { DateOnly } from "@simplysm/core-common";
-
-new DateOnly();                        // 오늘
-new DateOnly(2024, 1, 15);             // 2024-01-15
-new DateOnly(tick);                    // tick(밀리초)으로 생성
-new DateOnly(new Date());             // Date 객체에서 생성
-DateOnly.parse("2024-01-15");          // yyyy-MM-dd
-DateOnly.parse("20240115");            // yyyyMMdd
-DateOnly.parse("2024-01-15T00:00:00Z"); // ISO 8601 (UTC -> 로컬 변환)
-```
-
-### 속성
-
-| 속성 | 타입 | 설명 |
-|------|------|------|
-| `year` | `number` | 연도 |
-| `month` | `number` | 월 (1~12) |
-| `day` | `number` | 일 |
-| `tick` | `number` | epoch 밀리초 |
-| `dayOfWeek` | `number` | 요일 (0=일요일) |
-| `isValid` | `boolean` | 유효성 |
-| `date` | `Date` | 내부 Date 객체 (readonly) |
-
-### 주차 계산
-
-모든 주차 메서드는 `weekStartDay`(주 시작 요일, 기본값 1=월요일)와 `minDaysInFirstWeek`(첫 주 최소 일수, 기본값 4=ISO 8601) 옵션을 지원한다.
-
-```typescript
-const date = new DateOnly(2024, 1, 15);
-
-// 연간 주차
-date.getWeekSeqOfYear();
-// { year: 2024, weekSeq: 3 }
-
-// 월간 주차
-date.getWeekSeqOfMonth();
-// { year: 2024, monthSeq: 1, weekSeq: 3 }
-
-// 해당 주의 시작일
-date.getWeekSeqStartDate();
-
-// 주차 기준 기본 연/월
-date.getBaseYearMonthSeqForWeekSeq();
-// { year: 2024, monthSeq: 1 }
-
-// 연/주차로 날짜 계산
-DateOnly.getDateByYearWeekSeq({ year: 2024, weekSeq: 3 });
-// 2024년 3주차 시작일 (월요일)
-
-// 월/주차로 날짜 계산
-DateOnly.getDateByYearWeekSeq({ year: 2025, month: 1, weekSeq: 3 });
-// 2025년 1월 3주차 시작일
-
-// US 스타일 (일요일 시작, 첫 주 최소 1일)
-date.getWeekSeqOfYear(0, 1);
-```
-
-### 변경/포맷
-
-```typescript
-// 변경 메서드 (새 인스턴스 반환)
-date.setYear(2025);     date.setMonth(6);     date.setDay(20);
-date.addYears(1);       date.addMonths(3);    date.addDays(10);
-
-// 포맷
-date.toFormatString("yyyy-MM-dd");   // "2024-01-15"
-date.toString();                      // "2024-01-15"
-```
-
----
-
-## Time
-
-불변 시간 전용 타입 (24시간 래핑).
-
-### 생성/파싱
-
-```typescript
-import { Time } from "@simplysm/core-common";
-
-new Time();                            // 현재 시각
-new Time(14, 30);                      // 14:30:00
-new Time(14, 30, 15, 500);             // 14:30:15.500
-new Time(tick);                        // tick(밀리초)으로 생성
-new Time(new Date());                  // Date 객체에서 시간 부분만 추출
-Time.parse("14:30:00");               // HH:mm:ss
-Time.parse("14:30:00.123");           // HH:mm:ss.fff
-Time.parse("AM 10:30:00");            // AM/PM HH:mm:ss
-Time.parse("2025-01-15T10:30:00Z");   // ISO 8601 (시간 부분만 추출)
-```
-
-### 속성
-
-| 속성 | 타입 | 설명 |
-|------|------|------|
-| `hour` | `number` | 시 (0~23) |
-| `minute` | `number` | 분 |
-| `second` | `number` | 초 |
-| `millisecond` | `number` | 밀리초 |
-| `tick` | `number` | 하루 기준 밀리초 |
-| `isValid` | `boolean` | 유효성 |
-
-### 24시간 래핑
-
-```typescript
-const time = new Time(23, 0);
-time.addHours(3);                      // 02:00:00 (다음날로 넘어감)
-
-const time2 = new Time(1, 0);
-time2.addHours(-3);                    // 22:00:00 (이전날로 넘어감)
-```
-
-### 변경/포맷
-
-```typescript
-// 변경 메서드 (새 인스턴스 반환, 24시간 래핑)
-time.setHour(10);        time.setMinute(45);
-time.setSecond(30);      time.setMillisecond(500);
-time.addHours(2);        time.addMinutes(30);
-time.addSeconds(30);     time.addMilliseconds(500);
-
-// 포맷
-time.toFormatString("HH:mm:ss");    // "14:30:00"
-time.toString();                      // "14:30:00.000"
-```
-
----
-
-## Uuid
-
-UUID v4 생성/변환. `crypto.getRandomValues` 기반.
-
-```typescript
-import { Uuid } from "@simplysm/core-common";
-
-const id = Uuid.generate();                        // 새 UUID 생성
-const fromStr = new Uuid("550e8400-e29b-41d4-a716-446655440000");
-const fromBytes = Uuid.fromBytes(bytes);           // 16바이트 배열에서 생성 (길이가 16이 아니면 ArgumentError)
-id.toString();                                     // "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx"
-id.toBytes();                                      // Uint8Array (16 bytes)
-```
-
----
-
-## LazyGcMap
-
-자동 만료 기능이 있는 LRU 캐시. GC 타이머를 사용하므로 반드시 `dispose()` 또는 `using` 문으로 정리해야 한다.
-
-```typescript
-import { LazyGcMap } from "@simplysm/core-common";
-
-const cache = new LazyGcMap<string, object>({
-  expireTime: 60_000,                   // 60초 만료 (필수)
-  gcInterval: 10_000,                   // 10초마다 GC (기본값: expireTime/10, 최소 1000ms)
-  onExpire: (key, value) => { /* 정리 로직, async 가능 */ },
-});
-
-cache.set("key", value);                // 값 저장 (GC 타이머 시작)
-cache.get("key");                       // 값 조회 (접근 시 만료 시간 갱신)
-cache.getOrCreate("key", () => createValue()); // 없으면 생성
-cache.has("key");                       // 존재 여부 (접근 시간 갱신 안 함)
-cache.delete("key");                    // 삭제
-cache.clear();                          // 전체 삭제 (인스턴스는 재사용 가능)
-cache.size;                             // 저장된 항목 수
-
-// 이터레이터
-for (const value of cache.values()) { /* ... */ }
-for (const key of cache.keys()) { /* ... */ }
-for (const [key, value] of cache.entries()) { /* ... */ }
-
-// 정리 (Disposable 지원)
-cache.dispose();
-// 또는
-using cache2 = new LazyGcMap({ expireTime: 30_000 });
-```
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `get` | `get(key: TKey): TValue \| undefined` | 값 조회 (만료 갱신) |
-| `set` | `set(key: TKey, value: TValue): void` | 값 설정 |
-| `getOrCreate` | `getOrCreate(key: TKey, factory: () => TValue): TValue` | 없으면 생성 |
-| `has` | `has(key: TKey): boolean` | 존재 여부 (만료 갱신 안 함) |
-| `delete` | `delete(key: TKey): boolean` | 삭제 |
-| `clear` | `clear(): void` | 전체 삭제 |
-| `size` | `number` (getter) | 저장된 항목 수 |
-| `values` | `values(): IterableIterator<TValue>` | 값 이터레이터 |
-| `keys` | `keys(): IterableIterator<TKey>` | 키 이터레이터 |
-| `entries` | `entries(): IterableIterator<[TKey, TValue]>` | 엔트리 이터레이터 |
-| `dispose` | `dispose(): void` | GC 타이머 정리 및 데이터 삭제 |
-
----
-
-## Bytes
-
-`Uint8Array`의 타입 별칭. `Buffer` 대신 사용한다.
-
-```typescript
-import type { Bytes } from "@simplysm/core-common";
-```
-
----
-
-## 공통 타입
-
-```typescript
-// 프리미티브 타입 맵
-type PrimitiveTypeMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  DateTime: DateTime;
-  DateOnly: DateOnly;
-  Time: Time;
-  Uuid: Uuid;
-  Bytes: Bytes;
-};
-
-type PrimitiveTypeStr = keyof PrimitiveTypeMap;
-type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
-
-// 재귀 Partial
-type DeepPartial<T> = Partial<{
-  [K in keyof T]: T[K] extends PrimitiveType ? T[K] : DeepPartial<T[K]>;
-}>;
-
-// 생성자 타입 (DI용)
-interface Type<T> extends Function { new (...args: unknown[]): T; }
-```

package/docs/utilities.md

@@ -1,359 +0,0 @@
-# 유틸리티
-
-네임스페이스로 그룹화된 유틸리티 함수들.
-
-## obj -- 객체 유틸리티
-
-### 클론/비교/병합
-
-```typescript
-import { obj } from "@simplysm/core-common";
-
-// 딥 클론 (순환 참조, 커스텀 타입 지원)
-// 지원: DateTime, DateOnly, Time, Uuid, Uint8Array, Date, RegExp, Error, Map, Set, Array
-// 함수/Symbol은 참조 유지, 프로토타입 체인 유지
-const cloned = obj.clone(source);
-
-// 딥 비교
-obj.equal(a, b);
-obj.equal(a, b, { shallow: true });                    // 1단계만 비교
-obj.equal(a, b, { ignoreArrayIndex: true });           // 배열 순서 무시 (O(n^2))
-obj.equal(a, b, { topLevelIncludes: ["name", "age"] }); // 특정 키만 비교 (최상위만)
-obj.equal(a, b, { topLevelExcludes: ["updatedAt"] });  // 특정 키 제외 (최상위만)
-
-// 딥 병합
-obj.merge(source, target);
-obj.merge(source, target, { arrayProcess: "concat" });   // 배열 연결 (Set 기반 중복 제거)
-obj.merge(source, target, { arrayProcess: "replace" });  // 배열 교체 (기본값)
-obj.merge(source, target, { useDelTargetNull: true });   // target이 null이면 키 삭제
-
-// 3-way 병합
-const { conflict, result } = obj.merge3(source, origin, target);
-// source와 origin 같고 target 다름 -> target 값 사용
-// target과 origin 같고 source 다름 -> source 값 사용
-// 세 값 모두 다름 -> conflict = true, origin 값 유지
-
-// 키별 비교 옵션
-obj.merge3(source, origin, target, {
-  name: { keys: ["first", "last"] },
-  tags: { ignoreArrayIndex: true },
-});
-```
-
-### 객체 조작
-
-```typescript
-// pick/omit
-obj.pick(item, ["name", "age"]);               // { name, age }
-obj.omit(item, ["password"]);                  // password 제외
-obj.omitByFilter(item, (key) => key.startsWith("_")); // 조건부 제외
-
-// 체인 접근 (점 표기법)
-obj.getChainValue(data, "user.address[0].city");
-obj.getChainValue(data, "user.name", true);       // optional: 중간 경로 없으면 undefined
-obj.setChainValue(data, "user.name", "new");      // 중간 경로 없으면 자동 생성
-obj.deleteChainValue(data, "user.temp");           // 중간 경로 없으면 무시
-
-// 깊이 기반 체인 접근
-obj.getChainValueByDepth(data, "parent", 2);       // data.parent.parent
-obj.getChainValueByDepth(data, "parent", 2, true); // optional 모드
-
-// 기타
-obj.clearUndefined(data);                    // undefined 키 제거 (mutate)
-obj.clear(data);                             // 모든 키 제거 (mutate)
-obj.nullToUndefined(data);                   // null -> undefined (재귀, mutate, 순환 참조 안전)
-obj.unflatten({ "a.b.c": 1 });               // { a: { b: { c: 1 } } }
-```
-
-### 타입 유틸리티
-
-```typescript
-obj.keys(myObj);                             // 타입 안전한 Object.keys
-obj.entries(myObj);                          // 타입 안전한 Object.entries
-obj.fromEntries(pairs);                      // 타입 안전한 Object.fromEntries
-
-// 객체 엔트리 변환
-obj.map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
-// key를 null로 반환하면 원래 key 유지, 새 key를 반환하면 key 변환
-
-type A = obj.UndefToOptional<{ a: string | undefined }>; // { a?: string | undefined }
-type B = obj.OptionalToUndef<{ a?: string }>;            // { a: string | undefined }
-```
-
----
-
-## str -- 문자열 유틸리티
-
-```typescript
-import { str } from "@simplysm/core-common";
-
-str.toPascalCase("hello-world");   // "HelloWorld"
-str.toCamelCase("hello-world");    // "helloWorld"
-str.toKebabCase("HelloWorld");     // "hello-world"
-str.toSnakeCase("HelloWorld");     // "hello_world"
-
-str.isNullOrEmpty(value);          // value is "" | undefined (타입 가드)
-str.insert("abcde", 2, "XY");     // "abXYcde"
-str.replaceFullWidth("ABC");    // "ABC" (전각 -> 반각)
-
-// 한국어 조사
-str.getKoreanSuffix("사과", "을");  // "를"
-str.getKoreanSuffix("바나나", "을"); // "을"
-str.getKoreanSuffix("칼", "로");    // "로" (ㄹ 종성 특수 처리)
-// 지원 타입: "을"(을/를), "은"(은/는), "이"(이/가), "와"(과/와), "랑"(이랑/랑), "로"(으로/로), "라"(이라/라)
-```
-
----
-
-## num -- 숫자 유틸리티
-
-```typescript
-import { num } from "@simplysm/core-common";
-
-// 파싱 (비숫자 문자 자동 제거)
-num.parseInt("1,234원");           // 1234
-num.parseFloat("$1,234.56");       // 1234.56
-num.parseRoundedInt("1.7");        // 2
-
-num.isNullOrEmpty(value);          // value is 0 | undefined (타입 가드)
-
-// 포맷 (천 단위 구분자)
-num.format(1234567);               // "1,234,567"
-num.format(1234.5678, { max: 2 }); // "1,234.57"
-num.format(1234.5, { min: 2 });    // "1,234.50"
-num.format(1234.5, { min: 2, max: 4 }); // "1,234.50"
-```
-
----
-
-## bytes -- 바이너리 유틸리티
-
-```typescript
-import { bytes } from "@simplysm/core-common";
-
-bytes.concat([arr1, arr2, arr3]);  // Uint8Array 연결
-bytes.toHex(data);                 // 소문자 hex 문자열
-bytes.fromHex("48656c6c6f");       // Uint8Array
-bytes.toBase64(data);              // base64 인코딩
-bytes.fromBase64(b64str);          // base64 디코딩
-```
-
----
-
-## json -- JSON 직렬화
-
-커스텀 타입(DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array, Date, RegExp 등)을 지원하는 JSON 직렬화/역직렬화.
-
-내부적으로 `__type__`/`data` 형식의 태그 객체를 사용하여 타입 정보를 보존한다.
-
-```typescript
-import { json, DateTime } from "@simplysm/core-common";
-
-// 직렬화 (커스텀 타입 자동 처리)
-const str = json.stringify({
-  date: new DateTime(),
-  id: Uuid.generate(),
-  items: new Set([1, 2, 3]),
-  mapping: new Map([["a", 1]]),
-});
-
-// 역직렬화 (타입 자동 복원, null -> undefined 변환)
-const data = json.parse<{ date: DateTime }>(str);
-
-// 옵션
-json.stringify(obj, { space: 2 });           // 들여쓰기
-json.stringify(obj, { redactBytes: true });  // Uint8Array를 "__hidden__"로 대체 (로깅용)
-json.stringify(obj, { replacer: (key, value) => value }); // 커스텀 replacer
-```
-
-**주의사항:**
-- `parse()`는 모든 JSON null을 undefined로 변환한다 (simplysm 프레임워크의 null-free 규칙)
-- `redactBytes: true`로 직렬화한 결과는 `parse()`로 복원 불가 (SdError 발생)
-- 순환 참조가 있으면 TypeError 발생
-
----
-
-## xml -- XML 처리
-
-```typescript
-import { xml } from "@simplysm/core-common";
-
-// 파싱 (속성은 $ 객체, 텍스트는 _ 키, 자식 요소는 배열)
-const obj = xml.parse('<root attr="1"><child>text</child></root>');
-// { root: { $: { attr: "1" }, child: [{ _: "text" }] } }
-
-// 네임스페이스 접두사 제거
-xml.parse(xmlStr, { stripTagPrefix: true });
-
-// 직렬화
-const xmlStr = xml.stringify(obj);
-// fast-xml-parser의 XmlBuilderOptions를 두 번째 인자로 전달 가능
-xml.stringify(obj, { format: true });
-```
-
----
-
-## path -- 경로 유틸리티
-
-POSIX 스타일 전용 경로 유틸리티. 브라우저 환경과 Capacitor 플러그인을 위해 설계되었다. Windows 백슬래시 경로는 지원하지 않는다.
-
-```typescript
-import { path } from "@simplysm/core-common";
-
-path.join("a", "b", "c.txt");       // "a/b/c.txt"
-path.basename("/a/b/file.ts");      // "file.ts"
-path.basename("/a/b/file.ts", ".ts"); // "file"
-path.extname("/a/b/file.ts");       // ".ts"
-path.extname("/a/b/.gitignore");    // "" (숨김 파일은 빈 문자열)
-```
-
----
-
-## wait -- 비동기 대기
-
-```typescript
-import { wait } from "@simplysm/core-common";
-
-// 조건 충족까지 대기
-await wait.until(() => isReady, 100, 50);
-// 100ms 간격으로 체크, 최대 50회 (초과 시 TimeoutError)
-// 첫 호출에서 true면 즉시 반환
-
-// 시간 대기
-await wait.time(1000); // 1초 대기
-```
-
----
-
-## err -- 에러 처리
-
-```typescript
-import { err } from "@simplysm/core-common";
-
-try { /* ... */ } catch (e) {
-  const message = err.message(e); // unknown 타입에서 안전하게 메시지 추출
-  // Error 인스턴스면 .message, 아니면 String(e)
-}
-```
-
----
-
-## dt -- 날짜 포맷
-
-```typescript
-import { dt } from "@simplysm/core-common";
-
-// 포맷 (DateTime/DateOnly/Time의 toFormatString이 내부적으로 사용)
-dt.format("yyyy-MM-dd", { year: 2024, month: 1, day: 15 });
-dt.format("HH:mm:ss", { hour: 14, minute: 30, second: 0 });
-
-// 월 정규화
-dt.normalizeMonth(2024, 13, 1);    // { year: 2025, month: 1, day: 1 }
-dt.normalizeMonth(2025, 2, 31);    // { year: 2025, month: 2, day: 28 }
-
-// 12시간 -> 24시간 변환
-dt.convert12To24(12, false);       // 0 (12 AM = 0시)
-dt.convert12To24(12, true);        // 12 (12 PM = 12시)
-dt.convert12To24(2, true);         // 14 (PM 2시 = 14시)
-```
-
----
-
-## primitive -- 프리미티브 타입 판별
-
-```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(new Uuid("..."));   // "Uuid"
-primitive.typeStr(new Uint8Array());  // "Bytes"
-```
-
----
-
-## transfer -- Worker 데이터 전송
-
-Worker `postMessage`용 직렬화/역직렬화. 순환 참조 감지(경로 포함 TypeError), 커스텀 타입 지원.
-
-지원 타입: Date, DateTime, DateOnly, Time, Uuid, RegExp, Error(cause/code/detail 포함), Uint8Array, Array, Map, Set, plain object.
-
-```typescript
-import { transfer } from "@simplysm/core-common";
-
-// Worker로 전송
-const { result, transferList } = transfer.encode(data);
-worker.postMessage(result, transferList);
-// Uint8Array의 ArrayBuffer가 자동으로 transferList에 추가됨
-// SharedArrayBuffer는 transferList에 포함되지 않음
-
-// Worker에서 수신
-const original = transfer.decode(event.data);
-```
-
----
-
-## 템플릿 문자열 태그
-
-IDE 구문 강조를 위한 태그 함수. 들여쓰기 자동 정규화 (공통 들여쓰기 제거, 앞뒤 빈 줄 제거).
-
-```typescript
-import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
-
-const query = tsql`
-  SELECT *
-  FROM Users
-  WHERE id = ${userId}
-`;
-
-const markup = html`
-  <div class="container">
-    <h1>${title}</h1>
-  </div>
-`;
-
-// js, ts, mysql, pgsql도 동일하게 동작
-```
-
----
-
-## ZipArchive -- ZIP 처리
-
-`@zip.js/zip.js` 기반 ZIP 파일 처리. 내부 캐싱으로 동일 파일 중복 해제를 방지한다.
-
-```typescript
-import { ZipArchive } from "@simplysm/core-common";
-
-// ZIP 읽기 (await using 지원)
-await using zip = new ZipArchive(blobOrBytes);
-const fileData = await zip.get("path/to/file.txt");
-const exists = await zip.exists("file.txt");
-
-// 전체 파일 추출 (진행률 콜백)
-const allFiles = await zip.extractAll((progress) => {
-  // progress: { fileName, totalSize, extractedSize }
-});
-// 반환: Map<string, Bytes | undefined>
-
-// ZIP 생성
-await using newZip = new ZipArchive();
-newZip.write("file1.txt", data1);
-newZip.write("dir/file2.txt", data2);
-const compressed = await newZip.compress();
-
-// 수동 정리 (await using을 사용하지 않는 경우)
-await zip.close();
-```
-
-| 메서드 | 시그니처 | 설명 |
-|--------|---------|------|
-| `get` | `get(fileName: string): Promise<Bytes \| undefined>` | 파일 추출 (캐시 사용) |
-| `exists` | `exists(fileName: string): Promise<boolean>` | 파일 존재 여부 |
-| `extractAll` | `extractAll(cb?): Promise<Map<string, Bytes \| undefined>>` | 전체 추출 |
-| `write` | `write(fileName: string, bytes: Bytes): void` | 파일 쓰기 (캐시에 저장) |
-| `compress` | `compress(): Promise<Bytes>` | 캐시 내용을 ZIP으로 압축 |
-| `close` | `close(): Promise<void>` | 리더 닫기 및 캐시 정리 |