@jay-framework/json-patch 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+declare const ADD = "add";
+declare const REPLACE = "replace";
+declare const REMOVE = "remove";
+declare const MOVE = "move";
+type JSONPointer = (string | number)[];
+interface JSONPatchAdd {
+    op: typeof ADD;
+    path: JSONPointer;
+    value: any;
+}
+interface JSONPatchReplace {
+    op: typeof REPLACE;
+    path: JSONPointer;
+    value: any;
+}
+interface JSONPatchRemove {
+    op: typeof REMOVE;
+    path: JSONPointer;
+}
+interface JSONPatchMove {
+    op: typeof MOVE;
+    from: JSONPointer;
+    path: JSONPointer;
+}
+type JSONPatchOperation = JSONPatchAdd | JSONPatchReplace | JSONPatchRemove | JSONPatchMove;
+type JSONPatch = JSONPatchOperation[];
+
+type MeasureOfChange = number;
+type DataFields = number;
+type ArrayContext = {
+    matchBy: string;
+};
+type ArrayContexts = [JSONPointer, ArrayContext][];
+declare function diff<T>(newValue: T, oldValue: T, contexts?: ArrayContexts, path?: JSONPointer): [JSONPatch, MeasureOfChange, DataFields];
+
+declare function patch<T>(target: T, jsonPatch: JSONPatch, level?: number): T;
+
+export { ADD, type ArrayContexts, type JSONPatch, type JSONPatchAdd, type JSONPatchMove, type JSONPatchOperation, type JSONPatchRemove, type JSONPatchReplace, type JSONPointer, MOVE, REMOVE, REPLACE, diff, patch };

package/dist/index.js

