0
# DiffPatcher Class
1

2
Object-oriented interface providing full control over diff and patch operations with customizable options and processing pipeline access.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new DiffPatcher instance with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Create DiffPatcher instance with custom options
13
 * @param options - Configuration options for diff/patch behavior
14
 */
15
class DiffPatcher {
16
  constructor(options?: Options);
17
}
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { DiffPatcher } from "jsondiffpatch";
24

25
// Default instance
26
const patcher = new DiffPatcher();
27

28
// Custom configuration
29
const customPatcher = new DiffPatcher({
30
  objectHash: (obj) => obj.id || obj.name,
31
  arrays: {
32
    detectMove: true,
33
    includeValueOnMove: false
34
  },
35
  textDiff: {
36
    minLength: 60
37
  },
38
  cloneDiffValues: true
39
});
40
```
41

42
### Diff Method
43

44
Generates a delta representing the differences between two values.
45

46
```javascript { .api }
47
/**
48
 * Generate diff between two values
49
 * @param left - Original value
50
 * @param right - Target value
51
 * @returns Delta representing changes needed to transform left into right
52
 */
53
diff(left: unknown, right: unknown): Delta;
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
const patcher = new DiffPatcher();
60

61
// Object diff
62
const objectDelta = patcher.diff(
63
  { name: "Alice", age: 25, tags: ["user"] },
64
  { name: "Alice", age: 26, tags: ["user", "admin"], active: true }
65
);
66
// Result: { age: [25, 26], tags: { _t: "a", 1: ["admin"] }, active: [true] }
67

68
// Array diff with move detection
69
const arrayDelta = patcher.diff(
70
  [{ id: 1, name: "A" }, { id: 2, name: "B" }, { id: 3, name: "C" }],
71
  [{ id: 2, name: "B" }, { id: 3, name: "C" }, { id: 1, name: "A" }]
72
);
73
```
74

75
### Patch Method
76

77
Applies a delta to a value to produce the target value.
78

79
```javascript { .api }
80
/**
81
 * Apply patch to transform a value
82
 * @param left - Original value to patch
83
 * @param delta - Delta to apply
84
 * @returns Transformed value
85
 */
86
patch(left: unknown, delta: Delta): unknown;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
const patcher = new DiffPatcher();
93

94
const original = { name: "Alice", age: 25, tags: ["user"] };
95
const delta = { age: [25, 26], tags: { _t: "a", 1: ["admin"] }, active: [true] };
96

97
const result = patcher.patch(original, delta);
98
// Result: { name: "Alice", age: 26, tags: ["user", "admin"], active: true }
99

100
// Patch preserves original by default (unless cloneDiffValues is false)
101
console.log(original); // Still { name: "Alice", age: 25, tags: ["user"] }
102
```
103

104
### Unpatch Method
105

106
Applies the reverse of a delta to revert changes.
107

108
```javascript { .api }
109
/**
110
 * Apply reverse patch to revert changes
111
 * @param right - Target value to unpatch
112
 * @param delta - Original delta to reverse
113
 * @returns Original value before patch was applied
114
 */
115
unpatch(right: unknown, delta: Delta): unknown;
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
const patcher = new DiffPatcher();
122

123
const target = { name: "Alice", age: 26, tags: ["user", "admin"], active: true };
124
const delta = { age: [25, 26], tags: { _t: "a", 1: ["admin"] }, active: [true] };
125

126
const original = patcher.unpatch(target, delta);
127
// Result: { name: "Alice", age: 25, tags: ["user"] }
128
```
129

130
### Reverse Method
131

132
Creates a reversed delta that can undo the original delta's changes.
133

134
```javascript { .api }
135
/**
136
 * Reverse a delta to create undo operation
137
 * @param delta - Delta to reverse
138
 * @returns Reversed delta
139
 */
140
reverse(delta: Delta): Delta;
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
const patcher = new DiffPatcher();
147

148
const originalDelta = { age: [25, 26], role: ["admin"] };
149
const reversedDelta = patcher.reverse(originalDelta);
150
// Result: { age: [26, 25], role: [undefined, 0, 0] }
151

