@simplysm/core-common 13.0.82 → 13.0.83

package/README.md

@@ -0,0 +1,35 @@
+# @simplysm/core-common
+
+> Simplysm package - Core module (common)
+
+A platform-neutral (Node.js and browser) utility library providing immutable date/time types, rich Array/Map/Set extensions, typed error classes, object manipulation, serialization (JSON/XML/ZIP), and async control primitives. It serves as the leaf dependency for the entire Simplysm monorepo.
+
+## Installation
+
+```bash
+npm install @simplysm/core-common
+```
+
+## Documentation
+
+| Category | Description |
+|----------|-------------|
+| [Types](docs/types.md) | Immutable date/time classes (`DateTime`, `DateOnly`, `Time`), `Uuid`, `LazyGcMap`, and shared type aliases |
+| [Errors](docs/errors.md) | Error class hierarchy: `SdError`, `ArgumentError`, `NotImplementedError`, `TimeoutError` |
+| [Features](docs/features.md) | Async control primitives: `EventEmitter`, `DebounceQueue`, `SerialQueue` |
+| [Extensions](docs/extensions.md) | Prototype extensions for `Array`, `Map`, and `Set` |
+| [Object Utilities](docs/object-utilities.md) | `obj` namespace: `clone`, `equal`, `merge`, `merge3`, `omit`, `pick`, chain access, and type-safe Object helpers |
+| [String Utilities](docs/string-utilities.md) | `str` namespace: case conversion, Korean particles, full-width conversion, and string helpers |
+| [Number Utilities](docs/number-utilities.md) | `num` namespace: robust parsing (`parseInt`, `parseFloat`) and locale-aware formatting |
+| [Byte Utilities](docs/byte-utilities.md) | `bytes` namespace: `concat`, hex/base64 encode/decode for `Uint8Array` |
+| [Path Utilities](docs/path-utilities.md) | `path` namespace: browser-safe `join`, `basename`, `extname` (POSIX only) |
+| [JSON Utilities](docs/json-utilities.md) | `json` namespace: `stringify` / `parse` with custom type support (`DateTime`, `Set`, `Map`, `Error`, etc.) |
+| [XML Utilities](docs/xml-utilities.md) | `xml` namespace: `parse` / `stringify` via fast-xml-parser |
+| [Wait Utilities](docs/wait-utilities.md) | `wait` namespace: `time` (sleep) and `until` (poll with timeout) |
+| [Transfer Utilities](docs/transfer-utilities.md) | `transfer` namespace: Worker-safe `encode` / `decode` for custom types |
+| [Date Format Utilities](docs/date-format-utilities.md) | `dt` namespace: C#-style format strings and month normalization |
+| [Primitive Utilities](docs/primitive-utilities.md) | `primitive` namespace: runtime type-string inference |
+| [Error Utilities](docs/error-utilities.md) | `err` namespace: extract message from unknown catch values |
+| [Template Strings](docs/template-strings.md) | Tagged template literals (`js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`) with auto-indent normalization |
+| [ZIP Archive](docs/zip-archive.md) | `ZipArchive` class for reading, writing, and compressing ZIP files |
+| [Environment](docs/environment.md) | `env` object exposing `DEV` and `VER` from `process.env` |

package/docs/byte-utilities.md