@@ -0,0 +1,163 @@
+import { RandomAccessLinkedList, listCompare, ITEM_ADDED, ITEM_MOVED, ITEM_REMOVED } from "@jay-framework/list-compare";
+const ADD = "add";
+const REPLACE = "replace";
+const REMOVE = "remove";
+const MOVE = "move";
+const LIST_COMPARE_RESULT_TO_JSON_PATCH = {};
+LIST_COMPARE_RESULT_TO_JSON_PATCH[ITEM_ADDED] = (instruction, path) => ({
+  op: ADD,
+  value: instruction.item,
+  path: [...path, instruction.pos]
+});
+LIST_COMPARE_RESULT_TO_JSON_PATCH[ITEM_MOVED] = (instruction, path) => ({
+  op: MOVE,
+  from: [...path, instruction.fromPos],
+  path: [...path, instruction.pos]
+});
+LIST_COMPARE_RESULT_TO_JSON_PATCH[ITEM_REMOVED] = (instruction, path) => ({
+  op: REMOVE,
+  path: [...path, instruction.pos]
+});
+function findArrayContext(contexts, path) {
+  let foundContext = contexts?.find(([pointer]) => {
+    return path.length === pointer.length && path.reduce((prev, curr, index) => {
+      return prev && curr === "*" ? true : curr === path[index];
+    }, true);
+  });
+  return foundContext ? foundContext[1] : void 0;
+}
+function diffObjectOrArray(newValue, oldValue, contexts, path) {
+  let diffResults = [];
+  let keys, i, length;
+  keys = Object.keys(newValue);
+  let oldKeys = Object.keys(oldValue);
+  length = keys.length;
+  for (i = length; i-- !== 0; ) {
+    const key = keys[i];
+    diffResults.push(
+      diff(
+        newValue[key],
+        oldValue[key],
+        contexts,
+        [...path, key]
+      )
+    );
+  }
+  for (i = oldKeys.length; i-- !== 0; ) {
+    const key = oldKeys[i];
+    if (!(key in newValue))
+      diffResults.push([[{ op: REMOVE, path: [...path, key] }], 1, 1]);
+  }
+  return flattenPatch(diffResults, path, newValue);
+}
+function flattenPatch(diffResults, path, newValue) {
+  let [measureOfChange, dataFields] = diffResults.reduce(
+    (prev, curr) => [prev[0] + curr[1], prev[1] + curr[2]],
+    [0, 0]
+  );
+  if (measureOfChange / dataFields > 0.5)
+    return [[{ op: REPLACE, path, value: newValue }], 1, 1];
+  else
+    return [diffResults.map((_) => _[0]).flat(), measureOfChange, dataFields];
+}
+function diffArrayWithContext(context, oldValue, newValue, path, contexts) {
+  let { matchBy } = context;
+  const lastArray = new RandomAccessLinkedList(oldValue, matchBy);
+  const newArray = new RandomAccessLinkedList(newValue, matchBy);
+  const instructions = listCompare(lastArray, newArray, () => {
+  });
+  const arrayPatch = instructions.map(
+    (instruction) => LIST_COMPARE_RESULT_TO_JSON_PATCH[instruction.action](instruction, path)
+  );
+  const arrayItemPatches = [
+    [arrayPatch, instructions.length, newValue.length]
+  ];
+  newArray.forEach((newArrayItem, _, index) => {
+    let oldArrayItem = lastArray.get(newArrayItem[matchBy]);
+    if (oldArrayItem)
+      arrayItemPatches.push(
+        diff(newArrayItem, oldArrayItem.value, contexts, [...path, "" + index])
+      );
+  });
+  return flattenPatch(arrayItemPatches, path, newValue);
+}
+function diff(newValue, oldValue, contexts, path = []) {
+  if (oldValue === void 0 || oldValue === null)
+    return [[{ op: ADD, path, value: newValue }], 1, 1];
+  if (newValue === oldValue)
+    return [[], 0, 1];
+  if (newValue && oldValue && typeof newValue === "object" && typeof oldValue === "object") {
+    if (Array.isArray(newValue) && Array.isArray(oldValue)) {
+      let context = findArrayContext(contexts, path);
+      if (context) {
+        return diffArrayWithContext(context, oldValue, newValue, path, contexts);
+      }
+    }
+    if (Array.isArray(newValue) !== Array.isArray(oldValue))
+      return [[{ op: REPLACE, path, value: newValue }], 1, 1];
+    return diffObjectOrArray(
+      newValue,
+      oldValue,
+      contexts,
+      path
+    );
+  }
+  return [[{ op: REPLACE, path, value: newValue }], 1, 1];
+}
+function validateMove({ from, path }) {
+  let valid = from.length === path.length;
+  for (let i = 0, length = from.length - 1; i < length; i++)
+    valid = valid && from[i] === path[i];
+  return valid;
+}
+function patch(target, jsonPatch, level = 0) {
+  const copy = Array.isArray(target) ? [...target] : { ...target };
+  let equalCount = 0;
+  const patchesGroupedByProp = jsonPatch.reduce((prev, patchOperation) => {
+    const pathItem = patchOperation.path[level];
+    const op = patchOperation.op;
+    if (patchOperation.path.length - 1 === level) {
+      if (op === REPLACE || op === ADD) {
+        if (Array.isArray(copy) && op === ADD)
+          copy.splice(pathItem, 0, patchOperation.value);
+        else if (copy[pathItem] === patchOperation.value)
+          equalCount += 1;
+        else
+          copy[pathItem] = patchOperation.value;
+      } else if (op === REMOVE) {
+        if (Array.isArray(copy))
+          copy.splice(pathItem, 1);
+        else
+          delete copy[pathItem];
+      } else if (op === MOVE && Array.isArray(copy) && validateMove(patchOperation)) {
+        let [item] = copy.splice(patchOperation.from[level], 1);
+        copy.splice(pathItem, 0, item);
+      }
+    } else if (!prev[pathItem])
+      prev[pathItem] = [patchOperation];
+    else
+      prev[pathItem].push(patchOperation);
+    return prev;
+  }, {});
+  Object.keys(patchesGroupedByProp).forEach((key) => {
+    if (copy[key]) {
+      const patched = patch(copy[key], patchesGroupedByProp[key], level + 1);
+      if (target[key] === patched)
+        equalCount += patchesGroupedByProp[key].length;
+      else
+        copy[key] = patch(copy[key], patchesGroupedByProp[key], level + 1);
+    }
+  });
+  if (equalCount === jsonPatch.length)
+    return target;
+  else
+    return copy;
+}
+export {
+  ADD,
+  MOVE,
+  REMOVE,
+  REPLACE,
+  diff,
+  patch
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jay-framework/json-patch",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/list-compare": "workspace:^"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,126 @@
+# JSON Patch algorithm (diff, patch)
+
+JSON Patch compatible with RFC 6902 from the IETF, with support for **item movement** and **immutable** objects,
+[JSON Patch page](https://jsonpatch.com/)
+
+This JSON Patch algorithm is unique by it's support for array item movement (`move` operation).
+Most other JSON Patch algorithm, when faced with a new item in an array, will resort for `add`, `replace`
+and `remove` operations
+[See overview of other implementations](../../../design-log/23%20-%20JSON%20compare%20and%20patch.md)
+
+## The diff signature
+
+```typescript
+type MeasureOfChange = number;
+type DataFields = number;
+type ArrayContext = {
+  matchBy: string;
+};
+export type ArrayContexts = [JSONPointer, ArrayContext][];
+
+declare function diff<T>(
+  newValue: T,
+  oldValue: T,
+  contexts?: ArrayContexts,
+  path: JSONPointer = [],
+): [JSONPatch, MeasureOfChange, DataFields];
+```
+
+The `diff` function accepts two values and computes the difference between.
+
+In default mode, it only supports `add`, `replace` and `remove` operations.
+In order to support `move` a `contexts: ArrayContexts` 3rd parameter has to be provided.
+The `ArrayContexts` is an array of tuples including `JSONPointer` and `ArrayContext` which instruct the algorithm
+how to compare the array at the `JSONPointer` location. The `ArrayContext` has the name of an attribute to match object by,
+the same `id` used by `@jay-framework/list-compare`.
+
+The `path` parameter is internal for the function working recursively.
+
+The function returns a tuple of 3 values -
+
+- `JSONPatch` - the computed patch
+- `MeasureOfChange = nummber` - the number of atomic data fields that have changed
+- `DataFields = number` - the number of atomic data fields that have been compared
+
+## The patch signature
+
+```typescript
+declare function patch<T>(target: T, jsonPatch: JSONPatch, level = 0): T;
+```
+
+The function receives a `target` object and a `jsonPatch` and returns a new object only if there is actual change.
+The `level` parameter is internal for the function working recursively.
+
+On patches of type `REPLACE` the function validates the replacement value is different from the original value.
+If the replacement value is the same by the `===` operator, the operation is ignored.
+
+## Algorithm notes
+
+- This algorithm is using the `@jay-framework/list-compare` package to compute array mutations.
+- This algorithm is using the `MeasureOfChange` and `DataFields` at each level to decide if to
+  use detailed patch of sub-objects, or to just replace the whole object.
+  The threshold is `measureOfChange / dataFields > 0.5` (not configurable for now).
+
+## Example diff
+
+```typescript
+const NESTED_ARRAY_CONTEXT: ArrayContexts = [[['b'], { matchBy: 'id' }]];
+const patch = diff(
+  {
+    a: 1,
+    b: [
+      { id: 1, c: '1' },
+      { id: 2, c: '2' },
+      { id: 3, c: '3' },
+      { id: 5, c: '5' },
+      { id: 7, c: '7' },
+      { id: 6, c: '6' },
+    ],
+  },
+  {
+    a: 1,
+    b: [
+      { id: 1, c: '1' },
+      { id: 3, c: '3' },
+      { id: 4, c: '4' },
+      { id: 2, c: '2' },
+      { id: 5, c: '5' },
+      { id: 6, c: '6' },
+    ],
+  },
+  NESTED_ARRAY_CONTEXT,
+);
+
+expect(patch[0]).toEqual([
+  { op: MOVE, from: ['b', 3], path: ['b', 1] },
+  { op: REMOVE, path: ['b', 3] },
+  { op: ADD, path: ['b', 4], value: { id: 7, c: '7' } },
+]);
+```
+
+## Examples patch
+
+add example
+
+```typescript
+const obj = patch({ a: 1, b: 2, c: 3 }, [{ op: ADD, path: ['d'], value: 4 }]);
+
+expect(obj).toEqual({ a: 1, b: 2, c: 3, d: 4 });
+```
+
+move example
+
+```typescript
+const original = [
+  { id: 1, c: '1' },
+  { id: 2, c: '2' },
+  { id: 3, c: '3' },
+];
+const patched = patch(original, [{ op: MOVE, path: [1], from: [2] }]);
+
+expect(patched).toEqual([
+  { id: 1, c: '1' },
+  { id: 3, c: '3' },
+  { id: 2, c: '2' },
+]);
+```