@greatcloak/json-patch

中文文档
4.0.0发布于 2026/05/16MITTypeScriptES Module零依赖近 30 天下载 1.2万

现代(sm)版本快活-json-patch. 快速实施JSON-Patch(RFC-6902),具有双层(观察变化)能力

中文使用文档
文档目录16 节
  1. 为什么要用 JSON -Patch
  2. 安装
  3. 添加到您的项目中
  4. 在节点.js
  5. 目录
  6. API 密码
  7. OperationResult 类型
  8. 校正说明
  9. 重叠和 move 运行
  10. undefined s(JS至JSON投影)
  11. 光谱/测试
  12. 捐款
  13. 更改日志
  14. 脚印
  15. 业绩
  16. 许可证

@greatcloak/json-patch (英语)

一个叉子 快速编程 与现代esm配置.

这种叉子的目标是维持一个安全而现代化的快活-Json-patch版本,用于我们的产品.

  • 保持粗糙的相容性,无论旧的打字符设置、模块包装格式等是否必要,都不应被打破
  • 欢迎速度、错误和安全修复
  • 对共同的现实世界问题来说,方便使用是鼓励的.

推测这个项目现在与vitest和现代角测试设置相兼容.

带着JSON-Patch,你可以:

  • 应用 jS 对象上的补丁( 阵列) 和单项操作
  • 验证 补丁序列
  • 观察 更改和 生成 检测到变化时补丁
  • 比较 获取差异的两个对象

在Firefox、Chrome、Edge、Safari、IE11、Deno和Node.js测试

为什么要用 JSON -Patch

JSON- Patch 游戏 (RFC6902) (中文(简体) ) 是标准格式 允许您通过发送更改而不是整个文档来更新 JSON 文档. JSON Patch在HTTP PATCH动词(方法)和REST风格编程上表现良好.

马克诺丁汉有一个 不错的博客 关于它.

安装

# NPM
npm install @greatcloak/json-patch --save

添加到您的项目中

在节点.js

在Webpack(当然还有基于Babel的其他捆绑器)中,以下代码使用这个库作为ECMAScript模块:

import * as jsonpatch from '@greatcloak/json-patch'
import { applyOperation } from '@greatcloak/json-patch'

目录

此包中使用的目录 :

  • dist/ - 包含网络浏览器的ES5文件
  • commonjs/ - 包含普通JS模块和打字
  • module/ - 包含ECMAScript模块和打字
  • src/ - 包含类型Script源文件

API 密码

function applyPatch<T>(document: T, patch: Operation[], validateOperation?: boolean | Validator<T>, mutateDocument: boolean = true, banPrototypeModifications: boolean = true): PatchResult<T>

应用 patch 阵列在 obj。 。 。 .

  • document 要补丁的文档
  • patch a 应用JSON-Patch系列操作
  • validateOperation 布尔用于是否用默认验证器验证每个操作, 或是通过验证器回调
  • mutateDocument 是否在应用前对原始文档进行突变或复制
  • banPrototypeModifications 是否禁止修改 __proto__,默认为 true。 。 。 .

