@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要补丁的文档patcha 应用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操作它自己.indexoperation补丁数组中的索引( 如果应用) .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 基准

replace 基准

于2018年8月29日被试. 比较库 :
- 恒星对接杰克/JSON-Patch 2.0.6 联合国
- bruth/jsonpatch-js (英语) 0.7.0 (简体中文)
- dharmafly/jsonpatch.js (英语) 3.0.1 (中文(简体) )
- 齐夫 0.7.3 (中文(简体) )
- RFC6902 (法语) 2.4.0 (中文(简体) )
我们的目标是公平测试。 我们的图书馆将表演作为一号优先,而其他图书馆可以有不同的优先. 如果你想更新基准 或增加一个图书馆, 请叉出 每区 将上述基准联系起来,并开启一个包括新成果的问题.
许可证
麻省理工学院