@simplysm/core-common 13.0.100 → 14.0.4

package/docs/utils.md

@@ -1,264 +1,201 @@
-# Utilities
+# Utils
 
-Utility namespaces and directly exported functions.
+Namespace-exported utility functions and standalone exports. Import as `import { obj, str, num, ... } from "@simplysm/core-common"`.
 
-Source: `src/utils/*.ts`
+## `obj` -- Object Utilities
 
----
+### `obj.clone<T>(source: T): T`
 
-## Namespace: `obj`
+Deep clone with support for circular references and custom types (DateTime, DateOnly, Time, Uuid, Uint8Array, Date, RegExp, Map, Set, Error). Preserves prototype chain. Functions and Symbols are kept as references.
 
-Object manipulation utilities. Source: `src/utils/obj.ts`
+```typescript
+const cloned = obj.clone({ a: 1, b: new DateTime() });
+```
 
-### `obj.clone`
+### `obj.equal(source, target, options?): boolean`
 
-Deep clone. Supports circular references and custom types (DateTime, DateOnly, Time, Uuid, Uint8Array, Error, Map, Set, RegExp). Functions and Symbols maintain references. Prototype chain is maintained.
+Deep equality comparison.
 
 ```typescript
-export function clone<TObj>(source: TObj): TObj;
+function equal(source: unknown, target: unknown, options?: EqualOptions): boolean;
 ```
 
-### `obj.equal`
+**`EqualOptions`:**
 
-Deep equality comparison. Supports DateTime, DateOnly, Time, Uuid, Date, RegExp, Map, Set, Array, and plain objects.
+| Field | Type | Description |
+|-------|------|-------------|
+| `topLevelIncludes` | `string[]` | Only compare these top-level keys |
+| `topLevelExcludes` | `string[]` | Exclude these top-level keys from comparison |
+| `ignoreArrayIndex` | `boolean` | Ignore array order (O(n^2)) |
+| `shallow` | `boolean` | Compare only one level deep (reference equality for nested) |
 
-```typescript
-export function equal(source: unknown, target: unknown, options?: EqualOptions): boolean;
+Supports: Date, DateTime, DateOnly, Time, Uuid, RegExp, Array, Map, Set, plain objects.
 
-export interface EqualOptions {
-  /** List of keys to compare (applies only to top level) */
-  topLevelIncludes?: string[];
-  /** List of keys to exclude from comparison (applies only to top level) */
-  topLevelExcludes?: string[];
-  /** Whether to ignore array order. O(n^2) complexity when true */
-  ignoreArrayIndex?: boolean;
-  /** Whether to do shallow comparison. Only compare 1 level (reference comparison) when true */
-  shallow?: boolean;
-}
-```
-
-### `obj.merge`
+### `obj.merge<S, T>(source: S, target: T, opt?): S & T`
 
-Deep merge (merge target into source as base). Returns a new object without modifying originals.
+Deep merge. Returns a new object (immutable).
 
 ```typescript
-export function merge<TSource, TMergeTarget>(
-  source: TSource,
-  target: TMergeTarget,
-  opt?: MergeOptions,
-): TSource & TMergeTarget;
-
-export interface MergeOptions {
-  /** Array processing method. "replace": replace with target (default), "concat": merge (deduplicate) */
-  arrayProcess?: "replace" | "concat";
-  /** Whether to delete the key when target is null */
-  useDelTargetNull?: boolean;
-}
+function merge<S, T>(source: S, target: T, opt?: MergeOptions): S & T;
 ```
 
-### `obj.merge3`
+**`MergeOptions`:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `arrayProcess` | `"replace" \| "concat"` | `"replace"` | How to handle arrays. `"concat"` deduplicates via Set |
+| `useDelTargetNull` | `boolean` | `false` | If `true`, `null` target values delete the key |
 
-3-way merge. Compares source, origin, and target to produce a merged result with conflict detection.
+### `obj.merge3<S, O, T>(source, origin, target, optionsObj?)`
+
+3-way merge. Compares source and target against a common origin.
 
 ```typescript
-export function merge3<
-  S extends Record<string, unknown>,
-  O extends Record<string, unknown>,
-  T extends Record<string, unknown>,
->(
-  source: S,
-  origin: O,
-  target: T,
+function merge3<S, O, T>(
+  source: S, origin: O, target: T,
   optionsObj?: Record<string, Merge3KeyOptions>,
 ): { conflict: boolean; result: O & S & T };
-
-export interface Merge3KeyOptions {
-  /** List of sub-keys to compare (same as equal's topLevelIncludes) */
-  keys?: string[];
-  /** List of sub-keys to exclude from comparison */
-  excludes?: string[];
-  /** Whether to ignore array order */
-  ignoreArrayIndex?: boolean;
-}
 ```
 
