@simplysm/core-common 13.0.84 → 13.0.86

package/docs/extensions.md

@@ -1,201 +0,0 @@
-# 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/json-utilities.md

@@ -1,57 +0,0 @@
-# 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 });
-```

package/docs/number-utilities.md

@@ -1,76 +0,0 @@
-# Number Utilities
-
-Imported as the `num` namespace.
-
-```typescript
-import { num } from "@simplysm/core-common";
-```
-
-## parseInt
-
-```typescript
-function parseInt(text: unknown): number | undefined;
-```
-
-Parses a string to integer after stripping non-numeric characters (except `0-9`, `-`, `.`). Returns `undefined` for non-parsable input. For strings with decimals, returns only the integer part (truncates).
-
----
-
-## parseFloat
-
-```typescript
-function parseFloat(text: unknown): number | undefined;
-```
-
-Parses a string to float after stripping non-numeric characters. Returns `undefined` for non-parsable input.
-
----
-
-## parseRoundedInt
-
-```typescript
-function parseRoundedInt(text: unknown): number | undefined;
-```
-
-Parses to float then rounds to the nearest integer.
-
----
-
-## isNullOrEmpty
-
-```typescript
-function isNullOrEmpty(val: number | undefined): val is 0 | undefined;
-```
-
-Type guard that returns `true` for `undefined`, `null`, or `0`.
-
----
-
-## format
-
-```typescript
-function format(val: number, digit?: { max?: number; min?: number }): string;
-function format(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined;
-```
-
-Formats a number with locale-aware thousand separators. Control decimal places with `max` (maximum) and `min` (minimum, zero-padded).
-
----
-
-## Usage Examples
-
-```typescript
-import { num } from "@simplysm/core-common";
-
-num.parseInt("$1,234");           // 1234
-num.parseInt("12.34");            // 12
-num.parseFloat("$1,234.56");     // 1234.56
-num.parseRoundedInt("12.6");     // 13
-
-num.isNullOrEmpty(0);            // true
-num.isNullOrEmpty(undefined);    // true
-num.isNullOrEmpty(42);           // false
-
-num.format(1234.567, { max: 2 });  // "1,234.57"
-num.format(1234, { min: 2 });      // "1,234.00"
-```

package/docs/object-utilities.md

@@ -1,165 +0,0 @@
-# Object Utilities
-
-Imported as the `obj` namespace. Provides deep clone, equality, merge, object manipulation, and chain-path access.
-
-```typescript
-import { obj } from "@simplysm/core-common";
-```
-
-## clone
-
-```typescript
-function clone<T>(source: T): T;
-```
-
-Deep clone supporting circular references, custom types (`DateTime`, `DateOnly`, `Time`, `Uuid`, `Uint8Array`, `Error`, `RegExp`, `Map`, `Set`), and prototype chain preservation. Functions and Symbols maintain references.
-
----
-
-## equal
-
-```typescript
-function equal(source: unknown, target: unknown, options?: EqualOptions): boolean;
-
-interface EqualOptions {
-  topLevelIncludes?: string[];
-  topLevelExcludes?: string[];
-  ignoreArrayIndex?: boolean;
-  shallow?: boolean;
-}
-```
-
-Deep equality comparison with support for custom types. Options allow filtering compared keys at top level, ignoring array order (O(n^2)), or doing shallow reference comparison.
-
----
-
-## merge
-
-```typescript
-function merge<S, T>(source: S, target: T, opt?: MergeOptions): S & T;
-
-interface MergeOptions {
-  arrayProcess?: "replace" | "concat";
-  useDelTargetNull?: boolean;
-}
-```
-
-Deep merge of target into source. Returns a new object (immutable). Arrays default to replacement; use `"concat"` for deduplication via Set. When `useDelTargetNull` is true, `null` in target deletes the key.
-
----
-
-## merge3
-
-```typescript
-function merge3<S, O, T>(
-  source: S,
-  origin: O,
-  target: T,
-  optionsObj?: Record<string, Merge3KeyOptions>,
-): { conflict: boolean; result: O & S & T };
-
-interface Merge3KeyOptions {
-  keys?: string[];
-  excludes?: string[];
-  ignoreArrayIndex?: boolean;
-}
-```
-
-Three-way merge comparing source, origin, and target. Returns whether a conflict occurred and the merged result.
-
----
-
-## omit / pick
-
-```typescript
-function omit<T, K extends keyof T>(item: T, omitKeys: K[]): Omit<T, K>;
-function pick<T, K extends keyof T>(item: T, pickKeys: K[]): Pick<T, K>;
-```
-
-Create new objects by excluding or including specific keys.
-
----
-
-## Chain Access
-
-```typescript
-function getChainValue(obj: unknown, chain: string): unknown;
-function getChainValue(obj: unknown, chain: string, optional: true): unknown | undefined;
-function setChainValue(obj: unknown, chain: string, value: unknown): void;
-function deleteChainValue(obj: unknown, chain: string): void;
-```
-
-Get, set, or delete values using dot-bracket chain paths (e.g., `"a.b[0].c"`).
-
----
-
-## keys / entries / fromEntries
-
-```typescript
-function keys<T extends object>(obj: T): (keyof T)[];
-function entries<T extends object>(obj: T): [keyof T, T[keyof T]][];
-function fromEntries<T extends [string, unknown]>(entries: T[]): { [K in T[0]]: T[1] };
-```
-
-Type-safe wrappers around `Object.keys`, `Object.entries`, and `Object.fromEntries`.
-
----
-
-## map
-
-```typescript
-function map<S extends object, K extends string, V>(
-  obj: S,
-  fn: (key: keyof S, value: S[keyof S]) => [K | null, V],
-): Record<K | Extract<keyof S, string>, V>;
-```
-
-Transforms each entry of an object. Return `[null, newValue]` to keep the original key, or `[newKey, newValue]` to rename.
-
----
-
-## Type Utilities
-
-```typescript
-type UndefToOptional<T>; // { a: string; b: string | undefined } -> { a: string; b?: string | undefined }
-type OptionalToUndef<T>; // { a: string; b?: string } -> { a: string; b: string | undefined }
-```
-
----
-
-## Usage Examples
-
-```typescript
-import { obj } from "@simplysm/core-common";
-
-// Clone
-const original = { a: 1, nested: { b: 2 } };
-const copy = obj.clone(original);
-
-// Equal
-obj.equal({ a: 1 }, { a: 1 }); // true
-obj.equal([1, 2], [2, 1], { ignoreArrayIndex: true }); // true
-
-// Merge
-obj.merge({ a: 1, b: 2 }, { b: 3, c: 4 }); // { a: 1, b: 3, c: 4 }
-
-// 3-way merge
-const { conflict, result } = obj.merge3(
-  { a: 1, b: 2 },  // source
-  { a: 1, b: 1 },  // origin
-  { a: 2, b: 1 },  // target
-);
-// conflict: false, result: { a: 2, b: 2 }
-
-// Omit / Pick
-obj.omit({ name: "Alice", age: 30, email: "a@b.c" }, ["email"]);
-// { name: "Alice", age: 30 }
-
-// Chain access
-const data = { a: { b: [{ c: 42 }] } };
-obj.getChainValue(data, "a.b[0].c"); // 42
-obj.setChainValue(data, "a.b[0].c", 99);
-
-// Type-safe Object helpers
-obj.keys({ x: 1, y: 2 }); // ["x", "y"] with type (keyof { x; y })[]
-```

package/docs/path-utilities.md

@@ -1,54 +0,0 @@
-# Path Utilities
-
-Imported as the `path` namespace. Browser-safe replacements for Node.js `path` module functions.
-
-```typescript
-import { path } from "@simplysm/core-common";
-```
-
-**Note:** Supports POSIX-style paths (forward slash `/`) only. Windows backslash paths are not supported.
-
-## join
-
-```typescript
-function join(...segments: string[]): string;
-```
-
-Combines path segments (replacement for `path.join`).
-
----
-
-## basename
-
-```typescript
-function basename(filePath: string, ext?: string): string;
-```
-
-Extracts the filename from a path. Optionally removes the specified extension.
-
----
-
-## extname
-
-```typescript
-function extname(filePath: string): string;
-```
-
-Extracts the file extension. Hidden files (e.g., `.gitignore`) return an empty string, matching Node.js behavior.
-
----
-
-## Usage Examples
-
-```typescript
-import { path } from "@simplysm/core-common";
-
-path.join("a", "b", "c.txt");          // "a/b/c.txt"
-path.join("/root/", "/dir/", "file");   // "/root/dir/file"
-
-path.basename("/dir/file.txt");         // "file.txt"
-path.basename("/dir/file.txt", ".txt"); // "file"
-
-path.extname("archive.tar.gz");  // ".gz"
-path.extname(".gitignore");      // ""
-```

package/docs/primitive-utilities.md

@@ -1,40 +0,0 @@
-# Primitive Utilities
-
-Imported as the `primitive` namespace. Runtime type-string inference.
-
-```typescript
-import { primitive } from "@simplysm/core-common";
-```
-
-## typeStr
-
-```typescript
-function typeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]): PrimitiveTypeStr;
-```
-
-Infers the `PrimitiveTypeStr` from a runtime value. Throws `ArgumentError` if the type is not supported.
-
-**Mapping:**
-- `string` -> `"string"`
-- `number` -> `"number"`
-- `boolean` -> `"boolean"`
-- `DateTime` -> `"DateTime"`
-- `DateOnly` -> `"DateOnly"`
-- `Time` -> `"Time"`
-- `Uuid` -> `"Uuid"`
-- `Uint8Array` -> `"Bytes"`
-
----
-
-## Usage Examples
-
-```typescript
-import { primitive, DateTime, Uuid } from "@simplysm/core-common";
-
-primitive.typeStr("hello");           // "string"
-primitive.typeStr(123);               // "number"
-primitive.typeStr(true);              // "boolean"
-primitive.typeStr(new DateTime());    // "DateTime"
-primitive.typeStr(Uuid.generate());   // "Uuid"
-primitive.typeStr(new Uint8Array());  // "Bytes"
-```

package/docs/string-utilities.md

@@ -1,79 +0,0 @@
-# String Utilities
-
-Imported as the `str` namespace.
-
-```typescript
-import { str } from "@simplysm/core-common";
-```
-
-## getKoreanSuffix
-
-```typescript
-function getKoreanSuffix(text: string, type: "eul" | "eun" | "i" | "wa" | "rang" | "ro" | "ra"): string;
-```
-
-Returns the appropriate Korean grammatical particle based on whether the last character has a final consonant (jongseong). Supports seven particle types.
-
----
-
-## replaceFullWidth
-
-```typescript
-function replaceFullWidth(str: string): string;
-```
-
-Converts full-width characters to half-width: uppercase/lowercase letters, digits, spaces, and parentheses.
-
----
-
-## Case Conversion
-
-```typescript
-function toPascalCase(str: string): string;  // "hello-world" -> "HelloWorld"
-function toCamelCase(str: string): string;   // "hello-world" -> "helloWorld"
-function toKebabCase(str: string): string;   // "HelloWorld" -> "hello-world"
-function toSnakeCase(str: string): string;   // "HelloWorld" -> "hello_world"
-```
-
-Converts between PascalCase, camelCase, kebab-case, and snake_case. Input separators (`-`, `_`, `.`) are recognized.
-
----
-
-## isNullOrEmpty
-
-```typescript
-function isNullOrEmpty(str: string | undefined): str is "" | undefined;
-```
-
-Type guard that returns `true` for `undefined`, `null`, or empty string.
-
----
-
-## insert
-
-```typescript
-function insert(str: string, index: number, insertString: string): string;
-```
-
-Inserts a string at the specified position.
-
----
-
-## Usage Examples
-
-```typescript
-import { str } from "@simplysm/core-common";
-
-str.toPascalCase("hello-world");   // "HelloWorld"
-str.toCamelCase("HelloWorld");     // "helloWorld"
-str.toKebabCase("HelloWorld");     // "hello-world"
-str.toSnakeCase("helloWorld");     // "hello_world"
-
-str.replaceFullWidth("ABC123"); // "ABC123"
-
-str.isNullOrEmpty("");          // true
-str.isNullOrEmpty(undefined);   // true
-str.isNullOrEmpty("hello");     // false
-
-str.insert("Hello World", 5, ","); // "Hello, World"
-```