无效的补丁导致丢出错误( 见 jsonpatch.validate 关于错误对象的更多信息.

它修改了 document 对象和 patch - 它通过参考得到数值. 请不要碰你 patch 数组值, 复制它们 : jsonpatch.applyPatch(document, jsonpatch.deepClone(patch))。 。 。 .

返回数组 OperationResult 对象 - 每个项目在 patches,每个项目都是对象 {newDocument: any, test?: boolean, removed?: any}。 。 。 .

  • test - 测试的布尔结果
  • remove, (中文(简体) ), replace 财务报告和审定财务报表 move - 已删除的原始对象
  • add (仅在添加到数组时) - 插入项目所在的索引(在使用时有用) - (别名)
  • ** 注:投出 TEST_OPERATION_FAILED 错误,如果 test 操作失败 。 页:1

  • ** 注意 二: 返回的数组有 newDocument 属性,可以用作补丁文档的最后状态**.

  • ** 附注三:默认情况下 banPrototypeModifications 实值 true,该方法将 TypeError 当你试图修改一个对象的原型时.

  • 见 审定说明。 。 。 .

示例

var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var patch = [
  { op: 'replace', path: '/firstName', value: 'Joachim' },
  { op: 'add', path: '/lastName', value: 'Wester' },
  {
    op: 'add',
    path: '/contactDetails/phoneNumbers/0',
    value: { number: '555-123' },
  },
]
document = jsonpatch.applyPatch(document, patch).newDocument
// document == { firstName: "Joachim", lastName: "Wester", contactDetails: { phoneNumbers: [{number:"555-123"}] } };

function applyOperation<T>(document: T, operation: Operation, validateOperation: boolean | Validator<T> = false, mutateDocument: boolean = true, banPrototypeModifications: boolean = true, index: number = 0): OperationResult<T>

应用单个操作对象 operation 打开 document。 。 。 .

  • document 要补丁的文档
  • operation 申请行动
  • validateOperation 是否验证操作, 还是通过验证符回调
  • mutateDocument 是否在应用前对原始文档进行突变或复制
  • banPrototypeModifications 是否禁止修改 __proto__,默认为 true。 。 。 .
  • index 您补丁阵列中的操作索引 。 当操作失败时, 用于更好的错误报告 .

它修改了 document 对象和 operation - 它通过参考得到数值. 如果你想避免触摸你的价值观,请复制: jsonpatch.applyOperation(document, jsonpatch.deepClone(operation))。 。 。 .

返回 a OperationResult 对象 {newDocument: any, test?: boolean, removed?: any}。 。 。 .

  • ** 注:投出 TEST_OPERATION_FAILED 错误,如果 test 操作失败 。 页:1

  • ** 附注二:默认情况下 banPrototypeModifications 实值 true,该方法将 TypeError 当你试图修改一个对象的原型时.

  • 见 审定说明。 。 。 .

示例

var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var operation = { op: 'replace', path: '/firstName', value: 'Joachim' }
document = jsonpatch.applyOperation(document, operation).newDocument
// document == { firstName: "Joachim", contactDetails: { phoneNumbers: [] }}

jsonpatch.applyReducer<T>(document: T, operation: Operation, index: number): T

理想为 patch.reduce(jsonpatch.applyReducer, document)。 。 。 .

应用单个操作对象 operation 打开 document。 。 。 .

返回已修改的文档.

注意: 它抛出 TEST_OPERATION_FAILED 错误,如果 test 操作失败 .

示例

var document = { firstName: 'Albert', contactDetails: { phoneNumbers: [] } }
var patch = [
  { op: 'replace', path: '/firstName', value: 'Joachim' },
  { op: 'add', path: '/lastName', value: 'Wester' },
  {
    op: 'add',
    path: '/contactDetails/phoneNumbers/0',
    value: { number: '555-123' },
  },
]
var updatedDocument = patch.reduce(applyReducer, document)
// updatedDocument == { firstName:"Joachim", lastName:"Wester", contactDetails:{ phoneNumbers[ {number:"555-123"} ] } };

jsonpatch.deepClone(value: any): any

返回深克隆值 .

jsonpatch.escapePathComponent(path: string): string

返回已逃出路径 .

jsonpatch.unescapePathComponent(path: string): string

返回未脱逃路径.

jsonpatch.getValueByPointer(document: object, pointer: string)

用 JSON 指针从 JSON 文档中获取一个值 .

返回该值.

jsonpatch.observe(document: any, callback?: Function): Observer

设置一个深入的观察者 关于 document 用于聆听对象树的变化。 当检测到变化时,可选 以生成的补丁数组作为参数调用回调.

回返 observer。 。 。 .

jsonpatch.generate(document: any, observer: Observer, invertible = false): Operation[]

如果待修改,则 obj,并同步返回它们。 如果有的话 callback 定义于 observe 方法,它也会同步被触发。 若为 invertible ,然后在每次修改之前先进行值的测试操作.

如果没有待处理的变动 obj,返回空数组(长度为0).

示例

var document = {
  firstName: 'Joachim',
  lastName: 'Wester',
  contactDetails: { phoneNumbers: [{ number: '555-123' }] },
}
var observer = jsonpatch.observe(document)
document.firstName = 'Albert'
document.contactDetails.phoneNumbers[0].number = '123'
document.contactDetails.phoneNumbers.push({ number: '456' })
var patch = jsonpatch.generate(observer)
// patch  == [
//   { op: "replace", path: "/firstName", value: "Albert"},
//   { op: "replace", path: "/contactDetails/phoneNumbers/0/number", value: "123" },
//   { op: "add", path: "/contactDetails/phoneNumbers/1", value: {number:"456"}}
// ];

对第一个对象中值进行测试操作生成补丁的示例:

var document = {
  firstName: 'Joachim',
  lastName: 'Wester',
  contactDetails: { phoneNumbers: [{ number: '555-123' }] },
}
var observer = jsonpatch.observe(document)
document.firstName = 'Albert'
document.contactDetails.phoneNumbers[0].number = '123'
document.contactDetails.phoneNumbers.push({ number: '456' })
var patch = jsonpatch.generate(observer, true)
// patch  == [
//   { op: "test", path: "/firstName", value: "Joachim"},
//   { op: "replace", path: "/firstName", value: "Albert"},
//   { op: "test", path: "/contactDetails/phoneNumbers/0/number", value: "555-123" },
//   { op: "replace", path: "/contactDetails/phoneNumbers/0/number", value: "123" },
//   { op: "add", path: "/contactDetails/phoneNumbers/1", value: {number:"456"}}
// ];

jsonpatch.unobserve(document, observer)

jsonpatch.unobserve(document: any, observer: Observer): void

type JsonableObj = { [key:string]: Jsonable };
type JsonableArr = Jsonable[];
type Jsonable = JsonableArr | JsonableObj | string | number | boolean | null;

摧毁在 document。 。 。 .

任何剩余更改均同步交付(如 jsonpatch.generate) (中文(简体) ). 注:这与ES6/7不同 Object.unobserve,可以同步实现剩余变化.

jsonpatch.compare(document1, document2, invertible)

jsonpatch.compare(document1: Jsonable, document2: Jsonable, invertible = false): Operation[]

type JsonableObj = { [key:string]: Jsonable };
type JsonableArr = Jsonable[];
type Jsonable = JsonableArr | JsonableObj | string | number | boolean | null;

比较对象树 document1 财务报告和审定财务报表 document2 与 document1 作为补丁数组。 若为 invertible ,然后在每次更改之前,先对数值进行测试操作 document1。 。 。 .

如果没有差异,则返回一个空数组(长为0).

示例

var documentA = { user: { firstName: 'Albert', lastName: 'Einstein' } }
var documentB = { user: { firstName: 'Albert', lastName: 'Collins' } }
var diff = jsonpatch.compare(documentA, documentB)
//diff == [{op: "replace", path: "/user/lastName", value: "Collins"}]

将两个对象树与第一个对象值的测试操作进行比较的例子:

var documentA = { user: { firstName: 'Albert', lastName: 'Einstein' } }
var documentB = { user: { firstName: 'Albert', lastName: 'Collins' } }
var diff = jsonpatch.compare(documentA, documentB, true)
//diff == [
//   {op: "test", path: "/user/lastName", value: "Einstein"},
//   {op: "replace", path: "/user/lastName", value: "Collins"}
// ];

jsonpatch.validate(patch: Operation[], document?: any, validator?: Function): JsonPatchError

见 审定说明

验证一系列操作。 若为 document 提供了参数,序列会针对对象树进行额外的验证.

如果没有出错, 返回未定义 。 如果存在错误,返回具有以下属性的 JsonPatchError 对象:

  • name 字符串 - 短错误代码
  • message 字符串 - 长可读错误消息
  • index 数字 - 序列中操作的索引
  • operation 对象 - 操作的引用
  • tree 对象 - 树的引用

可能的错误 :

错误名称错误消息
安全性 NOT AN ARRAY补丁序列必须是数组
操作 NOT AN OBJECT操作不是一个对象
操作 OP 评估运行 op 属性不是 RFC-6902 定义的操作之一
操作 PATH 评估运行 path 属性不是一个有效的字符串
操作 FROM REQUIED运行 from 属性不存在(适用于 move 财务报告和审定财务报表 copy 业务)
操作 评估 完成运行 value 属性不存在,或 undefined (适用于 add, (中文(简体) ), replace 财务报告和审定财务报表 test 业务)
操作 VALUE CANNOT CONANDINED运行 value 属性对象至少有一个 undefined 值(适用于 add, (中文(简体) ), replace 财务报告和审定财务报表 test 业务)
操作 PATH CANNOT ADD无法执行 add 运行在理想路径
无法操作无法在不存在的路径上执行操作
无法操作无法从不存在的路径执行操作
操作 PATH ILLLEGAL ARRAY INDEX期望一个没有符号的 Base- 10 整数值, 使新的引用值成为以零为基础的索引的数组元素
行动 评价 OUT OF BOUNDS指定的索引 MUST 不大于数组中的元素数
测试 测试 测试当操作是 test 测试失败,则适用于 applyReducer。 。 。 .

示例

var obj = { user: { firstName: 'Albert' } }
var patches = [
  { op: 'replace', path: '/user/firstName', value: 'Albert' },
  { op: 'replace', path: '/user/lastName', value: 'Einstein' },
]
var errors = jsonpatch.validate(patches, obj)
if (errors.length == 0) {
  //there are no errors!
} else {
  for (var i = 0; i < errors.length; i++) {
    if (!errors[i]) {
      console.log('Valid patch at index', i, patches[i])
    } else {
      console.error('Invalid patch at index', i, errors[i], patches[i])
    }
  }
}

OperationResult 类型

职能 applyPatch 财务报告和审定财务报表 applyOperation 双向返回 OperationResult 对象。 此对象为:

{newDocument: any, test?: boolean, removed?: any}

地点:

  • newDocument:应用补丁/操作后文档的新状态.
  • test: 如果操作是 test 操作。 这将是它的结果.
  • removed: 包含文档中已删除、已移动或替换的值 remove, (中文(简体) ), move 或者说 replace 操作.

校正说明

职能 applyPatch, (中文(简体) ), applyOperation,以及 validate 接受一个 validate编号 : validator 参数 :

  • 如果 validateOperation 参数设置为 false,不会进行验证.
  • 如果设置为 true,该补丁在应用jsonpatch的默认验证之前被广泛验证.
  • 如果设置为 function 调回,补丁使用此函数验证 .

如果你通过一个验证器,它将被调用 四个参数每个操作, function(operation, index, tree, existingPath) 并有望投出 JsonPatchError 当你的条件没有满足.

  • operation 操作它自己.
  • index operation补丁数组中的索引( 如果应用) .
  • tree 应补丁的对象.
  • existingPath 路径 operation 指点.

重叠和 move 运行

当移动操作的目标已经存在时,它会被缓存,被深克隆并返回为 removed 内 OperationResult。 。 。 .

undefineds(JS至JSON投影)

作为 undefined 类型在JSON不存在,它也不是JSON补丁操作的有效值. 因此 jsonpatch 将不生成 JSON 补丁设置到 undefined。 。 。 .

当一个值设定为 undefined jSON-Patch方法 generate 财务报告和审定财务报表 compare 将类似于 JavaScript 方法 JSON.stringify (MDN) (韩语) 治疗他们:

若为 undefined 在转换过程中遇到(.),它要么被省略(当在对象中发现时),要么被审查到 null (当它在一个阵列中被发现时).

见 ECMAScript 光谱 详细情况.

光谱/测试

捐款

更改日志

要查看最近更改的清单,见 释放。 。 。 .

脚印

4 KB 变焦并被克齐克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克

业绩

add 基准

image

replace 基准

image

于2018年8月29日被试. 比较库 :

我们的目标是公平测试。 我们的图书馆将表演作为一号优先,而其他图书馆可以有不同的优先. 如果你想更新基准 或增加一个图书馆, 请叉出 每区 将上述基准联系起来,并开启一个包括新成果的问题.

许可证

麻省理工学院

版本与发布记录

@greatcloak/json-patch 共发布 1 个版本,首次发布于 2026/05/16;过去 12 个月发布了 1 个版本。

版本发布日期距今
4.0.0latest2026/05/166 个月前

关于 @greatcloak/json-patch 的常见问题

@greatcloak/json-patch 是什么?

现代(sm)版本快活-json-patch. 快速实施JSON-Patch(RFC-6902),具有双层(观察变化)能力

如何安装 @greatcloak/json-patch?

在项目目录运行 npm install @greatcloak/json-patch,或使用 pnpm add / yarn add / bun add。

@greatcloak/json-patch 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@greatcloak/json-patch 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@greatcloak/json-patch 可以商用吗?

@greatcloak/json-patch 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@greatcloak/json-patch 的下载量有多少?

根据 npm 官方下载统计,@greatcloak/json-patch 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,134 次,日均约 404 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@greatcloak/json-patch 还在维护吗?

最新版本 4.0.0 发布于 2026/05/16(6 个月前);至今共发布 1 个版本,其中过去 12 个月发布了 1 个;首次发布于 2026/05/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。