@simplysm/core-common 14.0.1 → 14.0.4

package/docs/utils.md

@@ -0,0 +1,641 @@
+# Utils
+
+Namespace-exported utility functions and standalone exports. Import as `import { obj, str, num, ... } from "@simplysm/core-common"`.
+
+## `obj` -- Object Utilities
+
+### `obj.clone<T>(source: T): T`
+
+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.
+
+```typescript
+const cloned = obj.clone({ a: 1, b: new DateTime() });
+```
+
+### `obj.equal(source, target, options?): boolean`
+
+Deep equality comparison.
+
+```typescript
+function equal(source: unknown, target: unknown, options?: EqualOptions): boolean;
+```
+
+**`EqualOptions`:**
+
+| 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) |
+
+Supports: Date, DateTime, DateOnly, Time, Uuid, RegExp, Array, Map, Set, plain objects.
+
+### `obj.merge<S, T>(source: S, target: T, opt?): S & T`
+
+Deep merge. Returns a new object (immutable).
+
+```typescript
+function merge<S, T>(source: S, target: T, opt?: MergeOptions): S & T;
+```
+
+**`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 |
+
+### `obj.merge3<S, O, T>(source, origin, target, optionsObj?)`
+
+3-way merge. Compares source and target against a common origin.
+
+```typescript
+function merge3<S, O, T>(
+  source: S, origin: O, target: T,
+  optionsObj?: Record<string, Merge3KeyOptions>,
+): { conflict: boolean; result: O & S & T };
+```
+
+**`Merge3KeyOptions`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `keys` | `string[]` | Sub-keys to compare |
+| `excludes` | `string[]` | Sub-keys to exclude |
+| `ignoreArrayIndex` | `boolean` | Ignore array order |
+
+Rules: origin -> source change wins; origin -> target change wins; both changed same way = ok; both changed differently = conflict (origin value kept).
+
+### `obj.omit<T, K>(item, omitKeys): Omit<T, K>`
+
+Returns a new object excluding the specified keys.
+
+```typescript
+obj.omit({ a: 1, b: 2, c: 3 }, ["c"]); // { a: 1, b: 2 }
+```
+
+### `obj.omitByFilter<T>(item, omitKeyFn): T`
+
+Returns a new object excluding keys where the predicate returns `true`.
+
+```typescript
+obj.omitByFilter({ name: "a", _internal: "x" }, (k) => k.startsWith("_"));
+```
+
+### `obj.pick<T, K>(item, pickKeys): Pick<T, K>`
+
+Returns a new object with only the specified keys.
+
+```typescript
+obj.pick({ a: 1, b: 2, c: 3 }, ["a", "b"]); // { a: 1, b: 2 }
+```
+
+### `obj.getChainValue(obj, chain, optional?): unknown`
+
+Access a deeply nested value using a dot/bracket chain string.
+
+```typescript
+obj.getChainValue(data, "a.b[0].c");
+obj.getChainValue(data, "a?.b?.c", true); // returns undefined if intermediate is missing
+```
+
+### `obj.getChainValueByDepth<T, K>(obj, key, depth, optional?)`
+
+Descend into the same key repeatedly by a given depth.
+
+```typescript
+obj.getChainValueByDepth({ parent: { parent: { name: "root" } } }, "parent", 2);
+// { name: "root" }
+```
+
+### `obj.setChainValue(obj, chain, value): void`
+
+Set a deeply nested value. Creates intermediate objects as needed.
+
+```typescript
+obj.setChainValue(data, "a.b[0].c", 42);
+```
+
+### `obj.deleteChainValue(obj, chain): void`
+
+Delete a deeply nested value.
+
+```typescript
+obj.deleteChainValue(data, "a.b[0].c");
+```
+
+### `obj.clearUndefined<T>(obj): T`
+
+Mutates: deletes keys with `undefined` values from an object.
+
+### `obj.clear<T>(obj): Record<string, never>`
+
+Mutates: deletes all keys from an object.
+
+### `obj.nullToUndefined<T>(obj): T | undefined`
+
+Mutates: recursively converts all `null` values to `undefined`.
+
+### `obj.unflatten(flatObj): Record<string, unknown>`
+
+Converts a flat dotted-key object to a nested object.
+
+```typescript
+obj.unflatten({ "a.b.c": 1 }); // { a: { b: { c: 1 } } }
+```
+
+### `obj.keys<T>(obj): (keyof T)[]`
+
+Type-safe `Object.keys`.
+
+### `obj.entries<T>(obj): [keyof T, T[keyof T]][]`
+
+Type-safe `Object.entries`.
+
+### `obj.fromEntries<T>(entries): object`
+
+Type-safe `Object.fromEntries`.
+
+### `obj.map<S, K, V>(obj, fn): Record<K, V>`
+
+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
+obj.map({ a: 1, b: 2 }, (k, v) => [null, v * 10]);
+// { a: 10, b: 20 }
+```
+
+### Type Utilities (from `obj`)
+
+#### `UndefToOptional<T>`
+
+Converts properties that include `undefined` in their type to optional properties.
+
+```typescript
+type UndefToOptional<T> = { [K in ...]?: T[K] } & { [K in ...]: T[K] };
+```
+
+#### `OptionalToUndef<T>`
+
+Converts optional properties to required properties with `| undefined`.
+
+```typescript
+type OptionalToUndef<T> = { [K in keyof T]-?: ... };
+```
+
+## `str` -- String Utilities
+
+### `str.getKoreanSuffix(text, type): string`
+
+Returns the appropriate Korean suffix based on whether the last character has a final consonant.
+
+```typescript
+function getKoreanSuffix(text: string, type: "을" | "은" | "이" | "와" | "랑" | "로" | "라"): string;
+```
+
+| Type | With final consonant | Without |
+|------|---------------------|---------|
+| `"을"` | 을 | 를 |
+| `"은"` | 은 | 는 |
+| `"이"` | 이 | 가 |
+| `"와"` | 과 | 와 |
+| `"랑"` | 이랑 | 랑 |
+| `"로"` | 으로 | 로 |
+| `"라"` | 이라 | 라 |
+
+### `str.replaceFullWidth(str): string`
+
+Converts full-width characters to half-width (A-Z, a-z, 0-9, space, parentheses).
+
+```typescript
+str.replaceFullWidth("Ａ１２３"); // "A123"
+```
+
+### `str.toPascalCase(str): string`
+
+Converts to PascalCase. Handles `-`, `_`, `.` separators.
+
+```typescript
+str.toPascalCase("hello-world"); // "HelloWorld"
+```
+
+### `str.toCamelCase(str): string`
+
+Converts to camelCase.
+
+```typescript
+str.toCamelCase("hello-world"); // "helloWorld"
+```
+
+### `str.toKebabCase(str): string`
+
+Converts to kebab-case from PascalCase/camelCase.
+
+```typescript
+str.toKebabCase("HelloWorld"); // "hello-world"
+```
+
+### `str.toSnakeCase(str): string`
+
+Converts to snake_case from PascalCase/camelCase.
+
+```typescript
+str.toSnakeCase("HelloWorld"); // "hello_world"
+```
+
+### `str.isNullOrEmpty(str): str is "" | undefined`
+
+Type guard that returns `true` if the string is `undefined`, `null`, or `""`.
+
+```typescript
+if (!str.isNullOrEmpty(name)) {
+  // name is guaranteed to be a non-empty string
+}
+```
+
+### `str.insert(str, index, insertString): string`
+
+Inserts a string at the given position.
+
+```typescript
+str.insert("Hello World", 5, ","); // "Hello, World"
+```
+
+## `num` -- Number Utilities
+
+### `num.parseInt(text): number | undefined`
+
+Parses a string to integer. Strips non-numeric characters first (keeps `0-9`, `-`, `.`). Returns `undefined` if unparseable.
+
+### `num.parseFloat(text): number | undefined`
+
+Parses a string to float. Strips non-numeric characters first.
+
+### `num.parseRoundedInt(text): number | undefined`
+
+Parses to float then rounds to nearest integer.
+
+### `num.isNullOrEmpty(val): val is 0 | undefined`
+
+Type guard that returns `true` if the value is `undefined`, `null`, or `0`.
+
+### `num.format(val, digit?): string | undefined`
+
+Formats a number with thousands separators and optional decimal control.
+
+```typescript
+function format(val: number, digit?: { max?: number; min?: number }): string;
+function format(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined;
+```
+
+```typescript
+num.format(1234.567, { max: 2 }); // "1,234.57"
+num.format(1234, { min: 2 });     // "1,234.00"
+```
+
+## `bytes` -- Uint8Array Utilities
+
+### `bytes.concat(arrays): Bytes`
+
+Concatenates multiple `Uint8Array` instances into one.
+
+### `bytes.toHex(bytes): string`
+
+Converts to lowercase hex string.
+
+### `bytes.fromHex(hex): Bytes`
+
+Converts hex string to `Uint8Array`. Throws `ArgumentError` on invalid input.
+
+### `bytes.toBase64(bytes): string`
+
+Converts to base64 string.
+
+### `bytes.fromBase64(base64): Bytes`
+
+Converts base64 string to `Uint8Array`. Throws `ArgumentError` on invalid input.
+
+```typescript
+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])
+```
+
+## `path` -- Path Utilities
+
+POSIX-style path utilities (forward slash only). Designed for browser and Capacitor environments. Does not support Windows backslash paths.
+
+### `path.join(...segments): string`
+
+Joins path segments with `/`.
+
+### `path.basename(filePath, ext?): string`
+
+Extracts the file name from a path. Optionally strips the extension.
+
+### `path.extname(filePath): string`
+
+Extracts the file extension (including the dot). Hidden files (e.g., `.gitignore`) return `""`.
+
+```typescript
+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"
+```
+
+## `json` -- JSON Utilities
+
+JSON stringify/parse with support for custom types: DateTime, DateOnly, Time, Uuid, Set, Map, Error, Uint8Array, Date.
+
+### `json.stringify(obj, options?): string`
+
+```typescript
+function stringify(obj: unknown, options?: {
+  space?: string | number;
+  replacer?: (key: string | undefined, value: unknown) => unknown;
+  redactBytes?: boolean;
+}): string;
+```
+
+| 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) |
+
+Custom types are serialized as `{ __type__: "TypeName", data: ... }`. Circular references throw `TypeError`.
+
+### `json.parse<T>(json): T`
+
+Restores custom types from `__type__` markers. All JSON `null` values are converted to `undefined` (simplysm null-free convention).
+
+```typescript
+const data = json.parse<MyType>(jsonString);
+```
+
+## `xml` -- XML Utilities
+
+Built on `fast-xml-parser`.
+
+### `xml.parse(str, options?): unknown`
+
+Parses XML string to an object. Attributes are grouped under `$`, text nodes under `_`, child elements as arrays.
+
+```typescript
+function parse(str: string, options?: { stripTagPrefix?: boolean }): unknown;
+```
+
+| Option | Description |
+|--------|-------------|
+| `stripTagPrefix` | Remove namespace prefixes from tag names |
+
+```typescript
+xml.parse('<root id="1"><item>hello</item></root>');
+// { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
+```
+
+### `xml.stringify(obj, options?): string`
+
+Converts an object to XML string.
+
+```typescript
+function stringify(obj: unknown, options?: XmlBuilderOptions): string;
+```
+
+## `wait` -- Wait Utilities
+
+### `wait.until(forwarder, milliseconds?, maxCount?): Promise<void>`
+
+Polls a condition function until it returns `true`.
+
+```typescript
+function until(
+  forwarder: () => boolean | Promise<boolean>,
+  milliseconds?: number,  // default: 100ms
+  maxCount?: number,      // default: unlimited
+): Promise<void>;
+```
+
+Throws `TimeoutError` if `maxCount` is reached.
+
+### `wait.time(millisecond): Promise<void>`
+
+Delays for the specified number of milliseconds.
+
+```typescript
+await wait.time(1000); // wait 1 second
+```
+
+## `transfer` -- Transferable Utilities
+
+Encode/decode objects for Worker `postMessage` with zero-copy `ArrayBuffer` transfer. Handles custom types that `structuredClone` does not support.
+
+### `transfer.encode(obj): { result, transferList }`
+
+Encodes an object for Worker transfer. Custom types become tagged objects. `Uint8Array` buffers are added to `transferList` for zero-copy transfer.
+
+```typescript
+function encode(obj: unknown): {
+  result: unknown;
+  transferList: ArrayBuffer[];
+};
+```
+
+Throws `TypeError` on circular references (with path info).
+
+Supported types: Date, DateTime, DateOnly, Time, Uuid, RegExp, Error, Uint8Array, Array, Map, Set, plain objects.
+
+### `transfer.decode(obj): unknown`
+
+Decodes a previously encoded object, restoring custom types.
+
+```typescript
+function decode(obj: unknown): unknown;
+```
+
+```typescript
+// Sending
+const { result, transferList } = transfer.encode(data);
+worker.postMessage(result, transferList);
+
+// Receiving
+const decoded = transfer.decode(event.data);
+```
+
+## `err` -- Error Utilities
+
+### `err.message(err): string`
+
+Extracts a message string from an `unknown` error value.
+
+```typescript
+function message(err: unknown): string;
+```
+
+Returns `err.message` if `err` is an `Error`, otherwise `String(err)`.
+
+## `dt` -- Date Format Utilities
+
+### `dt.format(formatString, args): string`
+
+Formats date/time components using C#-style format strings.
+
+```typescript
+function format(formatString: string, args: {
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+  timezoneOffsetMinutes?: number;
+}): string;
+```
+
+**Format patterns:**
+
+| Pattern | 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) | 일, 월, 화, 수, 목, 금, 토 |
+| `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 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
+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.
+
+## `primitive` -- Primitive Type Utilities
+
+### `primitive.typeStr(value): PrimitiveTypeStr`
+
+Returns the `PrimitiveTypeStr` for a given value at runtime.
+
+```typescript
+function typeStr(value: PrimitiveTypeMap[PrimitiveTypeStr]): PrimitiveTypeStr;
+```
+
+```typescript
+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.
+
+## Template String Tags
+
+Template tag functions for IDE syntax highlighting. All perform string interpolation + indent normalization (strips common leading whitespace).
+
+### `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`
+
+```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;
+```
+
+```typescript
+const code = ts`
+  interface User {
+    name: string;
+    age: number;
+  }
+`;
+// Result: "interface User {\n  name: string;\n  age: number;\n}"
+```
+
+## `ZipArchive`
+
+ZIP file read/write/compress/extract. Supports `await using` syntax (`Symbol.asyncDispose`).
+
+```typescript
+class ZipArchive {
+  constructor(data?: Blob | Bytes);
+
+  async get(fileName: string): Promise<Bytes | undefined>;
+  async exists(fileName: string): Promise<boolean>;
+  write(fileName: string, bytes: Bytes): void;
+  async extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
+  async compress(): Promise<Bytes>;
+  async close(): Promise<void>;
+  async [Symbol.asyncDispose](): Promise<void>;
+}
+```
+
+### `ZipArchiveProgress`
+
+```typescript
+interface ZipArchiveProgress {
+  fileName: string;
+  totalSize: number;
+  extractedSize: number;
+}
+```
+
+### 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
+// Reading a ZIP
+await using archive = new ZipArchive(zipBytes);
+const content = await archive.get("file.txt");
+
+// 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}`);
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - 코어 (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,7 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": [
     "./src/extensions/arr-ext.ts",
@@ -26,6 +27,9 @@
     "./dist/extensions/set-ext.js",
     "./dist/index.js"
   ],
+  "devDependencies": {
+    "@types/node": "^20.19.37"
+  },
   "dependencies": {
     "@zip.js/zip.js": "^2.8.23",
     "consola": "^3.4.2",

package/src/env.ts

@@ -1,8 +1,9 @@
 declare const process: { env: { DEV?: string; VER?: string; [key: string]: string | undefined } };
 
 declare global {
+  interface ImportMetaEnv extends Record<string, unknown> {}
   interface ImportMeta {
-    env?: Record<string, unknown>;
+    readonly env: ImportMetaEnv;
   }
 }
 
@@ -14,7 +15,7 @@ export function parseBoolEnv(value: unknown): boolean {
   return ["true", "1", "yes", "on"].includes(String(value ?? "").toLowerCase());
 }
 
-const _metaEnv: Record<string, unknown> = import.meta.env ?? {};
+const _metaEnv: Record<string, unknown> = { ...import.meta.env };
 const _processEnv: Record<string, unknown> = typeof process !== "undefined" ? process.env : {};
 const _raw: Record<string, unknown> = { ..._metaEnv, ..._processEnv };