plugins.md•4.33 kB
# Plugins
`diff()`, `patch()` and `reverse()` functions are implemented using a pipes &filters pattern, making them extremely customizable by adding or replacing filters.
Some examples of what you can achieve writing your own filter:
- diff special custom objects (eg. DOM nodes, native objects, functions, RegExp, node.js streams?)
- ignore parts of the graph using any custom rule (type, path, flags)
- change diff strategy in specific parts of the graph, eg. rely on change tracking info for Knockout.js tracked objects
- implement custom diff mechanisms, like relative numeric deltas
- surprise me! :)
Check the `/src/filters` folder for filter examples.
## Plugin Example
Here is an example to provide number differences in deltas (when left and right values are both numbers)
This, way when diffing 2 numbers instead of obtaining `[ oldValue, newValue ] `, the difference between both values will be saved, this could be useful for counters simultaneously incremented in multiple client applications (patches that both increment a value would be combined, instead of failing with a conflict).
```ts
/*
Plugin a new diff filter
*/
var diffpatcher = jsondiffpatch.create();
var NUMERIC_DIFFERENCE = -8;
var numericDiffFilter = function (context) {
if (typeof context.left === 'number' && typeof context.right === 'number') {
context
.setResult([0, context.right - context.left, NUMERIC_DIFFERENCE])
.exit();
}
};
// a filterName is useful if I want to allow other filters to be inserted before/after this one
numericDiffFilter.filterName = 'numeric';
// to decide where to insert your filter you can look at the pipe's filter list
assertSame(diffpatcher.processor.pipes.diff.list(), [
'collectChildren',
'trivial',
'dates',
'texts',
'objects',
'arrays',
]);
// insert my new filter, right before trivial one
diffpatcher.processor.pipes.diff.before('trivial', numericDiffFilter);
// for debugging, log each filter
diffpatcher.processor.pipes.diff.debug = true;
// try it
var delta = diffpatcher.diff({ population: 400 }, { population: 403 });
assertSame(delta, [0, 3, NUMERIC_DIFFERENCE]);
/*
Let's make the corresponding patch filter that will handle the new delta type
*/
var numericPatchFilter = function (context) {
if (
context.delta &&
Array.isArray(context.delta) &&
context.delta[2] === NUMERIC_DIFFERENCE
) {
context.setResult(context.left + context.delta[1]).exit();
}
};
numericPatchFilter.filterName = 'numeric';
diffpatcher.processor.pipes.patch.before('trivial', numericPatchFilter);
// try it
var right = diffpatcher.patch({ population: 400 }, delta);
assertSame(right, { population: 403 });
// patch twice!
diffpatcher.patch(right, delta);
assertSame(right, { population: 406 });
/*
To complete the plugin, let's add the reverse filter, so numeric deltas can be reversed
(this is needed for unpatching too)
*/
var numericReverseFilter = function (context) {
if (context.nested) {
return;
}
if (
context.delta &&
Array.isArray(context.delta) &&
context.delta[2] === NUMERIC_DIFFERENCE
) {
context.setResult([0, -context.delta[1], NUMERIC_DIFFERENCE]).exit();
}
};
numericReverseFilter.filterName = 'numeric';
diffpatcher.processor.pipes.reverse.after('trivial', numericReverseFilter);
// try it
var reverseDelta = diffpatcher.reverse(delta);
assertSame(reverseDelta, [0, -3, NUMERIC_DIFFERENCE]);
// unpatch twice!
diffpatcher.unpatch(right, delta);
assertSame(right, { population: 403 });
diffpatcher.unpatch(right, delta);
assertSame(right, { population: 400 });
```
## Pipe API
The following methods are offered to manipulate filters in a pipe.
- `append(filter1, filter2, ...)` - Append one or more filters to the existing list
- `prepend(filter1, filter2, ...)` - Prepend one or more filters to the existing list
- `after(filterName, filter1, filter2, ...)` - Add one ore more filters after the specified filter
- `before(filterName, filter1, filter2, ...)` - Add one ore more filters before the specified filter
- `replace(filterName, filter1, filter2, ...)` - Replace the specified filter with one ore more filters
- `remove(filterName)` - Remove the filter with the specified name
- `clear()` - Remove all filters from this pipe
- `list()` - Return array of ordered filter names for this pipe