#moonbit-jsonpatch

#Try it online / 在线体验

#Install / 安装

moon add Xu107-hhh/moonbit-jsonpatch

#Why / 为什么做这个

1. API 客户端与服务端 —— PATCH /users/42 请求体是 JSON Patch， 服务端逐操作应用并在失败时返回第几个操作、哪条路径出错（400 响应）。
2. 配置与状态同步 —— 用 diff 计算两份配置/状态的差异并下发补丁， 对端 apply 原子应用；失败时原文档不受影响（本库不做部分应用）。
3. Agent / LLM 输出自修正 —— 模型只需返回小补丁而非整份文档， test 操作先做前置断言，不满足即整体拒绝，避免半新半旧的状态。

#Related work / 与既有项目的关系

• tiye/recollect（v0.2.1）：面向不可变 UI 框架（Cumulo/Respo）状态同步的私有格式 diff/patch——补丁是内存中的 PatchOp/PathSegment 结构体，仅在 recollect 实例之间可用，不读写标准 JSON Patch 文档；数组操作依赖带 "id" 的键控数组；其 Set 会自动创建缺失的中间节点（RFC 6902 明确将此判定为错误）。
• moondiff / piediff：文本/源码 diff（difftastic 风格、patience/Myers 算法），处理的是文本行，不是 JSON 文档结构。

#Conformance / 标准符合性

• diff —— 从两份文档生成等价补丁（保证可回放，不保证最小化）；
• RFC 7386 merge_patch；
• 不可变语义 —— 所有操作函数式更新，输入文档永不改动，失败零副作用。

#Usage / 用法

let doc = @json.parse("{\"a\":1,\"list\":[1,2]}")
let patch = @json.parse("[{\"op\":\"add\",\"path\":\"/list/-\",\"value\":3}]")
match @jsonpatch.apply_patch(doc, patch) {
  Ok(result) => // {"a":1,"list":[1,2,3]}
  Err(e) => // e.index / e.op / e.path / e.kind / e.message
}

Err(@jsonpatch.PatchError::{ index: 1, op: "add", path: "/x/9", ... })
// message: "array index is malformed or beyond the end of the array"

@jsonpatch.diff(old, new)          // -> RFC 6902 patch (Json)
@jsonpatch.merge_patch(target, p)  // RFC 7386，null 删除成员、对象递归合并

// 删除中间项并在头部插入新项：
@jsonpatch.diff_keyed(old, new, "id")
// -> [{"op":"remove","path":"/list/1"},{"op":"add","path":"/list/0","value":{"id":0}}]
// 位置 diff 则会输出连锁 replace（把 id:1 改成 id:0、id:2 改成 id:1）

match @jsonpatch.apply(doc_text, patch_text) { ... }

$ moon run cmd/patch -- apply '{"a":1,"list":[1,2]}' \
    '[{"op":"add","path":"/list/-","value":3},{"op":"replace","path":"/a","value":9}]'
{"a":9,"list":[1,2,3]}

$ moon run cmd/patch -- diff '{"a":1,"b":2}' '{"a":2,"c":3}'
[{"op":"remove","path":"/b"},{"op":"replace","path":"/a","value":2},{"op":"add","path":"/c","value":3}]

$ moon run cmd/patch -- diff '{"list":[{"id":1},{"id":2},{"id":3}]}' \
    '{"list":[{"id":0},{"id":1},{"id":3}]}' --key id
[{"op":"remove","path":"/list/1"},{"op":"add","path":"/list/0","value":{"id":0}}]

$ moon run cmd/patch -- merge '{"a":{"x":1,"y":2}}' '{"a":{"y":null,"z":3}}'
{"a":{"x":1,"z":3}}

$ moon run cmd/patch -- apply @doc.json @patch.json
$ cat patch.json | moon run --target js cmd/patch -- apply @doc.json -

#Performance / 性能

#Development

moon check             # static checks
moon fmt               # format
moon test              # unit tests + official conformance suite
moon run examples/basic  # runnable example (apply / diff / merge / errors)
moon run cmd/patch --  # run the CLI
moon run --release benches  # benchmarks (apply / diff / merge)
python tools/gen_suite.py  # regenerate suite tests from fixtures

#Project layout

• pointer.mbt — RFC 6901 JSON Pointer（解析/转义/规范索引）
• tree.mbt — 不可变树定位与函数式更新、深度相等
• apply.mbt — 补丁文档校验与六种操作的应用
• merge.mbt — RFC 7386 JSON Merge Patch
• diff.mbt — 差量（补丁）生成；diff_keyed 支持按唯一键对齐数组
• cmd/patch — CLI（apply / merge / diff；参数支持内联 JSON、@文件、- stdin）
• examples/basic — 可运行示例（moon run examples/basic）
• benches/ — 基准测试（moon run --release benches，固定种子可复现）
• suite/fixtures — vendored 官方测试套件（json-patch-tests）
• suite/gen — 生成的符合性测试（tools/gen_suite.py）
• demo/ — 浏览器 playground（js target）

#License