@simplysm/core-common 14.0.23 → 14.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "14.0.23",
+  "version": "14.0.24",
   "description": "심플리즘 패키지 - 코어 (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,8 +14,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
-    "docs"
+    "src"
   ],
   "sideEffects": [
     "./src/extensions/arr-ext.ts",

package/README.md

@@ -1,218 +0,0 @@
-# @simplysm/core-common
-
-Platform-neutral utility library for the Simplysm framework. Provides type-safe primitives, collection extensions, error hierarchy, async utilities, and serialization helpers that work in both browser and Node.js environments.
-
-## Installation
-
-```bash
-npm install @simplysm/core-common
-```
-
-## API Overview
-
-### Environment
-
-| API | Type | Description |
-|-----|------|-------------|
-| `env` | `const` | Unified environment variables from `import.meta.env` and `process.env`. `DEV` is parsed as boolean, `VER` as optional string. |
-| `parseBoolEnv(value)` | `function` | Parse a value to boolean (`"true"`, `"1"`, `"yes"`, `"on"` case-insensitive -> `true`, otherwise `false`) |
-
--> See [docs/env.md](./docs/env.md) for details.
-
-### Errors
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdError` | `class` | Tree-structured error with chained messages via ES2024 `cause` |
-| `ArgumentError` | `class` | Invalid argument error with YAML-formatted argument dump |
-| `NotImplementedError` | `class` | Unimplemented feature error |
-| `TimeoutError` | `class` | Timeout exceeded error with retry count |
-
--> See [docs/errors.md](./docs/errors.md) for details.
-
-### Types
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Uuid` | `class` | UUID v4 generation and parsing using `crypto.getRandomValues` |
-| `LazyGcMap<K,V>` | `class` | Auto-expiring Map with LRU access tracking and GC timer |
-| `DateTime` | `class` | Immutable date-time wrapper around `Date` with millisecond precision |
-| `DateOnly` | `class` | Immutable date-only class (no time component) with week-sequence support |
-| `Time` | `class` | Immutable time-only class with 24-hour wrapping |
-
--> See [docs/types.md](./docs/types.md) for details.
-
-### Features
-
-| API | Type | Description |
-|-----|------|-------------|
-| `DebounceQueue` | `class` | Async debounce queue -- only the last enqueued function runs after delay |
-| `SerialQueue` | `class` | Async serial queue -- functions execute one at a time in order |
-| `EventEmitter<TEvents>` | `class` | Type-safe event emitter built on `EventTarget` |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Array Extensions
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Array.prototype.single` | extension | Return single matching element or throw if multiple |
-| `Array.prototype.first` | extension | Return first element or first matching |
-| `Array.prototype.last` | extension | Return last element or last matching |
-| `Array.prototype.filterExists` | extension | Remove null/undefined elements |
-| `Array.prototype.ofType` | extension | Filter by primitive type string or constructor |
-| `Array.prototype.filterAsync` | extension | Async sequential filter |
-| `Array.prototype.mapAsync` | extension | Async sequential map |
-| `Array.prototype.mapMany` | extension | Flatten or map-then-flatten |
-| `Array.prototype.mapManyAsync` | extension | Async map then flatten |
-| `Array.prototype.parallelAsync` | extension | Parallel async map via `Promise.all` |
-| `Array.prototype.groupBy` | extension | Group by key selector |
-| `Array.prototype.toMap` | extension | Convert to `Map` with key/value selectors |
-| `Array.prototype.toMapAsync` | extension | Async version of `toMap` |
-| `Array.prototype.toArrayMap` | extension | Convert to `Map<K, V[]>` |
-| `Array.prototype.toSetMap` | extension | Convert to `Map<K, Set<V>>` |
-| `Array.prototype.toMapValues` | extension | Group then aggregate values |
-| `Array.prototype.toObject` | extension | Convert to `Record<string, V>` |
-| `Array.prototype.toTree` | extension | Convert flat array to tree structure |
-| `Array.prototype.distinct` | extension | Remove duplicates (new array) |
-| `Array.prototype.orderBy` | extension | Sort ascending (new array) |
-| `Array.prototype.orderByDesc` | extension | Sort descending (new array) |
-| `Array.prototype.diffs` | extension | Compare two arrays (insert/delete/update) |
-| `Array.prototype.oneWayDiffs` | extension | One-way diff (create/update/same) |
-| `Array.prototype.merge` | extension | Merge two arrays by key |
-| `Array.prototype.sum` | extension | Sum of elements |
-| `Array.prototype.min` | extension | Minimum element |
-| `Array.prototype.max` | extension | Maximum element |
-| `Array.prototype.shuffle` | extension | Random shuffle (new array) |
-| `Array.prototype.distinctThis` | extension | Remove duplicates in-place |
-| `Array.prototype.orderByThis` | extension | Sort ascending in-place |
-| `Array.prototype.orderByDescThis` | extension | Sort descending in-place |
-| `Array.prototype.insert` | extension | Insert items at index in-place |
-| `Array.prototype.remove` | extension | Remove items in-place |
-| `Array.prototype.toggle` | extension | Toggle item in-place |
-| `Array.prototype.clear` | extension | Remove all items in-place |
-| `ArrayDiffsResult<T,P>` | `type` | Diff result: insert / delete / update |
-| `ArrayOneWayDiffResult<T>` | `type` | One-way diff result: create / update / same |
-| `TreeArray<T>` | `type` | Tree node type with `children` array |
-| `ComparableType` | `type` | Union of sortable types |
-
--> See [docs/array-extensions.md](./docs/array-extensions.md) for details.
-
-### Map Extensions
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Map.prototype.getOrCreate` | extension | Get value or create with default/factory |
-| `Map.prototype.update` | extension | Update a value using a transform function |
-
--> See [docs/map-extensions.md](./docs/map-extensions.md) for details.
-
-### Set Extensions
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Set.prototype.adds` | extension | Add multiple values at once |
-| `Set.prototype.toggle` | extension | Toggle a value with optional force add/delete |
-
--> See [docs/set-extensions.md](./docs/set-extensions.md) for details.
-
-### Utility Namespaces
-
-All utility namespaces are exported as `export * as name` and accessed as `obj.clone(...)`, `str.toPascalCase(...)`, etc.
-
-| Namespace | Description |
-|-----------|-------------|
-| `obj` | Deep clone, deep equal, deep merge, 3-way merge, omit, pick, chain value access, type-safe keys/entries/fromEntries/map |
-| `str` | Korean suffix, full-width conversion, case conversion (pascal/camel/kebab/snake), isNullOrEmpty, insert |
-| `num` | parseInt, parseFloat, parseRoundedInt, isNullOrEmpty, format with thousand separators |
-| `bytes` | Uint8Array concat, hex, base64 conversion |
-| `path` | POSIX path join, basename, extname (browser-compatible, no backslash support) |
-| `json` | Custom JSON stringify/parse with DateTime, Uuid, Set, Map, Error, Uint8Array support |
-| `xml` | XML parse/stringify via fast-xml-parser |
-| `wait` | Async `until` (poll condition) and `time` (delay) |
-| `transfer` | Worker-safe encode/decode for custom types with transferable list extraction |
-| `err` | Extract error message from unknown catch value |
-| `dt` | Date/time formatting with C#-style format strings, normalizeMonth, convert12To24 |
-| `primitive` | Get PrimitiveTypeStr from runtime value |
-
--> See [docs/utilities.md](./docs/utilities.md) for details.
-
-### Template Strings and Zip
-
-| API | Type | Description |
-|-----|------|-------------|
-| `js` | tag function | JavaScript template tag with indent normalization |
-| `ts` | tag function | TypeScript template tag with indent normalization |
-| `html` | tag function | HTML template tag with indent normalization |
-| `tsql` | tag function | MSSQL T-SQL template tag with indent normalization |
-| `mysql` | tag function | MySQL template tag with indent normalization |
-| `pgsql` | tag function | PostgreSQL template tag with indent normalization |
-| `ZipArchive` | `class` | ZIP read/write/compress/extract with caching |
-| `ZipArchiveProgress` | `interface` | Progress callback data for extraction |
-
--> See [docs/template-strings-and-zip.md](./docs/template-strings-and-zip.md) for details.
-
-### Type Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `Bytes` | `type` | Alias for `Uint8Array` (replaces `Buffer`) |
-| `PrimitiveTypeMap` | `type` | Maps type-string keys to their TypeScript types |
-| `PrimitiveTypeStr` | `type` | `keyof PrimitiveTypeMap` |
-| `PrimitiveType` | `type` | Union of all primitive type values plus `undefined` |
-| `DeepPartial<T>` | `type` | Recursively makes all properties optional |
-| `Type<T>` | `interface` | Constructor type (`new (...args: unknown[]) => T`) |
-
--> See [docs/type-utilities.md](./docs/type-utilities.md) for details.
-
-## Usage Examples
-
-### Deep Cloning and Comparing
-
-```typescript
-import { obj } from "@simplysm/core-common";
-
-const original = { a: 1, b: { c: [2, 3] } };
-const cloned = obj.clone(original);
-obj.equal(original, cloned); // true
-
-const merged = obj.merge(original, { b: { d: 4 } });
-// { a: 1, b: { c: [2, 3], d: 4 } }
-```
-
-### Array Extensions
-
-```typescript
-import "@simplysm/core-common";
-
-const users = [
-  { id: 1, role: "admin", name: "Alice" },
-  { id: 2, role: "user", name: "Bob" },
-  { id: 3, role: "user", name: "Carol" },
-];
-
-users.groupBy((u) => u.role);
-// [{ key: "admin", values: [Alice] }, { key: "user", values: [Bob, Carol] }]
-
-users.toMap((u) => u.id);
-// Map { 1 => Alice, 2 => Bob, 3 => Carol }
-
-[3, 1, 2].orderBy(); // [1, 2, 3]
-[1, 2, 2, 3].distinct(); // [1, 2, 3]
-```
-
-### JSON Serialization with Custom Types
-
-```typescript
-import { json, DateTime, Uuid } from "@simplysm/core-common";
-
-const data = {
-  id: Uuid.generate(),
-  createdAt: new DateTime(2025, 6, 15, 10, 30, 0),
-  tags: new Set(["a", "b"]),
-};
-
-const serialized = json.stringify(data);
-const restored = json.parse(serialized);
-// restored.id is Uuid, restored.createdAt is DateTime, restored.tags is Set
-```

package/docs/array-extensions.md

@@ -1,399 +0,0 @@
-# Array Extensions
-
-Prototype extensions added to both `Array` and `ReadonlyArray`. Available after importing `@simplysm/core-common`.
-
-Also exports helper functions and result types.
-
-## ReadonlyArray Extensions
-
-These methods do not mutate the original array.
-
-### `single`
-
-Return the single element matching the predicate. Returns `undefined` if no match. Throws `ArgumentError` if more than one element matches.
-
-```typescript
-single(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-### `first`
-
-Return the first element, or the first element matching the predicate.
-
-```typescript
-first(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-### `last`
-
-Return the last element, or the last element matching the predicate.
-
-```typescript
-last(predicate?: (item: T, index: number) => boolean): T | undefined;
-```
-
-### `filterExists`
-
-Remove all `null` and `undefined` elements.
-
-```typescript
-filterExists(): NonNullable<T>[];
-```
-
-### `ofType`
-
-Filter elements by type. Accepts a `PrimitiveTypeStr` (e.g., `"string"`, `"DateTime"`) or a constructor function.
-
-```typescript
-ofType<TKey extends PrimitiveTypeStr>(type: TKey): Extract<T, PrimitiveTypeMap[TKey]>[];
-ofType<TNarrow extends T>(type: Type<TNarrow>): TNarrow[];
-```
-
-### `filterAsync`
-
-Async sequential filter. Evaluates the predicate for each element in order.
-
-```typescript
-filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
-```
-
-### `mapAsync`
-
-Async sequential map. Evaluates the selector for each element in order.
-
-```typescript
-mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
-```
-
-### `mapMany`
-
-Flatten a nested array, or map then flatten. Filters out null/undefined from the result.
-
-```typescript
-mapMany(): T extends readonly (infer U)[] ? U[] : T;
-mapMany<R>(selector: (item: T, index: number) => R[]): R[];
-```
-
-### `mapManyAsync`
-
-Async map then flatten.
-
-```typescript
-mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
-```
-
-### `parallelAsync`
-
-Parallel async map using `Promise.all`. All promises run concurrently.
-
-```typescript
-parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-```
-
-### `groupBy`
-
-Group elements by a key selector. Supports object keys via deep comparison (O(n^2)). Primitive keys use Map-based O(n) lookup.
-
-```typescript
-groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
-groupBy<K, V>(
-  keySelector: (item: T, index: number) => K,
-  valueSelector: (item: T, index: number) => V,
-): { key: K; values: V[] }[];
-```
-
-### `toMap`
-
-Convert to a `Map`. Throws `ArgumentError` on duplicate keys.
-
-```typescript
-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`
-
-Async version of `toMap`.
-
-```typescript
-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`
-
-Convert to a `Map<K, V[]>`. Multiple items with the same key are grouped into an array.
-
-```typescript
-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`
-
-Convert to a `Map<K, Set<V>>`.
-
-```typescript
-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`
-
-Group by key, then aggregate each group's items using a value selector.
-
-```typescript
-toMapValues<K, V>(
-  keySelector: (item: T, index: number) => K,
-  valueSelector: (items: T[]) => V,
-): Map<K, V>;
-```
-
-### `toObject`
-
-Convert to a plain object `Record<string, V>`. Throws `ArgumentError` on duplicate keys.
-
-```typescript
-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>;
-```
-
-### `toTree`
-
-Convert a flat array to a tree structure. Items where `parentKey` is null/undefined become root nodes. Uses O(n) Map-based indexing internally.
-
-```typescript
-toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
-```
-
-### `distinct`
-
-Remove duplicates (returns a new array).
-
-```typescript
-distinct(
-  options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
-): T[];
-```
-
-| Option | Description |
-|--------|-------------|
-| `true` or `{ matchAddress: true }` | Reference equality (Set-based, O(n)) |
-| `{ keyFn }` | Custom key function (O(n)) |
-| Default (no options) | Deep equality for objects (O(n^2)), type-based for primitives (O(n)) |
-
-### `orderBy`
-
-Sort ascending (returns a new array). Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
-
-```typescript
-orderBy(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-### `orderByDesc`
-
-Sort descending (returns a new array).
-
-```typescript
-orderByDesc(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-### `diffs`
-
-Compare this array (source) with a target array. Returns a list of insert/delete/update operations.
-
-```typescript
-diffs<P>(target: P[]): ArrayDiffsResult<T, P>[];
-diffs<P extends Record<string, unknown>>(
-  target: P[],
-  options: { keys: string[]; excludes?: string[] },
-): ArrayDiffsResult<T, P>[];
-diffs<P extends Record<string, unknown>>(
-  target: P[],
-  options: { excludes: string[] },
-): ArrayDiffsResult<T, P>[];
-```
-
-| Option | Description |
-|--------|-------------|
-| `keys` | Properties to use for matching source to target items |
-| `excludes` | Properties to ignore in equality comparison |
-
-### `oneWayDiffs`
-
-One-way diff: compare this array against original items. Returns create/update/same results.
-
-```typescript
-oneWayDiffs<K extends keyof T>(
-  orgItems: T[] | Map<T[K], T>,
-  keyPropNameOrGetValFn: K | ((item: T) => string | number | undefined),
-  options?: { includeSame?: boolean; excludes?: string[]; includes?: string[] },
-): ArrayOneWayDiffResult<T>[];
-```
-
-### `merge`
-
-Merge this array with a target array. Matched items are deep-merged; unmatched target items are appended.
-
-```typescript
-merge<P>(target: P[]): (T | P | (T & P))[];
-merge<P extends Record<string, unknown>>(
-  target: P[],
-  options: { keys: string[]; excludes?: string[] },
-): (T | P | (T & P))[];
-merge<P extends Record<string, unknown>>(
-  target: P[],
-  options: { excludes: string[] },
-): (T | P | (T & P))[];
-```
-
-### `sum`
-
-Sum of elements. If no selector is provided, elements must be numbers.
-
-```typescript
-sum(selector?: (item: T, index: number) => number): number;
-```
-
-Returns `0` for empty arrays.
-
-### `min`
-
-Minimum element or minimum selected value.
-
-```typescript
-min(): T extends number | string ? T | undefined : never;
-min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-```
-
-### `max`
-
-Maximum element or maximum selected value.
-
-```typescript
-max(): T extends number | string ? T | undefined : never;
-max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
-```
-
-### `shuffle`
-
-Return a new array with elements in random order (Fisher-Yates algorithm).
-
-```typescript
-shuffle(): T[];
-```
-
----
-
-## Mutable Array Extensions
-
-These methods mutate the original array in-place.
-
-### `distinctThis`
-
-Remove duplicates in-place. Same options as `distinct`.
-
-```typescript
-distinctThis(
-  options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
-): T[];
-```
-
-### `orderByThis`
-
-Sort ascending in-place.
-
-```typescript
-orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-### `orderByDescThis`
-
-Sort descending in-place.
-
-```typescript
-orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-```
-
-### `insert`
-
-Insert items at a given index. Mutates the array.
-
-```typescript
-insert(index: number, ...items: T[]): this;
-```
-
-### `remove`
-
-Remove items by value or predicate. Mutates the array.
-
-```typescript
-remove(item: T): this;
-remove(selector: (item: T, index: number) => boolean): this;
-```
-
-### `toggle`
-
-Toggle an item: remove if present, add (push) if absent.
-
-```typescript
-toggle(item: T): this;
-```
-
-### `clear`
-
-Remove all items from the array.
-
-```typescript
-clear(): this;
-```
-
----
-
-## Exported Types
-
-### `ArrayDiffsResult<TOriginal, TOther>`
-
-```typescript
-type ArrayDiffsResult<TOriginal, TOther> =
-  | { source: undefined; target: TOther }       // INSERT
-  | { source: TOriginal; target: undefined }     // DELETE
-  | { source: TOriginal; target: TOther };       // UPDATE
-```
-
-### `ArrayOneWayDiffResult<TItem>`
-
-```typescript
-type ArrayOneWayDiffResult<TItem> =
-  | { type: "create"; item: TItem; orgItem: undefined }
-  | { type: "update"; item: TItem; orgItem: TItem }
-  | { type: "same"; item: TItem; orgItem: TItem };
-```
-
-### `TreeArray<TNode>`
-
-```typescript
-type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
-```
-
-### `ComparableType`
-
-```typescript
-type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
-```
-

package/docs/env.md

@@ -1,33 +0,0 @@
-# Environment
-
-## `parseBoolEnv`
-
-Parse a value to boolean. Recognizes `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive) as `true`; everything else is `false`.
-
-```typescript
-function parseBoolEnv(value: unknown): boolean;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `value` | `unknown` | The value to parse. Converted to string internally. |
-
-**Returns:** `boolean`
-
-## `env`
-
-Unified environment variable object. Merges `import.meta.env` and `process.env` (process.env takes precedence). `DEV` is auto-parsed as boolean, `VER` is typed as optional string.
-
-```typescript
-const env: {
-  DEV: boolean;
-  VER?: string;
-  [key: string]: unknown;
-};
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `DEV` | `boolean` | Whether the app is running in development mode. Parsed from raw `DEV` env var via `parseBoolEnv`. |
-| `VER` | `string \| undefined` | Application version string, if set. |
-| `[key: string]` | `unknown` | Any other environment variable. |