feat: rename comparator back to objectHash and add example to readme

Author: marcolink

.github/workflows/test.yml

@@ -1,7 +1,7 @@
 # This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
 
-name: Node.js CI
+name: CI Tests
 
 on:
   push:

README.md

@@ -1,30 +1,68 @@
 # generate-json-patch
 
-
-Creates [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/) compliant JSON Patch objects based on two given JSON objects. 
+Create [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/) compliant JSON Patch objects based on two given [JSON](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/) objects with a configurable interface. 
 
 [![Version](https://img.shields.io/npm/v/generate-json-patch.svg)](https://npmjs.org/package/generate-json-patch)
 [![Downloads/week](https://img.shields.io/npm/dw/generate-json-patch.svg)](https://npmjs.org/package/generate-json-patch)
+[![Tests](https://github.com/marcolink/generate-json-patch/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com/marcolink/generate-json-patch/actions/workflows/test.yml)
 [![License](https://img.shields.io/npm/l/generate-json-patch.svg)](https://github.com/marcoxlink/generate-json-patch/blob/main/package.json)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 
+# TL;DR
+- Can diff any two [JSON](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/)  compliant objects - returns differences as [JSON Patch](http://jsonpatch.com/).
+- Elegant array diffing by providing an `objectHash` to match array elements
+- Ignore specific keys by providing a `propertyFilter`
+- `move` operations are ALWAYS **appended at the end**, therefore, they can be ignored (if wanted) when the patch gets applied.
+- :paw_prints: ***Is it small?*** Zero dependencies - it's ~**7 KB** (uncompressed).
+- :crystal_ball: ***Is it fast?*** I haven't done any performance comparison yet.
+- :hatched_chick: ***Is it stable?*** Test coverage is high, but it's still in its early days - bugs are expected.
+- The interface is inspired by [jsondiffpatch](https://github.com/benjamine/jsondiffpatch)
+- **100%** Typescript
 
 # Installation 
+Works on node and browser environments. 
 ```bash
 npm install generate-json-patch
 ```
 
 # Usage
 
 ```typescript
-import {generateJSONPatch} from 'generate-json-patch';
+import { generateJSONPatch } from 'generate-json-patch';
 
 const before = { name: "Berta", manufacturer: "Ford", type: "Granada", year: 1972 };
 const after = { name: "Berta", manufacturer: "Ford", type: "Granada", year: 1974 };
 
-const patch = generateJSONPatch(before, after):
+const patch = generateJSONPatch(before, after);
 
 console.log(patch) // => [{op: 'replace', path: '/year', value: 1974}]
 ```
-                           
 
-> This project is inspired by https://github.com/benjamine/jsondiffpatch
+## Configuration
+
+```typescript
+import { generateJSONPatch, JsonPatchConfig, JSONValue } from 'generate-json-patch';
+
+generateJSONPatch({/*...*/}, {/*...*/}, {
+    // called when comparing array elements
+    objectHash: function(value: JSONValue, context: JsonPatchConfig) {
+        return value.name
+    },
+    // called for every property on objects. Can be used to ignore sensitive or irrelevant 
+    // properties when comparing data.
+    propertyFilter: function (propertyName: string, context: JsonPatchConfig) {
+        return !['sensitiveProperty'].includes(propertyName);
+    },
+    array: {
+        // When true, no move operations will be created. 
+        // The rersulting patch will not lead to identical objects, 
+        // as postions of array elements can be different!
+        ignoreMove: true
+    }
+});
+``` 
+
+
+> For more examples, check out the [tests](./src/index.spec.ts)
+
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "generate-json-patch",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "author": "Marco Link <[email protected]>",
   "private": false,
   "repository": "marcolink/generate-json-patch",
@@ -23,7 +23,10 @@
   "keywords": [
     "json",
     "diff",
-    "patch"
+    "patch",
+    "compare",
+    "generate",
+    "create"
   ],
   "scripts": {
     "build": "tsup src/index.ts",

src/index.spec.ts

@@ -127,7 +127,7 @@ describe('a generate json patch function', () => {
     })
 
     describe('with an array comparator', () => {
-        it("throws when comparator is not a function", () => {
+        it("throws when objectHash is not a function", () => {
             const before = [
                 {id: 1, paramOne: "before"},
             ]
@@ -137,7 +137,7 @@ describe('a generate json patch function', () => {
 
             assert.throws(() => generateJSONPatch(before, after, {
                 // @ts-ignore
-                comparator: 'not-a-function'
+                objectHash: 'not-a-function'
             }))
 
         })
@@ -154,7 +154,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any) {
+                objectHash: function (obj: any) {
                     return `${obj.id}`;
                 }
             })
@@ -167,7 +167,7 @@ describe('a generate json patch function', () => {
             ]);
         })
 
-        it("handles changes with custom comparator based on direction param", () => {
+        it("handles changes with custom objectHash based on direction param", () => {
             const before = [
                 {
                     id: 1, value: 'before'
@@ -186,7 +186,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any, context) {
+                objectHash: function (obj: any, context) {
                     if (obj.id === 1 && context.side === 'right') {
                         return '4'
                     }
@@ -249,7 +249,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any) {
+                objectHash: function (obj: any) {
                     return `${obj.id}`;
                 },
             })
@@ -281,7 +281,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any) {
+                objectHash: function (obj: any) {
                     return `${obj.id}`;
                 },
             })
@@ -316,7 +316,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any) {
+                objectHash: function (obj: any) {
                     return `${obj.id}`;
                 },
             })
@@ -351,7 +351,7 @@ describe('a generate json patch function', () => {
             ]
 
             const patch = generateJSONPatch(before, after, {
-                comparator: function (obj: any) {
+                objectHash: function (obj: any) {
                     return `${obj.id}`;
                 },
                 array:{ignoreMove: true}