@nxtspace/immutable-patch

将 RFC 6902 补丁列表应用到任意 Immutable.js 数据结构上，返回更新后的新集合。补丁列表通常由 @nxtspace/immutable-diff 生成。

安装

npm i @nxtspace/immutable-patch

immutable 为 peer dependency（^5），需由宿主项目自行提供。

快速开始

import { fromJS } from "immutable";
import patch from "@nxtspace/immutable-patch";
import diff from "@nxtspace/immutable-diff";

const a = fromJS({ x: 1, list: [1, 2, 3] });
const b = fromJS({ x: 2, list: [1, 3] });

patch(a, diff(a, b)).equals(b); // true

也可以手工构造补丁（必须是 List<Map> 形式，不是普通 JS 对象）：

import { fromJS, List, Map } from "immutable";

const patches = List([
  Map({ op: "replace", path: "/x", value: 9 }),
  Map({ op: "add", path: "/list/-", value: 4 }),
  fromJS({ op: "remove", path: "/stale" }),
]);

patch(fromJS({ x: 1, list: [1, 2], stale: true }), patches).toJS();
// { x: 9, list: [1, 2, 4] }

API

默认导出与具名导出 eachPatch 为同一函数。

eachPatch<T>(value, patches): T

| 参数 | 说明 | | --- | --- | | value | 目标数据结构：Map / List / Record / 基础类型均可 | | patches | List<PatchOperationMap>，按顺序依次应用 |

按补丁顺序逐条应用，返回最终的新集合；输入集合本身不被修改。

Path / escape / unescape

JSON Pointer 片段工具：~ → ~0、/ → ~1，unescape 为其逆运算。

类型

import type {
  PatchOp, // "add" | "replace" | "remove"
  PatchOperationMap, // Map<string, unknown>，即补丁的单条元素
} from "@nxtspace/immutable-patch";

支持的 op

仅实现 add / replace / remove，不实现 RFC 6902 的 move / copy / test；遇到未知 op 会抛错（unknown op）。

行为要点

• add 命中已存在的数组下标时是插入（后续元素后移），与 RFC 6902 对数组 add 的定义一致；要覆盖某位请改用 replace。
• add 的路径末段为 "-" 时追加到序列末尾。
• add 的路径中间节点缺失时会自动补建容器：下一段是纯数字则建 List，否则建 Map。
• remove 作用于基础类型（既非 Indexed 也非 Keyed/Record）时结果为 null。
• 补丁只有单条且为 { op: "replace", path: "/" } 时，直接整体替换为目标值（对应 diff 在两侧类型不同或单边为空时的输出）。
• 目标结构为 Record 时通过鸭子类型识别（具备 updateIn 与 set），并按其既有 key 写入。
• 应用 @nxtspace/immutable-diff 的产物时，两侧集合需整体 immutable（统一 fromJS 构造）；若结构中混有普通 JS 对象，补丁的 value 已被深转换为 Map / List，写回后与原对象不再 is() 相等。

License

MIT © Nxtspace