@@ -0,0 +1,55 @@
+# Byte Utilities
+
+Imported as the `bytes` namespace. Provides `Uint8Array` manipulation utilities.
+
+```typescript
+import { bytes } from "@simplysm/core-common";
+```
+
+## concat
+
+```typescript
+function concat(arrays: Bytes[]): Bytes;
+```
+
+Concatenates multiple `Uint8Array` instances into a single new array.
+
+---
+
+## toHex / fromHex
+
+```typescript
+function toHex(bytes: Bytes): string;
+function fromHex(hex: string): Bytes;
+```
+
+Converts between `Uint8Array` and lowercase hex strings. `fromHex` throws `ArgumentError` for odd-length strings or invalid hex characters.
+
+---
+
+## toBase64 / fromBase64
+
+```typescript
+function toBase64(bytes: Bytes): string;
+function fromBase64(base64: string): Bytes;
+```
+
+Converts between `Uint8Array` and base64 strings. `fromBase64` throws `ArgumentError` for invalid characters or length.
+
+---
+
+## Usage Examples
+
+```typescript
+import { bytes } from "@simplysm/core-common";
+
+const a = new Uint8Array([1, 2]);
+const b = new Uint8Array([3, 4]);
+bytes.concat([a, b]); // Uint8Array [1, 2, 3, 4]
+
+bytes.toHex(new Uint8Array([255, 0, 127]));  // "ff007f"
+bytes.fromHex("ff007f"); // Uint8Array [255, 0, 127]
+
+bytes.toBase64(new Uint8Array([72, 101, 108, 108, 111])); // "SGVsbG8="
+bytes.fromBase64("SGVsbG8="); // Uint8Array [72, 101, 108, 108, 111]
+```

package/docs/date-format-utilities.md

@@ -0,0 +1,96 @@
+# Date Format Utilities
+
+Imported as the `dt` namespace. C#-style date/time formatting and month normalization.
+
+```typescript
+import { dt } from "@simplysm/core-common";
+```
+
+## format
+
+```typescript
+function format(formatString: string, args: {
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+  timezoneOffsetMinutes?: number;
+}): string;
+```
+
+Converts date/time components to a string using a C#-compatible format string.
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `yyyy` | 4-digit year | 2024 |
+| `yy` | 2-digit year | 24 |
+| `MM` | Zero-padded month | 01-12 |
+| `M` | Month | 1-12 |
+| `ddd` | Day of week (Korean) | Sun, Mon, ... |
+| `dd` | Zero-padded day | 01-31 |
+| `d` | Day | 1-31 |
+| `tt` | AM/PM | AM, PM |
+| `hh` | Zero-padded 12-hour | 01-12 |
+| `h` | 12-hour | 1-12 |
+| `HH` | Zero-padded 24-hour | 00-23 |
+| `H` | 24-hour | 0-23 |
+| `mm` | Zero-padded minute | 00-59 |
+| `m` | Minute | 0-59 |
+| `ss` | Zero-padded second | 00-59 |
+| `s` | Second | 0-59 |
+| `fff` | Milliseconds (3 digits) | 000-999 |
+| `ff` | Milliseconds (2 digits) | 00-99 |
+| `f` | Milliseconds (1 digit) | 0-9 |
+| `zzz` | Timezone offset | +09:00 |
+| `zz` | Timezone offset | +09 |
+| `z` | Timezone offset | +9 |
+
+---
+
+## normalizeMonth
+
+```typescript
+function normalizeMonth(year: number, month: number, day: number): {
+  year: number;
+  month: number;
+  day: number;
+};
+```
+
+Normalizes year/month/day when month is outside 1-12 range. Adjusts day to last day of month if needed (e.g., Jan 31 + setMonth(2) = Feb 28).
+
+---
+
+## convert12To24
+
+```typescript
+function convert12To24(rawHour: number, isPM: boolean): number;
+```
+
+Converts 12-hour format to 24-hour format. `12 AM = 0`, `12 PM = 12`.
+
+---
+
+## Usage Examples
+
+```typescript
+import { dt } from "@simplysm/core-common";
+
+dt.format("yyyy-MM-dd", { year: 2024, month: 3, day: 15 });
+// "2024-03-15"
+
+dt.format("tt h:mm:ss", { hour: 14, minute: 30, second: 45 });
+// "PM 2:30:45"
+
+dt.normalizeMonth(2025, 13, 15);
+// { year: 2026, month: 1, day: 15 }
+
+dt.normalizeMonth(2025, 2, 31);
+// { year: 2025, month: 2, day: 28 }
+
+dt.convert12To24(12, false); // 0 (12 AM)
+dt.convert12To24(12, true);  // 12 (12 PM)
+```

