@simplysm/core-common 13.0.97 → 13.0.98

package/README.md

@@ -0,0 +1,160 @@
+# @simplysm/core-common
+
+Core module (common) — platform-neutral core utilities for the Simplysm framework.
+
+Provides error classes, immutable date/time types, prototype extensions, event handling, and utility namespaces that work in both browser and Node.js environments.
+
+## Installation
+
+```bash
+npm install @simplysm/core-common
+```
+
+## Side-Effect Imports
+
+Importing the package entry point (`@simplysm/core-common`) automatically patches `Array`, `Map`, and `Set` prototypes with extension methods. These are declared as side effects in `package.json`:
+
+- `extensions/arr-ext` — Array prototype extensions
+- `extensions/map-ext` — Map prototype extensions
+- `extensions/set-ext` — Set prototype extensions
+
+If you import only specific modules (e.g., `@simplysm/core-common/dist/types/date-time`), the prototype extensions are **not** applied unless you also import the entry point or the extension modules directly.
+
+## API Overview
+
+### Errors
+
+| API | Type | Description |
+|-----|------|-------------|
+| `SdError` | class | Error with tree-structured cause chaining |
+| `ArgumentError` | class | Invalid argument error with YAML-formatted details |
+| `NotImplementedError` | class | Unimplemented feature error |
+| `TimeoutError` | class | Waiting time exceeded error |
+
+-> See [docs/errors.md](./docs/errors.md) for details.
+
+### Types
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Uuid` | class | UUID v4 generation and parsing |
+| `DateTime` | class | Immutable date+time (millisecond precision) |
+| `DateOnly` | class | Immutable date without time |
+| `Time` | class | Immutable time without date (24h wraparound) |
+| `LazyGcMap` | class | Map with LRU-based automatic expiration |
+| `Bytes` | type alias | `Uint8Array` (replaces `Buffer`) |
+| `PrimitiveTypeMap` | type | Mapping of type name strings to types |
+| `PrimitiveTypeStr` | type | `keyof PrimitiveTypeMap` |
+| `PrimitiveType` | type | Union of all primitive types |
+| `DeepPartial<T>` | type | Recursively makes all properties optional |
+| `Type<T>` | interface | Constructor type for DI and factory patterns |
+| `env` | const | Unified `DEV` / `VER` environment accessor |
+
+-> See [docs/types.md](./docs/types.md) for details.
+
+### Features
+
+| API | Type | Description |
+|-----|------|-------------|
+| `EventEmitter` | class | Type-safe event emitter (EventTarget wrapper) |
+| `DebounceQueue` | class | Async debounce — only the last call executes |
+| `SerialQueue` | class | Async serial execution queue |
+
+-> See [docs/features.md](./docs/features.md) for details.
+
+### Prototype Extensions (side-effect)
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Array` extensions | prototype | 34 methods — query, transform, diff, sort, mutate |
+| `Map` extensions | prototype | `getOrCreate`, `update` |
+| `Set` extensions | prototype | `adds`, `toggle` |
+
+-> See [docs/extensions.md](./docs/extensions.md) for details.
+
+### Utilities
+
+| API | Type | Description |
+|-----|------|-------------|
+| `obj` | namespace | clone, equal, merge, merge3, omit, pick, chain access |
+| `str` | namespace | Korean particles, case conversion, full-width replacement |
+| `num` | namespace | parseInt, parseFloat, format with separators |
+| `bytes` | namespace | concat, hex, base64 conversion |
+| `path` | namespace | POSIX-only join, basename, extname |
+| `json` | namespace | Custom-type-aware JSON stringify/parse |
+| `xml` | namespace | XML parse/stringify via fast-xml-parser |
+| `wait` | namespace | `until` (polling) and `time` (delay) |
+| `transfer` | namespace | Worker-safe encode/decode for custom types |
+| `err` | namespace | Extract message from unknown error |
+| `dt` | namespace | Date format, month normalization, 12h/24h conversion |
+| `primitive` | namespace | Infer `PrimitiveTypeStr` from a value |
+| `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql` | function | Template tag functions for syntax highlighting |
+| `ZipArchive` | class | ZIP read/write/compress with caching |
+
+-> See [docs/utils.md](./docs/utils.md) for details.
+
+## Quick Usage Examples
+
+### DateTime (immutable date/time)
+
+```typescript
+import { DateTime, DateOnly } from "@simplysm/core-common";
+
+const now = new DateTime();
+const tomorrow = now.addDays(1);
+const formatted = now.toFormatString("yyyy-MM-dd HH:mm:ss");
+const parsed = DateTime.parse("2025-01-15 10:30:00");
+
+const today = new DateOnly();
+const weekInfo = today.getWeekSeqOfYear(); // { year, weekSeq }
+```
+
+### Object utilities
+
+```typescript
+import { obj, json } from "@simplysm/core-common";
+
+const cloned = obj.clone(deepObject);
+const isEqual = obj.equal(a, b, { ignoreArrayIndex: true });
+const merged = obj.merge(base, override);
+const value = obj.getChainValue(data, "a.b[0].c");
+
+// Custom-type-aware JSON
+const str = json.stringify({ date: new DateTime(), id: Uuid.generate() });
+const restored = json.parse(str); // DateTime and Uuid instances restored
+```
+
+### Array extensions
+
+```typescript
+import "@simplysm/core-common";
+
+const items = [3, 1, 4, 1, 5];
+items.distinct();          // [3, 1, 4, 5]
+items.orderBy();           // [1, 1, 3, 4, 5]
+items.sum();               // 14
+items.groupBy((x) => x % 2 === 0 ? "even" : "odd");
+
+const users = [{ id: 1, name: "A" }, { id: 2, name: "B" }];
+users.toMap((u) => u.id);  // Map { 1 => {...}, 2 => {...} }
+users.single((u) => u.id === 1); // { id: 1, name: "A" }
+```
+
+### EventEmitter
+
+```typescript
+import { EventEmitter } from "@simplysm/core-common";
+
+interface MyEvents { data: string; done: void }
+
+class MyService extends EventEmitter<MyEvents> {}
+
+const svc = new MyService();
+svc.on("data", (msg) => console.log(msg));
+svc.emit("data", "hello");
+svc.emit("done");
+```
+
+## License
+
+Apache-2.0