-### `obj.omit`
+**`Merge3KeyOptions`:**
 
-Exclude specific keys from object.
+| Field | Type | Description |
+|-------|------|-------------|
+| `keys` | `string[]` | Sub-keys to compare |
+| `excludes` | `string[]` | Sub-keys to exclude |
+| `ignoreArrayIndex` | `boolean` | Ignore array order |
 
-```typescript
-export function omit<T extends Record<string, unknown>, K extends keyof T>(item: T, omitKeys: K[]): Omit<T, K>;
-```
+Rules: origin -> source change wins; origin -> target change wins; both changed same way = ok; both changed differently = conflict (origin value kept).
 
-### `obj.omitByFilter`
+### `obj.omit<T, K>(item, omitKeys): Omit<T, K>`
 
-Exclude keys matching condition.
+Returns a new object excluding the specified keys.
 
 ```typescript
-export function omitByFilter<T extends Record<string, unknown>>(item: T, omitKeyFn: (key: keyof T) => boolean): T;
+obj.omit({ a: 1, b: 2, c: 3 }, ["c"]); // { a: 1, b: 2 }
 ```
 
-### `obj.pick`
+### `obj.omitByFilter<T>(item, omitKeyFn): T`
 
-Select specific keys from object.
+Returns a new object excluding keys where the predicate returns `true`.
 
 ```typescript
-export function pick<T extends Record<string, unknown>, K extends keyof T>(item: T, pickKeys: K[]): Pick<T, K>;
+obj.omitByFilter({ name: "a", _internal: "x" }, (k) => k.startsWith("_"));
 ```
 
-### `obj.getChainValue`
+### `obj.pick<T, K>(item, pickKeys): Pick<T, K>`
 
-Get value by chain path (e.g., `"a.b[0].c"`).
+Returns a new object with only the specified keys.
 
 ```typescript
-export function getChainValue(obj: unknown, chain: string): unknown;
-export function getChainValue(obj: unknown, chain: string, optional: true): unknown | undefined;
+obj.pick({ a: 1, b: 2, c: 3 }, ["a", "b"]); // { a: 1, b: 2 }
 ```
 
-### `obj.getChainValueByDepth`
+### `obj.getChainValue(obj, chain, optional?): unknown`
 
-Descend by the same key for depth levels.
+Access a deeply nested value using a dot/bracket chain string.
 
 ```typescript
-export function getChainValueByDepth<TObject, TKey extends keyof TObject>(
-  obj: TObject, key: TKey, depth: number,
-): TObject[TKey];
-export function getChainValueByDepth<TObject, TKey extends keyof TObject>(
-  obj: TObject, key: TKey, depth: number, optional: true,
-): TObject[TKey] | undefined;
+obj.getChainValue(data, "a.b[0].c");
+obj.getChainValue(data, "a?.b?.c", true); // returns undefined if intermediate is missing
 ```
 
-### `obj.setChainValue`
+### `obj.getChainValueByDepth<T, K>(obj, key, depth, optional?)`
 
-Set value by chain path.
+Descend into the same key repeatedly by a given depth.
 
 ```typescript
-export function setChainValue(obj: unknown, chain: string, value: unknown): void;
+obj.getChainValueByDepth({ parent: { parent: { name: "root" } } }, "parent", 2);
+// { name: "root" }
 ```
 
-### `obj.deleteChainValue`
+### `obj.setChainValue(obj, chain, value): void`
 
-Delete value by chain path.
+Set a deeply nested value. Creates intermediate objects as needed.
 
 ```typescript
-export function deleteChainValue(obj: unknown, chain: string): void;
+obj.setChainValue(data, "a.b[0].c", 42);
 ```
 
-### `obj.clearUndefined`
+### `obj.deleteChainValue(obj, chain): void`
 
-Delete keys with `undefined` values from object. Mutates the original.
+Delete a deeply nested value.
 
 ```typescript
-export function clearUndefined<T extends object>(obj: T): T;
+obj.deleteChainValue(data, "a.b[0].c");
 ```
 
-### `obj.clear`
+### `obj.clearUndefined<T>(obj): T`
 
-Delete all keys from object. Mutates the original.
+Mutates: deletes keys with `undefined` values from an object.
 
-```typescript
-export function clear<T extends Record<string, unknown>>(obj: T): Record<string, never>;
-```
+### `obj.clear<T>(obj): Record<string, never>`
 
