0
# Line Comparison
1
2
Line-by-line comparison for arrays of strings with multiple output formats including unified diff, raw operations, and dual display/comparison modes.
3
4
## Capabilities
5
6
### Unified Line Diff
7
8
Compares arrays of strings line-by-line and returns formatted unified diff output.
9
10
```typescript { .api }
11
/**
12
* Compare two arrays of strings line-by-line and format as comparison lines
13
* @param aLines - First array of strings to compare
14
* @param bLines - Second array of strings to compare
15
* @param options - Optional formatting configuration
16
* @returns Formatted unified diff string
17
*/
18
function diffLinesUnified(
19
aLines: Array<string>,
20
bLines: Array<string>,
21
options?: DiffOptions
22
): string;
23
```
24
25
**Features:**
26
- **Empty String Handling**: Properly handles arrays with single empty strings
27
- **Control Character Escaping**: Automatically escapes control characters for visibility
28
- **Context Lines**: Shows configurable number of unchanged lines around changes
29
- **Annotation Headers**: Includes Expected/Received headers with optional change counts
30
31
**Usage Examples:**
32
33
```typescript
34
import { diffLinesUnified } from "jest-diff";
35
36
// Basic line comparison
37
const lines1 = ["line 1", "line 2", "line 3"];
38
const lines2 = ["line 1", "modified line 2", "line 3", "new line 4"];
39
const result = diffLinesUnified(lines1, lines2);
40
console.log(result);
41
42
// With custom options
43
const result2 = diffLinesUnified(lines1, lines2, {
44
contextLines: 1,
45
includeChangeCounts: true,
46
aAnnotation: "Original",
47
bAnnotation: "Modified"
48
});
49
console.log(result2);
50
51
// Empty arrays
52
const result3 = diffLinesUnified([], ["new line"]);
53
console.log(result3);
54
```
55
56
### Dual Mode Line Diff
57
58
Compares using separate arrays for display and comparison, allowing different content for visual output vs comparison logic.
59
60
```typescript { .api }
61
/**
62
* Compare two pairs of arrays: one pair for comparison logic, another for display
63
* @param aLinesDisplay - Lines to display for first value
64
* @param bLinesDisplay - Lines to display for second value
65
* @param aLinesCompare - Lines to use for comparison logic for first value
66
* @param bLinesCompare - Lines to use for comparison logic for second value
67
* @param options - Optional formatting configuration
68
* @returns Formatted unified diff string using display lines
69
*/
70
function diffLinesUnified2(
71
aLinesDisplay: Array<string>,
72
bLinesDisplay: Array<string>,
73
aLinesCompare: Array<string>,
74
bLinesCompare: Array<string>,
75
options?: DiffOptions
76
): string;
77
```
78
79
**Use Cases:**
80
- **Pretty Formatting**: Compare simplified versions but display formatted versions
81
- **Normalized Comparison**: Compare normalized data while showing original formatting
82
- **Fallback Behavior**: Falls back to standard diffLinesUnified if array lengths don't match
83
84
**Usage Examples:**
85
86
```typescript
87
import { diffLinesUnified2 } from "jest-diff";
88
89
// Different display vs comparison content
90
const displayA = [" formatted line 1 ", " formatted line 2 "];
91
const displayB = [" formatted line 1 ", " NEW formatted line 2 "];
92
const compareA = ["formatted line 1", "formatted line 2"];
93
const compareB = ["formatted line 1", "NEW formatted line 2"];
94
95
const result = diffLinesUnified2(displayA, displayB, compareA, compareB);
96
console.log(result);
97
```
98
99
### Raw Line Diff
100
101
Compares arrays of strings line-by-line and returns raw diff operations array.
102
103
```typescript { .api }
104
/**
105
* Compare two arrays of strings line-by-line and return raw diff operations
106
* @param aLines - First array of strings to compare
107
* @param bLines - Second array of strings to compare
108
* @returns Array of Diff objects representing line-level operations
109
*/
110
function diffLinesRaw(
111
aLines: Array<string>,
112
bLines: Array<string>
113
): Array<Diff>;
114
```
115
116
**Algorithm:**
117
- **Longest Common Subsequence**: Uses efficient diff-sequences algorithm to find optimal diff
118
- **Line-level Operations**: Each Diff represents insertion, deletion, or equality of entire lines
119
- **Sequential Processing**: Processes lines in order with optimal performance
120
121
**Usage Examples:**
122
123
```typescript
124
import { diffLinesRaw, DIFF_DELETE, DIFF_INSERT, DIFF_EQUAL } from "jest-diff";
125
126
const lines1 = ["keep", "delete", "keep"];
127
const lines2 = ["keep", "insert", "keep"];
128
const diffs = diffLinesRaw(lines1, lines2);
129
130
diffs.forEach(diff => {
131
const [op, line] = [diff[0], diff[1]];
132
switch (op) {
133
case DIFF_DELETE:
134
console.log(`- ${line}`);
135
break;
136
case DIFF_INSERT:
137
console.log(`+ ${line}`);
138
break;
139
case DIFF_EQUAL:
140
console.log(` ${line}`);
141
break;
142
}
143
});
144
```
145
146
## Formatting Options
147
148
```typescript { .api }
149
interface DiffOptions {
150
// Annotation customization
151
aAnnotation?: string; // Default: "Expected"
152
bAnnotation?: string; // Default: "Received"
153
omitAnnotationLines?: boolean; // Default: false
154
155
// Visual indicators
156
aIndicator?: string; // Default: "-"
157
bIndicator?: string; // Default: "+"
158
commonIndicator?: string; // Default: " "
159
160
// Color functions
161
aColor?: DiffOptionsColor; // Default: chalk.green
162
bColor?: DiffOptionsColor; // Default: chalk.red
163
commonColor?: DiffOptionsColor; // Default: chalk.dim
164
changeColor?: DiffOptionsColor; // Default: chalk.inverse
165
patchColor?: DiffOptionsColor; // Default: chalk.yellow
166
167
// Context and expansion
168
contextLines?: number; // Default: 5
169
expand?: boolean; // Default: true
170
171
// Additional features
172
includeChangeCounts?: boolean; // Default: false
173
emptyFirstOrLastLinePlaceholder?: string; // Default: ""
174
}
175
176
type DiffOptionsColor = (arg: string) => string;
177
```