@simplysm/core-common 13.0.16 → 13.0.20

package/README.md

@@ -1,7 +1,6 @@
 # @simplysm/core-common
 
-A common utility package for the Simplysm framework.
-As a neutral base module usable in both Node.js and browser environments, it provides date/time types, error classes, object/array/string utilities, JSON serialization, ZIP processing, prototype extensions, and more.
+A common utility package for the Simplysm framework. As a neutral base module usable in both Node.js and browser environments, it provides date/time types, error classes, object/array/string utilities, JSON serialization, ZIP processing, prototype extensions, and more.
 
 ## Installation
 
@@ -11,7 +10,7 @@ npm install @simplysm/core-common
 pnpm add @simplysm/core-common
 ```
 
-## Initialization
+### Initialization
 
 Import the package at your application entry point (e.g., `index.ts`, `main.ts`):
 
@@ -22,61 +21,16 @@ import "@simplysm/core-common";
 This import globally activates Array, Map, and Set prototype extensions.
 To use extension methods (`getOrCreate()`, `toggle()`, etc.), you must import this at app startup.
 
-## Caveats
-
-### Prototype Extension Conflicts
-
-This package extends Array, Map, and Set prototypes.
-Conflicts may occur when used with other libraries that extend the same method names.
-In case of conflict, the last defined implementation is applied based on load order.
-
-### Timezone Handling
-
-When using `DateOnly.parse()`, `DateTime.parse()`:
-- `yyyy-MM-dd`, `yyyyMMdd` format: parse directly from string (no timezone influence)
-- ISO 8601 format (`2024-01-15T00:00:00Z`): interpret as UTC then convert to local
-
-When server and client timezones differ, actively use `yyyy-MM-dd` format.
-
-### Memory Management (LazyGcMap)
-
-`LazyGcMap` has an internal GC timer, so it must be cleaned up.
-
-```typescript
-// using statement (recommended)
-// gcInterval: GC execution interval (ms), expireTime: item expiration time (ms)
-using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds
-
-// Or explicit dispose() call
-const map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds
-try {
-  // ... use
-} finally {
-  map.dispose();
-}
-```
-
-### jsonStringify's __type__ Reserved Word
-
-`jsonStringify`/`jsonParse` uses objects with `__type__` and `data` keys for type restoration.
-Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may be unintentionally type-converted.
-
-### Circular References
-
-- `objClone`: supports circular references (tracked with WeakMap)
-- `jsonStringify`: throws TypeError on circular reference
-- `transferableEncode`: throws TypeError on circular reference (includes path information)
+## Main Modules
 
----
-
-## Errors
+### Errors
 
 - [`SdError`](docs/types.md#sderror) - Base error class with cause chain tracking
 - [`ArgumentError`](docs/types.md#argumenterror) - Argument validation error with YAML formatting
 - [`NotImplementedError`](docs/types.md#notimplementederror) - Indicates unimplemented functionality
 - [`TimeoutError`](docs/types.md#timeouterror) - Timeout error
 
-## Custom Types
+### Custom Types
 
 - [`DateTime`](docs/types.md#datetime) - Date + time (millisecond precision, local timezone)
 - [`DateOnly`](docs/types.md#dateonly) - Date only (no time)
@@ -84,14 +38,14 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`Uuid`](docs/types.md#uuid) - UUID v4 (cryptographically secure)
 - [`LazyGcMap`](docs/types.md#lazygcmap) - Map with auto-expiration (LRU style)
 
-## Features
+### Features
 
 - [`DebounceQueue`](docs/features.md#debouncequeue) - Async debounce queue (executes only last request)
 - [`SerialQueue`](docs/features.md#serialqueue) - Async serial queue (sequential execution)
 - [`EventEmitter`](docs/features.md#eventemitter) - EventTarget wrapper with type-safe events
 - [`ZipArchive`](docs/features.md#ziparchive) - ZIP file compression/decompression utility
 
-## Object Utilities
+### Object Utilities
 
 - [`objClone`](docs/utils.md#objclone) - Deep clone (supports circular references, custom types)
 - [`objEqual`](docs/utils.md#objequal) - Deep comparison with options
@@ -107,17 +61,17 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`objFromEntries`](docs/utils.md#objfromentries) - Type-safe `Object.fromEntries`
 - [`objMap`](docs/utils.md#objmap) - Transform each entry of object
 
-## JSON Utilities
+### JSON Utilities
 
 - [`jsonStringify`](docs/utils.md#jsonstringify) - JSON serialization with custom type support
 - [`jsonParse`](docs/utils.md#jsonparse) - JSON deserialization with custom type restoration
 
-## XML Utilities
+### XML Utilities
 
 - [`xmlParse`](docs/utils.md#xmlparse) - Parse XML string to object
 - [`xmlStringify`](docs/utils.md#xmlstringify) - Serialize object to XML string
 
-## String Utilities
+### String Utilities
 
 - [`strGetSuffix`](docs/utils.md#strgetsuffix) - Korean postposition handling
 - [`strReplaceFullWidth`](docs/utils.md#strreplacefullwidth) - Convert full-width to half-width
@@ -128,7 +82,7 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`strIsNullOrEmpty`](docs/utils.md#strisnullorempty) - Check for undefined/null/empty (type guard)
 - [`strInsert`](docs/utils.md#strinsert) - Insert at position in string
 
-## Number Utilities
+### Number Utilities
 
 - [`numParseInt`](docs/utils.md#numparseint) - Parse string to integer
 - [`numParseFloat`](docs/utils.md#numparsefloat) - Parse string to float
@@ -136,12 +90,12 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`numFormat`](docs/utils.md#numformat) - Thousands separator formatting
 - [`numIsNullOrEmpty`](docs/utils.md#numisnullorempty) - Check for undefined/null/0 (type guard)
 
-## Date/Time Formatting
+### Date/Time Formatting
 
 - [`formatDate`](docs/utils.md#formatdate) - Convert date/time to formatted string
 - [`normalizeMonth`](docs/utils.md#normalizemonth) - Normalize year/month/day when setting month
 
-## Byte Utilities
+### Byte Utilities
 
 - [`bytesConcat`](docs/utils.md#bytesconcat) - Concatenate multiple Uint8Arrays
 - [`bytesToHex`](docs/utils.md#bytestohex) - Convert Uint8Array to hex string
@@ -149,23 +103,23 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`bytesToBase64`](docs/utils.md#bytestobase64) - Convert Uint8Array to base64 string
 - [`bytesFromBase64`](docs/utils.md#bytesfrombase64) - Convert base64 string to Uint8Array
 
-## Async Wait
+### Async Wait
 
 - [`waitTime`](docs/utils.md#waittime) - Wait for specified time
 - [`waitUntil`](docs/utils.md#waituntil) - Wait until condition is true
 
-## Worker Data Conversion
+### Worker Data Conversion
 
 - [`transferableEncode`](docs/utils.md#transferableencode) - Serialize custom types for Worker transfer
 - [`transferableDecode`](docs/utils.md#transferabledecode) - Deserialize Worker data to custom types
 
-## Path Utilities
+### Path Utilities
 
 - [`pathJoin`](docs/utils.md#pathjoin) - Combine paths (POSIX-style only)
 - [`pathBasename`](docs/utils.md#pathbasename) - Extract filename
 - [`pathExtname`](docs/utils.md#pathextname) - Extract extension
 
-## Template Literal Tags
+### Template Literal Tags
 
 - [`js`](docs/utils.md#js) - JavaScript code highlighting
 - [`ts`](docs/utils.md#ts) - TypeScript code highlighting
@@ -174,44 +128,30 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`mysql`](docs/utils.md#mysql) - MySQL SQL highlighting
 - [`pgsql`](docs/utils.md#pgsql) - PostgreSQL SQL highlighting
 
-## Other Utilities
+### Other Utilities
 
 - [`getPrimitiveTypeStr`](docs/utils.md#getprimitivetypestr) - Infer `PrimitiveTypeStr` from runtime value
 - [`env`](docs/utils.md#env) - Environment variable object
 
-## Type Utilities
-
-- [`Bytes`](docs/types.md#bytes) - Alias for `Uint8Array`
-- [`PrimitiveTypeStr`](docs/types.md#primitivetypestr) - Primitive type string keys
-- [`PrimitiveTypeMap`](docs/types.md#primitivetypemap) - Mapping from type string to type
-- [`PrimitiveType`](docs/types.md#primitivetype) - Union of all primitive types
-- [`DeepPartial`](docs/types.md#deeppartial) - Recursively convert properties to optional
-- [`Type`](docs/types.md#type) - Constructor type
-- [`ObjUndefToOptional`](docs/types.md#objundeftooptional) - Convert `undefined` properties to optional
-- [`ObjOptionalToUndef`](docs/types.md#objoptionaltoundef) - Convert optional properties to `required + undefined`
-- [`ArrayDiffsResult`](docs/types.md#arraydiffsresult) - Result type of `Array.diffs()`
-- [`ArrayDiffs2Result`](docs/types.md#arraydiffs2result) - Result type of `Array.oneWayDiffs()`
-- [`TreeArray`](docs/types.md#treearray) - Result type of `Array.toTree()`
-
-## Array Extensions
+### Array Extensions
 
-### Query
+#### Query
 - [`single`](docs/extensions.md#single) - Return single element (error if 2+)
 - [`first`](docs/extensions.md#first) - Return first element
 - [`last`](docs/extensions.md#last) - Return last element
 
-### Filtering
+#### Filtering
 - [`filterExists`](docs/extensions.md#filterexists) - Remove `null`/`undefined`
 - [`ofType`](docs/extensions.md#oftype) - Filter by type
 - [`filterAsync`](docs/extensions.md#filterasync) - Async filter
 
-### Mapping/Transformation
+#### Mapping/Transformation
 - [`mapAsync`](docs/extensions.md#mapasync) - Async mapping (sequential)
 - [`mapMany`](docs/extensions.md#mapmany) - flat + filterExists
 - [`mapManyAsync`](docs/extensions.md#mapmanyasync) - Async mapMany
 - [`parallelAsync`](docs/extensions.md#parallelasync) - Parallel async mapping
 
-### Grouping
+#### Grouping
 - [`groupBy`](docs/extensions.md#groupby) - Group by key
 - [`toMap`](docs/extensions.md#tomap) - Convert to Map
 - [`toMapAsync`](docs/extensions.md#tomapasync) - Async Map conversion
@@ -221,43 +161,102 @@ Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may
 - [`toObject`](docs/extensions.md#toobject) - Convert to `Record<string, V>`
 - [`toTree`](docs/extensions.md#totree) - Convert to tree structure
 
-### Deduplication
+#### Deduplication
 - [`distinct`](docs/extensions.md#distinct) - Remove duplicates (new array)
 - [`distinctThis`](docs/extensions.md#distinctthis) - Remove duplicates (modify original)
 
-### Sorting
+#### Sorting
 - [`orderBy`](docs/extensions.md#orderby) - Ascending sort (new array)
 - [`orderByDesc`](docs/extensions.md#orderbydesc) - Descending sort (new array)
 - [`orderByThis`](docs/extensions.md#orderbythis) - Ascending sort (modify original)
 - [`orderByDescThis`](docs/extensions.md#orderbydescthis) - Descending sort (modify original)
 
-### Comparison/Merging
+#### Comparison/Merging
 - [`diffs`](docs/extensions.md#diffs) - Compare differences between arrays
 - [`oneWayDiffs`](docs/extensions.md#onewaydiffs) - One-way diff comparison
 - [`merge`](docs/extensions.md#merge) - Merge arrays
 
-### Aggregation
+#### Aggregation
 - [`sum`](docs/extensions.md#sum) - Sum
 - [`min`](docs/extensions.md#min) - Minimum
 - [`max`](docs/extensions.md#max) - Maximum
 
-### Mutation
+#### Mutation
 - [`insert`](docs/extensions.md#insert) - Insert at specific position
 - [`remove`](docs/extensions.md#remove) - Remove item
 - [`toggle`](docs/extensions.md#toggle) - Toggle item
 - [`clear`](docs/extensions.md#clear) - Remove all items
 - [`shuffle`](docs/extensions.md#shuffle) - Shuffle array
 
-## Map Extensions
+### Map Extensions
 
 - [`getOrCreate`](docs/extensions.md#getorcreate) - Get or create and return value
 - [`update`](docs/extensions.md#update) - Update value using function
 
-## Set Extensions
+### Set Extensions
 
 - [`adds`](docs/extensions.md#adds) - Add multiple values at once
 - [`toggle`](docs/extensions.md#toggle-1) - Toggle value (add/remove)
 
+## Types
+
+- [`Bytes`](docs/types.md#bytes) - Alias for `Uint8Array`
+- [`PrimitiveTypeStr`](docs/types.md#primitivetypestr) - Primitive type string keys
+- [`PrimitiveTypeMap`](docs/types.md#primitivetypemap) - Mapping from type string to type
+- [`PrimitiveType`](docs/types.md#primitivetype) - Union of all primitive types
+- [`DeepPartial`](docs/types.md#deeppartial) - Recursively convert properties to optional
+- [`Type`](docs/types.md#type) - Constructor type
+- [`ObjUndefToOptional`](docs/types.md#objundeftooptional) - Convert `undefined` properties to optional
+- [`ObjOptionalToUndef`](docs/types.md#objoptionaltoundef) - Convert optional properties to `required + undefined`
+- [`ArrayDiffsResult`](docs/types.md#arraydiffsresult) - Result type of `Array.diffs()`
+- [`ArrayDiffs2Result`](docs/types.md#arraydiffs2result) - Result type of `Array.oneWayDiffs()`
+- [`TreeArray`](docs/types.md#treearray) - Result type of `Array.toTree()`
+
+## Caveats
+
+### Prototype Extension Conflicts
+
+This package extends Array, Map, and Set prototypes.
+Conflicts may occur when used with other libraries that extend the same method names.
+In case of conflict, the last defined implementation is applied based on load order.
+
+### Timezone Handling
+
+When using `DateOnly.parse()`, `DateTime.parse()`:
+- `yyyy-MM-dd`, `yyyyMMdd` format: parse directly from string (no timezone influence)
+- ISO 8601 format (`2024-01-15T00:00:00Z`): interpret as UTC then convert to local
+
+When server and client timezones differ, actively use `yyyy-MM-dd` format.
+
+### Memory Management (LazyGcMap)
+
+`LazyGcMap` has an internal GC timer, so it must be cleaned up.
+
+```typescript
+// using statement (recommended)
+// gcInterval: GC execution interval (ms), expireTime: item expiration time (ms)
+using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds
+
+// Or explicit dispose() call
+const map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds
+try {
+  // ... use
+} finally {
+  map.dispose();
+}
+```
+
+### jsonStringify's __type__ Reserved Word
+
+`jsonStringify`/`jsonParse` uses objects with `__type__` and `data` keys for type restoration.
+Be careful as user data in the form `{ __type__: "DateTime", data: "..." }` may be unintentionally type-converted.
+
+### Circular References
+
+- `objClone`: supports circular references (tracked with WeakMap)
+- `jsonStringify`: throws TypeError on circular reference
+- `transferableEncode`: throws TypeError on circular reference (includes path information)
+
 ## License
 
 Apache-2.0

package/dist/common.types.d.ts

@@ -51,8 +51,8 @@ export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
  * };
  * ```
  */
