@simplysm/core-common 13.0.100 → 14.0.4

package/docs/array-extensions.md

@@ -0,0 +1,430 @@
+# Array / Set / Map Extensions
+
+Prototype extensions added to `Array`, `Set`, and `Map` at import time. Importing `@simplysm/core-common` automatically installs these extensions.
+
+## Array -- Readonly Extensions
+
+These methods return new arrays/values without mutating the original.
+
+### `single(predicate?)`
+
+Returns the single matching element, or `undefined` if none. Throws `ArgumentError` if more than one element matches.
+
+```typescript
+single(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `first(predicate?)`
+
+Returns the first matching element, or `undefined` if none.
+
+```typescript
+first(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `last(predicate?)`
+
+Returns the last matching element, or `undefined` if none.
+
+```typescript
+last(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `filterAsync(predicate)`
+
+Async sequential filter.
+
+```typescript
+filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+```
+
+### `filterExists()`
+
+Removes `null` and `undefined` elements. Returns `NonNullable<T>[]`.
+
+```typescript
+filterExists(): NonNullable<T>[];
+```
+
+### `ofType(type)`
+
+Filters elements by type. Accepts a `PrimitiveTypeStr` (`"string"`, `"number"`, `"boolean"`, `"DateTime"`, `"DateOnly"`, `"Time"`, `"Uuid"`, `"Bytes"`) or a constructor function.
+
+```typescript
+ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
+ofType<N extends T>(type: Type<N>): N[];
+```
+
+### `mapAsync(selector)`
+
+Async sequential map.
+
+```typescript
+mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+### `mapMany(selector?)`
+
+Maps then flattens one level. Removes `null`/`undefined` from results.
+
+```typescript
+mapMany(): T extends readonly (infer U)[] ? U[] : T;
+mapMany<R>(selector: (item: T, index: number) => R[]): R[];
+```
+
+### `mapManyAsync(selector?)`
+
+Async version of `mapMany`.
+
+```typescript
+mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+```
+
+### `parallelAsync(fn)`
+
+Runs `fn` for all items in parallel via `Promise.all`. If any rejects, the entire result rejects.
+
+```typescript
+parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+### `groupBy(keySelector, valueSelector?)`
+
+Groups items by key. Supports both primitive keys (O(n) via Map) and object keys (O(n^2) via deep equality).
+
+```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(keySelector, valueSelector?)`
+
+Converts array to `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(keySelector, valueSelector?)`
+
+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(keySelector, valueSelector?)`
+
+Converts array to `Map<K, V[]>` (groups values into arrays per key).
+
+```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(keySelector, valueSelector?)`
+
+Converts array to `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(keySelector, valueSelector)`
+
+Groups by key, then applies `valueSelector` to the group array to produce the final value.
+
+```typescript
+toMapValues<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (items: T[]) => V,
+): Map<K, V>;
+```
+
+### `toObject(keySelector, valueSelector?)`
+
+Converts array to a plain object. 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(keyProp, parentKey)`
+
+Converts a flat array to a tree structure. Items where `parentKey` is `null`/`undefined` become roots. O(n) complexity.
+
+```typescript
+toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
+```
+
+```typescript
+const items = [
+  { id: 1, parentId: undefined, name: "root" },
+  { id: 2, parentId: 1, name: "child" },
+];
+const tree = items.toTree("id", "parentId");
+// [{ id: 1, name: "root", children: [{ id: 2, name: "child", children: [] }] }]
+```
+
+### `distinct(options?)`
+
+Returns a new array with duplicates removed.
+
+```typescript
+distinct(options?: boolean | {
+  matchAddress?: boolean;
+  keyFn?: (item: T) => string | number;
+}): T[];
+```
+
+| Option | Description |
+|--------|-------------|
+| `true` or `{ matchAddress: true }` | Use reference equality (Set-based, O(n)) |
+| `{ keyFn }` | Use custom key function (O(n)) |
+| No options | Deep equality comparison (O(n^2) for objects) |
+
+### `orderBy(selector?)` / `orderByDesc(selector?)`
+
+Returns a sorted copy. Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
+
+```typescript
+orderBy(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+orderByDesc(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+### `diffs(target, options?)`
+
+Compares two arrays and returns INSERT/DELETE/UPDATE diff results.
+
+```typescript
+diffs<P>(target: P[], options?: {
+  keys?: string[];
+  excludes?: string[];
+}): ArrayDiffsResult<T, P>[];
+```
+
+Result items:
+- `{ source: T, target: undefined }` -- item exists only in source (DELETE)
+- `{ source: undefined, target: P }` -- item exists only in target (INSERT)
+- `{ source: T, target: P }` -- item exists in both but differs (UPDATE)
+
+### `oneWayDiffs(orgItems, keyPropNameOrGetValFn, options?)`
+
+One-way diff: compares current array against original items.
+
+```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>[];
+```
+
+Result types: `"create"`, `"update"`, `"same"` (only if `includeSame: true`).
+
+### `merge(target, options?)`
+
+Merges two arrays using deep merge on matched items and appends unmatched target items.
+
+```typescript
+merge<P>(target: P[], options?: {
+  keys?: string[];
+  excludes?: string[];
+}): (T | P | (T & P))[];
+```
+
+### `sum(selector?)`
+
+Returns the sum of elements. Returns `0` for empty arrays.
+
+```typescript
+sum(selector?: (item: T, index: number) => number): number;
+```
+
+### `min(selector?)` / `max(selector?)`
+
+Returns the minimum/maximum element. Returns `undefined` for empty arrays.
+
+```typescript
+min(selector?: (item: T, index: number) => string | number): string | number | undefined;
+max(selector?: (item: T, index: number) => string | number): string | number | undefined;
+```
+
+### `shuffle()`
+
+Returns a new array with elements in random order (Fisher-Yates algorithm).
+
+```typescript
+shuffle(): T[];
+```
+
+## Array -- Mutable Extensions
+
+These methods mutate the original array in place.
+
+### `distinctThis(options?)`
+
+Removes duplicates from the original array in place. Same options as `distinct()`.
+
+```typescript
+distinctThis(options?: boolean | {
+  matchAddress?: boolean;
+  keyFn?: (item: T) => string | number;
+}): T[];
+```
+
+### `orderByThis(selector?)` / `orderByDescThis(selector?)`
+
+Sorts the original array in place.
+
+```typescript
+orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+### `insert(index, ...items)`
+
+Inserts items at the given index in place.
+
+```typescript
+insert(index: number, ...items: T[]): this;
+```
+
+### `remove(itemOrSelector)`
+
+Removes matching items in place.
+
+```typescript
+remove(item: T): this;
+remove(selector: (item: T, index: number) => boolean): this;
+```
+
+### `toggle(item)`
+
+Toggles an item: removes if present, adds if absent.
+
+```typescript
+toggle(item: T): this;
+```
+
+### `clear()`
+
+Removes all items from the array.
+
+```typescript
+clear(): this;
+```
+
+## Set Extensions
+
+### `adds(...values)`
+
+Adds multiple values at once. Returns `this` for chaining.
+
+```typescript
+adds(...values: T[]): this;
+```
+
+### `toggle(value, addOrDel?)`
+
+Toggles a value in the Set. Optionally force add or delete.
+
+```typescript
+toggle(value: T, addOrDel?: "add" | "del"): this;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `T` | Value to toggle |
+| `addOrDel` | `"add" \| "del" \| undefined` | Force add or delete. Omit for auto-toggle |
+
+```typescript
+const set = new Set([1, 2, 3]);
+set.toggle(2);           // removes 2 -> {1, 3}
+set.toggle(4);           // adds 4    -> {1, 3, 4}
+set.toggle(5, "add");    // force add -> {1, 3, 4, 5}
+set.toggle(5, "del");    // force del -> {1, 3, 4}
+```
+
+## Map Extensions
+
+### `getOrCreate(key, newValue)`
+
+Returns the value for `key`. If the key does not exist, creates it with `newValue` (or calls `newValue` as a factory function if it is a function).
+
+```typescript
+getOrCreate(key: K, newValue: V): V;
+getOrCreate(key: K, newValueFn: () => V): V;
+```
+
+**Note:** If `V` is a function type, wrap it in a factory to avoid it being called:
+```typescript
+fnMap.getOrCreate("key", () => myFunction);
+```
+
+### `update(key, updateFn)`
+
+Updates a key's value using a function. If the key does not exist, `updateFn` receives `undefined`.
+
+```typescript
+update(key: K, updateFn: (v: V | undefined) => V): void;
+```
+
+```typescript
+const counts = new Map<string, number>();
+counts.update("hits", (v) => (v ?? 0) + 1);
+```
+
+## 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

@@ -0,0 +1,52 @@
+# Environment
+
+Unified access to environment variables from both `import.meta.env` (Vite/browser) and `process.env` (Node.js). `process.env` takes precedence when both are available.
+
+## `parseBoolEnv`
+
+Parses an unknown value to a boolean. Returns `true` for `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive), `false` for everything else.
+
+```typescript
+function parseBoolEnv(value: unknown): boolean;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `unknown` | The value to parse |
+
+**Returns:** `boolean`
+
+```typescript
+parseBoolEnv("true");  // true
+parseBoolEnv("1");     // true
+parseBoolEnv("yes");   // true
+parseBoolEnv("on");    // true
+parseBoolEnv("false"); // false
+parseBoolEnv(undefined); // false
+```
+
+## `env`
+
+A pre-built environment object that merges `import.meta.env` and `process.env`.
+
+```typescript
+const env: {
+  DEV: boolean;
+  VER?: string;
+  [key: string]: unknown;
+};
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `DEV` | `boolean` | Whether in development mode (parsed via `parseBoolEnv` from `DEV` env var) |
+| `VER` | `string \| undefined` | Version string from `VER` env var |
+| `[key]` | `unknown` | Any other environment variable |
+
+```typescript
+import { env } from "@simplysm/core-common";
+
+if (env.DEV) {
+  // development-only logic
+}
+```

package/docs/errors.md

@@ -1,119 +1,104 @@
 # Errors
 
-Error classes for the Simplysm framework. All classes extend `SdError`, which itself extends `Error`.
-
-Source: `src/errors/*.ts`
-
----
+A hierarchy of error classes built on `SdError`, which supports tree-structured cause chaining via the ES2024 `cause` property.
 
 ## `SdError`
 
-Error class supporting tree-structured cause chaining. Utilizes ES2024 `cause` property. Messages are joined in reverse order with ` => ` separator, and cause stack traces are appended.
+Base error class with cause-chain support. Messages are joined in reverse order with ` => `.
 
 ```typescript
-export class SdError extends Error {
-  override cause?: Error;
+class SdError extends Error {
+  cause?: Error;
 
-  /** Create by wrapping a cause error. Messages are joined in reverse order (upper message => lower message => cause message) */
   constructor(cause: Error, ...messages: string[]);
-  /** Create with messages only. Messages are joined in reverse order (upper message => lower message) */
   constructor(...messages: string[]);
 }
 ```
 
-**Example:**
+| Constructor Overload | Description |
+|---------------------|-------------|
+| `new SdError(cause, ...messages)` | Wraps an existing error. Message becomes `"messages[n] => ... => messages[0] => cause.message"` |
+| `new SdError(...messages)` | Creates without cause. Message becomes `"messages[n] => ... => messages[0]"` |
+
+When a cause error is provided, its stack trace is appended under a `---- cause stack ----` separator.
 
 ```typescript
 try {
   await fetch(url);
 } catch (err) {
   throw new SdError(err, "API call failed", "User load failed");
+  // message: "User load failed => API call failed => <original message>"
 }
-// Result message: "User load failed => API call failed => original error message"
 
-throw new SdError("invalid state", "processing not possible");
-// Result message: "processing not possible => invalid state"
+throw new SdError("Invalid state", "Cannot process");
+// message: "Cannot process => Invalid state"
 ```
 
----
-
 ## `ArgumentError`
 
-An error thrown when invalid arguments are received. Includes the argument object in YAML format in the message to facilitate debugging. Extends `SdError`.
+Error for invalid arguments. Extends `SdError`. Formats the argument object as YAML in the message for easy debugging.
 
 ```typescript
-export class ArgumentError extends SdError {
-  /** Output argument object in YAML format with default message ("Invalid arguments.") */
+class ArgumentError extends SdError {
   constructor(argObj: Record<string, unknown>);
-  /** Output argument object in YAML format with a custom message */
   constructor(message: string, argObj: Record<string, unknown>);
 }
 ```
 
-**Example:**
+| Constructor Overload | Description |
+|---------------------|-------------|
+| `new ArgumentError(argObj)` | Default message + YAML-formatted args |
+| `new ArgumentError(message, argObj)` | Custom message + YAML-formatted args |
 
 ```typescript
 throw new ArgumentError({ userId: 123, name: null });
-// Result message: "Invalid arguments.\n\nuserId: 123\nname: null"
+// message: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
 
 throw new ArgumentError("Invalid user", { userId: 123 });
-// Result message: "Invalid user\n\nuserId: 123"
+// message: "Invalid user\n\nuserId: 123"
 ```
 
----
-
 ## `NotImplementedError`
 
-An error thrown when a feature that has not yet been implemented is called. Extends `SdError`.
+Error for unimplemented features. Extends `SdError`.
 
 ```typescript
-export class NotImplementedError extends SdError {
-  /**
-   * @param message Additional description message
-   */
+class NotImplementedError extends SdError {
   constructor(message?: string);
 }
 ```
 
-**Example:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | `string \| undefined` | Optional description of what is not implemented |
 
 ```typescript
-class BaseService {
-  process(): void {
-    throw new NotImplementedError("Implementation required in subclass");
-  }
-}
+throw new NotImplementedError();
+// message: "미구현"
 
-switch (type) {
-  case "A": return handleA();
-  case "B": throw new NotImplementedError(`Handling for type ${type}`);
-}
+throw new NotImplementedError("Subclass must override");
+// message: "미구현: Subclass must override"
 ```
 
----
-
 ## `TimeoutError`
 
-An error that occurs when the waiting time is exceeded. Automatically thrown when the maximum number of attempts is exceeded in `wait.until()`. Extends `SdError`.
+Error for timeout conditions. Extends `SdError`.
 
 ```typescript
-export class TimeoutError extends SdError {
-  /**
-   * @param count Number of attempts
-   * @param message Additional message
-   */
+class TimeoutError extends SdError {
   constructor(count?: number, message?: string);
 }
 ```
 
-**Example:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `count` | `number \| undefined` | Number of attempts made |
+| `message` | `string \| undefined` | Additional description |
 
 ```typescript
-try {
-  await wait.until(() => isReady, 100, 50);
-} catch (err) {
-  if (err instanceof TimeoutError) {
-    // "Waiting time exceeded(50 attempts)"
-  }
-}
+throw new TimeoutError(50);
+// message: "대기 시간 초과(50회 시도)"
+
+throw new TimeoutError(undefined, "API response wait exceeded");
+// message: "대기 시간 초과: API response wait exceeded"
 ```