@simplysm/core-common 14.0.51 → 14.0.53

package/docs/utils/num.md

@@ -1,56 +0,0 @@
-# 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

@@ -1,107 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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

@@ -1,28 +0,0 @@
-# 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"
-```

package/docs/utils/str.md

@@ -1,63 +0,0 @@
-# str
-
-문자열 유틸리티 네임스페이스.
-
-```typescript
-import { str } from "@simplysm/core-common";
-```
-
-## Functions
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `getKoreanSuffix` | `(text, type) => string` | 받침 유무에 따라 적절한 한국어 조사 반환 |
-| `replaceFullWidth` | `(str) => string` | 전각 문자(Ａ-Ｚ, ａ-ｚ, ０-９, 전각 공백, 전각 괄호)를 반각 문자로 변환 |
-| `toPascalCase` | `(str) => string` | PascalCase로 변환 (`-`, `_`, `.` 구분자 지원) |
-| `toCamelCase` | `(str) => string` | camelCase로 변환 |
-| `toKebabCase` | `(str) => string` | kebab-case로 변환 |
-| `toSnakeCase` | `(str) => string` | snake_case로 변환 |
-| `isNullOrEmpty` | `(str: string \| undefined) => str is "" \| undefined` | 타입 가드: undefined, null, 빈 문자열이면 true |
-| `insert` | `(str, index, insertString) => string` | 특정 위치에 문자열 삽입 |
-
-## `getKoreanSuffix` — 조사 타입
-
-| `type` | 받침 있음 | 받침 없음 | 설명 |
-|--------|----------|----------|------|
-| `"을"` | 을 | 를 | 목적격 조사 |
-| `"은"` | 은 | 는 | 주격 보조사 |
-| `"이"` | 이 | 가 | 주격 조사 |
-| `"와"` | 과 | 와 | 접속 조사 |
-| `"랑"` | 이랑 | 랑 | 접속 조사 |
-| `"로"` | 으로 (ㄹ 받침은 "로") | 로 | 도구격 조사 |
-| `"라"` | 이라 | 라 | 서술격 조사 |
-
-## Usage
-
-```typescript
-import { str } from "@simplysm/core-common";
-
-// 한국어 조사
-str.getKoreanSuffix("Apple", "을"); // "를"
-str.getKoreanSuffix("책", "이");    // "이"
-str.getKoreanSuffix("파일", "을");  // "을"
-
-// 전각 → 반각
-str.replaceFullWidth("Ａ１２３"); // "A123"
-
-// 케이스 변환
-str.toPascalCase("hello-world"); // "HelloWorld"
-str.toCamelCase("HelloWorld");   // "helloWorld"
-str.toKebabCase("HelloWorld");   // "hello-world"
-str.toSnakeCase("HelloWorld");   // "hello_world"
-
-// null/empty 검사 (타입 가드)
-const name: string | undefined = getValue();
-if (str.isNullOrEmpty(name)) {
-  // name: "" | undefined
-} else {
-  // name: string (non-empty)
-}
-
-// 문자열 삽입
-str.insert("Hello World", 5, ","); // "Hello, World"
-```

package/docs/utils/template-strings.md

@@ -1,49 +0,0 @@
-# Template Strings
-
-IDE 코드 하이라이팅 지원용 태그드 템플릿 리터럴 함수. 실제 동작은 문자열 결합 + 들여쓰기 정규화(앞뒤 빈 줄 제거, 공통 들여쓰기 제거)이다.
-
-```typescript
-export function js(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function html(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-직접 named import로 사용한다 (네임스페이스 아님):
-
-```typescript
-import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
-```
-
-## Functions
-
-| Function | Description |
-|----------|-------------|
-| `js` | JavaScript 코드 하이라이팅용 |
-| `ts` | TypeScript 코드 하이라이팅용 |
-| `html` | HTML 마크업 하이라이팅용 |
-| `tsql` | MSSQL T-SQL 하이라이팅용 |
-| `mysql` | MySQL SQL 하이라이팅용 |
-| `pgsql` | PostgreSQL SQL 하이라이팅용 |
-
-## Usage
-
-```typescript
-import { ts, tsql } from "@simplysm/core-common";
-
-const code = ts`
-  interface User {
-    name: string;
-    age: number;
-  }
-`;
-// "interface User {\n  name: string;\n  age: number;\n}"
-
-const query = tsql`
-  SELECT TOP 10 *
-  FROM Users
-  WHERE Name = ${keyword}
-`;
-```

package/docs/utils/transfer.md

@@ -1,35 +0,0 @@
-# transfer
-
-Worker 간 전송 가능한 객체 변환 유틸리티 네임스페이스. `structuredClone`이 지원하지 않는 커스텀 타입을 처리한다.
-
-```typescript
-import { transfer } from "@simplysm/core-common";
-```
-
-## Functions
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `encode` | `(obj) => { result: unknown; transferList: ArrayBuffer[] }` | Simplysm 타입을 포함한 객체를 Worker 전송 가능한 형태로 변환. 순환 참조 시 `TypeError` 발생 |
-| `decode` | `(obj) => unknown` | `encode()`로 변환된 객체를 원래 Simplysm 타입으로 복원 |
-
-## 지원 타입
-
-`Date`, `DateTime`, `DateOnly`, `Time`, `Uuid`, `RegExp`, `Error` (cause, code, detail 포함), `Uint8Array`, `Array`, `Map`, `Set`, 일반 객체
-
-`Uint8Array`는 zero-copy 전송을 위해 `ArrayBuffer`를 `transferList`에 추가한다. `SharedArrayBuffer`는 이미 공유 메모리이므로 `transferList`에 추가하지 않는다.
-
-## Usage
-
-```typescript
-import { transfer } from "@simplysm/core-common";
-
-// Worker로 데이터 전송
-const { result, transferList } = transfer.encode(data);
-worker.postMessage(result, transferList);
-
-// Worker에서 데이터 수신
-self.onmessage = (event) => {
-  const decoded = transfer.decode(event.data);
-};
-```

package/docs/utils/wait.md

@@ -1,35 +0,0 @@
-# wait
-
-비동기 대기 유틸리티 네임스페이스.
-
-```typescript
-import { wait } from "@simplysm/core-common";
-```
-
-## Functions
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `until` | `(forwarder, milliseconds?, maxCount?) => Promise<void>` | 조건이 true가 될 때까지 대기 |
-| `time` | `(millisecond: number) => Promise<void>` | 지정된 시간만큼 대기 |
-
-## `until` — Parameters
-
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `forwarder` | `() => boolean \| Promise<boolean>` | - | 조건 함수. 첫 번째 호출에서 true이면 즉시 반환 |
-| `milliseconds` | `number` | `100` | 확인 간격 (ms) |
-| `maxCount` | `number` | `undefined` | 최대 시도 횟수. 초과 시 `TimeoutError` 발생. 미지정 시 무제한 |
-
-## Usage
-
-```typescript
-import { wait } from "@simplysm/core-common";
-
-// 조건 대기
-await wait.until(() => isReady);
-await wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회
-
-// 시간 대기
-await wait.time(1000); // 1초 대기
-```

package/docs/utils/xml.md

@@ -1,49 +0,0 @@
-# xml
-
-XML 변환 유틸리티 네임스페이스. `fast-xml-parser` 기반.
-
-```typescript
-import { xml } from "@simplysm/core-common";
-```
-
-## Functions
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `parse` | `(str, options?) => unknown` | XML 문자열을 객체로 파싱 |
-| `stringify` | `(obj, options?) => string` | 객체를 XML 문자열로 직렬화 |
-
-## `parse` — 파싱 규칙
-
-- 속성: `$` 객체에 그룹화
-- 텍스트 노드: `_` key에 저장
-- 자식 요소: 배열로 변환 (루트 요소 제외)
-
-## `parse` — options
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `stripTagPrefix` | `boolean` | 태그 접두사(네임스페이스) 제거 여부. 속성은 접두사 유지 |
-
-## Usage
-
-```typescript
-import { xml } from "@simplysm/core-common";
-
-// 파싱
-const result = xml.parse('<root id="1"><item>hello</item></root>');
-// { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
-
-// 네임스페이스 제거
-const clean = xml.parse('<ns:root><ns:item>hello</ns:item></ns:root>', { stripTagPrefix: true });
-// { root: { item: [{ _: "hello" }] } }
-
-// 직렬화
-const str = xml.stringify({
-  root: {
-    $: { id: "1" },
-    item: [{ _: "hello" }, { _: "world" }],
-  },
-});
-// '<root id="1"><item>hello</item><item>world</item></root>'
-```

package/docs/utils/zip-archive.md

@@ -1,77 +0,0 @@
-# ZipArchive
-
-ZIP 파일 처리 클래스. ZIP 파일의 읽기, 쓰기, 압축, 해제를 처리한다. 동일 파일의 중복 해제를 방지하기 위해 내부 캐싱을 사용한다. `@zip.js/zip.js` 기반.
-
-```typescript
-import { ZipArchive } from "@simplysm/core-common";
-
-export class ZipArchive {
-  constructor(data?: Blob | Bytes);
-}
-```
-
-## Members
-
-| Member | Kind | Type | Description |
-|--------|------|------|-------------|
-| `extractAll` | method | `(progressCallback?) => Promise<Map<string, Bytes \| undefined>>` | 모든 파일 추출 |
-| `get` | method | `(fileName: string) => Promise<Bytes \| undefined>` | 특정 파일 추출. 내부 캐시 활용 |
-| `exists` | method | `(fileName: string) => Promise<boolean>` | 파일 존재 여부 확인 |
-| `write` | method | `(fileName: string, bytes: Bytes) => void` | 파일 쓰기 (캐시에 저장) |
-| `compress` | method | `() => Promise<Bytes>` | 캐시된 파일을 ZIP으로 압축 |
-| `close` | method | `() => Promise<void>` | 리더 닫기 및 캐시 비우기 |
-
-## Related Types
-
-### `ZipArchiveProgress`
-
-`extractAll()` 진행률 콜백의 파라미터 타입:
-
-```typescript
-export interface ZipArchiveProgress {
-  fileName: string;
-  totalSize: number;
-  extractedSize: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `fileName` | `string` | 현재 처리 중인 파일명 |
-| `totalSize` | `number` | 전체 파일 크기 (바이트) |
-| `extractedSize` | `number` | 현재까지 추출된 크기 (바이트) |
-
-## Usage
-
-```typescript
-import { ZipArchive } from "@simplysm/core-common";
-
-// ZIP 파일 읽기
-const archive = new ZipArchive(zipBytes);
-try {
-  const content = await archive.get("file.txt");
-} finally {
-  await archive.close();
-}
-
-// ZIP 파일 생성
-const newArchive = new ZipArchive();
-try {
-  newArchive.write("file.txt", textBytes);
-  newArchive.write("data.json", jsonBytes);
-  const zipBytes = await newArchive.compress();
-} finally {
-  await newArchive.close();
-}
-
-// 모든 파일 추출 (진행률 보고 포함)
-const archive2 = new ZipArchive(zipBytes);
-try {
-  const files = await archive2.extractAll((progress) => {
-    const pct = (progress.extractedSize / progress.totalSize * 100).toFixed(1);
-    console.log(`${progress.fileName}: ${pct}%`);
-  });
-} finally {
-  await archive2.close();
-}
-```