0
# Value Comparison
1

2
The main diff function handles any JavaScript values by detecting types and routing to appropriate comparison methods. It provides automatic serialization, type checking, and colorized output.
3

4
## Capabilities
5

6
### Main Diff Function
7

8
Compares any two JavaScript values and returns formatted diff string with automatic type detection and routing.
9

10
```typescript { .api }
11
/**
12
 * Generate a string that will highlight the difference between two values
13
 * with green and red coloring (similar to how GitHub does code diffing)
14
 * @param a - First value to compare (any type)
15
 * @param b - Second value to compare (any type)  
16
 * @param options - Optional formatting configuration
17
 * @returns Formatted diff string or null if no meaningful diff
18
 */
19
function diff(a: any, b: any, options?: DiffOptions): string | null;
20
```
21

22
**Behavior by Type:**
23
- **Identical values**: Returns "Compared values have no visual difference." message
24
- **Different types**: Returns type mismatch message with expected vs received types
25
- **Strings**: Uses line-by-line comparison with escaped control characters
26
- **Primitives** (boolean, number): Uses pretty-format with line comparison
27
- **Maps**: Converts to sorted object format for comparison  
28
- **Sets**: Converts to sorted array format for comparison
29
- **Objects**: Uses pretty-format serialization with fallback handling
30

31
**Usage Examples:**
32

33
```typescript
34
import { diff } from "jest-diff";
35

36
// Object comparison
37
const user1 = { name: "Alice", age: 25, active: true };
38
const user2 = { name: "Alice", age: 26, active: false };
39
console.log(diff(user1, user2));
40

41
// Array comparison  
42
const arr1 = [1, 2, 3];
43
const arr2 = [1, 3, 4];
44
console.log(diff(arr1, arr2));
45

46
// Primitive comparison
47
console.log(diff(42, 43));
48
console.log(diff(true, false));
49

50
// Type mismatch
51
console.log(diff("string", 123));
52
// Output: "Comparing two different types of values. Expected string but received number."
53

54
// No difference
55
console.log(diff("same", "same"));
56
// Output: "Compared values have no visual difference."
57
```
58

59
**Special Handling:**
60

61
- **Asymmetric Matchers**: Supports Jest asymmetric matchers with proper type detection
62
- **Control Characters**: Automatically escapes control characters in strings for visibility
63
- **Serialization Fallback**: Uses fallback formatting without toJSON when primary serialization fails
64
- **Map/Set Sorting**: Automatically sorts Maps and Sets for consistent comparison