152
// Use reversed delta for undo functionality
153
const target = { name: "Alice", age: 26, role: "admin" };
154
const undone = patcher.patch(target, reversedDelta);
155
// Result: { name: "Alice", age: 25 }
156
```
157

158
### Clone Method
159

160
Creates a deep clone of any value using the same cloning logic as internal operations.
161

162
```javascript { .api }
163
/**
164
 * Create deep clone of a value
165
 * @param value - Value to clone
166
 * @returns Deep cloned copy
167
 */
168
clone(value: unknown): unknown;
169
```
170

171
**Usage Examples:**
172

173
```javascript
174
const patcher = new DiffPatcher();
175

176
const original = {
177
  user: { name: "Alice", permissions: ["read", "write"] },
178
  metadata: { created: new Date(), version: 1 }
179
};
180

181
const cloned = patcher.clone(original);
182

183
// Modify clone without affecting original
184
cloned.user.name = "Bob";
185
cloned.user.permissions.push("admin");
186

187
console.log(original.user.name); // "Alice"
188
console.log(original.user.permissions); // ["read", "write"]
189
```
190

191
### Options Method
192

193
Gets or sets the DiffPatcher instance options.
194

195
```javascript { .api }
196
/**
197
 * Get or set DiffPatcher options
198
 * @param options - New options to set (optional)
199
 * @returns Current options object
200
 */
201
options(options?: Options): Options;
202
```
203

204
**Usage Examples:**
205

206
```javascript
207
const patcher = new DiffPatcher();
208

209
// Get current options
210
const currentOptions = patcher.options();
211
console.log(currentOptions.arrays?.detectMove); // true (default)
212

213
// Update options
214
patcher.options({
215
  arrays: {
216
    detectMove: false,
217
    includeValueOnMove: true
218
  },
219
  objectHash: (obj) => obj.id
220
});
221

222
// Options are merged with existing options
223
const updatedOptions = patcher.options();
224
console.log(updatedOptions.cloneDiffValues); // true (preserved from defaults)
225
```
226

227
## Advanced Usage
228

229
### Custom Object Hashing
230

231
```javascript
232
const patcher = new DiffPatcher({
233
  objectHash: (item, index) => {
234
    // Use id field for object matching
235
    if (item && typeof item === 'object' && 'id' in item) {
236
      return String(item.id);
237
    }
238
    // Use name field as fallback
239
    if (item && typeof item === 'object' && 'name' in item) {
240
      return String(item.name);
241
    }
242
    // Default to position-based matching
243
    return undefined;
244
  }
245
});
246

247
const delta = patcher.diff(
248
  [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
249
  [{ id: 2, name: "Bob" }, { id: 1, name: "Alice", role: "admin" }]
250
);
251
// Detects move and modification based on id matching
252
```
253

254
### Property Filtering
255

256
```javascript
257
const patcher = new DiffPatcher({
258
  propertyFilter: (name, context) => {
259
    // Skip private properties
260
    if (name.startsWith('_')) return false;
261
    
262
    // Skip computed properties in certain contexts
263
    if (name === 'computed' && context.left && context.left.type === 'temp') {
264
      return false;
265
    }
266
    
267
    return true;
268
  }
269
});
270

271
const delta = patcher.diff(
272
  { name: "Alice", _private: "secret", computed: "temp" },
273
  { name: "Bob", _private: "changed", computed: "updated" }
274
);
275
// Only includes changes to 'name' property
276
```
277

278
### Text Diff Integration
279

280
```javascript
281
// Using with-text-diffs module
282
import { DiffPatcher } from "jsondiffpatch/with-text-diffs";
283

284
const textPatcher = new DiffPatcher({
285
  textDiff: {
286
    minLength: 40 // Only diff strings longer than 40 characters
287
  }
288
});
289

290
const delta = textPatcher.diff(
291
  "The quick brown fox jumps over the lazy dog",
292
  "The quick brown fox jumped over the lazy cat"
293
);
294
// Creates text diff instead of simple replacement
295
```
296

297
## Properties
298

299
### Processor Access
300

301
```javascript { .api }
302
/**
303
 * Access to internal processor for advanced pipeline customization
304
 */
305
readonly processor: Processor;
306
```
307

308
The processor property provides access to the internal processing pipeline for advanced customization of diff, patch, and reverse operations through filter manipulation.