@simplysm/core-common 14.0.49 → 14.0.51

package/docs/utils/str.md

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

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

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

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

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

@@ -0,0 +1,77 @@
+# 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();
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "14.0.49",
+  "version": "14.0.51",
   "description": "심플리즘 패키지 - 코어 (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",

package/src/errors/sd-error.ts

@@ -48,10 +48,7 @@ export class SdError extends Error {
 
     // captureStackTrace는 V8 엔진(Node.js, Chrome)에서만 사용 가능
     if ("captureStackTrace" in Error) {
-      (Error.captureStackTrace as (targetObject: object, constructorOpt?: Function) => void)(
-        this,
-        new.target,
-      );
+      (Error as unknown as Record<string, Function>)["captureStackTrace"](this, new.target);
     }
 
     // 원인 체인 stack을 현재 stack에 추가

package/src/utils/json.ts

@@ -131,7 +131,7 @@ export function stringify(
       // toJSON 메서드가 있으면 호출 (Date, DateTime 같은 커스텀 타입은 위에서 이미 처리됨)
       if (
         "toJSON" in currValue &&
-        typeof (currValue as { toJSON: unknown }).toJSON === "function"
+        typeof currValue.toJSON === "function"
       ) {
         const toJsonResult = (currValue as { toJSON: (key?: string) => unknown }).toJSON(key);
         seen.delete(currValue);

package/src/utils/obj.ts

@@ -866,8 +866,8 @@ function nullToUndefinedImpl<TObject>(obj: TObject, seen: WeakSet<object>): TObj
   }
 
   if (typeof obj === "object") {
-    if (seen.has(obj as object)) return obj;
-    seen.add(obj as object);
+    if (seen.has(obj)) return obj;
+    seen.add(obj);
     const objRec = obj as Record<string, unknown>;
     for (const key of Object.keys(obj)) {
       objRec[key] = nullToUndefinedImpl(objRec[key], seen);

package/docs/errors.md

@@ -1,82 +0,0 @@
-# Errors
-
-## `SdError`
-
-트리 구조 에러 체인을 지원하는 에러 클래스. ES2024 `cause` 속성을 활용한다.
-
-```typescript
-export class SdError extends Error {
-  override cause?: Error;
-
-  /** 원인 에러를 감싸서 생성. 메시지는 역순으로 결합됨 */
-  constructor(cause: Error, ...messages: string[]);
-  /** 메시지만으로 생성 */
-  constructor(...messages: string[]);
-}
-```
-
-생성자에 전달된 메시지들은 역순으로 결합된다. `cause`가 `Error` 인스턴스이면 그 메시지도 체인 끝에 추가된다.
-
-```typescript
-throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
-// message: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
-
-throw new SdError("잘못된 상태", "처리 불가");
-// message: "처리 불가 => 잘못된 상태"
-```
-
-## `ArgumentError`
-
-유효하지 않은 인자를 전달받았을 때 발생하는 에러. 인자 객체를 YAML 형식으로 메시지에 포함하여 디버깅을 용이하게 한다.
-
-```typescript
-export class ArgumentError extends SdError {
-  /** 기본 메시지("잘못된 인자입니다.")와 함께 인자 객체를 YAML 형식으로 출력 */
-  constructor(argObj: Record<string, unknown>);
-  /** 커스텀 메시지와 함께 인자 객체를 YAML 형식으로 출력 */
-  constructor(message: string, argObj: Record<string, unknown>);
-}
-```
-
-```typescript
-throw new ArgumentError({ userId: 123, name: null });
-// message: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
-
-throw new ArgumentError("잘못된 사용자", { userId: 123 });
-// message: "잘못된 사용자\n\nuserId: 123"
-```
-
-## `NotImplementedError`
-
-아직 구현되지 않은 기능이 호출되었을 때 발생하는 에러.
-
-```typescript
-export class NotImplementedError extends SdError {
-  constructor(message?: string);
-}
-```
-
-```typescript
-throw new NotImplementedError("서브클래스에서 구현 필요");
-// message: "미구현: 서브클래스에서 구현 필요"
-```
-
-## `TimeoutError`
-
-대기 시간이 초과되었을 때 발생하는 에러. `wait.until()`에서 최대 시도 횟수를 초과하면 자동으로 발생한다.
-
-```typescript
-export class TimeoutError extends SdError {
-  constructor(count?: number, message?: string);
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `count` | `number \| undefined` | 시도 횟수 |
-| `message` | `string \| undefined` | 추가 메시지 |
-
-```typescript
-throw new TimeoutError(50, "API 응답 대기 초과");
-// message: "대기 시간 초과(50회 시도): API 응답 대기 초과"
-```

package/docs/extensions.md

@@ -1,167 +0,0 @@
-# Extensions (Prototype)
-
-`@simplysm/core-common`을 import하면 `Array`, `Map`, `Set` 프로토타입 확장이 자동 등록된다.
-
-```typescript
-import "@simplysm/core-common"; // side-effect import — 확장 등록
-```
-
-## Array Extensions (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) => TNarrow[]` | 특정 타입의 요소만 필터 (`PrimitiveTypeStr` 또는 생성자) |
-| `mapAsync` | `(selector) => Promise<TResult[]>` | 비동기 매핑 (순차 실행) |
-| `filterAsync` | `(predicate) => Promise<T[]>` | 비동기 필터 (순차 실행) |
-| `mapMany` | `(selector?) => TResult[]` | 매핑 후 평탄화 (또는 중첩 배열 평탄화) |
-| `mapManyAsync` | `(selector?) => Promise<TResult[]>` | 비동기 매핑 후 평탄화 (순차 실행) |
-| `parallelAsync` | `(fn) => Promise<TResult[]>` | 비동기 병렬 처리 (`Promise.all` 사용) |
-| `groupBy` | `(keySelector, valueSelector?) => { key, values }[]` | key 기준 그룹화. 객체 key는 O(n²), 원시 key는 O(n) |
-| `toMap` | `(keySelector, valueSelector?) => Map<TKey, TValue>` | Map으로 변환. 중복 key이면 `ArgumentError` 발생 |
-| `toMapAsync` | `(keySelector, valueSelector?) => Promise<Map<TKey, TValue>>` | 비동기 Map으로 변환 |
-| `toArrayMap` | `(keySelector, valueSelector?) => Map<TKey, TValue[]>` | 그룹 Map으로 변환. O(n) 성능 |
-| `toSetMap` | `(keySelector, valueSelector?) => Map<TKey, Set<TValue>>` | 그룹 Set Map으로 변환 |
-| `toMapValues` | `(keySelector, valueSelector) => Map<TKey, TValue>` | 그룹화 후 그룹별로 값 변환 |
-| `toObject` | `(keySelector, valueSelector?) => Record<string, TValue>` | 일반 객체로 변환. 중복 key이면 `ArgumentError` 발생 |
-| `toTree` | `(keyProp, parentKey) => TreeArray<T>[]` | 평면 배열을 트리 구조로 변환. O(n) 복잡도 |
-| `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)[]` | 두 배열 병합 |
-| `sum` | `(selector?) => number` | 합계. 빈 배열이면 0 |
-| `min` | `(selector?) => T \| undefined` | 최솟값 |
-| `max` | `(selector?) => T \| undefined` | 최댓값 |
-| `shuffle` | `() => T[]` | 무작위 섞기 |
-
-### `toTree` 상세
-
-```typescript
-interface Item {
-  id: number;
-  parentId?: number;
-  name: string;
-}
-
-const items: Item[] = [
-  { id: 1, name: "root" },
-  { id: 2, parentId: 1, name: "child1" },
-  { id: 3, parentId: 2, name: "grandchild" },
-];
-
-const tree = items.toTree("id", "parentId");
-// [{ id: 1, name: "root", children: [
-//   { id: 2, name: "child1", children: [
-//     { id: 3, name: "grandchild", children: [] }
-//   ]}
-// ]}]
-```
-
-### `diffs` 상세
-
-```typescript
-const diffs = newItems.diffs(oldItems, { keys: ["id"], excludes: ["updatedAt"] });
-// ArrayDiffsResult: { source: undefined, target: item } (INSERT)
-//                  { source: item, target: undefined } (DELETE)
-//                  { source: item, target: item }       (UPDATE)
-```
-
-### `oneWayDiffs` 상세
-
-```typescript
-const diffs = newItems.oneWayDiffs(orgItems, "id", { includeSame: false });
-// ArrayOneWayDiffResult: { type: "create", item, orgItem: undefined }
-//                        { type: "update", item, orgItem }
-//                        { type: "same", item, orgItem }
-```
-
-## Array Extensions (Mutable)
-
-원본 배열을 직접 변경한다.
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `insert` | `(index, ...items) => this` | 지정 위치에 항목 삽입 |
-| `remove` | `(item \| selector) => this` | 항목 또는 조건에 맞는 항목 제거 |
-| `toggle` | `(item) => this` | 항목 토글 (있으면 제거, 없으면 추가) |
-| `clear` | `() => this` | 배열 비우기 |
-| `distinctThis` | `(options?) => T[]` | 원본 배열에서 중복 제거 |
-| `orderByThis` | `(selector?) => T[]` | 원본 배열을 오름차순 정렬 |
-| `orderByDescThis` | `(selector?) => T[]` | 원본 배열을 내림차순 정렬 |
-
-## Map Extensions
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `getOrCreate` | `(key, newValue \| newValueFn) => V` | key가 없으면 새 값을 설정하고 반환. V 타입이 함수이면 팩토리로 감싸야 함 |
-| `update` | `(key, updateFn) => void` | 기존 값을 기반으로 업데이트. key가 없어도 `updateFn`이 호출됨 |
-
-```typescript
-const map = new Map<string, number[]>();
-const arr = map.getOrCreate("key", []); // 없으면 [] 설정 후 반환
-
-const countMap = new Map<string, number>();
-countMap.update("key", (v) => (v ?? 0) + 1); // 카운터 증가
-```
-
-## Set Extensions
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `adds` | `(...values: T[]) => this` | 여러 값을 한 번에 추가 |
-| `toggle` | `(value, addOrDel?) => this` | 값 토글. `addOrDel`로 강제 추가/제거 가능 |
-
-```typescript
-const set = new Set<number>([1, 2, 3]);
-set.adds(4, 5, 6); // 여러 항목 추가
-set.toggle(2); // 2가 있으므로 제거 → {1, 3, 4, 5, 6}
-set.toggle(99, "add"); // 강제 추가
-set.toggle(99, "del"); // 강제 제거
-```
-
-## Exported Types
-
-### `ArrayDiffsResult<TOriginal, TOther>`
-
-`diffs()` 메서드의 반환 타입. discriminated union으로 `source`와 `target` 중 하나가 `undefined`이면 INSERT/DELETE, 둘 다 있으면 UPDATE.
-
-```typescript
-export type ArrayDiffsResult<TOriginal, TOther> =
-  | { source: undefined; target: TOther }    // INSERT
-  | { source: TOriginal; target: undefined } // DELETE
-  | { source: TOriginal; target: TOther };   // UPDATE
-```
-
-### `ArrayOneWayDiffResult<TItem>`
-
-`oneWayDiffs()` 메서드의 반환 타입. `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`, `orderByThis`, `orderByDescThis`의 selector 반환 타입.
-
-```typescript
-export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
-```