0
# Value Formatting
1

2
Core functions for converting objects to formatted string representations with proper styling and whitespace handling for test output.
3

4
## Capabilities
5

6
### Stringify Function
7

8
Converts objects to string representation with formatting control for maximum readability in test output.
9

10
```typescript { .api }
11
/**
12
 * Convert objects to string representation with formatting
13
 * @param object - Object to stringify
14
 * @param maxDepth - Maximum recursion depth (default: 10)
15
 * @param maxWidth - Maximum width for formatting (default: 10)
16
 * @returns Formatted string representation
17
 */
18
function stringify(
19
  object: unknown,
20
  maxDepth?: number,
21
  maxWidth?: number
22
): string;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { stringify } from "jest-matcher-utils";
29

30
// Basic object stringification
31
const user = { name: "Alice", age: 25, active: true };
32
const result = stringify(user);
33
// Result: '{"name": "Alice", "age": 25, "active": true}'
34

35
// Control depth and width
36
const nested = { a: { b: { c: { d: "deep" } } } };
37
const shallow = stringify(nested, 2);
38
// Limits recursion depth to prevent overly verbose output
39

40
// Large objects are automatically truncated
41
const large = { data: new Array(1000).fill("item") };
42
const compact = stringify(large, 10, 5);
43
// Automatically reduces depth/width to stay under length limits
44
```
45

46
### Print Received
47

48
Formats received (actual) values with red color styling and trailing whitespace indicators.
49

50
```typescript { .api }
51
/**
52
 * Format received values with red color and whitespace indicators
53
 * @param object - Value to format as received
54
 * @returns Red-colored string with whitespace indicators
55
 */
56
function printReceived(object: unknown): string;
57
```
58

59
**Usage Examples:**
60

61
```typescript
62
import { printReceived } from "jest-matcher-utils";
63

64
// Format actual values for error messages
65
const actual = { name: "Bob", age: 30 };
66
const formatted = printReceived(actual);
67
// Result: Red-colored '{"name": "Bob", "age": 30}' 
68

69
// Handles whitespace visualization
70
const withSpaces = "hello world   ";
71
const spaced = printReceived(withSpaces);
72
// Result: Red-colored 'hello world···' (shows trailing spaces)
73
```
74

75
### Print Expected
76

77
Formats expected values with green color styling and trailing whitespace indicators.
78

79
```typescript { .api }
80
/**
81
 * Format expected values with green color and whitespace indicators
82
 * @param value - Value to format as expected
83
 * @returns Green-colored string with whitespace indicators
84
 */
85
function printExpected(value: unknown): string;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { printExpected } from "jest-matcher-utils";
92

93
// Format expected values for error messages
94
const expected = { name: "Alice", age: 25 };
95
const formatted = printExpected(expected);
96
// Result: Green-colored '{"name": "Alice", "age": 25}'
97

98
// Works with all data types
99
const expectedNumber = printExpected(42);
100
const expectedString = printExpected("hello");
101
const expectedArray = printExpected([1, 2, 3]);
102
```
103

104
### Highlight Trailing Whitespace
105

106
Highlights trailing whitespace in text using inverse color formatting.
107

108
```typescript { .api }
109
/**
110
 * Highlight trailing whitespace in text with inverse colors
111
 * @param text - Input text to process
112
 * @returns Text with highlighted trailing whitespace
113
 */
114
function highlightTrailingWhitespace(text: string): string;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import { highlightTrailingWhitespace } from "jest-matcher-utils";
121

122
// Highlight invisible trailing spaces
123
const text = "Line 1   \nLine 2  \nLine 3";
124
const highlighted = highlightTrailingWhitespace(text);
125
// Result: 'Line 1[INVERSE]   [/INVERSE]\nLine 2[INVERSE]  [/INVERSE]\nLine 3'
126

127
// Useful for debugging string comparison issues
128
const userInput = "username ";
129
const processed = highlightTrailingWhitespace(userInput);
130
// Makes trailing space visible in test output
131
```
132

133
### Print With Type
134

135
Prints a value along with its type information for debugging complex type issues.
136

137
```typescript { .api }
138
/**
139
 * Print value with its type information
140
 * @param name - Name/label for the value
141
 * @param value - Value to print
142
 * @param print - Function to format the value
143
 * @returns Formatted output with type info
144
 */
145
function printWithType<T>(
146
  name: string,
147
  value: T,
148
  print: (value: T) => string
149
): string;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import { printWithType, printReceived } from "jest-matcher-utils";
156

157
// Show value with type for debugging
158
const mysterious = Symbol.for("test");
159
const result = printWithType("Received", mysterious, printReceived);
160
// Result: 'Received has type:  symbol\nReceived has value: Symbol(test)'
161

162
// Helpful for null/undefined debugging
163
const empty = null;
164
const nullResult = printWithType("Expected", empty, printReceived);
165
// Result: 'Expected has value: null'
166

167
// Works with any formatter function
168
const obj = { x: 1 };
169
const objResult = printWithType("Data", obj, (val) => JSON.stringify(val));
170
// Result: 'Data has type:  object\nData has value: {"x":1}'
171
```