refactor: rename class and add readme section

deblockt · deblockt · commit 1c6565b8ba40 · 2026-01-06T19:05:53.000+01:00
diff --git a/README.md b/README.md
@@ -165,6 +165,7 @@ final var mixedMatcher = new CompositeJsonMatcher(
 | Matcher | Description |
 |---------|-------------|
 | `NullEqualsEmptyArrayMatcher` | Treats `null` and `[]` as equivalent |
+| `IgnoredPathMatcher` | Ignores specified fields during comparison |
 
 ## Treating Null as Empty Array
 
@@ -196,6 +197,64 @@ System.out.println(diff.similarityRate()); // 100.0
 - This matcher only handles `null` vs empty array `[]`, not missing properties
 - Non-empty arrays do not match `null`
 
+## Ignoring path
+
+The `IgnoredPathMatcher` allows you to ignore specific fields during comparison. This is useful for fields like timestamps, IDs, or other dynamic values that you don't want to compare.
+
+```java
+final var jsonMatcher = new CompositeJsonMatcher(
+    new IgnoredPathMatcher("timestamp", "id"),  // Must be first
+    new LenientJsonArrayPartialMatcher(),
+    new LenientJsonObjectPartialMatcher(),
+    new StrictPrimitivePartialMatcher()
+);
+
+// These will match with 100% similarity:
+final var diff = DiffGenerator.diff(
+    "{\"name\": \"John\", \"timestamp\": \"2024-01-01\"}",
+    "{\"name\": \"John\", \"timestamp\": \"2024-12-31\"}",
+    jsonMatcher
+);
+
+System.out.println(diff.similarityRate()); // 100.0
+```
+
+### Path Patterns
+
+The `IgnoredPathMatcher` supports various path patterns:
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `name` | Matches field `name` at any level | Ignores `$.name`, `$.user.name`, `$.data.user.name` |
+| `user.name` | Matches `name` under `user` | Ignores `$.user.name`, `$.data.user.name` |
+| `*.name` | Wildcard for any property | Ignores `$.foo.name`, `$.bar.name` |
+| `items[0]` | Matches specific array index | Ignores `$.items[0]` |
+| `items[*]` | Wildcard for any array index | Ignores `$.items[0]`, `$.items[1]`, etc. |
+| `items[*].id` | Field in any array element | Ignores `$.items[0].id`, `$.items[5].id` |
+
+### Examples
+
+```java
+// Ignore a single field everywhere
+new IgnoredPathMatcher("createdAt")
+
+// Ignore multiple fields
+new IgnoredPathMatcher("createdAt", "updatedAt", "id")
+
+// Ignore nested field
+new IgnoredPathMatcher("metadata.timestamp")
+
+// Ignore field in all array elements
+new IgnoredPathMatcher("users[*].password")
+
+// Combine multiple patterns
+new IgnoredPathMatcher("id", "*.createdAt", "items[*].internalId")
+```
+
+**Important:**
+- Place `IgnoredPathMatcher` **before** other matchers in the constructor
+- Patterns match against the end of the path, so `name` matches `$.user.name` as well as `$.name`
+
 ## Advanced Example
 
 ```java
diff --git a/src/main/java/com/deblock/jsondiff/matcher/IgnoredPathMatcher.java b/src/main/java/com/deblock/jsondiff/matcher/IgnoredPathMatcher.java
@@ -7,16 +7,16 @@
 import java.util.Arrays;
 import java.util.List;
 
-public class IgnoringFieldMatcher implements PartialJsonMatcher {
-    private final List<PathMatcher> fieldsToIgnore;
+public class IgnoredPathMatcher implements PartialJsonMatcher {
+    private final List<PathMatcher> pathsToIgnore;
 
-    public IgnoringFieldMatcher(List<String> paths) {
-        this.fieldsToIgnore = paths.stream()
+    public IgnoredPathMatcher(List<String> paths) {
+        this.pathsToIgnore = paths.stream()
                 .map(PathMatcher::from)
                 .toList();
     }
 
-    public IgnoringFieldMatcher(String ...paths) {
+    public IgnoredPathMatcher(String ...paths) {
         this(Arrays.stream(paths).toList());
     }
 
@@ -27,6 +27,6 @@ public JsonDiff jsonDiff(Path path, JsonNode expectedJson, JsonNode receivedJson
 
     @Override
     public boolean manage(Path path, JsonNode expected, JsonNode received) {
-        return fieldsToIgnore.stream().anyMatch(pattern -> pattern.match(path));
+        return pathsToIgnore.stream().anyMatch(pattern -> pattern.match(path));
     }
 }
diff --git a/src/test/java/com/deblock/jsondiff/integration/IgnoredPathIntegrationTest.java b/src/test/java/com/deblock/jsondiff/integration/IgnoredPathIntegrationTest.java
@@ -6,10 +6,10 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-public class IgnoringFieldsIntegrationTest {
+public class IgnoredPathIntegrationTest {
 
     private final CompositeJsonMatcher jsonMatcher = new CompositeJsonMatcher(
-            new IgnoringFieldMatcher("foo"),
+            new IgnoredPathMatcher("foo"),
             new LenientJsonArrayPartialMatcher(),
             new LenientJsonObjectPartialMatcher(),
             new StrictPrimitivePartialMatcher()
diff --git a/src/test/java/com/deblock/jsondiff/matcher/IgnoredPathMatcherTest.java b/src/test/java/com/deblock/jsondiff/matcher/IgnoredPathMatcherTest.java
@@ -10,22 +10,22 @@
 
 import static org.junit.jupiter.api.Assertions.*;
 
-class IgnoringFieldMatcherTest {
+class IgnoredPathMatcherTest {
 
     @Nested
     class ManageMethod {
 
         @Test
         void shouldMatchExactPath() {
-            var matcher = new IgnoringFieldMatcher("name");
+            var matcher = new IgnoredPathMatcher("name");
             var path = Path.ROOT.add(Path.PathItem.of("name"));
 
             assertTrue(matcher.manage(path, null, null));
         }
 
         @Test
         void shouldMatchEndOfPath() {
-            var matcher = new IgnoringFieldMatcher("name");
+            var matcher = new IgnoredPathMatcher("name");
             var path = Path.ROOT
                     .add(Path.PathItem.of("user"))
                     .add(Path.PathItem.of("name"));
@@ -35,15 +35,15 @@ void shouldMatchEndOfPath() {
 
         @Test
         void shouldNotMatchDifferentPath() {
-            var matcher = new IgnoringFieldMatcher("name");
+            var matcher = new IgnoredPathMatcher("name");
             var path = Path.ROOT.add(Path.PathItem.of("age"));
 
             assertFalse(matcher.manage(path, null, null));
         }
 
         @Test
         void shouldMatchNestedPath() {
-            var matcher = new IgnoringFieldMatcher("user.name");
+            var matcher = new IgnoredPathMatcher("user.name");
             var path = Path.ROOT
                     .add(Path.PathItem.of("data"))
                     .add(Path.PathItem.of("user"))
@@ -54,7 +54,7 @@ void shouldMatchNestedPath() {
 
         @Test
         void shouldNotMatchPartialNestedPath() {
-            var matcher = new IgnoringFieldMatcher("user.name");
+            var matcher = new IgnoredPathMatcher("user.name");
             var path = Path.ROOT
                     .add(Path.PathItem.of("name"));
 
@@ -63,7 +63,7 @@ void shouldNotMatchPartialNestedPath() {
 
         @Test
         void shouldMatchWithWildcardProperty() {
-            var matcher = new IgnoringFieldMatcher("*.name");
+            var matcher = new IgnoredPathMatcher("*.name");
             var path = Path.ROOT
                     .add(Path.PathItem.of("user"))
                     .add(Path.PathItem.of("name"));
@@ -73,7 +73,7 @@ void shouldMatchWithWildcardProperty() {
 
         @Test
         void shouldMatchArrayIndex() {
-            var matcher = new IgnoringFieldMatcher("items[0]");
+            var matcher = new IgnoredPathMatcher("items[0]");
             var path = Path.ROOT
                     .add(Path.PathItem.of("items"))
                     .add(Path.PathItem.of(0));
@@ -83,7 +83,7 @@ void shouldMatchArrayIndex() {
 
         @Test
         void shouldMatchArrayWildcard() {
-            var matcher = new IgnoringFieldMatcher("items[*].id");
+            var matcher = new IgnoredPathMatcher("items[*].id");
             var path = Path.ROOT
                     .add(Path.PathItem.of("items"))
                     .add(Path.PathItem.of(5))
@@ -94,7 +94,7 @@ void shouldMatchArrayWildcard() {
 
         @Test
         void shouldMatchAnyOfMultiplePatterns() {
-            var matcher = new IgnoringFieldMatcher("name", "age", "email");
+            var matcher = new IgnoredPathMatcher("name", "age", "email");
             var pathName = Path.ROOT.add(Path.PathItem.of("name"));
             var pathAge = Path.ROOT.add(Path.PathItem.of("age"));
             var pathEmail = Path.ROOT.add(Path.PathItem.of("email"));
@@ -108,7 +108,7 @@ void shouldMatchAnyOfMultiplePatterns() {
 
         @Test
         void shouldWorkWithListConstructor() {
-            var matcher = new IgnoringFieldMatcher(List.of("name", "age"));
+            var matcher = new IgnoredPathMatcher(List.of("name", "age"));
             var pathName = Path.ROOT.add(Path.PathItem.of("name"));
             var pathAge = Path.ROOT.add(Path.PathItem.of("age"));
 
@@ -118,7 +118,7 @@ void shouldWorkWithListConstructor() {
 
         @Test
         void shouldNotMatchRootPath() {
-            var matcher = new IgnoringFieldMatcher("name");
+            var matcher = new IgnoredPathMatcher("name");
 
             assertFalse(matcher.manage(Path.ROOT, null, null));
         }
@@ -129,7 +129,7 @@ class JsonDiffMethod {
 
         @Test
         void shouldReturnMatchedDiffWithFullSimilarity() {
-            var matcher = new IgnoringFieldMatcher("name");
+            var matcher = new IgnoredPathMatcher("name");
             var path = Path.ROOT.add(Path.PathItem.of("name"));
             var expected = StringNode.valueOf("John");
             var received = StringNode.valueOf("Jane");
@@ -142,7 +142,7 @@ void shouldReturnMatchedDiffWithFullSimilarity() {
 
         @Test
         void shouldReturnMatchedDiffEvenWithDifferentTypes() {
-            var matcher = new IgnoringFieldMatcher("value");
+            var matcher = new IgnoredPathMatcher("value");
             var path = Path.ROOT.add(Path.PathItem.of("value"));
             var expected = StringNode.valueOf("100");
             var received = IntNode.valueOf(100);
@@ -154,7 +154,7 @@ void shouldReturnMatchedDiffEvenWithDifferentTypes() {
 
         @Test
         void shouldReturnMatchedDiffForNestedPath() {
-            var matcher = new IgnoringFieldMatcher("user.timestamp");
+            var matcher = new IgnoredPathMatcher("user.timestamp");
             var path = Path.ROOT
                     .add(Path.PathItem.of("user"))
                     .add(Path.PathItem.of("timestamp"));

Original file line number	Diff line number	Diff line change
`@@ -7,16 +7,16 @@`
`7`	`7`	`import java.util.Arrays;`
`8`	`8`	`import java.util.List;`
`9`	`9`
`10`		`-public class IgnoringFieldMatcher implements PartialJsonMatcher {`
`11`		`- private final List<PathMatcher> fieldsToIgnore;`
	`10`	`+public class IgnoredPathMatcher implements PartialJsonMatcher {`
	`11`	`+ private final List<PathMatcher> pathsToIgnore;`
`12`	`12`
`13`		`- public IgnoringFieldMatcher(List<String> paths) {`
`14`		`- this.fieldsToIgnore = paths.stream()`
	`13`	`+ public IgnoredPathMatcher(List<String> paths) {`
	`14`	`+ this.pathsToIgnore = paths.stream()`
`15`	`15`	`.map(PathMatcher::from)`
`16`	`16`	`.toList();`
`17`	`17`	`}`
`18`	`18`
`19`		`- public IgnoringFieldMatcher(String ...paths) {`
	`19`	`+ public IgnoredPathMatcher(String ...paths) {`
`20`	`20`	`this(Arrays.stream(paths).toList());`
`21`	`21`	`}`
`22`	`22`
`@@ -27,6 +27,6 @@ public JsonDiff jsonDiff(Path path, JsonNode expectedJson, JsonNode receivedJson`
`27`	`27`
`28`	`28`	`@Override`
`29`	`29`	`public boolean manage(Path path, JsonNode expected, JsonNode received) {`
`30`		`- return fieldsToIgnore.stream().anyMatch(pattern -> pattern.match(path));`
	`30`	`+ return pathsToIgnore.stream().anyMatch(pattern -> pattern.match(path));`
`31`	`31`	`}`
`32`	`32`	`}`