0
# jest-diff
1

2
Jest-diff is a comprehensive TypeScript library for displaying differences between values with multiple comparison methods. It provides functions for comparing strings character-by-character, arrays line-by-line, and JavaScript objects with serialization. The library offers colorized output using chalk for easy change visualization and supports configurable formatting options.
3

4
## Package Information
5

6
- **Package Name**: jest-diff
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install jest-diff`
10

11
## Core Imports
12

13
```typescript
14
import { diff, diffStringsUnified, diffLinesUnified, DiffOptions } from "jest-diff";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { diff, diffStringsUnified, diffLinesUnified } = require("jest-diff");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { diff, diffStringsUnified, diffLinesUnified } from "jest-diff";
27

28
// Compare any two JavaScript values
29
const a = ['delete', 'common', 'changed from'];
30
const b = ['common', 'changed to', 'insert'];
31
const result = diff(a, b);
32
console.log(result);
33

34
// Compare strings character-by-character
35
const stringDiff = diffStringsUnified('Hello world', 'Hello Jest');
36
console.log(stringDiff);
37

38
// Compare arrays of strings line-by-line
39
const lines1 = ['line 1', 'line 2', 'line 3'];
40
const lines2 = ['line 1', 'modified line 2', 'line 3'];
41
const lineDiff = diffLinesUnified(lines1, lines2);
42
console.log(lineDiff);
43
```
44

45
## Architecture
46

47
Jest-diff is built around several key components:
48

49
- **Main diff function**: Handles any JavaScript values by detecting types and routing to appropriate comparison methods
50
- **String comparison**: Character-by-character diffing with semantic cleanup for readable output
51
- **Line comparison**: Line-by-line diffing for arrays of strings with unified diff formatting
52
- **Pretty formatting**: Integration with pretty-format for consistent object serialization
53
- **Colorization system**: Configurable chalk-based coloring for clear visual distinction
54
- **Options normalization**: Comprehensive default handling and validation for formatting options
55

56
## Capabilities
57

58
### Value Comparison
59

60
Main comparison function that handles any JavaScript values including primitives, objects, arrays, Maps, and Sets.
61

62
```typescript { .api }
63
function diff(a: any, b: any, options?: DiffOptions): string | null;
64
```
65

66
[Value Comparison](./value-comparison.md)
67

68
### String Comparison
69

70
Character-by-character string comparison with unified diff output and semantic cleanup.
71

72
```typescript { .api }
73
function diffStringsUnified(a: string, b: string, options?: DiffOptions): string;
74
function diffStringsRaw(a: string, b: string, cleanup: boolean): Array<Diff>;
75
```
76

77
[String Comparison](./string-comparison.md)
78

79
### Line Comparison
80

81
Line-by-line comparison for arrays of strings with multiple output formats.
82

83
```typescript { .api }
84
function diffLinesUnified(
85
  aLines: Array<string>, 
86
  bLines: Array<string>, 
87
  options?: DiffOptions
88
): string;
89

90
function diffLinesUnified2(
91
  aLinesDisplay: Array<string>,
92
  bLinesDisplay: Array<string>, 
93
  aLinesCompare: Array<string>,
94
  bLinesCompare: Array<string>,
95
  options?: DiffOptions
96
): string;
97

98
function diffLinesRaw(
99
  aLines: Array<string>, 
100
  bLines: Array<string>
101
): Array<Diff>;
102
```
103

104
[Line Comparison](./line-comparison.md)
105

106
## Configuration
107

108
```typescript { .api }
109
interface DiffOptions {
110
  aAnnotation?: string;
111
  aColor?: DiffOptionsColor;
112
  aIndicator?: string;
113
  bAnnotation?: string;
114
  bColor?: DiffOptionsColor;
115
  bIndicator?: string;
116
  changeColor?: DiffOptionsColor;
117
  changeLineTrailingSpaceColor?: DiffOptionsColor;
118
  commonColor?: DiffOptionsColor;
119
  commonIndicator?: string;
120
  commonLineTrailingSpaceColor?: DiffOptionsColor;
121
  contextLines?: number;
122
  emptyFirstOrLastLinePlaceholder?: string;
123
  expand?: boolean;
124
  includeChangeCounts?: boolean;
125
  omitAnnotationLines?: boolean;
126
  patchColor?: DiffOptionsColor;
127
  compareKeys?: CompareKeys;
128
}
129

130
type DiffOptionsColor = (arg: string) => string;
131

132
// From pretty-format package
133
type CompareKeys = ((a: string, b: string) => number) | undefined;
134
```
135

136
## Data Structures
137

138
```typescript { .api }
139
class Diff {
140
  0: number; // Operation type: DIFF_DELETE (-1), DIFF_INSERT (1), or DIFF_EQUAL (0)
141
  1: string; // Text content
142
  constructor(op: number, text: string);
143
}
144

145
const DIFF_DELETE = -1;
146
const DIFF_INSERT = 1; 
147
const DIFF_EQUAL = 0;
148
```