package/docs/environment.md

@@ -0,0 +1,35 @@
+# Environment
+
+The `env` object exposes build-time environment variables.
+
+```typescript
+import { env } from "@simplysm/core-common";
+```
+
+## env
+
+```typescript
+const env: {
+  DEV: boolean;
+  VER?: string;
+  [key: string]: unknown;
+};
+```
+
+- `DEV` - Whether running in development mode. Parsed from `process.env.DEV` (defaults to `false`).
+- `VER` - Application version string from `process.env.VER`.
+- Additional `process.env` properties are spread into the object.
+
+---
+
+## Usage Examples
+
+```typescript
+import { env } from "@simplysm/core-common";
+
+if (env.DEV) {
+  // development-only logic
+}
+
+console.log(`Version: ${env.VER}`);
+```

package/docs/error-utilities.md

@@ -0,0 +1,35 @@
+# Error Utilities
+
+Imported as the `err` namespace. Utilities for handling unknown error values.
+
+```typescript
+import { err } from "@simplysm/core-common";
+```
+
+## message
+
+```typescript
+function message(err: unknown): string;
+```
+
+Extracts a message string from an unknown error value (typically from a `catch` block). Returns `err.message` for `Error` instances, otherwise returns `String(err)`.
+
+---
+
+## Usage Examples
+
+```typescript
+import { err } from "@simplysm/core-common";
+
+try {
+  throw new Error("something failed");
+} catch (e) {
+  const msg = err.message(e); // "something failed"
+}
+
+try {
+  throw "raw string error";
+} catch (e) {
+  const msg = err.message(e); // "raw string error"
+}
+```

package/docs/errors.md

@@ -0,0 +1,79 @@
+# Errors
+
+Custom error class hierarchy with tree-structured cause chaining.
+
+## SdError
+
+```typescript
+class SdError extends Error {
+  cause?: Error;
+
+  constructor(cause: Error, ...messages: string[]);
+  constructor(...messages: string[]);
+}
+```
+
+Base error class supporting tree-structured cause chaining. Messages are joined in reverse order with ` => ` separator. The cause stack trace is appended to the current stack.
+
+---
+
+## ArgumentError
+
+```typescript
+class ArgumentError extends SdError {
+  constructor(argObj: Record<string, unknown>);
+  constructor(message: string, argObj: Record<string, unknown>);
+}
+```
+
+Error for invalid arguments. Includes the argument object formatted as YAML in the message for easy debugging.
+
+---
+
+## NotImplementedError
+
+```typescript
+class NotImplementedError extends SdError {
+  constructor(message?: string);
+}
+```
+
+Error for features not yet implemented. Used for abstract method stubs and planned branches.
+
+---
+
+## TimeoutError
+
+```typescript
+class TimeoutError extends SdError {
+  constructor(count?: number, message?: string);
+}
+```
+
+Error thrown when waiting time is exceeded. Automatically thrown by `wait.until()` when the maximum number of attempts is reached.
+
+---
+
+## Usage Examples
+
+```typescript
+import { SdError, ArgumentError, NotImplementedError, TimeoutError } from "@simplysm/core-common";
+
+// Wrap a cause error
+try {
+  await fetch(url);
+} catch (err) {
+  throw new SdError(err, "API call failed", "User load failed");
+  // message: "User load failed => API call failed => original error message"
+}
+
+// ArgumentError with YAML-formatted details
+throw new ArgumentError("Invalid user", { userId: 123, name: null });
+// message: "Invalid user\n\nuserId: 123\nname: null"
+
+// NotImplementedError
+throw new NotImplementedError("PDF export");
+
+// TimeoutError
+throw new TimeoutError(50, "Waiting for API response");
+```

package/docs/extensions.md

