0
# Pretty Format
1

2
Pretty Format is a highly configurable JavaScript value stringification library that converts any JavaScript value into a human-readable string format. It handles all built-in JavaScript types including primitives, complex objects, and special values with extensive customization through options for indentation, depth control, escaping, and color highlighting for terminal output.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { format } from "pretty-format";
15
// OR as default export
16
import format from "pretty-format";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { format } = require("pretty-format");
23
// OR as default export
24
const format = require("pretty-format");
25
```
26

27
Import with plugins and options:
28

29
```typescript
30
import { format, plugins, DEFAULT_OPTIONS } from "pretty-format";
31
const { ReactElement, DOMElement, Immutable } = plugins;
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { format } from "pretty-format";
38

39
// Basic formatting
40
const obj = { 
41
  name: "John", 
42
  age: 30, 
43
  hobbies: ["reading", "coding"],
44
  address: { city: "New York", zip: 10001 }
45
};
46

47
console.log(format(obj));
48
/*
49
Object {
50
  "address": Object {
51
    "city": "New York",
52
    "zip": 10001,
53
  },
54
  "age": 30,
55
  "hobbies": Array [
56
    "reading",
57
    "coding",
58
  ],
59
  "name": "John",
60
}
61
*/
62

63
// With options
64
console.log(format(obj, { 
65
  indent: 4, 
66
  min: false,
67
  maxDepth: 2 
68
}));
69
```
70

71
## Architecture
72

73
Pretty Format is built around several key components:
74

75
- **Core Formatter**: Main `format` function that dispatches to appropriate handlers based on value type
76
- **Plugin System**: Extensible architecture supporting both new and legacy plugin interfaces for custom data types
77
- **Built-in Plugins**: Comprehensive set of plugins for React elements, DOM nodes, Immutable.js structures, and Jest matchers
78
- **Configuration System**: Rich options system for controlling output format, depth, colors, and behavior
79
- **Type Safety**: Full TypeScript support with complete type definitions for all APIs
80

81
## Capabilities
82

83
### Core Formatting
84

85
Main formatting functionality that converts any JavaScript value to a human-readable string with extensive customization options.
86

87
```typescript { .api }
88
function format(val: unknown, options?: OptionsReceived): string;
89
export default format;
90

91
interface OptionsReceived {
92
  callToJSON?: boolean;
93
  compareKeys?: ((a: string, b: string) => number) | null;
94
  escapeRegex?: boolean;
95
  escapeString?: boolean;
96
  highlight?: boolean;
97
  indent?: number;
98
  maxDepth?: number;
99
  maxWidth?: number;
100
  min?: boolean;
101
  plugins?: Plugin[];
102
  printBasicPrototype?: boolean;
103
  printFunctionName?: boolean;
104
  theme?: Partial<Theme>;
105
}
106
```
107

108
[Core Formatting](./core-formatting.md)
109

110
### Plugin System
111

112
Extensible plugin architecture for handling custom data types with both modern and legacy interfaces.
113

114
```typescript { .api }
115
interface NewPlugin {
116
  test: (val: any) => boolean;
117
  serialize: (
118
    val: any,
119
    config: Config,
120
    indentation: string,
121
    depth: number,
122
    refs: Refs,
123
    printer: Printer
124
  ) => string;
125
}
126

127
interface OldPlugin {
128
  test: (val: any) => boolean;
129
  print: (
130
    val: unknown,
131
    print: (val: unknown) => string,
132
    indent: (str: string) => string,
133
    options: { edgeSpacing: string; min: boolean; spacing: string },
134
    colors: Colors
135
  ) => string;
136
}
137

138
type Plugin = NewPlugin | OldPlugin;
139
```
140

141
[Plugin System](./plugin-system.md)
142

143
### Built-in Plugins
144

145
Comprehensive collection of plugins for common JavaScript frameworks and data structures.
146

147
```typescript { .api }
148
const plugins: {
149
  AsymmetricMatcher: Plugin;
150
  DOMCollection: Plugin;
151
  DOMElement: Plugin;
152
  Immutable: Plugin;
153
  ReactElement: Plugin;
154
  ReactTestComponent: Plugin;
155
};
156
```
157

158
[Built-in Plugins](./built-in-plugins.md)
159

160
## Default Configuration
161

162
```typescript { .api }
163
const DEFAULT_OPTIONS: {
164
  callToJSON: true;
165
  compareKeys: undefined;
166
  escapeRegex: false;
167
  escapeString: true;
168
  highlight: false;
169
  indent: 2;
170
  maxDepth: number; // Number.POSITIVE_INFINITY
171
  maxWidth: number; // Number.POSITIVE_INFINITY
172
  min: false;
173
  plugins: [];
174
  printBasicPrototype: true;
175
  printFunctionName: true;
176
  theme: {
177
    comment: 'gray';
178
    content: 'reset';
179
    prop: 'yellow';
180
    tag: 'cyan';
181
    value: 'green';
182
  };
183
};
184
```
185

186
## Error Handling
187

188
```typescript { .api }
189
class PrettyFormatPluginError extends Error {
190
  constructor(message: string, stack: string);
191
}
192
```
193

194
## Common Types
195

196
```typescript { .api }
197
type CompareKeys = ((a: string, b: string) => number) | null | undefined;
198

199
interface Theme {
200
  comment: string;
201
  content: string;
202
  prop: string;
203
  tag: string;
204
  value: string;
205
}
206

207
interface Colors {
208
  comment: { close: string; open: string };
209
  content: { close: string; open: string };
210
  prop: { close: string; open: string };
211
  tag: { close: string; open: string };
212
  value: { close: string; open: string };
213
}
214

215
type Refs = Array<unknown>;
216

217
type Printer = (
218
  val: unknown,
219
  config: Config,
220
  indentation: string,
221
  depth: number,
222
  refs: Refs,
223
  hasCalledToJSON?: boolean
224
) => string;
225

226
interface Config {
227
  callToJSON: boolean;
228
  compareKeys: CompareKeys;
229
  colors: Colors;
230
  escapeRegex: boolean;
231
  escapeString: boolean;
232
  indent: string;
233
  maxDepth: number;
234
  maxWidth: number;
235
  min: boolean;
236
  plugins: Plugin[];
237
  printBasicPrototype: boolean;
238
  printFunctionName: boolean;
239
  spacingInner: string;
240
  spacingOuter: string;
241
}
242

243
type Plugin = NewPlugin | OldPlugin;
244
type Plugins = Array<Plugin>;
245

246
interface Options extends Omit<PrettyFormatOptions, 'compareKeys' | 'theme'> {
247
  compareKeys: CompareKeys;
248
  theme: Required<PrettyFormatOptions['theme']>;
249
}
250

251
interface PrettyFormatOptions {
252
  callToJSON?: boolean;
253
  compareKeys?: CompareKeys;
254
  escapeRegex?: boolean;
255
  escapeString?: boolean;
256
  highlight?: boolean;
257
  indent?: number;
258
  maxDepth?: number;
259
  maxWidth?: number;
260
  min?: boolean;
261
  plugins?: Plugins;
262
  printBasicPrototype?: boolean;
263
  printFunctionName?: boolean;
264
  theme?: Partial<Theme>;
265
}
266

267
type OptionsReceived = PrettyFormatOptions;
268
```