-### `obj.nullToUndefined`
+Mutates: deletes all keys from an object.
 
-Convert `null` to `undefined` recursively. Mutates the original.
+### `obj.nullToUndefined<T>(obj): T | undefined`
 
-```typescript
-export function nullToUndefined<TObject>(obj: TObject): TObject | undefined;
-```
+Mutates: recursively converts all `null` values to `undefined`.
 
-### `obj.unflatten`
+### `obj.unflatten(flatObj): Record<string, unknown>`
 
-Convert flattened object to nested object.
+Converts a flat dotted-key object to a nested object.
 
 ```typescript
-export function unflatten(flatObj: Record<string, unknown>): Record<string, unknown>;
-// Example: unflatten({ "a.b.c": 1 }) => { a: { b: { c: 1 } } }
+obj.unflatten({ "a.b.c": 1 }); // { a: { b: { c: 1 } } }
 ```
 
-### `obj.keys`
+### `obj.keys<T>(obj): (keyof T)[]`
 
 Type-safe `Object.keys`.
 
-```typescript
-export function keys<T extends object>(obj: T): (keyof T)[];
-```
-
-### `obj.entries`
+### `obj.entries<T>(obj): [keyof T, T[keyof T]][]`
 
 Type-safe `Object.entries`.
 
-```typescript
-export function entries<T extends object>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][];
-```
-
-### `obj.fromEntries`
+### `obj.fromEntries<T>(entries): object`
 
 Type-safe `Object.fromEntries`.
 
-```typescript
-export function fromEntries<T extends [string, unknown]>(entryPairs: T[]): { [K in T[0]]: T[1] };
-```
-
-### `obj.map`
+### `obj.map<S, K, V>(obj, fn): Record<K, V>`
 
-Transform each entry of object and return new object.
+Transform each entry of an object. The `fn` receives `(key, value)` and returns `[newKey | null, newValue]`. If `newKey` is `null`, the original key is preserved.
 
 ```typescript
-export function map<TSource extends object, TNewKey extends string, TNewValue>(
-  obj: TSource,
-  fn: (key: keyof TSource, value: TSource[keyof TSource]) => [TNewKey | null, TNewValue],
-): Record<TNewKey | Extract<keyof TSource, string>, TNewValue>;
+obj.map({ a: 1, b: 2 }, (k, v) => [null, v * 10]);
+// { a: 10, b: 20 }
 ```
 
-**Example:**
+### Type Utilities (from `obj`)
 
-```typescript
-const colors = { primary: "255, 0, 0", secondary: "0, 255, 0" };
+#### `UndefToOptional<T>`
 
-// Transform only values (pass null for key to keep original)
-obj.map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
-// { primary: "rgb(255, 0, 0)", secondary: "rgb(0, 255, 0)" }
+Converts properties that include `undefined` in their type to optional properties.
 
-// Transform both keys and values
-obj.map(colors, (key, rgb) => [`${key}Light`, `rgb(${rgb})`]);
-// { primaryLight: "rgb(255, 0, 0)", secondaryLight: "rgb(0, 255, 0)" }
+```typescript
+type UndefToOptional<T> = { [K in ...]?: T[K] } & { [K in ...]: T[K] };
 ```
 
-### Type utilities from `obj`
+#### `OptionalToUndef<T>`
 
-```typescript
-/** Convert properties with undefined to optional */
-export type UndefToOptional<TObject> = {
-  [K in keyof TObject as undefined extends TObject[K] ? K : never]?: TObject[K];
-} & { [K in keyof TObject as undefined extends TObject[K] ? never : K]: TObject[K] };
+Converts optional properties to required properties with `| undefined`.
 
-/** Convert optional properties to required + undefined union */
-export type OptionalToUndef<TObject> = {
-  [K in keyof TObject]-?: {} extends Pick<TObject, K> ? TObject[K] | undefined : TObject[K];
-};
+```typescript
+type OptionalToUndef<T> = { [K in keyof T]-?: ... };
 ```
 
----
+## `str` -- String Utilities
 
-## Namespace: `str`
+### `str.getKoreanSuffix(text, type): string`
 
-String utility functions. Source: `src/utils/str.ts`
-
-### `str.getKoreanSuffix`
-
-Return the appropriate Korean particle based on the final consonant (jongseong).
+Returns the appropriate Korean suffix based on whether the last character has a final consonant.
 
 ```typescript
-export function getKoreanSuffix(
-  text: string,
-  type: "을" | "은" | "이" | "와" | "랑" | "로" | "라",
-): string;
+function getKoreanSuffix(text: string, type: "을" | "은" | "이" | "와" | "랑" | "로" | "라"): string;
 ```
 