-export type DeepPartial<T> = Partial<{
-    [K in keyof T]: T[K] extends PrimitiveType ? T[K] : DeepPartial<T[K]>;
+export type DeepPartial<TObject> = Partial<{
+    [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
 }>;
 /**
  * 생성자 타입
@@ -68,7 +68,7 @@ export type DeepPartial<T> = Partial<{
  * class MyClass { name = "test"; }
  * const instance = create(MyClass); // MyClass 인스턴스
  */
-export interface Type<T> extends Function {
-    new (...args: unknown[]): T;
+export interface Type<TInstance> extends Function {
+    new (...args: unknown[]): TInstance;
 }
 //# sourceMappingURL=common.types.d.ts.map

package/dist/common.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.types.d.ts","sourceRoot":"","sources":["../src/common.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAIpC;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAM/B;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC;KAClC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,QAAQ;IACvC,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;CAC7B"}
+{"version":3,"file":"common.types.d.ts","sourceRoot":"","sources":["../src/common.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAIpC;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAM/B;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,OAAO,CAAC;KACxC,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9F,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,IAAI,CAAC,SAAS,CAAE,SAAQ,QAAQ;IAC/C,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;CACrC"}

package/dist/extensions/arr-ext.types.d.ts

@@ -5,54 +5,54 @@ import type { PrimitiveTypeMap, PrimitiveTypeStr, Type } from "../common.types";
 import type { DateTime } from "../types/date-time";
 import type { DateOnly } from "../types/date-only";
 import type { Time } from "../types/time";
-export interface ReadonlyArrayExt<T> {
+export interface ReadonlyArrayExt<TItem> {
     /**
      * 조건에 맞는 단일 요소 반환
      * @param predicate 필터 조건 (생략 시 배열 전체 대상)
      * @returns 요소가 없으면 undefined
      * @throws ArgumentError 조건에 맞는 요소가 2개 이상이면 발생
      */
-    single(predicate?: (item: T, index: number) => boolean): T | undefined;
+    single(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
     /**
      * 첫 번째 요소 반환
      * @param predicate 필터 조건 (생략 시 첫 번째 요소 반환)
      * @returns 요소가 없으면 undefined
      */
-    first(predicate?: (item: T, index: number) => boolean): T | undefined;
+    first(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
     /** 비동기 필터 (순차 실행) */
-    filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+    filterAsync(predicate: (item: TItem, index: number) => Promise<boolean>): Promise<TItem[]>;
     /**
      * 마지막 요소 반환
      * @param predicate 필터 조건 (생략 시 마지막 요소 반환)
      * @returns 요소가 없으면 undefined
      */
-    last(predicate?: (item: T, index: number) => boolean): T | undefined;
+    last(predicate?: (item: TItem, index: number) => boolean): TItem | undefined;
     /** null/undefined 제거 */
-    filterExists(): NonNullable<T>[];
+    filterExists(): NonNullable<TItem>[];
     /** 특정 타입의 요소만 필터링 (PrimitiveTypeStr 또는 생성자 타입) */
-    ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
-    ofType<N extends T>(type: Type<N>): N[];
+    ofType<K extends PrimitiveTypeStr>(type: K): Extract<TItem, PrimitiveTypeMap[K]>[];
+    ofType<N extends TItem>(type: Type<N>): N[];
     /** 비동기 매핑 (순차 실행) */
-    mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+    mapAsync<R>(selector: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
     /** 중첩 배열 평탄화 */
-    mapMany(): T extends readonly (infer U)[] ? U[] : T;
+    mapMany(): TItem extends readonly (infer U)[] ? U[] : TItem;
     /** 매핑 후 평탄화 */
-    mapMany<R>(selector: (item: T, index: number) => R[]): R[];
+    mapMany<R>(selector: (item: TItem, index: number) => R[]): R[];
     /** 비동기 매핑 후 평탄화 (순차 실행) */
-    mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+    mapManyAsync<R>(selector: (item: TItem, index: number) => Promise<R[]>): Promise<R[]>;
     /**
      * 비동기 병렬 처리 (Promise.all 사용)
      * @note 하나라도 reject되면 전체가 fail-fast로 reject됨 (Promise.all 동작)
      */
-    parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+    parallelAsync<R>(fn: (item: TItem, index: number) => Promise<R>): Promise<R[]>;
     /**
      * 키 기준 그룹화
      * @param keySelector 그룹 키 선택 함수
      * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
      */
-    groupBy<K>(keySelector: (item: T, index: number) => K): {
+    groupBy<K>(keySelector: (item: TItem, index: number) => K): {
         key: K;
-        values: T[];
+        values: TItem[];
     }[];
     /**
      * 키 기준 그룹화 (값 변환 포함)
@@ -60,21 +60,21 @@ export interface ReadonlyArrayExt<T> {
      * @param valueSelector 값 변환 함수
      * @note O(n²) 복잡도 (객체 키 지원을 위해 깊은 비교 사용). primitive 키만 필요하면 toArrayMap()이 O(n)으로 더 효율적
      */
-    groupBy<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): {
+    groupBy<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (item: TItem, index: number) => V): {
         key: K;
         values: V[];
     }[];
-    toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
-    toMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V>;
-    toMapAsync<K>(keySelector: (item: T, index: number) => Promise<K>): Promise<Map<K, T>>;
-    toMapAsync<K, V>(keySelector: (item: T, index: number) => Promise<K> | K, valueSelector: (item: T, index: number) => Promise<V> | V): Promise<Map<K, V>>;
-    toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
-    toArrayMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, V[]>;
-    toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
-    toSetMap<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (item: T, index: number) => V): Map<K, Set<V>>;
-    toMapValues<K, V>(keySelector: (item: T, index: number) => K, valueSelector: (items: T[]) => V): Map<K, V>;
-    toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
-    toObject<V>(keySelector: (item: T, index: number) => string, valueSelector: (item: T, index: number) => V): Record<string, V>;
+    toMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, TItem>;
+    toMap<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (item: TItem, index: number) => V): Map<K, V>;
+    toMapAsync<K>(keySelector: (item: TItem, index: number) => Promise<K>): Promise<Map<K, TItem>>;
+    toMapAsync<K, V>(keySelector: (item: TItem, index: number) => Promise<K> | K, valueSelector: (item: TItem, index: number) => Promise<V> | V): Promise<Map<K, V>>;
+    toArrayMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, TItem[]>;
+    toArrayMap<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (item: TItem, index: number) => V): Map<K, V[]>;
+    toSetMap<K>(keySelector: (item: TItem, index: number) => K): Map<K, Set<TItem>>;
+    toSetMap<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (item: TItem, index: number) => V): Map<K, Set<V>>;
+    toMapValues<K, V>(keySelector: (item: TItem, index: number) => K, valueSelector: (items: TItem[]) => V): Map<K, V>;
+    toObject(keySelector: (item: TItem, index: number) => string): Record<string, TItem>;
+    toObject<V>(keySelector: (item: TItem, index: number) => string, valueSelector: (item: TItem, index: number) => V): Record<string, V>;
     /**
      * 평탄한 배열을 트리 구조로 변환한다
      *
@@ -111,7 +111,7 @@ export interface ReadonlyArrayExt<T> {
      * // ]}]
      * ```
      */
-    toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
+    toTree<K extends keyof TItem, P extends keyof TItem>(keyProp: K, parentKey: P): TreeArray<TItem>[];
     /**
      * 중복 제거
      * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
@@ -119,46 +119,46 @@ export interface ReadonlyArrayExt<T> {
      */
     distinct(options?: boolean | {
         matchAddress?: boolean;
-        keyFn?: (item: T) => string | number;
-    }): T[];
-    orderBy(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
-    orderByDesc(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+        keyFn?: (item: TItem) => string | number;
+    }): TItem[];
+    orderBy(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
+    orderByDesc(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
     /**
      * 두 배열 비교 (INSERT/DELETE/UPDATE)
      * @param target 비교 대상 배열
      * @param options keys: 키 비교용, excludes: 비교 제외 속성
      * @note target에 중복 키가 있으면 첫 번째 매칭만 사용됨
      */
-    diffs<P>(target: P[], options?: {
+    diffs<TOtherItem>(target: TOtherItem[], options?: {
         keys?: string[];
         excludes?: string[];
-    }): ArrayDiffsResult<T, P>[];
-    oneWayDiffs<K extends keyof T>(orgItems: T[] | Map<T[K], T>, keyPropNameOrFn: K | ((item: T) => K), options?: {
+    }): ArrayDiffsResult<TItem, TOtherItem>[];
+    oneWayDiffs<K extends keyof TItem>(orgItems: TItem[] | Map<TItem[K], TItem>, keyPropNameOrFn: K | ((item: TItem) => K), options?: {
         includeSame?: boolean;
         excludes?: string[];
         includes?: string[];
-    }): ArrayDiffs2Result<T>[];
-    merge<P>(target: P[], options?: {
+    }): ArrayDiffs2Result<TItem>[];
+    merge<TOtherItem>(target: TOtherItem[], options?: {
         keys?: string[];
         excludes?: string[];
-    }): (T | P | (T & P))[];
+    }): (TItem | TOtherItem | (TItem & TOtherItem))[];
     /**
      * 요소의 합계 반환
      * @param selector 값 선택 함수 (생략 시 요소 자체를 number로 사용)
      * @returns 빈 배열인 경우 0 반환
      */
-    sum(selector?: (item: T, index: number) => number): number;
-    min(): T extends number | string ? T | undefined : never;
-    min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-    max(): T extends number | string ? T | undefined : never;
-    max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-    shuffle(): T[];
+    sum(selector?: (item: TItem, index: number) => number): number;
+    min(): TItem extends number | string ? TItem | undefined : never;
+    min<P extends number | string>(selector?: (item: TItem, index: number) => P): P | undefined;
+    max(): TItem extends number | string ? TItem | undefined : never;
+    max<P extends number | string>(selector?: (item: TItem, index: number) => P): P | undefined;
+    shuffle(): TItem[];
 }
 /**
  * 원본 배열을 변경하는 확장 메서드
  * @mutates 모든 메서드가 원본 배열을 직접 변경합니다
  */
-export interface MutableArrayExt<T> {
+export interface MutableArrayExt<TItem> {
     /**
      * 원본 배열에서 중복 제거
      * @param options matchAddress: 주소 비교 (true면 Set 사용), keyFn: 커스텀 키 함수 (O(n) 성능)
@@ -167,48 +167,48 @@ export interface MutableArrayExt<T> {
      */
     distinctThis(options?: boolean | {
         matchAddress?: boolean;
-        keyFn?: (item: T) => string | number;
-    }): T[];
+        keyFn?: (item: TItem) => string | number;
+    }): TItem[];
     /** 원본 배열 오름차순 정렬 @mutates */
-    orderByThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+    orderByThis(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
     /** 원본 배열 내림차순 정렬 @mutates */
-    orderByDescThis(selector?: (item: T) => string | number | DateOnly | DateTime | Time | undefined): T[];
+    orderByDescThis(selector?: (item: TItem) => string | number | DateOnly | DateTime | Time | undefined): TItem[];
     /** 원본 배열에 항목 삽입 @mutates */
-    insert(index: number, ...items: T[]): this;
+    insert(index: number, ...items: TItem[]): this;
     /** 원본 배열에서 항목 제거 @mutates */
-    remove(item: T): this;
+    remove(item: TItem): this;
     /** 원본 배열에서 조건에 맞는 항목 제거 @mutates */
-    remove(selector: (item: T, index: number) => boolean): this;
+    remove(selector: (item: TItem, index: number) => boolean): this;
     /** 원본 배열에서 항목 토글 (있으면 제거, 없으면 추가) @mutates */
-    toggle(item: T): this;
+    toggle(item: TItem): this;
     /** 원본 배열 비우기 @mutates */
     clear(): this;
 }
-export type ArrayDiffsResult<T, P> = {
+export type ArrayDiffsResult<TOriginal, TOther> = {
     source: undefined;
-    target: P;
+    target: TOther;
 } | {
-    source: T;
+    source: TOriginal;
     target: undefined;
 } | {
-    source: T;
-    target: P;
+    source: TOriginal;
+    target: TOther;
 };
-export type ArrayDiffs2Result<T> = {
+export type ArrayDiffs2Result<TItem> = {
     type: "create";
-    item: T;
+    item: TItem;
     orgItem: undefined;
 } | {
     type: "update";
-    item: T;
-    orgItem: T;
+    item: TItem;
+    orgItem: TItem;
 } | {
     type: "same";
-    item: T;
-    orgItem: T;
+    item: TItem;
+    orgItem: TItem;
 };
-export type TreeArray<T> = T & {
-    children: TreeArray<T>[];
+export type TreeArray<TNode> = TNode & {
+    children: TreeArray<TNode>[];
 };
 /** 정렬/비교 가능한 타입 */
 export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;