@@ -0,0 +1,201 @@
+# Extensions
+
+Prototype extensions for `Array`, `Map`, and `Set`. These are activated as side effects when importing from `@simplysm/core-common`.
+
+## Array Extensions (ReadonlyArray)
+
+### Query
+
+```typescript
+interface ReadonlyArray<T> {
+  single(predicate?: (item: T, index: number) => boolean): T | undefined;
+  first(predicate?: (item: T, index: number) => boolean): T | undefined;
+  last(predicate?: (item: T, index: number) => boolean): T | undefined;
+  filterExists(): NonNullable<T>[];
+  ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
+  ofType<N extends T>(type: Type<N>): N[];
+}
+```
+
+- `single` - Returns the only matching element; throws `ArgumentError` if more than one match.
+- `first` / `last` - Returns the first/last matching element, or `undefined`.
+- `filterExists` - Removes `null` and `undefined` values.
+- `ofType` - Filters elements by primitive type string or constructor type.
+
+### Async Operations
+
+```typescript
+interface ReadonlyArray<T> {
+  filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+  mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+  mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+  parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+}
+```
+
+- `filterAsync` / `mapAsync` / `mapManyAsync` - Sequential async operations (one at a time).
+- `parallelAsync` - Parallel async via `Promise.all`.
+
+### Transformation
+
+```typescript
+interface ReadonlyArray<T> {
+  mapMany<R>(selector?: (item: T, index: number) => R[]): R[];
+  groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
+  groupBy<K, V>(keySelector: ..., valueSelector: ...): { key: K; values: V[] }[];
+  toMap<K>(keySelector: ...): Map<K, T>;
+  toMap<K, V>(keySelector: ..., valueSelector: ...): Map<K, V>;
+  toMapAsync<K>(keySelector: ...): Promise<Map<K, T>>;
+  toArrayMap<K>(keySelector: ...): Map<K, T[]>;
+  toSetMap<K>(keySelector: ...): Map<K, Set<T>>;
+  toMapValues<K, V>(keySelector: ..., valueSelector: ...): Map<K, V>;
+  toObject(keySelector: ...): Record<string, T>;
+  toObject<V>(keySelector: ..., valueSelector: ...): Record<string, V>;
+  toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
+}
+```
+
+- `groupBy` - Groups by key. O(n) for primitive keys, O(n^2) for object keys.
+- `toMap` - Converts to `Map` (throws on duplicate keys).
+- `toArrayMap` / `toSetMap` - Converts to `Map<K, T[]>` or `Map<K, Set<T>>`.
+- `toTree` - Converts flat array to tree structure using key/parent-key properties.
+
+### Ordering and Deduplication
+
+```typescript
+interface ReadonlyArray<T> {
+  distinct(options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number }): T[];
+  orderBy(selector?: (item: T) => ComparableType): T[];
+  orderByDesc(selector?: (item: T) => ComparableType): T[];
+  shuffle(): T[];
+}
+```
+
+These return new arrays without modifying the original.
+
+### Aggregation
+
+```typescript
+interface ReadonlyArray<T> {
+  sum(selector?: (item: T, index: number) => number): number;
+  min(selector?: ...): number | string | undefined;
+  max(selector?: ...): number | string | undefined;
+}
+```
+
+### Diff and Merge
+
+```typescript
+interface ReadonlyArray<T> {
+  diffs<P>(target: P[], options?: { keys?: string[]; excludes?: string[] }): ArrayDiffsResult<T, P>[];
+  oneWayDiffs<K extends keyof T>(orgItems: T[] | Map<T[K], T>, keyPropNameOrGetValFn: K | ((item: T) => ...), options?: ...): ArrayOneWayDiffResult<T>[];
+  merge<P>(target: P[], options?: { keys?: string[]; excludes?: string[] }): (T | P | (T & P))[];
+}
+```
+
+- `diffs` - Computes INSERT/DELETE/UPDATE differences between two arrays.
+- `oneWayDiffs` - One-way diff returning `create` / `update` / `same` results.
+- `merge` - Deep merges matching elements from target into source.
+
+---
+
+## Array Extensions (Mutable)
+
+These methods modify the original array in-place and return `this` for chaining.
+
+```typescript
+interface Array<T> {
+  distinctThis(options?: ...): T[];
+  orderByThis(selector?: ...): T[];
+  orderByDescThis(selector?: ...): T[];
+  insert(index: number, ...items: T[]): this;
+  remove(itemOrSelector: T | ((item: T, index: number) => boolean)): this;
+  toggle(item: T): this;
+  clear(): this;
+}
+```
+
+---
+
+## Map Extensions
+
+```typescript
+interface Map<K, V> {
+  getOrCreate(key: K, newValue: V): V;
+  getOrCreate(key: K, newValueFn: () => V): V;
+  update(key: K, updateFn: (v: V | undefined) => V): void;
+}
+```
+
+- `getOrCreate` - Returns existing value, or creates and stores a new one. Accepts a direct value or a factory function.
+- `update` - Updates value using a function that receives the current value (or `undefined` if key is missing).
+
+---
+
+## Set Extensions
+
+```typescript
+interface Set<T> {
+  adds(...values: T[]): this;
+  toggle(value: T, addOrDel?: "add" | "del"): this;
+}
+```
+
+- `adds` - Adds multiple values at once.
+- `toggle` - Toggles value presence. Optional `addOrDel` parameter forces add or delete.
+
+---
+
+## Exported Types
+
+```typescript
+type ArrayDiffsResult<T, P> =
+  | { source: undefined; target: P }       // INSERT
+  | { source: T; target: undefined }        // DELETE
+  | { source: T; target: P };              // UPDATE
+
+type ArrayOneWayDiffResult<T> =
+  | { type: "create"; item: T; orgItem: undefined }
+  | { type: "update"; item: T; orgItem: T }
+  | { type: "same"; item: T; orgItem: T };
+
+type TreeArray<T> = T & { children: TreeArray<T>[] };
+type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
+```
+
+---
+
+## Usage Examples
+
+```typescript
+import "@simplysm/core-common";
+
+// Array extensions
+const items = [3, 1, 4, 1, 5, 9];
+items.distinct();                // [3, 1, 4, 5, 9]
+items.orderBy();                 // [1, 1, 3, 4, 5, 9]
+items.sum();                     // 23
+items.first((x) => x > 3);      // 4
+
+const users = [
+  { id: 1, dept: "A", name: "Alice" },
+  { id: 2, dept: "B", name: "Bob" },
+  { id: 3, dept: "A", name: "Charlie" },
+];
+users.groupBy((u) => u.dept);
+// [{ key: "A", values: [Alice, Charlie] }, { key: "B", values: [Bob] }]
+
+users.toMap((u) => u.id);
+// Map { 1 => Alice, 2 => Bob, 3 => Charlie }
+
+// Map extensions
+const map = new Map<string, number>();
+map.getOrCreate("counter", 0);  // 0
+map.update("counter", (v) => (v ?? 0) + 1); // counter = 1
+
+// Set extensions
+const set = new Set([1, 2, 3]);
+set.toggle(2);  // removes 2 -> {1, 3}
+set.toggle(4);  // adds 4 -> {1, 3, 4}
+set.adds(5, 6); // {1, 3, 4, 5, 6}
+```

