X2 Framework for Node.js | JSON Patches
This module is an implementation of JSON Patch (RFC 6902) for use with the record objects as defined by the X2 Framework's x2node-records module. Given patch specification JSON, the module builds a patch object that can be applied to records of the specified type.
The module also supports Merge Patch specification (RFC 7396).
See module's API Reference Documentation.
A patch is represented by a
RecordPatch class object and is parsed from the JSON using module's
build() function. For example:
const records = ;const patches = ;const recordTypes = records;// build the patchconst patch = patches;// apply patch to a recordconst order = ...patch;
build() function takes the following arguments:
recordTypeName- Name of the record type, against records of which the patch is going to be applied.
patch- The JSON patch specification according to the RFC 6902 specification.
If the record type is invalid, an
X2UsageError is thrown. If anything is wrong with the provided patch specification, the function throws an
X2SyntaxError. Otherwise, it returns a
RecordPatch instance, which exposes the following properties and methods:
Setof paths (in dot notation) of all record properties involved (read, erased and updated) in the patch.
Setof paths (in dot notaion) of those properties that may be updated by the patch, including paths of all parent properties of updated nested object properties. It will exclude properties that are only involved in "test" operations or as "from" properties of "copy" operations. Note that whether the patch actually changes the property value will depend on the current value in the supplied record. Naturally, if the value is the same, it won't change even though the property is still listed in the
apply(record, [handlers])- Applies the patch to the specified record. If the record is not good for the patch (e.g. some properties are missing that are expected to be present by the patch specification), the method throws an
X2DataError. Otherwise, it makes the necessary modifications to the provided record object and returns either
trueif all good, or
falseif a "test" patch operation fails. Note, that the method does not provide transactionality, so in case of an error or a failed "test" operation the provided record object may be left partially modified.
apply() method can be provided with a
handlers object that implements
RecordPatchHandlers interface. The interface methods on the object, if present, are invoked during the patch application to notify it about the changes that the patch is making to the record as it goes through the patch operations. The methods are:
onInsert(op, ptr, newValue, oldValue)- Called when a value is added to an array or map property as a result of an "add", "move" or "copy" patch operation. The
opargument is the operation, which can be "add", "move" or "copy". The
x2node-pointersmodule pointing at the array or map element, and the
newValueis the value being inserted. The value may be
nullfor a simple (non nested object) value array or map element, but never
oldValueis the previous value at the pointer location as would be returned by the pointer's
onRemove(op, ptr, oldValue)- Called when a value is removed from an array or map property as a result of a "remove" or "move" patch operation. The
opargument is the operation, which can be "remove" or "move". The
RecordElementPointerpointing at the array or map element. The
oldValueis the previous value at the pointer location.
onSet(op, ptr, newValue, oldValue)- Called when a value is set to a property (or an array or a map element is replaced) as a result of an "add", "remove" (the
null), "replace", "move" or "copy" patch operation. The
opargument is the operation, which can be "add", "remove", "replace", "move" or "copy". The
RecordElementPointer, and the
valueis the value being set. The value may be
oldValueis the previous value at the pointer location.
onTest(ptr, value, passed)- Called when a property value is tested as a result of a "test" patch operation. The
RecordElementPointerpointing at the property,
valueis the value, against which it is tested and
trueif the test was successful.
The methods are called only if present on the provided
handlers object and only if the record is actually modified as a result of the operation (except the
onTest(), which does not modify the record and is called always, if present).
Alternatively, instead of JSON Patch the patch may be specified using Merge Patch format:
const patch = patches;
The only difference is that
buildMerge() function is used instead of the regular
build(). The resulting patch object follows the same specification as described above.
Another option is to build JSON patch specification by analyzing differences between two records. The module provides
fromDiff() function for that:
const patchSpec = patches;const patch = patches;
A few notes about
- The top record id property is allowed to be missing in the provided updated record (if present, must be the same).
- View, calculated and record meta-info properties are ignored.
- Unrecognized properties in the updated record are not allowed.
- The resulting patch specification may still be invalid. For example,
fromDiff()does not check if properties are modifiable or optional. Attempt to build a patch from the resulting specification will reveal the error.
- The array properties are assumed to be sorted using the same criteria in both the original and the updated records.
- Elements of nested object arrays must have id property. All elements in the original record must have an id value. Elements in the updated record that do not have the id or have an id that is not found in the original array are assumed to be new and are inserted.