-| Type | With final consonant | Without final consonant |
-|------|---------------------|------------------------|
+| Type | With final consonant | Without |
+|------|---------------------|---------|
 | `"을"` | 을 | 를 |
 | `"은"` | 은 | 는 |
 | `"이"` | 이 | 가 |
@@ -267,364 +204,305 @@ export function getKoreanSuffix(
 | `"로"` | 으로 | 로 |
 | `"라"` | 이라 | 라 |
 
-### `str.replaceFullWidth`
+### `str.replaceFullWidth(str): string`
 
-Convert full-width characters to half-width (A-Z, a-z, 0-9, space, parentheses).
+Converts full-width characters to half-width (A-Z, a-z, 0-9, space, parentheses).
 
 ```typescript
-export function replaceFullWidth(str: string): string;
+str.replaceFullWidth("Ａ１２３"); // "A123"
 ```
 
-### `str.toPascalCase`
+### `str.toPascalCase(str): string`
+
+Converts to PascalCase. Handles `-`, `_`, `.` separators.
 
 ```typescript
-export function toPascalCase(str: string): string;
-// "hello-world" -> "HelloWorld"
-// "hello_world" -> "HelloWorld"
-// "hello.world" -> "HelloWorld"
+str.toPascalCase("hello-world"); // "HelloWorld"
 ```
 
-### `str.toCamelCase`
+### `str.toCamelCase(str): string`
+
+Converts to camelCase.
 
 ```typescript
-export function toCamelCase(str: string): string;
-// "hello-world" -> "helloWorld"
-// "hello_world" -> "helloWorld"
-// "HelloWorld"  -> "helloWorld"
+str.toCamelCase("hello-world"); // "helloWorld"
 ```
 
-### `str.toKebabCase`
+### `str.toKebabCase(str): string`
+
+Converts to kebab-case from PascalCase/camelCase.
 
 ```typescript
-export function toKebabCase(str: string): string;
-// "HelloWorld" -> "hello-world"
-// "helloWorld" -> "hello-world"
+str.toKebabCase("HelloWorld"); // "hello-world"
 ```
 
-### `str.toSnakeCase`
+### `str.toSnakeCase(str): string`
+
+Converts to snake_case from PascalCase/camelCase.
 
 ```typescript
-export function toSnakeCase(str: string): string;
-// "HelloWorld" -> "hello_world"
-// "helloWorld" -> "hello_world"
+str.toSnakeCase("HelloWorld"); // "hello_world"
 ```
 
-### `str.isNullOrEmpty`
+### `str.isNullOrEmpty(str): str is "" | undefined`
 
-Check if string is `undefined`, `null`, or empty (type guard).
+Type guard that returns `true` if the string is `undefined`, `null`, or `""`.
 
 ```typescript
-export function isNullOrEmpty(str: string | undefined): str is "" | undefined;
+if (!str.isNullOrEmpty(name)) {
+  // name is guaranteed to be a non-empty string
+}
 ```
 
-### `str.insert`
+### `str.insert(str, index, insertString): string`
 
-Insert a string at a specific position.
+Inserts a string at the given position.
 
 ```typescript
-export function insert(str: string, index: number, insertString: string): string;
-// insert("Hello World", 5, ",") => "Hello, World"
+str.insert("Hello World", 5, ","); // "Hello, World"
 ```
 
----
+## `num` -- Number Utilities
 
-## Namespace: `num`
+### `num.parseInt(text): number | undefined`
 
-Number utility functions. Source: `src/utils/num.ts`
+Parses a string to integer. Strips non-numeric characters first (keeps `0-9`, `-`, `.`). Returns `undefined` if unparseable.
 
-### `num.parseInt`
+### `num.parseFloat(text): number | undefined`
 
-Parse string to integer. Removes non-numeric characters before parsing.
+Parses a string to float. Strips non-numeric characters first.
 
-```typescript
-export function parseInt(text: unknown): number | undefined;
-```
+### `num.parseRoundedInt(text): number | undefined`
 
-### `num.parseRoundedInt`
+Parses to float then rounds to nearest integer.
 
-Parse string to float, then round and return integer.
+### `num.isNullOrEmpty(val): val is 0 | undefined`
 
-```typescript
-export function parseRoundedInt(text: unknown): number | undefined;
-```
+Type guard that returns `true` if the value is `undefined`, `null`, or `0`.
 
-### `num.parseFloat`
+### `num.format(val, digit?): string | undefined`
 
-Parse string to float. Removes non-numeric characters before parsing.
+Formats a number with thousands separators and optional decimal control.
 
 ```typescript
-export function parseFloat(text: unknown): number | undefined;
+function format(val: number, digit?: { max?: number; min?: number }): string;
+function format(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined;
 ```
 
-### `num.isNullOrEmpty`
-
-Check `undefined`, `null`, `0` (type guard).
-
 ```typescript
-export function isNullOrEmpty(val: number | undefined): val is 0 | undefined;
+num.format(1234.567, { max: 2 }); // "1,234.57"
+num.format(1234, { min: 2 });     // "1,234.00"
 ```
 
-### `num.format`
+## `bytes` -- Uint8Array Utilities
 
-Format number to string with thousand separators.
+### `bytes.concat(arrays): Bytes`
 
-```typescript
-export function format(val: number, digit?: { max?: number; min?: number }): string;
-export function format(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined;
-// num.format(1234.567, { max: 2 }) => "1,234.57"
-// num.format(1234, { min: 2 })     => "1,234.00"
-```
+Concatenates multiple `Uint8Array` instances into one.
 
----
+### `bytes.toHex(bytes): string`
 
-## Namespace: `bytes`
+Converts to lowercase hex string.
 
-Uint8Array utility functions. Source: `src/utils/bytes.ts`
+### `bytes.fromHex(hex): Bytes`
 
-### `bytes.concat`
+Converts hex string to `Uint8Array`. Throws `ArgumentError` on invalid input.
 
-Concatenate multiple Uint8Arrays.
+### `bytes.toBase64(bytes): string`
 
-```typescript
-export function concat(arrays: Bytes[]): Bytes;
-```
+Converts to base64 string.
 
-### `bytes.toHex`
+### `bytes.fromBase64(base64): Bytes`
 
-Convert to lowercase hex string.
+Converts base64 string to `Uint8Array`. Throws `ArgumentError` on invalid input.
 
 ```typescript
-export function toHex(bytes: Bytes): string;
+const a = new Uint8Array([1, 2]);
+const b = new Uint8Array([3, 4]);
+bytes.concat([a, b]);        // Uint8Array([1, 2, 3, 4])
+bytes.toHex(a);              // "0102"
+bytes.toBase64(a);           // "AQI="
+bytes.fromHex("ff00");       // Uint8Array([255, 0])
+bytes.fromBase64("SGVsbG8="); // Uint8Array([72, 101, 108, 108, 111])
 ```
 
-### `bytes.fromHex`
+## `path` -- Path Utilities
 
-Convert from hex string to Uint8Array.
+POSIX-style path utilities (forward slash only). Designed for browser and Capacitor environments. Does not support Windows backslash paths.
 
-```typescript
-export function fromHex(hex: string): Bytes;
-```
+### `path.join(...segments): string`
 
-### `bytes.toBase64`
+Joins path segments with `/`.
 
-Convert Bytes to base64 string.
+### `path.basename(filePath, ext?): string`
 
-```typescript
-export function toBase64(bytes: Bytes): string;
-```
+Extracts the file name from a path. Optionally strips the extension.
 
-### `bytes.fromBase64`
+### `path.extname(filePath): string`
 
-Convert base64 string to Bytes.
+Extracts the file extension (including the dot). Hidden files (e.g., `.gitignore`) return `""`.
 
 ```typescript
-export function fromBase64(base64: string): Bytes;
+path.join("a", "b", "c.txt");     // "a/b/c.txt"
+path.basename("/dir/file.txt");    // "file.txt"
+path.basename("/dir/file.txt", ".txt"); // "file"
+path.extname("/dir/file.txt");     // ".txt"
 ```
 
----
-
-## Namespace: `path`
-
-Path utility functions. Replacement for Node.js `path` module (supports browser environments). POSIX style paths only (slash `/`).
-
-Source: `src/utils/path.ts`
+## `json` -- JSON Utilities
 
-### `path.join`
+JSON stringify/parse with support for custom types: DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array, Date.
 
-Combine paths.
+### `json.stringify(obj, options?): string`
 
 ```typescript
-export function join(...segments: string[]): string;
+function stringify(obj: unknown, options?: {
+  space?: string | number;
+  replacer?: (key: string | undefined, value: unknown) => unknown;
+  redactBytes?: boolean;
+}): string;
 ```
 
-### `path.basename`
+| Option | Description |
+|--------|-------------|
+| `space` | Indentation (number of spaces or string) |
+| `replacer` | Custom replacer called before built-in type conversion |
+| `redactBytes` | If `true`, replaces `Uint8Array` content with `"__hidden__"` (for logging) |
 
-Extract filename.
+Custom types are serialized as `{ __type__: "TypeName", data: ... }`. Circular references throw `TypeError`.
 
-```typescript
-export function basename(filePath: string, ext?: string): string;
-```
+### `json.parse<T>(json): T`
 
-### `path.extname`
-
-Extract file extension. Hidden files (e.g., `.gitignore`) return empty string.
+Restores custom types from `__type__` markers. All JSON `null` values are converted to `undefined` (simplysm null-free convention).
 
 ```typescript
-export function extname(filePath: string): string;
+const data = json.parse<MyType>(jsonString);
 ```
 
----
-
-## Namespace: `json`
-
-JSON serialization/deserialization supporting custom types (DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array).
-
-Source: `src/utils/json.ts`
-
-### `json.stringify`
+## `xml` -- XML Utilities
 
-Serialize object to JSON string. Supports custom types via `__type__` markers.
+Built on `fast-xml-parser`.
 
-```typescript
-export function stringify(
-  obj: unknown,
-  options?: {
-    space?: string | number;
-    replacer?: (key: string | undefined, value: unknown) => unknown;
-    redactBytes?: boolean;
-  },
-): string;
-```
+### `xml.parse(str, options?): unknown`
 
-### `json.parse`
-
-Deserialize JSON string to object. Restores custom types from `__type__` markers. All JSON `null` values are converted to `undefined`.
+Parses XML string to an object. Attributes are grouped under `$`, text nodes under `_`, child elements as arrays.
 
 ```typescript
-export function parse<TResult = unknown>(json: string): TResult;
+function parse(str: string, options?: { stripTagPrefix?: boolean }): unknown;
 ```
 
----
-
-## Namespace: `xml`
-
-XML conversion utility using fast-xml-parser.
-
-Source: `src/utils/xml.ts`
-
-### `xml.parse`
-
-Parse XML string into an object. Attributes grouped in `$`, text nodes in `_`, child elements as arrays.
+| Option | Description |
+|--------|-------------|
+| `stripTagPrefix` | Remove namespace prefixes from tag names |
 
 ```typescript
-export function parse(str: string, options?: { stripTagPrefix?: boolean }): unknown;
+xml.parse('<root id="1"><item>hello</item></root>');
+// { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
 ```
 
-### `xml.stringify`
+### `xml.stringify(obj, options?): string`
 
-Serialize object to XML string.
+Converts an object to XML string.
 
 ```typescript
-export function stringify(obj: unknown, options?: XmlBuilderOptions): string;
+function stringify(obj: unknown, options?: XmlBuilderOptions): string;
 ```
 
----
-
-## Namespace: `wait`
+## `wait` -- Wait Utilities
 
-Wait utility functions. Source: `src/utils/wait.ts`
+### `wait.until(forwarder, milliseconds?, maxCount?): Promise<void>`
 
-### `wait.until`
-
-Wait until a condition becomes true.
+Polls a condition function until it returns `true`.
 
 ```typescript
-export async function until(
+function until(
   forwarder: () => boolean | Promise<boolean>,
-  milliseconds?: number,
-  maxCount?: number,
+  milliseconds?: number,  // default: 100ms
+  maxCount?: number,      // default: unlimited
 ): Promise<void>;
 ```
 
-- `milliseconds`: Check interval (default: 100ms)
-- `maxCount`: Maximum number of attempts (`undefined` for unlimited)
-- Throws `TimeoutError` when maximum number of attempts is exceeded
+Throws `TimeoutError` if `maxCount` is reached.
 
-### `wait.time`
+### `wait.time(millisecond): Promise<void>`
 
-Wait for a specified amount of time.
+Delays for the specified number of milliseconds.
 
 ```typescript
-export async function time(millisecond: number): Promise<void>;
+await wait.time(1000); // wait 1 second
 ```
 
----
-
-## Namespace: `transfer`
+## `transfer` -- Transferable Utilities
 
-Transferable conversion utility for Worker data transfer. Handles custom types that `structuredClone` does not support.
+Encode/decode objects for Worker `postMessage` with zero-copy `ArrayBuffer` transfer. Handles custom types that `structuredClone` does not support.
 
-Source: `src/utils/transferable.ts`
+### `transfer.encode(obj): { result, transferList }`
 
-Supported types: Date, DateTime, DateOnly, Time, Uuid, RegExp, Error (including cause, code, detail), Uint8Array, Array, Map, Set, plain objects.
-
-### `transfer.encode`
-
-Convert objects using Simplysm types to plain objects for Worker transfer.
+Encodes an object for Worker transfer. Custom types become tagged objects. `Uint8Array` buffers are added to `transferList` for zero-copy transfer.
 
 ```typescript
-export function encode(obj: unknown): {
+function encode(obj: unknown): {
   result: unknown;
-  transferList: Transferable[];
+  transferList: ArrayBuffer[];
 };
 ```
 
-### `transfer.decode`
+Throws `TypeError` on circular references (with path info).
+
+Supported types: Date, DateTime, DateOnly, Time, Uuid, RegExp, Error, Uint8Array, Array, Map, Set, plain objects.
 
-Convert serialized objects back to Simplysm types.
+### `transfer.decode(obj): unknown`
+
+Decodes a previously encoded object, restoring custom types.
 
 ```typescript
-export function decode(obj: unknown): unknown;
+function decode(obj: unknown): unknown;
 ```
 
-**Example:**
-
 ```typescript
+// Sending
 const { result, transferList } = transfer.encode(data);
 worker.postMessage(result, transferList);
 
-// In worker:
+// Receiving
 const decoded = transfer.decode(event.data);
 ```
 
----
-
-## Namespace: `err`
-
-Error utility. Source: `src/utils/error.ts`
+## `err` -- Error Utilities
 
-### `err.message`
+### `err.message(err): string`
 
-Extract message from unknown type error. Returns `message` property for `Error` instances, otherwise `String(err)`.
+Extracts a message string from an `unknown` error value.
 
 ```typescript
-export function message(err: unknown): string;
+function message(err: unknown): string;
 ```
 
----
+Returns `err.message` if `err` is an `Error`, otherwise `String(err)`.
 
-## Namespace: `dt`
+## `dt` -- Date Format Utilities
 
-Date format utilities. Source: `src/utils/date-format.ts`
+### `dt.format(formatString, args): string`
 
-### `dt.normalizeMonth`
-
-Normalize year/month/day when setting month. Adjusts year for out-of-range months, clamps day to last day of month.
+Formats date/time components using C#-style format strings.
 
 ```typescript
-export function normalizeMonth(year: number, month: number, day: number): DtNormalizedMonth;
-
-export interface DtNormalizedMonth {
-  year: number;
-  month: number;
-  day: number;
-}
+function format(formatString: string, args: {
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+  timezoneOffsetMinutes?: number;
+}): string;
 ```
 
-### `dt.convert12To24`
+**Format patterns:**
 
-Convert 12-hour format to 24-hour format.
-
-```typescript
-export function convert12To24(rawHour: number, isPM: boolean): number;
-```
-
-### `dt.format`
-
-Convert date/time components to string according to format string. Supports C#-style format specifiers:
-
-| Format | Description | Example |
-|--------|-------------|---------|
+| Pattern | Description | Example |
+|---------|-------------|---------|
 | `yyyy` | 4-digit year | 2024 |
 | `yy` | 2-digit year | 24 |
 | `MM` | Zero-padded month | 01-12 |
@@ -633,125 +511,131 @@ Convert date/time components to string according to format string. Supports C#-s
 | `dd` | Zero-padded day | 01-31 |
 | `d` | Day | 1-31 |
 | `tt` | AM/PM | AM, PM |
-| `hh` / `h` | 12-hour (zero-padded / plain) | 01-12 / 1-12 |
-| `HH` / `H` | 24-hour (zero-padded / plain) | 00-23 / 0-23 |
-| `mm` / `m` | Minute (zero-padded / plain) | 00-59 / 0-59 |
-| `ss` / `s` | Second (zero-padded / plain) | 00-59 / 0-59 |
-| `fff` / `ff` / `f` | Milliseconds (3/2/1 digits) | 000-999 |
-| `zzz` / `zz` / `z` | Timezone offset | +09:00 / +09 / +9 |
+| `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 minutes | 00-59 |
+| `m` | Minutes | 0-59 |
+| `ss` | Zero-padded seconds | 00-59 |
+| `s` | Seconds | 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 (hours) | +09 |
+| `z` | Timezone offset (short) | +9 |
+
+### `dt.normalizeMonth(year, month, day): DtNormalizedMonth`
+
+Normalizes month overflow/underflow and adjusts day to fit the target month.
 
 ```typescript
-export function format(
-  formatString: string,
-  args: {
-    year?: number;
-    month?: number;
-    day?: number;
-    hour?: number;
-    minute?: number;
-    second?: number;
-    millisecond?: number;
-    timezoneOffsetMinutes?: number;
-  },
-): string;
+dt.normalizeMonth(2025, 13, 15); // { year: 2026, month: 1, day: 15 }
+dt.normalizeMonth(2025, 2, 31);  // { year: 2025, month: 2, day: 28 }
 ```
 
----
+### `dt.convert12To24(rawHour, isPM): number`
+
+Converts 12-hour format to 24-hour format.
 
-## Namespace: `primitive`
+## `primitive` -- Primitive Type Utilities
 
-Primitive type inference. Source: `src/utils/primitive.ts`
+### `primitive.typeStr(value): PrimitiveTypeStr`
 
-### `primitive.typeStr`
+Returns the `PrimitiveTypeStr` for a given value at runtime.
 
-Infer `PrimitiveTypeStr` from a value at runtime.
+```typescript
+function typeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]): PrimitiveTypeStr;
+```
 
 ```typescript