package/docs/features.md

@@ -0,0 +1,88 @@
+# Features
+
+Async control primitives: type-safe event emitter, debounce queue, and serial queue.
+
+## EventEmitter
+
+```typescript
+class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
+  on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  emit<K extends keyof TEvents & string>(type: K, ...args: TEvents[K] extends void ? [] : [data: TEvents[K]]): void;
+  listenerCount<K extends keyof TEvents & string>(type: K): number;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+A type-safe event emitter that works in both browsers and Node.js. Internally implemented using `EventTarget`. Duplicate registration of the same listener to the same event is ignored.
+
+Use `void` as the event data type for events that carry no data -- `emit("done")` is called without arguments.
+
+---
+
+## DebounceQueue
+
+```typescript
+class DebounceQueue extends EventEmitter<{ error: SdError }> {
+  constructor(delay?: number);
+  run(fn: () => void | Promise<void>): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+When called multiple times within a short time, only the last request is executed. Previous requests are replaced. If `delay` is omitted, executes on the next event loop tick.
+
+Requests added during execution are processed immediately after the current execution completes (no debounce delay for mid-execution arrivals). Errors are emitted as `"error"` events; if no listener is registered, they are logged.
+
+---
+
+## SerialQueue
+
+```typescript
+class SerialQueue extends EventEmitter<{ error: SdError }> {
+  constructor(gap?: number);
+  run(fn: () => void | Promise<void>): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+```
+
+Functions added to the queue are executed sequentially -- the next task starts only after the previous one completes. Subsequent tasks continue even if an error occurs. The optional `gap` parameter adds a delay between each task. Errors are emitted as `"error"` events.
+
+---
+
+## Usage Examples
+
+```typescript
+import { EventEmitter, DebounceQueue, SerialQueue } from "@simplysm/core-common";
+
+// EventEmitter
+interface MyEvents {
+  data: string;
+  error: Error;
+  done: void;
+}
+
+class MyEmitter extends EventEmitter<MyEvents> {}
+
+const emitter = new MyEmitter();
+emitter.on("data", (data) => { /* data: string */ });
+emitter.emit("data", "hello");
+emitter.emit("done"); // void type, no arguments
+
+// DebounceQueue
+using queue = new DebounceQueue(300); // 300ms delay
+queue.on("error", (err) => { /* handle error */ });
+queue.run(() => { /* ignored */ });
+queue.run(() => { /* ignored */ });
+queue.run(() => { /* executed after 300ms */ });
+
+// SerialQueue
+using serial = new SerialQueue();
+serial.on("error", (err) => { /* handle error */ });
+serial.run(async () => { await fetch("/api/1"); });
+serial.run(async () => { await fetch("/api/2"); }); // runs after 1 completes
+serial.run(async () => { await fetch("/api/3"); }); // runs after 2 completes
+```

package/docs/json-utilities.md

@@ -0,0 +1,57 @@
+# JSON Utilities
+
+Imported as the `json` namespace. JSON serialization/deserialization with full support for custom types.
+
+```typescript
+import { json } from "@simplysm/core-common";
+```
+
+## stringify
+
+```typescript
+function stringify(obj: unknown, options?: {
+  space?: string | number;
+  replacer?: (key: string | undefined, value: unknown) => unknown;
+  redactBytes?: boolean;
+}): string;
+```
+
+Serializes an object to JSON string with custom type support. Special types are encoded as `{ __type__: "TypeName", data: ... }`.
+
+**Supported types:** `Date`, `DateTime`, `DateOnly`, `Time`, `Uuid`, `Set`, `Map`, `Error`, `Uint8Array`.
+
+- `redactBytes` replaces `Uint8Array` contents with `"__hidden__"` (for logging).
+- Objects with `toJSON()` are honored (except built-in special types).
+- Throws `TypeError` on circular references.
+
+---
+
+## parse
+
+```typescript
+function parse<T = unknown>(json: string): T;
+```
+
+Deserializes a JSON string, restoring all custom types from `__type__` markers. All JSON `null` values are converted to `undefined` (simplysm framework convention).
+
+---
+
+## Usage Examples
+
+```typescript
+import { json, DateTime, Uuid } from "@simplysm/core-common";
+
+const data = {
+  id: Uuid.generate(),
+  createdAt: new DateTime(2025, 1, 15),
+  tags: new Set(["a", "b"]),
+  meta: new Map([["key", "value"]]),
+};
+
+const str = json.stringify(data, { space: 2 });
+const restored = json.parse(str);
+// restored.id is Uuid, restored.createdAt is DateTime, etc.
+
+// Redact binary data for logging
+json.stringify({ file: new Uint8Array([1, 2, 3]) }, { redactBytes: true });
+```