@simplysm/core-common 13.0.28 → 13.0.30

package/docs/types.md

@@ -46,7 +46,7 @@ switch (type) {
 
 ### TimeoutError
 
-Timeout error.
+Timeout error. Thrown automatically by `waitUntil` when max attempts are exceeded.
 
 ```typescript
 import { TimeoutError } from "@simplysm/core-common";
@@ -82,23 +82,33 @@ DateTime.parse("2025-01-15 오전 10:30:00");           // Korean AM/PM
 DateTime.parse("2025-01-15T10:30:00Z");              // ISO 8601
 
 // Properties (read-only)
-dt.year;       // 2025
-dt.month;      // 1 (1-12)
-dt.day;        // 15
-dt.hour;       // 10
-dt.minute;     // 30
-dt.second;     // 0
-dt.millisecond; // 0
-dt.tick;       // Millisecond timestamp
-dt.dayOfWeek;  // Day of week (Sun~Sat: 0~6)
-dt.isValid;    // Validity check
+dt.year;                   // 2025
+dt.month;                  // 1 (1-12)
+dt.day;                    // 15
+dt.hour;                   // 10
+dt.minute;                 // 30
+dt.second;                 // 0
+dt.millisecond;            // 0
+dt.tick;                   // Millisecond timestamp
+dt.dayOfWeek;              // Day of week (Sun~Sat: 0~6)
+dt.timezoneOffsetMinutes;  // Timezone offset in minutes (e.g. 540 for UTC+9)
+dt.isValid;                // Validity check
 
 // Immutable transformations (return new instances)
 dt.setYear(2026);         // Change year
 dt.setMonth(3);           // Change month (day auto-adjusted)
+dt.setDay(1);             // Change day
+dt.setHour(9);            // Change hour
+dt.setMinute(0);          // Change minute
+dt.setSecond(0);          // Change second
+dt.setMillisecond(0);     // Change millisecond
+dt.addYears(1);           // 1 year later
+dt.addMonths(1);          // 1 month later
 dt.addDays(7);            // 7 days later
 dt.addHours(-2);          // 2 hours ago
-dt.addMonths(1);          // 1 month later
+dt.addMinutes(30);        // 30 minutes later
+dt.addSeconds(10);        // 10 seconds later
+dt.addMilliseconds(500);  // 500ms later
 
 // Formatting
 dt.toFormatString("yyyy-MM-dd");               // "2025-01-15"
@@ -120,20 +130,40 @@ const d = new DateOnly(2025, 1, 15);
 DateOnly.parse("2025-01-15");     // No timezone influence
 DateOnly.parse("20250115");       // No timezone influence
 
-// Immutable transformations
-d.addDays(30);
-d.addMonths(-1);
+// Properties (read-only)
+d.year;       // 2025
+d.month;      // 1
+d.day;        // 15
+d.tick;       // Millisecond timestamp
+d.dayOfWeek;  // Day of week (Sun~Sat: 0~6)
+d.isValid;    // Validity check
+
+// Immutable transformations (return new instances)
+d.setYear(2026);
 d.setMonth(2);  // Jan 31 -> Feb 28 (auto-adjusted)
+d.setDay(1);
+d.addYears(1);
+d.addMonths(-1);
+d.addDays(30);
 
-// Week calculation (ISO 8601 standard)
+// Week calculation (ISO 8601 standard: Monday start, min 4 days in first week)
 d.getWeekSeqOfYear();    // { year: 2025, weekSeq: 3 }
 d.getWeekSeqOfMonth();   // { year: 2025, monthSeq: 1, weekSeq: 3 }
 
 // US-style week (Sunday start, first week with 1+ days)
 d.getWeekSeqOfYear(0, 1);
+d.getWeekSeqOfMonth(0, 1);
+
+// Start date of the week containing this date
+d.getWeekSeqStartDate();          // ISO 8601 (Monday start)
+d.getWeekSeqStartDate(0, 1);      // US-style (Sunday start)
 
-// Reverse calculate date from week
-DateOnly.getDateByYearWeekSeq({ year: 2025, weekSeq: 2 }); // 2025-01-06 (Monday)
+// Base year/month for week sequence calculations
+d.getBaseYearMonthSeqForWeekSeq(); // { year: 2025, monthSeq: 1 }
+
+// Reverse calculate date from week number
+DateOnly.getDateByYearWeekSeq({ year: 2025, weekSeq: 2 });            // 2025-01-06 (Monday)
+DateOnly.getDateByYearWeekSeq({ year: 2025, month: 1, weekSeq: 3 });  // 2025-01-13 (Monday)
 
 // Formatting
 d.toFormatString("yyyy년 MM월 dd일"); // "2025년 01월 15일"
@@ -153,10 +183,25 @@ const t = new Time(14, 30, 0);
 Time.parse("14:30:00");           // HH:mm:ss
 Time.parse("14:30:00.123");       // HH:mm:ss.fff
 Time.parse("오후 2:30:00");       // Korean AM/PM
+Time.parse("2025-01-15T14:30:00"); // ISO 8601 (time part only)
 
-// 24-hour cycle
-t.addHours(12);    // 14:30 + 12 hours = 02:30 (cycles, not next day)
+// Properties (read-only)
+t.hour;        // 14
+t.minute;      // 30
+t.second;      // 0
+t.millisecond; // 0
+t.tick;        // Milliseconds since midnight
+t.isValid;     // Validity check
+
+// Immutable transformations (return new instances, 24-hour cycle)
+t.setHour(9);
+t.setMinute(0);
+t.setSecond(0);
+t.setMillisecond(0);
+t.addHours(12);    // 14:30 + 12 hours = 02:30 (wraps around midnight)
 t.addMinutes(-60); // 14:30 - 60 minutes = 13:30
+t.addSeconds(30);
+t.addMilliseconds(500);
 
 // Formatting
 t.toFormatString("tt h:mm"); // "오후 2:30"
@@ -192,7 +237,7 @@ import { LazyGcMap } from "@simplysm/core-common";
 
 // using statement (recommended)
 using map = new LazyGcMap<string, object>({
-  gcInterval: 10000,  // GC execution interval: 10 seconds
+  gcInterval: 10000,  // GC execution interval: 10 seconds (optional, defaults to expireTime/10)
   expireTime: 60000,  // Item expiration time: 60 seconds
   onExpire: (key, value) => {
     console.log(`Expired: ${key}`);
@@ -203,7 +248,14 @@ map.set("key1", { data: "hello" });
 map.get("key1");                       // Refreshes access time (LRU)
 map.getOrCreate("key2", () => ({}));   // Create and return if not exists
 map.has("key1");                       // Does not refresh access time
+map.size;                              // Number of stored entries
 map.delete("key1");
+map.clear();                           // Remove all items (instance remains usable)
+
+// Iteration
+for (const [key, value] of map.entries()) { /* ... */ }
+for (const key of map.keys()) { /* ... */ }
+for (const value of map.values()) { /* ... */ }
 ```
 
 ---
@@ -302,6 +354,78 @@ type Input = { a: string; b?: number };
 type Output = ObjOptionalToUndef<Input>; // { a: string; b: number | undefined }
 ```
 
+### EqualOptions
+
+Options for `objEqual`.
+
+```typescript
+import type { EqualOptions } from "@simplysm/core-common";
+
+// topLevelIncludes: only compare these keys (top level only)
+// topLevelExcludes: skip these keys (top level only)
+// ignoreArrayIndex: treat arrays as sets (O(n²))
+// onlyOneDepth: shallow comparison (reference equality for nested values)
+const options: EqualOptions = {
+  topLevelExcludes: ["updatedAt"],
+  ignoreArrayIndex: true,
+};
+```
+
+### ObjMergeOptions
+
+Options for `objMerge`.
+
+```typescript
+import type { ObjMergeOptions } from "@simplysm/core-common";
+
+// arrayProcess: "replace" (default) replaces arrays, "concat" merges and deduplicates
+// useDelTargetNull: when true, a null target value deletes the key from the result
+const options: ObjMergeOptions = {
+  arrayProcess: "concat",
+  useDelTargetNull: true,
+};
+```
+
+### ObjMerge3KeyOptions
+
+Per-key comparison options for `objMerge3`.
+
+```typescript
+import type { ObjMerge3KeyOptions } from "@simplysm/core-common";
+
+// keys: sub-keys to compare (equivalent to topLevelIncludes in objEqual)
+// excludes: sub-keys to exclude from comparison
+// ignoreArrayIndex: ignore array order when comparing
+const options: ObjMerge3KeyOptions = {
+  keys: ["id", "name"],
+  ignoreArrayIndex: false,
+};
+```
+
+### DtNormalizedMonth
+
+Return type of `normalizeMonth`. Contains year/month/day after overflow normalization.
+
+```typescript
+import type { DtNormalizedMonth } from "@simplysm/core-common";
+
+// { year: number; month: number; day: number }
+```
+
+### ZipArchiveProgress
+
+Progress information passed to the callback of `ZipArchive.extractAll`.
+
+```typescript
+import type { ZipArchiveProgress } from "@simplysm/core-common";
+
+// { fileName: string; totalSize: number; extractedSize: number }
+await archive.extractAll((progress: ZipArchiveProgress) => {
+  const pct = Math.round((progress.extractedSize / progress.totalSize) * 100);
+  console.log(`${progress.fileName}: ${pct}%`);
+});
+```
+
 ### ArrayDiffsResult
 
 Result of `Array.diffs()` — insert / delete / update entries.
@@ -323,6 +447,10 @@ Result of `Array.oneWayDiffs()` — create / update / same entries.
 
 ```typescript
 import type { ArrayDiffs2Result } from "@simplysm/core-common";
+
+// { type: "create"; item: T; orgItem: undefined }
+// { type: "update"; item: T; orgItem: T }
+// { type: "same";   item: T; orgItem: T }
 ```
 
 ### TreeArray
@@ -336,3 +464,13 @@ interface Category { id: number; parentId: number | undefined; name: string }
 const tree: TreeArray<Category>[] = categories.toTree("id", "parentId");
 // Each node has a `children` array of the same type
 ```
+
+### ComparableType
+
+Union of types that can be used as sort keys in `orderBy`, `orderByDesc`, etc.
+
+```typescript
+import type { ComparableType } from "@simplysm/core-common";
+
+// string | number | boolean | DateTime | DateOnly | Time | undefined
+```

package/docs/utils.md

@@ -22,6 +22,8 @@ import { objEqual } from "@simplysm/core-common";
 objEqual({ a: 1, b: [2] }, { a: 1, b: [2] });                       // true
 objEqual(arr1, arr2, { ignoreArrayIndex: true });                     // Ignore array order
 objEqual(obj1, obj2, { topLevelExcludes: ["updatedAt"] });            // Exclude specific keys
+objEqual(obj1, obj2, { topLevelIncludes: ["id", "name"] });           // Only compare these keys
+objEqual(obj1, obj2, { onlyOneDepth: true });                         // Shallow (reference) comparison
 ```
 
 ### objMerge
@@ -33,6 +35,14 @@ import { objMerge } from "@simplysm/core-common";
 
 objMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
 // { a: 1, b: { c: 2, d: 3 } }
+
+// Concat arrays instead of replacing
+objMerge({ tags: ["a"] }, { tags: ["b"] }, { arrayProcess: "concat" });
+// { tags: ["a", "b"] }
+
+// Delete key when target value is null
+objMerge({ a: 1, b: 2 }, { b: null }, { useDelTargetNull: true });
+// { a: 1 }
 ```
 
 ### objMerge3
@@ -60,6 +70,18 @@ import { objOmit } from "@simplysm/core-common";
 objOmit(user, ["password", "email"]);
 ```
 
+### objOmitByFilter
+
+Exclude keys matching a predicate function.
+
+```typescript
+import { objOmitByFilter } from "@simplysm/core-common";
+
+// Remove all keys starting with "_"
+objOmitByFilter(data, (key) => String(key).startsWith("_"));
+// { name: "Alice", age: 30 }  (private _internal key removed)
+```
+
 ### objPick
 
 Select specific keys.
@@ -78,6 +100,23 @@ Query value by chain path (`"a.b[0].c"`).
 import { objGetChainValue } from "@simplysm/core-common";
 
 objGetChainValue(obj, "a.b[0].c");
+
+// Optional: returns undefined instead of throwing when intermediate path is missing
+objGetChainValue(obj, "a.b[0].c", true);
+```
+
+### objGetChainValueByDepth
+
+Descend the same key repeatedly to a given depth and return the value.
+
+```typescript
+import { objGetChainValueByDepth } from "@simplysm/core-common";
+
+const nested = { parent: { parent: { name: "root" } } };
+objGetChainValueByDepth(nested, "parent", 2); // { name: "root" }
+
+// Optional: returns undefined instead of throwing when path is missing
+objGetChainValueByDepth(nested, "parent", 5, true); // undefined
 ```
 
 ### objSetChainValue
@@ -126,6 +165,9 @@ Type-safe `Object.fromEntries`.
 
 ```typescript
 import { objFromEntries } from "@simplysm/core-common";
+
+const entries: ["a" | "b", number][] = [["a", 1], ["b", 2]];
+objFromEntries(entries); // { a: number; b: number }
 ```
 
 ### objMap
@@ -135,7 +177,11 @@ Transform each entry of object and return new object.
 ```typescript
 import { objMap } from "@simplysm/core-common";
 
-objMap(colors, (key, rgb) => [null, `rgb(${rgb})`]); // Transform values only (keep keys)
+// Transform values only (pass null as new key to keep original key)
+objMap(colors, (key, rgb) => [null, `rgb(${rgb})`]);
+
+// Transform both keys and values
+objMap(colors, (key, rgb) => [`${key}Light`, `rgb(${rgb})`]);
 ```
 
 ---
@@ -165,6 +211,11 @@ const json = jsonStringify(data, { space: 2 });
 // For logging: hide binary data
 jsonStringify(data, { redactBytes: true });
 // Uint8Array content replaced with "__hidden__"
+
+// Custom replacer (called before built-in type conversion)
+jsonStringify(data, {
+  replacer: (key, value) => (key === "secret" ? undefined : value),
+});
 ```
 
 ### jsonParse
@@ -243,6 +294,9 @@ PascalCase conversion.
 
 ```typescript
 import { strToPascalCase } from "@simplysm/core-common";
+
+strToPascalCase("hello-world"); // "HelloWorld"
+strToPascalCase("hello_world"); // "HelloWorld"
 ```
 
 ### strToCamelCase
@@ -253,6 +307,7 @@ camelCase conversion.
 import { strToCamelCase } from "@simplysm/core-common";
 
 strToCamelCase("hello-world"); // "helloWorld"
+strToCamelCase("HelloWorld");  // "helloWorld"
 ```
 
 ### strToKebabCase
@@ -271,6 +326,8 @@ snake_case conversion.
 
 ```typescript
 import { strToSnakeCase } from "@simplysm/core-common";
+
+strToSnakeCase("HelloWorld"); // "hello_world"
 ```
 
 ### strIsNullOrEmpty
@@ -293,6 +350,10 @@ Insert at specific position in string.
 
 ```typescript
 import { strInsert } from "@simplysm/core-common";
+
+strInsert("Hello World", 5, ","); // "Hello, World"
+strInsert("abc", 0, "X");         // "Xabc"
+strInsert("abc", 3, "X");         // "abcX"
 ```
 
 ---
@@ -307,6 +368,7 @@ Parse string to integer (remove non-digit characters).
 import { numParseInt } from "@simplysm/core-common";
 
 numParseInt("12,345원"); // 12345
+numParseInt(3.7);        // 3 (truncated, not rounded)
 ```
 
 ### numParseFloat
@@ -325,6 +387,9 @@ Round float and return integer.
 
 ```typescript
 import { numParseRoundedInt } from "@simplysm/core-common";
+
+numParseRoundedInt("3.7"); // 4
+numParseRoundedInt("3.2"); // 3
 ```
 
 ### numFormat
@@ -336,6 +401,7 @@ import { numFormat } from "@simplysm/core-common";
 
 numFormat(1234567, { max: 2 });             // "1,234,567"
 numFormat(1234, { min: 2, max: 2 });        // "1,234.00"
+numFormat(undefined);                        // undefined
 ```
 
 ### numIsNullOrEmpty
@@ -368,12 +434,20 @@ Convert date/time to string according to format string. Supports the same format
 | `dd` | 0-padded day | 01~31 |
 | `d` | Day | 1~31 |
 | `tt` | AM/PM | 오전, 오후 |
-| `HH` | 0-padded 24-hour | 00~23 |
 | `hh` | 0-padded 12-hour | 01~12 |
+| `h` | 12-hour | 1~12 |
+| `HH` | 0-padded 24-hour | 00~23 |
+| `H` | 24-hour | 0~23 |
 | `mm` | 0-padded minute | 00~59 |
+| `m` | Minute | 0~59 |
 | `ss` | 0-padded second | 00~59 |
+| `s` | Second | 0~59 |
 | `fff` | Millisecond (3 digits) | 000~999 |
-| `zzz` | Timezone offset | +09:00 |
+| `ff` | Millisecond (2 digits) | 00~99 |
+| `f` | Millisecond (1 digit) | 0~9 |
+| `zzz` | Timezone offset (±HH:mm) | +09:00 |
+| `zz` | Timezone offset (±HH) | +09 |
+| `z` | Timezone offset (±H) | +9 |
 
 ```typescript
 import { formatDate } from "@simplysm/core-common";
@@ -383,17 +457,34 @@ formatDate("yyyy-MM-dd", { year: 2024, month: 3, day: 15 });
 
 formatDate("yyyy년 M월 d일 (ddd)", { year: 2024, month: 3, day: 15 });
 // "2024년 3월 15일 (금)"
+
+formatDate("tt h:mm:ss", { hour: 14, minute: 30, second: 45 });
+// "오후 2:30:45"
 ```
 
 ### normalizeMonth
 
-Normalize year/month/day when setting month.
+Normalize year/month/day when setting month. Handles month overflow and day clamping.
 
 ```typescript
 import { normalizeMonth } from "@simplysm/core-common";
 
 normalizeMonth(2025, 13, 15); // { year: 2026, month: 1, day: 15 }
 normalizeMonth(2025, 2, 31);  // { year: 2025, month: 2, day: 28 }
+normalizeMonth(2025, 0, 1);   // { year: 2024, month: 12, day: 1 }
+```
+
+### convert12To24
+
+Convert 12-hour (AM/PM) to 24-hour format.
+
+```typescript
+import { convert12To24 } from "@simplysm/core-common";
+
+convert12To24(12, false); // 0  (12 AM = midnight)
+convert12To24(12, true);  // 12 (12 PM = noon)
+convert12To24(1, false);  // 1  (1 AM)
+convert12To24(1, true);   // 13 (1 PM)
 ```
 
 ---
@@ -475,6 +566,9 @@ import { waitUntil } from "@simplysm/core-common";
 // Wait for condition (100ms interval, max 50 attempts = 5 seconds)
 await waitUntil(() => isReady, 100, 50);
 // Throws TimeoutError after 50 attempts
+
+// Unlimited wait (omit maxCount)
+await waitUntil(() => isReady, 200);
 ```
 
 ---
@@ -483,7 +577,7 @@ await waitUntil(() => isReady, 100, 50);
 
 ### transferableEncode
 
-Serialize custom types into Worker-transferable form.
+Serialize custom types into Worker-transferable form. Returns `{ result, transferList }` where `transferList` contains `ArrayBuffer` instances for zero-copy transfer.
 
 ```typescript
 import { transferableEncode } from "@simplysm/core-common";
@@ -518,6 +612,7 @@ Combine paths (`path.join` replacement).
 import { pathJoin } from "@simplysm/core-common";
 
 pathJoin("/home", "user", "file.txt"); // "/home/user/file.txt"
+pathJoin("a/", "/b/", "/c");           // "a/b/c"
 ```
 
 ### pathBasename
@@ -533,19 +628,21 @@ pathBasename("file.txt", ".txt");      // "file"
 
 ### pathExtname
 
-Extract extension (`path.extname` replacement).
+Extract extension (`path.extname` replacement). Returns empty string for hidden files (e.g., `.gitignore`).
 
 ```typescript
 import { pathExtname } from "@simplysm/core-common";
 
-pathExtname("file.txt"); // ".txt"
+pathExtname("file.txt");     // ".txt"
+pathExtname(".gitignore");   // ""
+pathExtname("archive.tar.gz"); // ".gz"
 ```
 
 ---
 
 ## Template literal tags (template-strings)
 
-Tag functions for IDE code highlighting. Actual behavior is string combination + indentation cleanup.
+Tag functions for IDE code highlighting. Actual behavior is string combination + leading/trailing blank line removal + common indentation removal.
 
 ### js
 
@@ -553,6 +650,12 @@ JavaScript code highlighting.
 
 ```typescript
 import { js } from "@simplysm/core-common";
+
+const code = js`
+  function hello() {
+    return "world";
+  }
+`;
 ```
 
 ### ts
@@ -615,6 +718,7 @@ import { getPrimitiveTypeStr } from "@simplysm/core-common";
 getPrimitiveTypeStr("hello");        // "string"
 getPrimitiveTypeStr(123);            // "number"
 getPrimitiveTypeStr(new DateTime()); // "DateTime"
+getPrimitiveTypeStr(new Uint8Array()); // "Bytes"
 ```
 
 ### env

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "13.0.28",
+  "version": "13.0.30",
   "description": "심플리즘 패키지 - 코어 모듈 (common)",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "./dist/index.js"
   ],
   "dependencies": {
-    "@zip.js/zip.js": "^2.8.20",
+    "@zip.js/zip.js": "^2.8.21",
     "consola": "^3.4.2",
     "fast-xml-parser": "^5.3.6",
     "yaml": "^2.8.2"

package/src/errors/sd-error.ts

@@ -26,7 +26,13 @@ export class SdError extends Error {
   constructor(arg1?: unknown, ...messages: string[]);
   constructor(arg1?: unknown, ...messages: string[]) {
     const arg1Message =
-      arg1 instanceof Error ? arg1.message : typeof arg1 === "string" ? arg1 : arg1 != null ? String(arg1) : undefined;
+      arg1 instanceof Error
+        ? arg1.message
+        : typeof arg1 === "string"
+          ? arg1
+          : arg1 != null
+            ? String(arg1)
+            : undefined;
 
     const fullMessage = [arg1Message, ...messages]
       .filter((m) => m != null)
@@ -42,7 +48,10 @@ export class SdError extends Error {
 
     // V8 엔진(Node.js, Chrome)에서만 사용 가능한 captureStackTrace
     if ("captureStackTrace" in Error) {
-      (Error.captureStackTrace as (targetObject: object, constructorOpt?: Function) => void)(this, new.target);
+      (Error.captureStackTrace as (targetObject: object, constructorOpt?: Function) => void)(
+        this,
+        new.target,
+      );
     }
 
     // cause 체인의 stack을 현재 stack에 추가

package/src/errors/timeout-error.ts

@@ -29,7 +29,9 @@ export class TimeoutError extends SdError {
    */
   constructor(count?: number, message?: string) {
     super(
-      "대기 시간이 초과되었습니다" + (count != null ? `(${count}회)` : "") + (message != null ? `: ${message}` : ""),
+      "대기 시간이 초과되었습니다" +
+        (count != null ? `(${count}회)` : "") +
+        (message != null ? `: ${message}` : ""),
     );
     this.name = "TimeoutError";
   }

package/src/extensions/arr-ext.helpers.ts

@@ -49,5 +49,8 @@ export function compareForOrder(pp: ComparableType, pn: ComparableType, desc: bo
     return cpn ? (desc ? 1 : -1) : desc ? -1 : 1;
   }
 
-  throw new ArgumentError("orderBy를 사용할 수 없는 타입입니다.", { type1: typeof cpp, type2: typeof cpn });
+  throw new ArgumentError("orderBy를 사용할 수 없는 타입입니다.", {
+    type1: typeof cpp,
+    type2: typeof cpn,
+  });
 }