0
# Core Operations
1

2
Primary diff and patch functions for generating and applying changes between JavaScript values. These functions use a default DiffPatcher instance internally.
3

4
## Capabilities
5

6
### Diff Function
7

8
Generates a delta representing the differences between two values.
9

10
```javascript { .api }
11
/**
12
 * Generate diff between two values
13
 * @param left - Original value
14
 * @param right - Target value  
15
 * @returns Delta representing changes needed to transform left into right
16
 */
17
function diff(left: unknown, right: unknown): Delta;
18
```
19

20
**Usage Examples:**
21

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

25
// Object diff
26
const delta1 = diff(
27
  { name: "Alice", age: 25 },
28
  { name: "Alice", age: 26, role: "admin" }
29
);
30
// Result: { age: [25, 26], role: ["admin"] }
31

32
// Array diff
33
const delta2 = diff([1, 2, 3], [1, 3, 4, 5]);
34
// Result: { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] }
35

36
// Primitive diff
37
const delta3 = diff("hello", "world");
38
// Result: ["hello", "world"]
39
```
40

41
### Patch Function
42

43
Applies a delta to a value to produce the target value.
44

45
```javascript { .api }
46
/**
47
 * Apply patch to transform a value
48
 * @param left - Original value to patch
49
 * @param delta - Delta to apply
50
 * @returns Transformed value
51
 */
52
function patch(left: unknown, delta: Delta): unknown;
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
import { patch } from "jsondiffpatch";
59

60
// Apply object patch
61
const result1 = patch(
62
  { name: "Alice", age: 25 },
63
  { age: [25, 26], role: ["admin"] }
64
);
65
// Result: { name: "Alice", age: 26, role: "admin" }
66

67
// Apply array patch
68
const result2 = patch([1, 2, 3], { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] });
69
// Result: [1, 4, 5]
70

71
// Apply primitive patch
72
const result3 = patch("hello", ["hello", "world"]);
73
// Result: "world"
74
```
75

76
### Unpatch Function
77

78
Applies the reverse of a delta to revert changes.
79

80
```javascript { .api }
81
/**
82
 * Apply reverse patch to revert changes
83
 * @param right - Target value to unpatch
84
 * @param delta - Original delta to reverse
85
 * @returns Original value before patch was applied
86
 */
87
function unpatch(right: unknown, delta: Delta): unknown;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
import { unpatch } from "jsondiffpatch";
94

95
// Revert object changes
96
const original1 = unpatch(
97
  { name: "Alice", age: 26, role: "admin" },
98
  { age: [25, 26], role: ["admin"] }
99
);
100
// Result: { name: "Alice", age: 25 }
101

102
// Revert array changes
103
const original2 = unpatch([1, 4, 5], { _t: "a", 1: [2, 0, 0], 2: [3, 4], 3: [5] });
104
// Result: [1, 2, 3]
105
```
106

107
### Reverse Function
108

109
Creates a reversed delta that can undo the original delta's changes.
110

111
```javascript { .api }
112
/**
113
 * Reverse a delta to create undo operation
114
 * @param delta - Delta to reverse
115
 * @returns Reversed delta
116
 */
117
function reverse(delta: Delta): Delta;
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
import { reverse, patch } from "jsondiffpatch";
124

125
const originalDelta = { age: [25, 26], role: ["admin"] };
126
const reversedDelta = reverse(originalDelta);
127
// Result: { age: [26, 25], role: [undefined, 0, 0] }
128

129
// Use reversed delta to undo changes
130
const target = { name: "Alice", age: 26, role: "admin" };
131
const restored = patch(target, reversedDelta);
132
// Result: { name: "Alice", age: 25 }
133
```
134

135
### Clone Function
136

137
Creates a deep clone of any value.
138

139
```javascript { .api }
140
/**
141
 * Create deep clone of a value
142
 * @param value - Value to clone
143
 * @returns Deep cloned copy
144
 */
145
function clone(value: unknown): unknown;
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
import { clone } from "jsondiffpatch";
152

153
const original = { user: { name: "Alice", tags: ["admin", "user"] } };
154
const cloned = clone(original);
155

156
// Modify clone without affecting original
157
cloned.user.name = "Bob";
158
cloned.user.tags.push("editor");
159

160
console.log(original.user.name); // "Alice"
161
console.log(original.user.tags); // ["admin", "user"]
162
```
163

164
### Create Function
165

166
Creates a new DiffPatcher instance with custom options.
167

168
```javascript { .api }
169
/**
170
 * Create DiffPatcher instance with custom options
171
 * @param options - Configuration options
172
 * @returns New DiffPatcher instance
173
 */
174
function create(options?: Options): DiffPatcher;
175
```
176

177
**Usage Examples:**
178

179
```javascript
180
import { create } from "jsondiffpatch";
181

182
// Create instance with custom array handling
183
const patcher = create({
184
  arrays: {
185
    detectMove: false,
186
    includeValueOnMove: true
187
  },
188
  objectHash: (obj) => obj.id || obj.name
189
});
190

191
const delta = patcher.diff([{id: 1, name: "A"}, {id: 2, name: "B"}], 
192
                          [{id: 2, name: "B"}, {id: 1, name: "A"}]);
193

194
// Create instance for text diffing
195
const textPatcher = create({
196
  textDiff: {
197
    minLength: 60
198
  }
199
});
200
```
201

202
## With Text Diffs Module
203

204
The `/with-text-diffs` export provides the same API with automatic text diffing support:
205

206
```javascript { .api }
207
import { create, diff, patch, unpatch, reverse, clone } from "jsondiffpatch/with-text-diffs";
208

209
// All functions have identical signatures but include text diff capabilities
210
function create(options?: Omit<Options, "textDiff"> & {
211
  textDiff?: Omit<Options["textDiff"], "diffMatchPatch">;
212
}): DiffPatcher;
213
```
214

215
**Usage Examples:**
216

217
```javascript
218
import { diff } from "jsondiffpatch/with-text-diffs";
219

220
// Automatically detects and creates text diffs for long strings
221
const textDelta = diff(
222
  "The quick brown fox jumps over the lazy dog.",
223
  "The quick brown fox jumped over the lazy cat."
224
);
225
// Result: [textDiffString, 0, 2] where textDiffString contains diff-match-patch format
226
```
227

228
## Error Handling
229

230
All core operations are designed to be safe with various input types:
231
- `undefined` or `null` values are handled gracefully
232
- Circular references in objects are handled during cloning
233
- Invalid deltas will not throw but may produce unexpected results
234
- Type mismatches between delta and target value are handled safely