@simplysm/core-common 14.0.4 → 14.0.5

package/docs/errors.md

@@ -1,14 +1,14 @@
 # Errors
 
-A hierarchy of error classes built on `SdError`, which supports tree-structured cause chaining via the ES2024 `cause` property.
+All error classes extend `SdError`, which extends the native `Error`.
 
 ## `SdError`
 
-Base error class with cause-chain support. Messages are joined in reverse order with ` => `.
+Tree-structured error class. Supports cause chaining via the ES2024 `cause` property. Messages are joined in reverse order with ` => ` separator.
 
 ```typescript
 class SdError extends Error {
-  cause?: Error;
+  override cause?: Error;
 
   constructor(cause: Error, ...messages: string[]);
   constructor(...messages: string[]);
@@ -16,27 +16,15 @@ class SdError extends Error {
 ```
 
 | 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]"` |
+|----------------------|-------------|
+| `new SdError(cause, ...messages)` | Wrap a cause error. Final message: `"outermost => ... => cause.message"` |
+| `new SdError(...messages)` | Messages only. Final message: `"outermost => ... => innermost"` |
 
-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>"
-}
-
-throw new SdError("Invalid state", "Cannot process");
-// message: "Cannot process => Invalid state"
-```
+The cause chain stack trace is appended to the current stack under a `---- cause stack ----` separator.
 
 ## `ArgumentError`
 
-Error for invalid arguments. Extends `SdError`. Formats the argument object as YAML in the message for easy debugging.
+Invalid argument error. Extends `SdError`. Formats the argument object as YAML in the error message for debugging.
 
 ```typescript
 class ArgumentError extends SdError {
@@ -46,21 +34,13 @@ class ArgumentError extends SdError {
 ```
 
 | 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 });
-// message: "잘못된 인자입니다.\n\nuserId: 123\nname: null"
-
-throw new ArgumentError("Invalid user", { userId: 123 });
-// message: "Invalid user\n\nuserId: 123"
-```
+|----------------------|-------------|
+| `new ArgumentError(argObj)` | Default message + YAML dump of arguments |
+| `new ArgumentError(message, argObj)` | Custom message + YAML dump of arguments |
 
 ## `NotImplementedError`
 
-Error for unimplemented features. Extends `SdError`.
+Unimplemented feature error. Extends `SdError`. Use for abstract method stubs or future branches.
 
 ```typescript
 class NotImplementedError extends SdError {
@@ -72,17 +52,9 @@ class NotImplementedError extends SdError {
 |-----------|------|-------------|
 | `message` | `string \| undefined` | Optional description of what is not implemented |
 
-```typescript
-throw new NotImplementedError();
-// message: "미구현"
-
-throw new NotImplementedError("Subclass must override");
-// message: "미구현: Subclass must override"
-```
-
 ## `TimeoutError`
 
-Error for timeout conditions. Extends `SdError`.
+Timeout exceeded error. Extends `SdError`. Thrown by `wait.until()` when max retry count is exceeded.
 
 ```typescript
 class TimeoutError extends SdError {
@@ -92,13 +64,5 @@ class TimeoutError extends SdError {
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `count` | `number \| undefined` | Number of attempts made |
-| `message` | `string \| undefined` | Additional description |
-
-```typescript
-throw new TimeoutError(50);
-// message: "대기 시간 초과(50회 시도)"
-
-throw new TimeoutError(undefined, "API response wait exceeded");
-// message: "대기 시간 초과: API response wait exceeded"
-```
+| `count` | `number \| undefined` | Number of attempts made before timeout |
+| `message` | `string \| undefined` | Additional context message |

package/docs/features.md

@@ -1,10 +1,10 @@
 # Features
 
-Async queue and event emitter utilities. All support `using` syntax via `Symbol.dispose`.
-
 ## `DebounceQueue`
 
-Async debounce queue. When called multiple times in rapid succession, only the last enqueued function executes after the delay. Extends `EventEmitter<{ error: SdError }>`.
+Async debounce queue. When multiple calls arrive in quick succession, only the last enqueued function executes after the delay. Extends `EventEmitter<{ error: SdError }>`.
+
+If a new request arrives while a previous one is executing, it runs immediately after the current execution completes (no debounce delay).
 
 ```typescript
 class DebounceQueue extends EventEmitter<{ error: SdError }> {
@@ -16,36 +16,27 @@ class DebounceQueue extends EventEmitter<{ error: SdError }> {
 }
 ```
 
-### Constructor
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `delay` | `number \| undefined` | `undefined` (next event loop) | Debounce delay in milliseconds |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `delay` | `number \| undefined` | Debounce delay in ms. If omitted, executes on next event loop tick. |
 
 ### Methods
 
 | Method | Description |
 |--------|-------------|
-| `run(fn)` | Enqueue a function. Replaces any previously pending function. After the delay, executes the last enqueued function |
-| `dispose()` | Cancels pending timer and clears state |
+| `run(fn)` | Enqueue a function. Replaces any previously pending function. |
+| `dispose()` | Cancel pending work and clean up timers. |
+| `[Symbol.dispose]()` | Supports `using` statement. |
 
-### Behavior
+### Error Handling
 
-- If a new `run()` call arrives while a previous function is executing, the new function runs immediately after the current one completes (no debounce delay).
-- Errors are emitted as `"error"` events if listeners exist; otherwise logged via consola.
+Errors from the executed function are emitted as `"error"` events. If no listener is registered, errors are logged via `consola`.
 
-```typescript
-const queue = new DebounceQueue(300);
-queue.on("error", (err) => console.error(err));
-
-queue.run(() => console.log("1")); // cancelled
-queue.run(() => console.log("2")); // cancelled
-queue.run(() => console.log("3")); // executes after 300ms
-```
+---
 
 ## `SerialQueue`
 
-Async serial queue. Functions are executed one at a time in the order they are enqueued. Errors in one function do not prevent subsequent functions from running. Extends `EventEmitter<{ error: SdError }>`.
+Async serial queue. Functions are executed one at a time in FIFO order. Errors in one task do not prevent subsequent tasks from running. Extends `EventEmitter<{ error: SdError }>`.
 
 ```typescript
 class SerialQueue extends EventEmitter<{ error: SdError }> {
@@ -57,72 +48,65 @@ class SerialQueue extends EventEmitter<{ error: SdError }> {
 }
 ```
 
-### Constructor
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `gap` | `number` | `0` | Delay between each task execution (ms) |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `gap` | `number` | Delay between tasks in ms. Default: `0`. |
 
 ### Methods
 
 | Method | Description |
 |--------|-------------|
-| `run(fn)` | Add a function to the queue. Starts processing if not already running |
-| `dispose()` | Clears the pending queue. The currently running task still completes |
+| `run(fn)` | Add a function to the queue. Starts processing if not already running. |
+| `dispose()` | Clear the pending queue (current task completes). |
+| `[Symbol.dispose]()` | Supports `using` statement. |
 
-```typescript
-const queue = new SerialQueue();
-queue.on("error", (err) => console.error(err));
+### Error Handling
 
-queue.run(async () => { await fetch("/api/1"); }); // runs first
-queue.run(async () => { await fetch("/api/2"); }); // runs after 1 completes
-queue.run(async () => { await fetch("/api/3"); }); // runs after 2 completes
-```
+Same as `DebounceQueue`: errors are emitted as `"error"` events or logged if no listener.
+
+---
 
 ## `EventEmitter<TEvents>`
 
-Type-safe event emitter built on the `EventTarget` API. Works in both browser and Node.js.
+Type-safe event emitter built on the `EventTarget` API. Works in both browser and Node.js. Duplicate listener registration for the same event is silently ignored.
 
 ```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]]
+  on<TEventName extends keyof TEvents & string>(
+    type: TEventName,
+    listener: (data: TEvents[TEventName]) => void,
+  ): void;
+
+  off<TEventName extends keyof TEvents & string>(
+    type: TEventName,
+    listener: (data: TEvents[TEventName]) => void,
+  ): void;
+
+  emit<TEventName extends keyof TEvents & string>(
+    type: TEventName,
+    ...args: TEvents[TEventName] extends void ? [] : [data: TEvents[TEventName]]
   ): void;
-  listenerCount<K extends keyof TEvents & string>(type: K): number;
+
+  listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): number;
+
   dispose(): void;
   [Symbol.dispose](): void;
 }
 ```
 
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `on(type, listener)` | Register a listener. Duplicate registration for the same event+listener is ignored |
-| `off(type, listener)` | Remove a listener |
-| `emit(type, data?)` | Dispatch an event. For `void` event types, data argument is omitted |
-| `listenerCount(type)` | Returns the number of registered listeners for an event type |
-| `dispose()` | Removes all listeners from all event types |
-
 ### Type Parameter
 
-`TEvents` is a map where keys are event names and values are event data types. Use `void` for events with no data.
+| Parameter | Description |
+|-----------|-------------|
+| `TEvents` | Object type mapping event names to their data types. Use `void` for events with no data. |
 
-```typescript
-interface MyEvents {
-  data: string;
-  error: Error;
-  done: void;
-}
-
-class MyService extends EventEmitter<MyEvents> {}
+### Methods
 
-const svc = new MyService();
-svc.on("data", (data) => {});   // data: string
-svc.on("done", () => {});       // no argument
-svc.emit("data", "hello");
-svc.emit("done");               // no argument needed
-```
+| Method | Description |
+|--------|-------------|
+| `on(type, listener)` | Register a listener. Duplicate registration for same event is ignored. |
+| `off(type, listener)` | Remove a listener. |
+| `emit(type, ...args)` | Dispatch an event. For `void` event types, no data argument is needed. |
+| `listenerCount(type)` | Return the number of listeners for an event type. |
+| `dispose()` | Remove all listeners from all events. |
+| `[Symbol.dispose]()` | Supports `using` statement. |

package/docs/map-extensions.md

@@ -0,0 +1,41 @@
+# Map Extensions
+
+Prototype extensions added to the global `Map` type. Available after importing `@simplysm/core-common`.
+
+## `Map.prototype.getOrCreate`
+
+Get the value for a key. If the key does not exist, create a new value (using the provided value or factory function), store it, and return it.
+
+```typescript
+interface Map<K, V> {
+  getOrCreate(key: K, newValue: V): V;
+  getOrCreate(key: K, newValueFn: () => V): V;
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `K` | The key to look up |
+| `newValue` | `V` | Default value to store if key is absent |
+| `newValueFn` | `() => V` | Factory function called only if key is absent |
+
+**Returns:** `V` -- the existing or newly created value.
+
+**Note:** If `V` is a function type (e.g., `Map<string, () => void>`), passing a function directly as the second argument will be treated as a factory. Wrap it in another function: `map.getOrCreate("key", () => myFn)`.
+
+---
+
+## `Map.prototype.update`
+
+Update the value for a key using a transform function. The function receives the current value (or `undefined` if the key does not exist) and its return value is stored.
+
+```typescript
+interface Map<K, V> {
+  update(key: K, updateFn: (v: V | undefined) => V): void;
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `K` | The key to update |
+| `updateFn` | `(v: V \| undefined) => V` | Transform function. Receives current value or `undefined`. |

package/docs/set-extensions.md

@@ -0,0 +1,38 @@
+# Set Extensions
+
+Prototype extensions added to the global `Set` type. Available after importing `@simplysm/core-common`.
+
+## `Set.prototype.adds`
+
+Add multiple values at once.
+
+```typescript
+interface Set<T> {
+  adds(...values: T[]): this;
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | `T[]` | Values to add |
+
+**Returns:** `this` (for method chaining)
+
+---
+
+## `Set.prototype.toggle`
+
+Toggle a value in the set. If the value exists, remove it; if absent, add it. Optionally force add or delete.
+
+```typescript
+interface Set<T> {
+  toggle(value: T, addOrDel?: "add" | "del"): this;
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `T` | The value to toggle |
+| `addOrDel` | `"add" \| "del" \| undefined` | Force `"add"` to always add, `"del"` to always remove. Omit for automatic toggle. |
+
+**Returns:** `this` (for method chaining)

package/docs/template-strings-and-zip.md

@@ -0,0 +1,87 @@
+# Template Strings and Zip
+
+## Template String Tag Functions
+
+All template tag functions perform the same operation: combine the template literals and normalize indentation. They exist as separate functions to enable IDE syntax highlighting for different languages.
+
+Each function:
+1. Joins the template strings with interpolated values
+2. Removes leading and trailing blank lines
+3. Calculates the minimum indentation across all non-empty lines
+4. Removes that minimum indentation from every line
+
+```typescript
+function js(strings: TemplateStringsArray, ...values: unknown[]): string;
+function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
+function html(strings: TemplateStringsArray, ...values: unknown[]): string;
+function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
+function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+| Function | Purpose |
+|----------|---------|
+| `js` | JavaScript code highlighting |
+| `ts` | TypeScript code highlighting |
+| `html` | HTML markup highlighting |
+| `tsql` | MSSQL T-SQL highlighting |
+| `mysql` | MySQL SQL highlighting |
+| `pgsql` | PostgreSQL SQL highlighting |
+
+---
+
+## `ZipArchiveProgress`
+
+Progress callback data for ZIP extraction.
+
+```typescript
+interface ZipArchiveProgress {
+  fileName: string;
+  totalSize: number;
+  extractedSize: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fileName` | `string` | Name of the file currently being extracted |
+| `totalSize` | `number` | Total uncompressed size of all files in bytes |
+| `extractedSize` | `number` | Cumulative bytes extracted so far |
+
+---
+
+## `ZipArchive`
+
+ZIP archive processing class. Supports reading, writing, compressing, and extracting ZIP files. Uses internal caching to avoid duplicate decompression. Built on `@zip.js/zip.js`.
+
+```typescript
+class ZipArchive {
+  constructor(data?: Blob | Bytes);
+
+  get(fileName: string): Promise<Bytes | undefined>;
+  exists(fileName: string): Promise<boolean>;
+  write(fileName: string, bytes: Bytes): void;
+  extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
+  compress(): Promise<Bytes>;
+  close(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `Blob \| Bytes \| undefined` | Existing ZIP data to read. Omit to create a new empty archive. |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get(fileName)` | `Promise<Bytes \| undefined>` | Extract a single file by name. Returns `undefined` if not found. Caches the result. |
+| `exists(fileName)` | `Promise<boolean>` | Check if a file exists in the archive. |
+| `write(fileName, bytes)` | `void` | Write a file to the cache (for later compression). |
+| `extractAll(progressCallback?)` | `Promise<Map<string, Bytes \| undefined>>` | Extract all files. Returns a Map of filename to bytes. Optionally reports progress. |
+| `compress()` | `Promise<Bytes>` | Compress all cached files into a new ZIP. Calls `extractAll()` internally first. |
+| `close()` | `Promise<void>` | Close the reader and clear the cache. |
+| `[Symbol.asyncDispose]()` | `Promise<void>` | Supports `await using` statement. Calls `close()`. |

package/docs/type-utilities.md

@@ -1,18 +1,20 @@
 # Type Utilities
 
-TypeScript type aliases and interfaces exported from `common.types.ts`.
+Exported from `common.types.ts`.
 
 ## `Bytes`
 
-Type alias for `Uint8Array`. Used throughout the framework instead of `Buffer`.
+Alias for `Uint8Array`. Used in place of Node.js `Buffer` throughout the framework.
 
 ```typescript
 type Bytes = Uint8Array;
 ```
 
+---
+
 ## `PrimitiveTypeMap`
 
-Maps primitive type string keys to their corresponding TypeScript types. Shared with `orm-common`.
+Maps primitive type string keys to their TypeScript types. Shared with `orm-common`.
 
 ```typescript
 type PrimitiveTypeMap = {
@@ -27,65 +29,47 @@ type PrimitiveTypeMap = {
 };
 ```
 
+---
+
 ## `PrimitiveTypeStr`
 
-Union of all keys in `PrimitiveTypeMap`.
+Union of all primitive type name strings.
 
 ```typescript
 type PrimitiveTypeStr = keyof PrimitiveTypeMap;
 // "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
 ```
 
+---
+
 ## `PrimitiveType`
 
-Union of all primitive type values (including `undefined`).
+Union of all primitive type values, plus `undefined`.
 
 ```typescript
 type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
-// string | number | boolean | DateTime | DateOnly | Time | Uuid | Uint8Array | undefined
 ```
 
-## `DeepPartial<TObject>`
+---
+
+## `DeepPartial<T>`
 
-Recursively makes all properties optional. Primitive types (`PrimitiveType`) are preserved as-is; only object/array types are recursively made partial.
+Recursively make all properties optional. Primitive types (string, number, boolean, DateTime, DateOnly, Time, Uuid, Bytes) are left as-is; only object/array types are recursively made partial.
 
 ```typescript
 type DeepPartial<TObject> = Partial<{
-  [K in keyof TObject]: TObject[K] extends PrimitiveType
-    ? TObject[K]
-    : DeepPartial<TObject[K]>;
+  [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
 }>;
 ```
 
-```typescript
-interface User {
-  name: string;
-  profile: {
-    age: number;
-    address: { city: string };
-  };
-}
-
-const partial: DeepPartial<User> = {
-  profile: { address: {} },
-};
-```
+---
 
-## `Type<TInstance>`
+## `Type<T>`
 
-Constructor type interface. Represents a class constructor that creates instances of `TInstance`. Used for dependency injection, factory patterns, and `instanceof` checks.
+Constructor type interface. Represents a class constructor that produces instances of type `T`. Used for dependency injection, factory patterns, and `instanceof` checks.
 
 ```typescript
 interface Type<TInstance> extends Function {
   new (...args: unknown[]): TInstance;
 }
 ```
-
-```typescript
-function create<T>(ctor: Type<T>): T {
-  return new ctor();
-}
-
-class MyClass { name = "test"; }
-const instance = create(MyClass); // MyClass instance
-```