-export function typeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]): PrimitiveTypeStr;
-// primitive.typeStr("hello")          => "string"
-// primitive.typeStr(new DateTime())   => "DateTime"
-// primitive.typeStr(new Uint8Array()) => "Bytes"
+primitive.typeStr("hello");           // "string"
+primitive.typeStr(123);               // "number"
+primitive.typeStr(true);              // "boolean"
+primitive.typeStr(new DateTime());    // "DateTime"
+primitive.typeStr(new Uint8Array());  // "Bytes"
 ```
 
----
+Throws `ArgumentError` for unsupported types.
 
-## Direct Exports: Template Tag Functions
+## Template String Tags
 
-Template string tag functions for IDE code highlighting support. Actual behavior is string concatenation with indent normalization (leading/trailing blank lines removed, common indentation stripped).
+Template tag functions for IDE syntax highlighting. All perform string interpolation + indent normalization (strips common leading whitespace).
 
-Source: `src/utils/template-strings.ts`
+### `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`
 
 ```typescript
-export function js(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function html(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
-export function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+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;
 ```
 
-**Example:**
-
 ```typescript
-const query = tsql`
-  SELECT TOP 10 *
-  FROM Users
-  WHERE Name LIKE '%${keyword}%'
+const code = ts`
+  interface User {
+    name: string;
+    age: number;
+  }
 `;
+// Result: "interface User {\n  name: string;\n  age: number;\n}"
 ```
 
----
-
-## Direct Export: `ZipArchive`
-
-ZIP archive processing class. Handles reading, writing, compression, and decompression of ZIP files. Uses internal caching to prevent duplicate decompression. Supports `await using` (`Symbol.asyncDispose`).
+## `ZipArchive`
 
-Source: `src/utils/zip.ts`
+ZIP file read/write/compress/extract. Supports `await using` syntax (`Symbol.asyncDispose`).
 
 ```typescript
-export class ZipArchive {
-  /**
-   * @param data ZIP data (omit to create a new archive)
-   */
+class ZipArchive {
   constructor(data?: Blob | Bytes);
 
-  /** Extract all files with optional progress callback */
-  async extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
-
-  /** Extract specific file */
   async get(fileName: string): Promise<Bytes | undefined>;
-
-  /** Check if file exists */
   async exists(fileName: string): Promise<boolean>;
-
-  /** Write file (store in cache) */
   write(fileName: string, bytes: Bytes): void;
-
-  /** Compress cached files to ZIP */
+  async extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
   async compress(): Promise<Bytes>;
-
-  /** Close reader and clear cache */
   async close(): Promise<void>;
-
   async [Symbol.asyncDispose](): Promise<void>;
 }
+```
+
+### `ZipArchiveProgress`
 
-export interface ZipArchiveProgress {
+```typescript
+interface ZipArchiveProgress {
   fileName: string;
   totalSize: number;
   extractedSize: number;
 }
 ```
 
-**Example:**
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `get(fileName)` | Extract a single file. Cached after first extraction |
+| `exists(fileName)` | Check if a file exists in the archive |
+| `write(fileName, bytes)` | Write a file to the cache (for compression) |
+| `extractAll(callback?)` | Extract all files with optional progress reporting |
+| `compress()` | Compress all cached files into a ZIP `Uint8Array` |
+| `close()` | Close the reader and clear cache |
 
 ```typescript
-// Read
+// Reading a ZIP
 await using archive = new ZipArchive(zipBytes);
 const content = await archive.get("file.txt");
 
-// Create
+// Creating a ZIP
 await using archive = new ZipArchive();
 archive.write("file.txt", textBytes);
+archive.write("data.json", jsonBytes);
 const zipBytes = await archive.compress();
+
+// Extracting all with progress
+const files = await archive.extractAll((p) => {
+  console.log(`${p.fileName}: ${p.extractedSize}/${p.totalSize}`);
+});
 ```