package/docs/errors.md

@@ -0,0 +1,119 @@
+# Errors
+
+Error classes for the Simplysm framework. All classes extend `SdError`, which itself extends `Error`.
+
+Source: `src/errors/*.ts`
+
+---
+
+## `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.
+
+```typescript
+export class SdError extends Error {
+  override 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:**
+
+```typescript
+try {
+  await fetch(url);
+} catch (err) {
+  throw new SdError(err, "API call failed", "User load failed");
+}
+// 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"
+```
+
+---
+
+## `ArgumentError`
+
+An error thrown when invalid arguments are received. Includes the argument object in YAML format in the message to facilitate debugging. Extends `SdError`.
+
+```typescript
+export class ArgumentError extends SdError {
+  /** Output argument object in YAML format with default message ("Invalid arguments.") */
+  constructor(argObj: Record<string, unknown>);
+  /** Output argument object in YAML format with a custom message */
+  constructor(message: string, argObj: Record<string, unknown>);
+}
+```
+
+**Example:**
+
+```typescript
+throw new ArgumentError({ userId: 123, name: null });
+// Result message: "Invalid arguments.\n\nuserId: 123\nname: null"
+
+throw new ArgumentError("Invalid user", { userId: 123 });
+// Result message: "Invalid user\n\nuserId: 123"
+```
+
+---
+
+## `NotImplementedError`
+
+An error thrown when a feature that has not yet been implemented is called. Extends `SdError`.
+
+```typescript
+export class NotImplementedError extends SdError {
+  /**
+   * @param message Additional description message
+   */
+  constructor(message?: string);
+}
+```
+
+**Example:**
+
+```typescript
+class BaseService {
+  process(): void {
+    throw new NotImplementedError("Implementation required in subclass");
+  }
+}
+
+switch (type) {
+  case "A": return handleA();
+  case "B": throw new NotImplementedError(`Handling for type ${type}`);
+}
+```
+
+---
+
+## `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`.
+
+```typescript
+export class TimeoutError extends SdError {
+  /**
+   * @param count Number of attempts
+   * @param message Additional message
+   */
+  constructor(count?: number, message?: string);
+}
+```
+
+**Example:**
+
+```typescript
+try {
+  await wait.until(() => isReady, 100, 50);
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    // "Waiting time exceeded(50 attempts)"
+  }
+}
+```

package/docs/extensions.md

@@ -0,0 +1,387 @@
+# Prototype Extensions (side-effect)
+
+Prototype extensions for `Array`, `Map`, and `Set`. These are applied as side effects when importing `@simplysm/core-common`.
+
+**Important:** Importing the package entry point automatically patches these prototypes. If you import only specific sub-modules, you must also import the extension modules or the entry point to get these methods.
+
+Source: `src/extensions/*.ts`
+
+---
+
+## Array Extensions
+
+### Readonly methods (return new array or value, do not mutate)
+
+#### `single`
+
+Return single element matching condition. Throws `ArgumentError` if 2+ elements match.
+
+```typescript
+single(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+#### `first`
+
+Return first element.
+
+```typescript
+first(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+#### `last`
+
+Return last element.
+
+```typescript
+last(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+#### `filterAsync`
+
+Async filter (sequential execution).
+
+```typescript
+filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+```
+
+#### `filterExists`
+
+Remove `null` and `undefined` values.
+
+```typescript
+filterExists(): NonNullable<T>[];
+```
+
+#### `ofType`
+
+Filter only elements of specific type (`PrimitiveTypeStr` or constructor type).
+
+```typescript
+ofType<TKey extends PrimitiveTypeStr>(type: TKey): Extract<T, PrimitiveTypeMap[TKey]>[];
+ofType<TNarrow extends T>(type: Type<TNarrow>): TNarrow[];
+```
+
+#### `mapAsync`
+
+Async mapping (sequential execution).
+
+```typescript
+mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+#### `mapMany`
+
+Flatten nested array, or map then flatten.
+
+```typescript
+mapMany(): T extends readonly (infer U)[] ? U[] : T;
+mapMany<R>(selector: (item: T, index: number) => R[]): R[];
+```
+
+#### `mapManyAsync`
+
+Async mapping and then flatten (sequential execution).
+
+```typescript
+mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+```
+
+#### `parallelAsync`
+
+Async parallel processing using `Promise.all`.
+
+```typescript
+parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+#### `groupBy`
+
+Group by key. O(n) for primitive keys, O(n^2) for object keys (deep comparison).
+
+```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 `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 `Map<K, T[]>` (groups values by 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`
+
+Convert to `Map<K, Set<T>>`.
+
+```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 reduce each group's values.
+
+```typescript
+toMapValues<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (items: T[]) => V,
+): Map<K, V>;
+```
+
+#### `toObject`
+
+Convert to 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`
+
+Convert flat array to tree structure. Items with `null`/`undefined` parent key become roots. Uses `toArrayMap` for O(n) complexity.
+
+```typescript
+toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
+```
+
+#### `distinct`
+
+Remove duplicates. Options: `matchAddress` for reference comparison, `keyFn` for custom key (O(n)). Without `keyFn` on objects: O(n^2).
+
+```typescript
+distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
+```
+
+#### `orderBy` / `orderByDesc`
+
+Sort in ascending or descending order. 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`
+
+Compare two arrays and return INSERT / DELETE / UPDATE results.
+
+```typescript
+diffs<P>(target: P[]): ArrayDiffsResult<T, P>[];
+diffs<P>(target: P[], options: { keys: string[]; excludes?: string[] }): ArrayDiffsResult<T, P>[];
+diffs<P>(target: P[], options: { excludes: string[] }): ArrayDiffsResult<T, P>[];
+```
+
+#### `oneWayDiffs`
+
+One-way diff against original items. Returns `"create"`, `"update"`, or `"same"` for each item.
+
+```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 source and target arrays based on diff results.
+
+```typescript
+merge<P>(target: P[]): (T | P | (T & P))[];
+merge<P>(target: P[], options: { keys: string[]; excludes?: string[] }): (T | P | (T & P))[];
+```
+
+#### `sum`
+
+Return sum of elements. Returns `0` for empty arrays.
+
+```typescript
+sum(selector?: (item: T, index: number) => number): number;
+```
+
+#### `min` / `max`
+
+Return minimum or maximum value.
+
+```typescript
+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`
+
+Return a shuffled copy (Fisher-Yates algorithm).
+
+```typescript
+shuffle(): T[];
+```
+
+---
+
+### Mutable methods (modify original array, marked `@mutates`)
+
+#### `distinctThis`
+
+Remove duplicates from original array.
+
+```typescript
+distinctThis(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
+```
+
+#### `orderByThis` / `orderByDescThis`
+
+Sort original array in ascending or descending order.
+
+```typescript
+orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+#### `insert`
+
+Insert items at index.
+
+```typescript
+insert(index: number, ...items: T[]): this;
+```
+
+#### `remove`
+
+Remove item or items matching condition.
+
+```typescript
+remove(item: T): this;
+remove(selector: (item: T, index: number) => boolean): this;
+```
+
+#### `toggle`
+
+Toggle item in array (remove if exists, add if not).
+
+```typescript
+toggle(item: T): this;
+```
+
+#### `clear`
+
+Clear all items from array.
+
+```typescript
+clear(): this;
+```
+
+---
+
+## Exported Types
+
+```typescript
+export type ArrayDiffsResult<TOriginal, TOther> =
+  | { source: undefined; target: TOther }      // INSERT
+  | { source: TOriginal; target: undefined }    // DELETE
+  | { source: TOriginal; target: TOther };      // UPDATE
+
+export type ArrayOneWayDiffResult<TItem> =
+  | { type: "create"; item: TItem; orgItem: undefined }
+  | { type: "update"; item: TItem; orgItem: TItem }
+  | { type: "same"; item: TItem; orgItem: TItem };
+
+export type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
+
+/** Type that can be sorted/compared */
+export type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
+```
+
+---
+
+## Map Extensions
+
+#### `getOrCreate`
+
+If no value exists for key, set new value and return it. If the second argument is a function, it is called as a factory.
+
+```typescript
+getOrCreate(key: K, newValue: V): V;
+getOrCreate(key: K, newValueFn: () => V): V;
+```
+
+**Caution:** If `V` is a function type, passing the function directly will be recognized as a factory and called. Wrap it in a factory to store the function itself.
+
+#### `update`
+
+Update value for key using function. Called even if key does not exist.
+
+```typescript
+update(key: K, updateFn: (v: V | undefined) => V): void;
+```
+
+**Example:**
+
+```typescript
+const countMap = new Map<string, number>();
+countMap.update("key", (v) => (v ?? 0) + 1);
+
+map.getOrCreate("users", []).push(newUser);
+```
+
+---
+
+## Set Extensions
+
+#### `adds`
+
+Add multiple values at once.
+
+```typescript
+adds(...values: T[]): this;
+```
+
+#### `toggle`
+
+Toggle value (remove if exists, add if not). Optional `addOrDel` parameter to force add or remove.
+
+```typescript
+toggle(value: T, addOrDel?: "add" | "del"): this;
+```
+
+**Example:**
+
+```typescript
+const set = new Set<number>([1, 2, 3]);
+set.toggle(2);  // 2 exists, so remove -> {1, 3}
+set.toggle(4);  // 4 doesn't exist, so add -> {1, 3, 4}
+
+const isAdmin = true;
+set.toggle(5, isAdmin ? "add" : "del"); // Force add
+```