# 整體 Tables 總覽 — Object / Data Utilities 本文件定義一組「**契約層（contract-level）**」的工具 tables。 Tables 依「**責任與語義**」分組，而非依實作細節分類。 目標是在 **跨模組、跨環境** 的情境下，提供 **穩定、可預期** 的物件操作與資料處理語義。 --- **Dependencies** ```mermaid graph TD Path --> Guard Path --> Read Guard --> Read Guard --> Normalize Path --> Write Guard --> Write Read --> Write Path --> Flat Guard --> Flat Write --> Flat Guard --> CloneMerge Write --> CloneMerge Flat --> Diff Write --> Diff Guard --> Query Path --> Query Read --> Convenience Write --> Convenience Flat --> Convenience Diff --> Convenience ``` **Structure** | Category | 語義定位 | 核心責任 | 典型方法 | | ----------- | ------ | ---------------------------------------------------- | -------------------------------------------------------- | | Guard | 判斷 | 檢查型別與結構前置條件，不改變資料 | `isObjectLikeOrArray`, `isObjectLikeNoArray`, `isPlainObject`, `isContainer`, `isStructuredClonable` | | Normalize | 治理 | 將資料轉為 serialize-safe 形狀（降級 / 清理 / 防止 runtime object） | `normalizeObjectShallow`, `normalizeObjectDeep`, `serializeSafe` | | Path | 路徑 | 解析、正規化與組裝資料路徑 | `normalizePath`, `pathToKeys`, `keysToPath`, `joinPath` | | Read | 讀取 | 以 path 為核心的安全讀取 | `getByPath`, `hasByPath`, `getOr`, `pickByPaths` | | Write | 寫入 | 以 path 為核心的安全寫入與更新 | `setByPath`, `unsetByPath`, `updateByPath`, `pushByPath` | | Flat | 結構轉換 | 巢狀結構 ⇄ flat path 結構 | `flatten`, `unflatten`, `toFlatPairs`, `flatKeys` | | Merge | 合併 | 定義 clone 與 merge 的資料合併語義 | `cloneJsonValue`, `cloneStructuredValue`, `mergeDeep` | | Diff | 差異 | 計算與套用資料差異 | `objDiff`, `diffToPatch`, `applyPatch`, `changedPaths` | | Query
Traversal | 遍歷 | 結構感知的遍歷與搜尋 | `walk`, `walkSafe`, `findByPredicate` | | Convenience | 高階 API | 封裝多個工具形成高階操作介面 | `readWriteFacade`, `flatFacade`, `diffFacade` | ## 概述 ### A. Read（讀取） **描述** 以 path 為核心的安全巢狀資料讀取。 **目的** 確保一致的讀取語義，避免直接存取屬性造成的例外或不一致行為。 --- ### B. Flat / Transform（展平 / 轉換） **描述** 在巢狀結構與 flat path 表示之間進行轉換。 **目的** 支援 diff、patch、merge 與 schema 驅動流程所需的標準化資料形態。 --- ### C. Write（寫入） **描述** 以 path 為單位的設值、更新與刪除操作。 **目的** 集中寫入規則（補齊策略、覆寫行為、immutable / mutating）， 避免寫入邏輯分散且不可控。 --- ### D. Query / Traverse（查詢 / 遍歷） **描述** 結構感知的遍歷、搜尋與存在性判斷。 **目的** 提供一致的結構查詢能力，避免零散的遞迴與臨時邏輯。 --- ### E. Clone / Merge（複製與合併） **描述** 定義可承諾的資料複製與合併行為。 **目的** 在跨環境情境下，提供語義清楚、可預期的 clone / merge 契約， 以支援 diff、patch、serialize 與狀態隔離等流程。 --- ### F. Diff / Patch（差異 / 補丁） **描述** 偵測並表達資料結構之間的差異。 **目的** 產生可預測、可重放的差異與補丁，用於更新、同步與審計。 --- ### G. Guard / Shape（型別 / 結構保護） **描述** 針對資料型別與結構的顯性檢查與保護。 **目的** 明確界定資料假設，避免隱性錯用或不符合契約的資料進入流程。 --- ### 設計原則 - Tables 定義的是 **契約（contract）**，而非 **實作（implementation）** - 內部可存在 helper 與 variant - **只有列於 tables 中的方法，才被視為可被依賴的穩定 API** # Object / Data Utilities 方法總覽 ## A. Path（路徑）家族：解析、正規化、判斷、組裝 - path === null | undefined 視為 empty path（keys=[]） - empty path 的語義：指向「整個 value 本身」 | num | method | description | 輸入 | 輸出 | 規則 | |---------|-------------------------------------|----------------------------|------------------|---------------------|------------------------| | PATH_01 | normalizePath
normalizeFlatPath | 將各種 path 形式統一轉為可安全操作的 keys | string | array | null | undefined | string[] | trim、split、過濾空段，僅 undefined 視為空 | | PATH_02 | pathToKeys | 將字串路徑解析為陣列 | flat path string | string[] | 以 `.` 拆解，忽略空 key | | PATH_03 | keysToPath | 將 keys 還原為 flat path | string[] | string | 以 `.` 串接 | | PATH_04 | isPathLike | 判斷是否可作為 path 輸入 | any | boolean | string 或 array 即為 true | | PATH_05 | isArrayIndexKey | 用於推斷容器型別 | string | boolean | 純數字字串為 array index | | PATH_06 | splitParentPath | 便於 unset / rename 操作 | flat path string | { parentPath, key } | 最後一段視為 key | | PATH_07 | joinPath | 動態組合多段路徑 | 多段 path | string | 自動忽略空段 | | PATH_08 | escapeKey
unescapeKey | 支援 key 含特殊字元 | string | string | 成對使用，轉義與還原 | --- ## B. Read（讀取）家族：安全取值、預設值、存在性 | num | method | description | 輸入 | 輸出 | 規則 | |---------|--------------|-------------------|--------------------|---------|-------------------------------------------| | READ_01 | getByPath | 容錯讀取深層欄位 | obj, path | any | 中途 null/undefined 直接回 undefined；終點可為 null | | READ_02 | hasByPath | 與 empty 定義一致的存在判斷 | obj, path | boolean | 僅 `!== undefined` 視為存在 | | READ_03 | getOr | 安全套用預設值 | obj, path, default | any | 只有 undefined 才套 default | | READ_04 | pickByPaths | 組合式查詢工具 | obj, paths[] | object | 只取指定 paths | | READ_05 | pluckByPaths | 對清單批次取值 | list, path | array | 對每個元素執行 getByPath | --- ## C. Write（寫入）家族：設值、刪除、更新 | num | method | description | 輸入 | 輸出 | 規則 | |------------|----------------|-----------------|---------------------|--------|---------------------| | WRITE_01 | setByPath | 核心安全寫入 API | target, path, value | void | 預設補齊缺失路徑（immutable） | | WRITE_01_2 | setByPathMut | 核心安全寫入 API（mut） | target, path, value | target | in-place 修改；補齊缺失路徑 | | WRITE_02 | setManyByPaths | 批次更新工具 | target, entries | void | 逐筆套用 setByPath | | WRITE_03 | ensureByPath | undefined 才初始化 | target, path, init | any | 保留 null 為合法值 | | WRITE_04 | updateByPath | 原子化更新指定路徑 | target, path, fn | any | fn 接收舊值 | | WRITE_05 | unsetByPath | 精準移除欄位 | target, path | void | 移除最後一段 key | | WRITE_06 | renameByPath | 欄位重新命名 | target, from, to | void | set 新路徑後 unset 舊路徑 | | WRITE_07 | pushByPath | 對 array 路徑累積 | target, path, item | number | 確保目標為 array | | WRITE_08 | removeAtByPath | 移除陣列指定項 | target, path, index | any | 操作 array index | --- ## D. Flatten / Unflatten 家族：obj ⇄ flat 結構 | num | method | description | 輸入 | 輸出 | 規則 | |---------|-----------------------------|---------------------|----------|--------------------|------------------| | FLAT_01 | fromObjToFlat
flatten | 巢狀結構轉 flat map | object | Object | 只輸出 leaf；保留 null | | FLAT_02 | fromFlatToObj
unFlatten | flat 結構還原巢狀 | flat map | object | 自動推斷 {} 或 [] | | FLAT_03 | toFlatPairs | 轉為 path/value pairs | object | {path,value}[] | 依 traversal 順序 | | FLAT_04 | fromFlatPairs | pairs 還原巢狀物件 | pairs[] | object | 逐筆 setByPath | | FLAT_05 | flatKeys | 取得所有 leaf paths | object | string[] | 只回 leaf paths | | FLAT_06 | flatValues | 取得所有 leaf values | object | any[] | 與 flatKeys 對應 | --- ## E. Clone / Merge 家族：複製與合併 | num | method | description | 輸入 | 輸出 | 規則 | |------------|----------------------|-----------------------|------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MERGE_01 | cloneJsonValue | 跨環境一致的 JSON value 複製 | any | any | 僅支援 JSON value；遇到不支援型別 **直接 throw** | | MERGE_01_2 | cloneStructuredValue | 跨環境可承諾的結構化 value 深層複製 | any | any | 僅支援結構化 value；**無法處理即 throw，不做隱性 fallback** | | MERGE_02 | mergeDeep | 結構安全的深層合併 | target, source | object | **遞迴合併規則（immutable）**：
1) **非 container**（plain object / array 以外）→ **直接回傳 source**。
2) **object × object** → 逐 key 合併：`source[key] === undefined` 時保留 `target[key]`，否則遞迴合併。
3) **array × array** → 依 `options.array`：`replace`（預設，回傳 `source.slice()`）或 `concat`（`target.concat(source)`）。
4) **container 型別不一致（object × array 或 array × object）** → **source wins（整體覆蓋）**，不做混合合併、不做隱性轉型。 | | MERGE_03 | mergeByPaths | 只合併指定 paths | target, flat map | void | 精準合併 | | MERGE_04 | assignDefined | partial update 核心工具 | target, patch | object | 只寫入 `!== undefined` | | MERGE_05 | omitUndefined | 清理輸出資料 | object | object | 遞迴移除 undefined | > cloneStructuredValue: 嚴格複製 JSON tree（object + array + primitive），不做 fallback。 --- ## F. Diff / Patch 家族：差異計算與套用 | num | method | description | 輸入 | 輸出 | 規則 | |---------|--------------|--------------|-------------|-------------|----------------| | DIFF_01 | objDiff | 計算兩物件結構差異 | a, b | diff result | 以 flat path 為主 | | DIFF_02 | diffToPatch | 差異轉為可套用格式 | a, b | patch ops[] | set / unset | | DIFF_03 | applyPatch | 套用 patch 到目標 | target, ops | object | 依序套用 | | DIFF_04 | changedPaths | 取得最小變更集 | a, b | string[] | 只回變更 paths | | DIFF_05 | pickChanged | 分類變更結果 | a, b | object | 新增/修改/刪除 | --- ## G. Query / Traverse 家族：遍歷與搜尋 | num | method | description | 輸入 | 輸出 | 規則 | |------------|-----------------|------------------|-----------------|--------------|-----------------------| | QUERY_01 | walk | 全結構走訪 | object, visitor | void | DFS / BFS | | QUERY_01_2 | walkSafe | 循環安全的結構走訪 | object, visitor | void | 偵測循環；可設定 skip / throw | | QUERY_02 | mapLeaves | 批次轉換 leaf values | object, fn | object | 僅處理 leaf | | QUERY_03 | filterLeaves | 條件式移除 leaf | object, fn | object | false 即移除 | | QUERY_04 | findByPredicate | 快速搜尋節點 | object, fn | {path,value} | undefined | 找到即停 | > walk 假設 tree；walkSafe 用於可能含循環的 object graph。 --- ## H. Guard / Shape 家族：型別與結構保護（regen + feedback integrated） | num | method | description | 輸入 | 輸出 | 規則 | |----------|---------------------------------------------|--------------------------------------------------|----------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | GUARD_01 | isPlainObject
isObjStrict
isStrictObj | 排除非純物件 | any | boolean | 僅 `[object Object]` 視為純物件 | | GUARD_01_2 | isObjectLikeOrArray | todo | any | boolean | todo | | GUARD_01_3 | isObjectLikeNoArray | todo | any | boolean | todo | | GUARD_02 | isContainer | 判斷是否可遞迴（容器判斷） | any | boolean | 只有 **plain object** 或 **array** 視為 container（排除 Date / Map / Set / Function 等） | | GUARD_03 | ensureContainerForNextKey | 推斷下一層容器（供 write/flat/unflat 使用） | nextKey | {} | [] | 依 `isArrayIndexKey(nextKey)` 推斷：true → `[]`，false → `{}` | | GUARD_04 | coerceContainer | 容錯轉為合法容器（覆蓋式矯正） | value, nextKey | {} | [] | 若 `value` 非 container，直接以 `ensureContainerForNextKey(nextKey)` 覆蓋；不保留原值、不做 fallback | | GUARD_05 | ~~isStructuredClonable~~ (obsolete) | ~~檢查是否符合 `MERGE_01_2 cloneStructuredValue` 的輸入前置條件~~ | any | boolean | - | | GUARD_06 | wrapToPlainObject | 強制收斂為純物件形狀 | any | Object | PlainObject 保持不變；Array 轉為 {items}；Primitive 轉為 {value}；null/undefined 轉 undefined。 | | GUARD_07 | ensurePlainObjectOrEmpty| 強制為純物件或空值 | any | Object | PlainObject 保持不變；null/undefined 轉 undefined；其他轉為 {}。 | --- ## I. Convenience 家族：高階整合 API | num | method | description | 輸入 | 輸出 | 規則 | |---------|-----------------|----------------------------------|---------------|---------------|----------------------------------------------------------------------| | CONV_01 | readWriteFacade | 綁定 target 的操作介面 | target | facade object | get/set/unset | | CONV_02 | flatFacade | flat 操作整合介面 | object | facade object | flatten/unflatten | | CONV_03 | diffFacade | diff/patch 工作流封裝 | options | facade object | 組合 diff / apply | | CONV_04 | extractByPath | collection 層級的 getByPath，保留原 key | path → object | object | 對每個第一層 key 的 value 套用 READ_01 getByPath；key 不變；不使用 flatten/unFlatten | --- ## J. Normalize / Serialization Safety | num | method | description | 輸入 | 輸出 | 規則 | | ------- | ---------------------- | ----------- | --- | ------------ | --- | | NORM_01 | normalizeObjectShallow | 輕量級邊界安全化 | any | any | 不遞迴 | | NORM_02 | normalizeObjectDeep / serializeSafe | 完整序列化治理 | any | plain object | 遞迴 |