@powerduck/conf-patch
@powerduck/conf-patch 是採用清楚雙層架構的設定編輯程式庫。它依循 RFC 6902 JSON Patch 語意修改 JSON、JSONC 和 YAML 字串，保留註解與格式，並為 Node.js 和 Electron 提供原子寫入與跨處理程序檔案鎖定。
- 版本：
- 授權條款： MIT
- Node.js 需求：
>= 22.12.0 - 原始碼： github.com/powerducklab/conf-patch
為什麼選擇 conf-patch？
透過程式修改設定檔，往往得在兩種方式之間取捨：重新序列化整份文件可能改變註解、空白與格式，自行操作文字又容易出錯。conf-patch 提供：
- 保留註解的增量修改： JSON/JSONC 使用
jsonc-parser，YAML 使用yaml修改 AST。JSON/JSONC 不必整份重新序列化；YAML 則重新序列化修改後的 AST。 - 原子寫入： 先寫入暫存檔再重新命名，避免目標檔案只寫入一部分。
- 跨處理程序檔案鎖定： 支援擁有權權杖、指數退避重試及過期鎖定復原。
- 適用多種環境的 API： 核心層也能在瀏覽器、邊緣函式與使用 IndexedDB 儲存的應用程式中執行。
雙層架構
┌──────────────────────────────────────────────────────────────┐
│ Application code │
├─────────── ───────────────────────────────────────────────────┤
│ File layer (Node.js / Electron only) │
│ ┌───────────────┐ ┌────────────────┐ ┌──────────────────┐ │
│ │ readConfigFile │ │ writeConfigFile│ │ patchConfigFile │ │
│ │ setConfigValue │ │ deleteConfig… │ │ withFileLock │ │
│ └──────┬────────┘ └───────┬────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ ┌──────▼──────────────────▼───────────────────▼───────────┐ │
│ │ Core layer (browser-safe, zero Node deps) │ │
│ │ patchContent setContentValue deleteContentValue │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
核心層 — @powerduck/conf-patch/core（相容於瀏覽器）
操作字串的純函式，不依賴 node:fs、node:path 或其他 Node.js 專用 API。此子路徑匯出可打包至瀏覽器、邊緣函式或 Service Worker 程式碼中。
| 函式 | 用途 |
|---|---|
patchContent | 對設定字串套用一組 RFC 6902 操作 |
setContentValue | 設定或建立巢狀值（使用 add） |
deleteContentValue | 刪除鍵或陣列元素（使用 remove） |
檔案層 — @powerduck/conf-patch（Node.js / Electron）
讀寫實際檔案的非同步函式，在核心層之上加入原子寫入與鎖定機制。
| 函式 | 用途 |
|---|---|
readConfigFile | 從檔案路徑或 file:// URL 讀取 UTF-8 文字 |
writeConfigFile | 原子寫入內容，可選擇加鎖 |
patchConfigFile | 在檔案鎖定內執行讀取、修改、寫入交易 |
setConfigValue | 設定檔案中的巢狀值 |
deleteConfigValue | 刪除檔案中的巢狀值 |
withFileLock | 在獨佔鎖定保護下執行工作 |
releaseAllLocalLocks | 釋放目前處理程序持有的所有鎖定 |
支援的格式
| 格式 | 副檔名 | 行為 |
|---|---|---|
| JSON | .json | 標準 JSON，透過 jsonc-parser 增量修改。 |
| JSONC | .jsonc | 支援註解與尾端逗號的 JSON，保留註解。 |
| YAML | .yaml, .yml | YAML 1.2，透過 AST 修改保留註解、錨點與縮排。 |
detectFormat 將副檔名對應至 ConfigFormat。其他副檔名會觸發錯誤，除非明確傳入 format。
RFC 6902 操作
conf-patch 實作 RFC 6902 的子集，僅支援以下操作：
op | 行為 |
|---|---|
"add" | 在陣列索引處插入，或新增、取代物件屬性 |
"replace" | 取代現有值，路徑必須存在 |
"remove" | 刪除現有鍵或陣列元素，路徑必須存在 |
警告
不支援 "move"、"copy" 和 "test"。JsonPatchOp 型別將 op 限定為 "add" | "replace" | "remove"。
行為說明：
- 對陣列索引執行
add會插入元素（RFC 6902）。若要取代現有元素，請使用replace。 add要求父路徑已存在；請先建立父節點，再建立子節點。replace和remove要求目標路徑已存在。- 設定
strict: true（預設值）時，操作失敗會擲回例外；設定strict: false時，則會略過失敗操作並記錄警告。
保留註解與格式
- JSON/JSONC： 根據語法樹計算需要修改的文字範圍，保留周圍的註解、尾端逗號與縮排。
- YAML： 原地修改
yamlAST 後重新序列化，保留註解、錨點、別名與縮排。
OpenAPI 驗證
conf-patch 以具備安全防護的介面封裝 @powerduck/openapi-parser，驗證 OpenAPI/Swagger 文件：
validateOpenAPISpec驗證原始 JSON 或 YAML 內容。validateOpenAPIFile根據檔案 路徑驗證文件。- 輸入處理涵蓋大小限制、路徑沙箱（
allowedRootDirectory）、結構複雜度檢查、逾時控制及AbortSignal取消。 - 失敗時擲回
OpenApiValidationError，內含可供程式辨識的code。