0
# Core Formatting
1

2
Core formatting functionality that converts any JavaScript value to a human-readable string with extensive customization options for indentation, depth control, escaping, and terminal colors.
3

4
## Capabilities
5

6
### Format Function
7

8
Main entry point for converting any JavaScript value to a formatted string.
9

10
```typescript { .api }
11
/**
12
 * Returns a presentation string of your `val` object
13
 * @param val - Any potential JavaScript object
14
 * @param options - Custom settings to control formatting behavior
15
 * @returns Formatted string representation
16
 */
17
function format(val: unknown, options?: OptionsReceived): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { format } from "pretty-format";
24
// OR as default export
25
import format from "pretty-format";
26

27
// Basic usage
28
const result = format({ name: "Alice", age: 25 });
29

30
// With custom options
31
const formatted = format(
32
  { items: [1, 2, 3], nested: { deep: true } },
33
  {
34
    indent: 4,
35
    maxDepth: 2,
36
    min: false,
37
    highlight: true
38
  }
39
);
40

41
// Circular reference handling
42
const obj = { name: "test" };
43
obj.self = obj;
44
const circular = format(obj);
45
// Result includes [Circular] notation
46
```
47

48
### Default Export
49

50
Same format function available as default export.
51

52
```typescript { .api }
53
export default format;
54
```
55

56
### Configuration Options
57

58
Complete configuration interface for customizing formatting behavior.
59

60
```typescript { .api }
61
interface OptionsReceived {
62
  /** Call toJSON method (if it exists) on objects */
63
  callToJSON?: boolean;
64
  /** Compare function used when sorting object keys, null can be used to skip over sorting */
65
  compareKeys?: ((a: string, b: string) => number) | null;
66
  /** Escape special characters in regular expressions */
67
  escapeRegex?: boolean;
68
  /** Escape special characters in strings */
69
  escapeString?: boolean;
70
  /** Highlight syntax with colors in terminal (some plugins) */
71
  highlight?: boolean;
72
  /** Spaces in each level of indentation */
73
  indent?: number;
74
  /** Levels to print in arrays, objects, elements, and so on */
75
  maxDepth?: number;
76
  /** Number of elements to print in arrays, sets, and so on */
77
  maxWidth?: number;
78
  /** Minimize added space: no indentation nor line breaks */
79
  min?: boolean;
80
  /** Plugins to serialize application-specific data types */
81
  plugins?: Plugin[];
82
  /** Print the prototype for plain objects and arrays */
83
  printBasicPrototype?: boolean;
84
  /** Include or omit the name of a function */
85
  printFunctionName?: boolean;
86
  /** Colors to highlight syntax in terminal */
87
  theme?: Partial<Theme>;
88
}
89
```
90

91
### Default Options
92

93
Pre-configured default options used when no custom options are provided.
94

95
```typescript { .api }
96
const DEFAULT_OPTIONS: {
97
  callToJSON: true;
98
  compareKeys: undefined;
99
  escapeRegex: false;
100
  escapeString: true;
101
  highlight: false;
102
  indent: 2;
103
  maxDepth: number; // Infinity
104
  maxWidth: number; // Infinity
105
  min: false;
106
  plugins: Plugin[];
107
  printBasicPrototype: true;
108
  printFunctionName: true;
109
  theme: {
110
    comment: 'gray';
111
    content: 'reset';
112
    prop: 'yellow';
113
    tag: 'cyan';
114
    value: 'green';
115
  };
116
};
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
// Control indentation
123
format(data, { indent: 4 });
124

125
// Minimize output
126
format(data, { min: true });
127

128
// Limit depth
129
format(data, { maxDepth: 2 });
130

131
// Custom key sorting
132
format(data, { 
133
  compareKeys: (a, b) => a.localeCompare(b) 
134
});
135

136
// Disable function names
137
format(fn, { printFunctionName: false });
138

139
// Enable terminal colors
140
format(data, { 
141
  highlight: true,
142
  theme: { prop: 'blue', value: 'red' }
143
});
144
```
145

146
## Supported Value Types
147

148
Pretty Format handles all JavaScript value types:
149

150
### Primitives
151
- **Boolean**: `true`, `false`
152
- **Number**: `42`, `-0`, `Infinity`, `NaN`
153
- **BigInt**: `123n`
154
- **String**: `"hello"` (with optional escaping)
155
- **Symbol**: `Symbol(description)`
156
- **Null**: `null`
157
- **Undefined**: `undefined`
158

159
### Objects and Collections
160
- **Arrays**: `[1, 2, 3]` and typed arrays
161
- **Objects**: `{ key: "value" }` with property sorting
162
- **Maps**: `Map { "key" => "value" }`
163
- **Sets**: `Set { 1, 2, 3 }`
164
- **WeakMap**: `WeakMap {}`
165
- **WeakSet**: `WeakSet {}`
166
- **Date**: ISO string or `Date { NaN }`
167
- **RegExp**: `/pattern/flags`
168
- **Error**: `[Error: message]`
169
- **Function**: `[Function name]` or `[Function]`
170

171
### Special Handling
172
- **Circular References**: `[Circular]`
173
- **Arguments Object**: `Arguments [...]`
174
- **ArrayBuffer/DataView**: Byte-level formatting
175
- **Global Window**: `[Window]` (safe handling in jsdom)
176

177
**Usage Examples:**
178

179
```typescript
180
// Complex object
181
const complex = {
182
  num: 42,
183
  big: 123n,
184
  sym: Symbol('test'),
185
  date: new Date(),
186
  regex: /test/gi,
187
  map: new Map([['key', 'value']]),
188
  set: new Set([1, 2, 3]),
189
  fn: function namedFn() {},
190
  arrow: () => {}
191
};
192

193
const formatted = format(complex, { 
194
  printFunctionName: true,
195
  indent: 2 
196
});
197
```
198

199
## Internal Configuration
200

201
The internal configuration object used during formatting (read-only).
202

203
```typescript { .api }
204
interface Config {
205
  callToJSON: boolean;
206
  compareKeys: CompareKeys;
207
  colors: Colors;
208
  escapeRegex: boolean;
209
  escapeString: boolean;
210
  indent: string;
211
  maxDepth: number;
212
  maxWidth: number;
213
  min: boolean;
214
  plugins: Plugin[];
215
  printBasicPrototype: boolean;
216
  printFunctionName: boolean;
217
  spacingInner: string;
218
  spacingOuter: string;
219
}
220
```