@simplysm/core-common 13.0.29 → 13.0.30

package/README.md

@@ -52,8 +52,10 @@ To use extension methods (`getOrCreate()`, `toggle()`, etc.), you must import th
 - [`objMerge`](docs/utils.md#objmerge) - Deep merge (source + target)
 - [`objMerge3`](docs/utils.md#objmerge3) - 3-way merge with conflict detection
 - [`objOmit`](docs/utils.md#objomit) - Exclude specific keys
+- [`objOmitByFilter`](docs/utils.md#objomitbyfilter) - Exclude keys matching a predicate
 - [`objPick`](docs/utils.md#objpick) - Select specific keys
 - [`objGetChainValue`](docs/utils.md#objgetchainvalue) - Query value by chain path
+- [`objGetChainValueByDepth`](docs/utils.md#objgetchainvaluebydepth) - Query value by descending the same key repeatedly
 - [`objSetChainValue`](docs/utils.md#objsetchainvalue) - Set value by chain path
 - [`objDeleteChainValue`](docs/utils.md#objdeletechainvalue) - Delete value by chain path
 - [`objKeys`](docs/utils.md#objkeys) - Type-safe `Object.keys`
@@ -94,6 +96,7 @@ To use extension methods (`getOrCreate()`, `toggle()`, etc.), you must import th
 
 - [`formatDate`](docs/utils.md#formatdate) - Convert date/time to formatted string
 - [`normalizeMonth`](docs/utils.md#normalizemonth) - Normalize year/month/day when setting month
+- [`convert12To24`](docs/utils.md#convert12to24) - Convert 12-hour to 24-hour format
 
 ### Byte Utilities
 
@@ -208,9 +211,15 @@ To use extension methods (`getOrCreate()`, `toggle()`, etc.), you must import th
 - [`Type`](docs/types.md#type) - Constructor type
 - [`ObjUndefToOptional`](docs/types.md#objundeftooptional) - Convert `undefined` properties to optional
 - [`ObjOptionalToUndef`](docs/types.md#objoptionaltoundef) - Convert optional properties to `required + undefined`
+- [`EqualOptions`](docs/types.md#equaloptions) - Options for `objEqual`
+- [`ObjMergeOptions`](docs/types.md#objmergeoptions) - Options for `objMerge`
+- [`ObjMerge3KeyOptions`](docs/types.md#objmerge3keyoptions) - Per-key options for `objMerge3`
+- [`DtNormalizedMonth`](docs/types.md#dtnormalizedmonth) - Return type of `normalizeMonth`
+- [`ZipArchiveProgress`](docs/types.md#ziparchiveprogress) - Progress info for `ZipArchive.extractAll`
 - [`ArrayDiffsResult`](docs/types.md#arraydiffsresult) - Result type of `Array.diffs()`
 - [`ArrayDiffs2Result`](docs/types.md#arraydiffs2result) - Result type of `Array.oneWayDiffs()`
 - [`TreeArray`](docs/types.md#treearray) - Result type of `Array.toTree()`
+- [`ComparableType`](docs/types.md#comparabletype) - Union of types usable for sorting/comparison
 
 ## Caveats
 

package/docs/extensions.md

@@ -15,6 +15,7 @@ import "@simplysm/core-common";
 
 const users = [{ id: 1, name: "Alice" }];
 users.single((u) => u.id === 1); // { id: 1, name: "Alice" }
+users.single();                  // Returns the only element (throws if 2+)
 ```
 
 #### first
@@ -22,7 +23,8 @@ users.single((u) => u.id === 1); // { id: 1, name: "Alice" }
 Return first element.
 
 ```typescript
-users.first(); // { id: 1, name: "Alice" }
+users.first();              // First element (or undefined)
+users.first((u) => u.id > 0); // First matching element
 ```
 
 #### last
@@ -30,7 +32,8 @@ users.first(); // { id: 1, name: "Alice" }
 Return last element.
 
 ```typescript
-users.last(); // Last user
+users.last();              // Last element (or undefined)
+users.last((u) => u.id > 0); // Last matching element
 ```
 
 ---
@@ -51,14 +54,23 @@ Filter by type (`PrimitiveTypeStr` or constructor).
 
 ```typescript
 import "@simplysm/core-common";
+
+// Filter by PrimitiveTypeStr
+mixed.ofType("string");   // string[]
+mixed.ofType("DateTime"); // DateTime[]
+
+// Filter by constructor
+mixed.ofType(MyClass);    // MyClass[]
 ```
 
 #### filterAsync
 
-Async filter.
+Async filter (sequential execution).
 
 ```typescript
 import "@simplysm/core-common";
+
+const activeUsers = await users.filterAsync(async (u) => await isActive(u.id));
 ```
 
 ---
@@ -75,18 +87,26 @@ await ids.mapAsync(async (id) => await fetchUser(id));
 
 #### mapMany
 
-flat + filterExists.
+Flatten nested arrays and remove null/undefined.
 
 ```typescript
 import "@simplysm/core-common";
+
+// Flatten existing nested array
+[[1, 2], [3, 4]].mapMany(); // [1, 2, 3, 4]
+
+// Map then flatten
+users.mapMany((u) => u.tags); // all tags from all users
 ```
 
 #### mapManyAsync
 
-Async mapMany.
+Async mapMany (sequential execution).
 
 ```typescript
 import "@simplysm/core-common";
+
+await groups.mapManyAsync(async (g) => await fetchMembers(g.id));
 ```
 
 #### parallelAsync
@@ -103,7 +123,7 @@ await ids.parallelAsync(async (id) => await fetchUser(id));
 
 #### groupBy
 
-Group by key.
+Group by key. Supports primitive keys (O(n)) and object keys (O(n²)).
 
 ```typescript
 const users = [
@@ -114,22 +134,29 @@ const users = [
 
 users.groupBy((u) => u.dept);
 // [{ key: "dev", values: [...] }, { key: "hr", values: [...] }]
+
+// With value selector
+users.groupBy((u) => u.dept, (u) => u.name);
+// [{ key: "dev", values: ["Alice", "Bob"] }, { key: "hr", values: ["Charlie"] }]
 ```
 
 #### toMap
 
-Convert to Map (error on duplicate key).
+Convert to Map (throws on duplicate key).
 
 ```typescript
-users.toMap((u) => u.id); // Map<number, User>
+users.toMap((u) => u.id);          // Map<number, User>
+users.toMap((u) => u.id, (u) => u.name); // Map<number, string>
 ```
 
 #### toMapAsync
 
-Async Map conversion.
+Async Map conversion (sequential execution).
 
 ```typescript
 import "@simplysm/core-common";
+
+await items.toMapAsync(async (item) => await resolveKey(item));
 ```
 
 #### toArrayMap
@@ -146,30 +173,47 @@ Convert to `Map<K, Set<V>>`.
 
 ```typescript
 import "@simplysm/core-common";
+
+users.toSetMap((u) => u.dept);   // Map<string, Set<User>>
 ```
 
 #### toMapValues
 
-Aggregate Map by group.
+Group by key and aggregate each group with a value selector.
 
 ```typescript
 import "@simplysm/core-common";
+
+// Sum scores per department
+users.toMapValues(
+  (u) => u.dept,
+  (group) => group.sum((u) => u.score),
+); // Map<string, number>
 ```
 
 #### toObject
 
-Convert to `Record<string, V>`.
+Convert to `Record<string, V>` (throws on duplicate key).
 
 ```typescript
 import "@simplysm/core-common";
+
+users.toObject((u) => u.name);          // Record<string, User>
+users.toObject((u) => u.name, (u) => u.id); // Record<string, number>
 ```
 
 #### toTree
 
-Convert to tree structure.
+Convert flat array to tree structure.
 
 ```typescript
 import "@simplysm/core-common";
+
+interface Category { id: number; parentId?: number; name: string }
+
+const tree = categories.toTree("id", "parentId");
+// Nodes with null/undefined parentId become roots
+// Each node gains a `children: TreeArray<Category>[]` property
 ```
 
 ---
@@ -181,15 +225,32 @@ import "@simplysm/core-common";
 Remove duplicates (return new array).
 
 ```typescript
+// Primitive values
 [1, 2, 2, 3, 3].distinct(); // [1, 2, 3]
+
+// Object deep equality (O(n²))
+objects.distinct();
+
+// Reference equality (O(n)) — fastest
+objects.distinct(true);
+objects.distinct({ matchAddress: true });
+
+// Custom key function (O(n)) — recommended for large arrays of objects
+objects.distinct({ keyFn: (item) => item.id });
 ```
 
 #### distinctThis
 
-Remove duplicates (modify original).
+Remove duplicates (modify original array).
 
 ```typescript
 import "@simplysm/core-common";
+
+const arr = [1, 2, 2, 3];
+arr.distinctThis(); // arr is now [1, 2, 3]
+
+// Same options as distinct
+arr.distinctThis({ keyFn: (item) => item.id });
 ```
 
 ---
@@ -201,7 +262,8 @@ import "@simplysm/core-common";
 Ascending sort (return new array).
 
 ```typescript
-users.orderBy((u) => u.name);
+users.orderBy((u) => u.name);      // Sort by name ascending
+numbers.orderBy();                  // Sort numbers ascending
 ```
 
 #### orderByDesc
@@ -214,18 +276,22 @@ users.orderByDesc((u) => u.id);
 
 #### orderByThis
 
-Ascending sort (modify original).
+Ascending sort (modify original array).
 
 ```typescript
 import "@simplysm/core-common";
+
+arr.orderByThis((item) => item.name);
 ```
 
 #### orderByDescThis
 
-Descending sort (modify original).
+Descending sort (modify original array).
 
 ```typescript
 import "@simplysm/core-common";
+
+arr.orderByDescThis((item) => item.score);
 ```
 
 ---
@@ -234,26 +300,57 @@ import "@simplysm/core-common";
 
 #### diffs
 
-Compare differences between two arrays.
+Compare differences between two arrays. Returns INSERT/DELETE/UPDATE entries.
 
 ```typescript
 import "@simplysm/core-common";
+
+const result = oldList.diffs(newList, { keys: ["id"] });
+for (const diff of result) {
+  if (diff.source === undefined) { /* target-only: INSERT */ }
+  else if (diff.target === undefined) { /* source-only: DELETE */ }
+  else { /* both exist: UPDATE */ }
+}
+
+// Exclude certain fields from equality check
+oldList.diffs(newList, { keys: ["id"], excludes: ["updatedAt"] });
 ```
 
 #### oneWayDiffs
 
-One-way diff comparison (create/update/same).
+One-way diff comparison (create/update/same). Compares current items against original items.
 
 ```typescript
 import "@simplysm/core-common";
+
+const diffs = currentItems.oneWayDiffs(originalItems, "id");
+// { type: "create", item, orgItem: undefined }
+// { type: "update", item, orgItem }
+// { type: "same",   item, orgItem } (only when includeSame: true)
+
+// With options
+currentItems.oneWayDiffs(originalItems, "id", {
+  includeSame: true,       // Include unchanged items in result
+  excludes: ["updatedAt"], // Ignore these fields when checking for changes
+  includes: ["name"],      // Only compare these fields
+});
+
+// Pass a pre-built Map for O(1) lookup
+const orgMap = originalItems.toMap((item) => item.id);
+currentItems.oneWayDiffs(orgMap, "id");
 ```
 
 #### merge
 
-Merge arrays.
+Merge arrays: apply target changes onto source.
 
 ```typescript
 import "@simplysm/core-common";
+
+const merged = source.merge(target, { keys: ["id"] });
+// Items present in both: merged with objMerge
+// Items only in target: appended
+// Items only in source: kept as-is
 ```
 
 ---
@@ -262,26 +359,35 @@ import "@simplysm/core-common";
 
 #### sum
 
-Sum.
+Sum values.
 
 ```typescript
 import "@simplysm/core-common";
+
+[1, 2, 3].sum(); // 6
+users.sum((u) => u.score); // total score
 ```
 
 #### min
 
-Minimum.
+Minimum value.
 
 ```typescript
 import "@simplysm/core-common";
+
+[3, 1, 2].min(); // 1
+users.min((u) => u.age); // youngest age
 ```
 
 #### max
 
-Maximum.
+Maximum value.
 
 ```typescript
 import "@simplysm/core-common";
+
+[3, 1, 2].max(); // 3
+users.max((u) => u.score); // highest score
 ```
 
 ---
@@ -290,34 +396,44 @@ import "@simplysm/core-common";
 
 #### insert
 
-Insert at specific position.
+Insert at specific position (modify original).
 
 ```typescript
 import "@simplysm/core-common";
+
+const arr = [1, 2, 3];
+arr.insert(1, 10, 11); // [1, 10, 11, 2, 3]
 ```
 
 #### remove
 
-Remove item.
+Remove item or items matching predicate (modify original).
 
 ```typescript
 import "@simplysm/core-common";
+
+arr.remove(2);                           // Remove by value
+arr.remove((item) => item > 2);          // Remove by predicate
 ```
 
 #### toggle
 
-Remove if exists, add if not.
+Toggle item — remove if exists, add if not (modify original).
 
 ```typescript
 import "@simplysm/core-common";
+
+arr.toggle(3); // removes 3 if present, adds if not
 ```
 
 #### clear
 
-Remove all items.
+Remove all items (modify original).
 
 ```typescript
 import "@simplysm/core-common";
+
+arr.clear(); // arr is now []
 ```
 
 #### shuffle
@@ -326,6 +442,8 @@ Shuffle (return new array).
 
 ```typescript
 import "@simplysm/core-common";
+
+[1, 2, 3, 4, 5].shuffle(); // random order
 ```
 
 ---
@@ -339,21 +457,25 @@ If key doesn't exist, set new value and return.
 ```typescript
 const map = new Map<string, number[]>();
 
-// Create and return if value doesn't exist
-const arr = map.getOrCreate("key", []);
-arr.push(1);
+// Direct value
+map.getOrCreate("key", []);
 
-// Create with factory function (when computation is expensive)
-map.getOrCreate("key2", () => expensiveComputation());
+// Factory function (called only when key is missing)
+map.getOrCreate("key", () => expensiveComputation());
 ```
 
+> **Note:** If the Map value type is a function (e.g., `Map<string, () => void>`), wrap the function in a factory to store it as a value: `map.getOrCreate("key", () => myFn)`.
+
 ### update
 
-Update value for key using function.
+Update value for key using function. The update function receives `undefined` if the key doesn't exist.
 
 ```typescript
 const countMap = new Map<string, number>();
 countMap.update("key", (v) => (v ?? 0) + 1); // Increment counter
+
+const arrayMap = new Map<string, string[]>();
+arrayMap.update("key", (v) => [...(v ?? []), "item"]); // Append to array
 ```
 
 ---
@@ -371,11 +493,11 @@ set.adds(4, 5, 6); // {1, 2, 3, 4, 5, 6}
 
 ### toggle
 
-Toggle value (remove if exists, add if not).
+Toggle value (remove if exists, add if not). Optionally force add or delete.
 
 ```typescript
-set.toggle(2);         // 2 exists so remove -> {1, 3, 4, 5, 6}
-set.toggle(7);         // 7 doesn't exist so add -> {1, 3, 4, 5, 6, 7}
-set.toggle(8, "add");  // Force add
-set.toggle(1, "del");  // Force delete
+set.toggle(2);          // 2 exists → remove
+set.toggle(7);          // 7 not exists → add
+set.toggle(8, "add");   // Force add regardless of current state
+set.toggle(1, "del");   // Force delete regardless of current state
 ```

package/docs/features.md

@@ -9,27 +9,32 @@ Async debounce queue (executes only last request).
 ```typescript
 import { DebounceQueue } from "@simplysm/core-common";
 
-using queue = new DebounceQueue(300); // 300ms debounce
+using queue = new DebounceQueue(300); // 300ms debounce delay
 
 // Error handling
 queue.on("error", (err) => console.error(err));
 
-// Only last call is executed
+// Only last call is executed after the delay
 queue.run(() => console.log("1")); // Ignored
 queue.run(() => console.log("2")); // Ignored
 queue.run(() => console.log("3")); // Executed after 300ms
+
+// Omit delay for immediate execution (next event loop tick)
+const immediate = new DebounceQueue();
 ```
 
+> **Note:** A request added while the queue is running is executed immediately after the current run completes (no additional delay). This prevents requests from being lost.
+
 ---
 
 ## SerialQueue
 
-Async serial queue (sequential execution).
+Async serial queue (sequential execution). Each task starts only after the previous one completes.
 
 ```typescript
 import { SerialQueue } from "@simplysm/core-common";
 
-using queue = new SerialQueue(100); // 100ms interval between tasks
+using queue = new SerialQueue(100); // 100ms gap between tasks (optional, default 0)
 
 queue.on("error", (err) => console.error(err));
 
@@ -38,6 +43,8 @@ queue.run(async () => { await fetch("/api/2"); }); // Runs after #1 completes
 queue.run(async () => { await fetch("/api/3"); }); // Runs after #2 completes
 ```
 
+> **Note:** Errors in a task are caught and emitted (or logged). Subsequent tasks continue regardless.
+
 ---
 
 ## EventEmitter
@@ -61,10 +68,11 @@ class MyService extends EventEmitter<MyEvents> {
 }
 
 const service = new MyService();
-service.on("data", (data) => console.log(data)); // data: string (type inferred)
-service.off("data", listener);                   // Remove listener
-service.listenerCount("data");                   // Number of registered listeners
-service.dispose();                                // Remove all listeners
+const listener = (data: string) => console.log(data);
+service.on("data", listener);              // Register listener (type: string inferred)
+service.off("data", listener);             // Remove specific listener
+service.listenerCount("data");             // Number of registered listeners
+service.dispose();                          // Remove all listeners
 ```
 
 ---
@@ -78,13 +86,18 @@ import { ZipArchive } from "@simplysm/core-common";
 
 // Read ZIP file
 await using archive = new ZipArchive(zipBytes);
-const content = await archive.get("file.txt");
-const exists = await archive.exists("data.json");
 
-// Extract all (with progress)
+// Get single file
+const content = await archive.get("file.txt");          // Uint8Array | undefined
+const exists = await archive.exists("data.json");       // boolean
+
+// Extract all files (with optional progress callback)
 const files = await archive.extractAll((progress) => {
-  console.log(`${progress.fileName}: ${progress.extractedSize}/${progress.totalSize}`);
+  // progress: { fileName: string; totalSize: number; extractedSize: number }
+  const pct = Math.round((progress.extractedSize / progress.totalSize) * 100);
+  console.log(`${progress.fileName}: ${pct}%`);
 });
+// files: Map<string, Uint8Array | undefined>
 
 // Create ZIP file
 await using newArchive = new ZipArchive();
@@ -92,3 +105,5 @@ newArchive.write("file.txt", textBytes);
 newArchive.write("data.json", jsonBytes);
 const zipBytes = await newArchive.compress();
 ```
+
+> **Note:** `compress()` loads all files into memory first. Be mindful of memory usage for large archives.

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.29",
+  "version": "13.0.30",
   "description": "심플리즘 패키지 - 코어 모듈 (common)",
   "author": "김석래",
   "license": "Apache-2.0",