@simplysm/core-common 13.0.82 → 13.0.84

package/docs/number-utilities.md

@@ -0,0 +1,76 @@
+# 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

@@ -0,0 +1,165 @@
+# 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

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,40 @@
+# 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

@@ -0,0 +1,79 @@
+# 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"
+```

package/docs/template-strings.md

@@ -0,0 +1,105 @@
+# Template Strings
+
+Tagged template literals for IDE code highlighting with automatic indentation normalization.
+
+These are directly exported (not namespaced).
+
+```typescript
+import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
+```
+
+## js
+
+```typescript
+function js(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for JavaScript code. Provides syntax highlighting in supported IDEs and normalizes indentation.
+
+---
+
+## ts
+
+```typescript
+function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for TypeScript code.
+
+---
+
+## html
+
+```typescript
+function html(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for HTML markup.
+
+---
+
+## tsql
+
+```typescript
+function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for MSSQL T-SQL queries.
+
+---
+
+## mysql
+
+```typescript
+function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for MySQL SQL queries.
+
+---
+
+## pgsql
+
+```typescript
+function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+Template tag for PostgreSQL SQL queries.
+
+---
+
+## Behavior
+
+All template tags perform the same operations:
+1. Concatenate the template strings with interpolated values.
+2. Strip leading and trailing empty lines.
+3. Determine the minimum indentation across all non-empty lines.
+4. Remove that common indentation prefix from every line.
+
+---
+
+## Usage Examples
+
+```typescript
+import { js, html, tsql } from "@simplysm/core-common";
+
+const name = "World";
+const code = js`
+  function hello() {
+    return "${name}";
+  }
+`;
+// "function hello() {\n  return \"World\";\n}"
+
+const markup = html`
+  <div class="container">
+    <span>${name}</span>
+  </div>
+`;
+
+const query = tsql`
+  SELECT TOP 10 *
+  FROM Users
+  WHERE Name LIKE '%${name}%'
+`;
+```

package/docs/transfer-utilities.md

@@ -0,0 +1,53 @@
+# Transfer Utilities
+
+Imported as the `transfer` namespace. Serialization/deserialization for Worker data transfer.
+
+```typescript
+import { transfer } from "@simplysm/core-common";
+```
+
+## encode
+
+```typescript
+function encode(obj: unknown): {
+  result: unknown;
+  transferList: Transferable[];
+};
+```
+
+Converts objects with custom types into plain objects suitable for `postMessage`. Returns the encoded result and a list of transferable `ArrayBuffer` objects for zero-copy transfer. Throws `TypeError` on circular references (with path info).
+
+**Supported types:** `Date`, `DateTime`, `DateOnly`, `Time`, `Uuid`, `RegExp`, `Error`, `Uint8Array`, `Array`, `Map`, `Set`, plain objects.
+
+---
+
+## decode
+
+```typescript
+function decode(obj: unknown): unknown;
+```
+
+Restores tagged objects (with `__type__` markers) back to their original custom types. Use this on the receiving side of Worker messages.
+
+---
+
+## Usage Examples
+
+```typescript
+import { transfer, DateTime, Uuid } from "@simplysm/core-common";
+
+// Sending data to Worker
+const data = {
+  id: Uuid.generate(),
+  timestamp: new DateTime(),
+  buffer: new Uint8Array([1, 2, 3]),
+};
+const { result, transferList } = transfer.encode(data);
+worker.postMessage(result, transferList);
+
+// Receiving data from Worker
+worker.onmessage = (event) => {
+  const decoded = transfer.decode(event.data);
+  // decoded.id is Uuid, decoded.timestamp is DateTime, etc.
+};
+```