0
# JSON and Structured Formats
1

2
Formats for structured data output including JSON serialization, Logstash compatibility, and pretty-printed object inspection.
3

4
## Capabilities
5

6
### JSON Format
7

8
Serializes log info objects to JSON using safe-stable-stringify for reliable output.
9

10
```javascript { .api }
11
/**
12
 * Creates a JSON format with configurable serialization options
13
 * @param {Object} opts - JSON formatting options
14
 * @param {Function} opts.replacer - Function that influences how info is stringified
15
 * @param {number} opts.space - Number of white spaces for formatting
16
 * @param {boolean} opts.bigint - Handle bigint values (default: true)
17
 * @param {string|null|Function} opts.circularValue - Value for circular references (default: "[Circular]")
18
 * @param {boolean} opts.deterministic - Guarantee deterministic key order (default: true)
19
 * @param {number} opts.maximumBreadth - Max properties per object (default: Infinity)
20
 * @param {number} opts.maximumDepth - Max nesting levels (default: Infinity)
21
 * @returns {Format} JSON format instance
22
 */
23
function json(opts);
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
const { format } = require('logform');
30
const { MESSAGE } = require('triple-beam');
31

32
// Basic JSON format
33
const jsonFormat = format.json();
34
const result = jsonFormat.transform({
35
  level: 'info',
36
  message: 'Hello world',
37
  meta: { userId: 123 }
38
});
39
console.log(result[MESSAGE]); 
40
// '{"level":"info","message":"Hello world","meta":{"userId":123}}'
41

42
// Pretty printed JSON
43
const prettyJson = format.json({ space: 2 });
44
const prettyResult = prettyJson.transform({
45
  level: 'info',
46
  message: 'Hello world'
47
});
48

49
// With custom replacer
50
const customJson = format.json({
51
  replacer: (key, value) => {
52
    if (key === 'password') return '[REDACTED]';
53
    return value;
54
  }
55
});
56

57
// With safe-stable-stringify options
58
const safeJson = format.json({
59
  maximumDepth: 5,
60
  circularValue: '[Circular Reference]',
61
  deterministic: true
62
});
63
```
64

65
### Logstash Format
66

67
Transforms log info objects into Logstash-compatible JSON format.
68

69
```javascript { .api }
70
/**
71
 * Creates a Logstash-compatible format
72
 * @returns {Format} Logstash format instance
73
 */
74
function logstash();
75
```
76

77
The Logstash format restructures the info object into Logstash's expected schema:
78
- `@message`: The original message
79
- `@timestamp`: The timestamp (if present)
80
- `@fields`: All other properties from the info object
81

82
**Usage Examples:**
83

84
```javascript
85
const { format } = require('logform');
86
const { MESSAGE } = require('triple-beam');
87

88
const logstashFormat = format.combine(
89
  format.timestamp(),
90
  format.logstash()
91
);
92

93
const result = logstashFormat.transform({
94
  level: 'info',
95
  message: 'User logged in',
96
  userId: 123,
97
  ip: '192.168.1.1'
98
});
99

100
console.log(result[MESSAGE]);
101
// '{"@message":"User logged in","@timestamp":"2023-01-01T00:00:00.000Z","@fields":{"level":"info","userId":123,"ip":"192.168.1.1"}}'
102
```
103

104
### Pretty Print Format
105

106
Pretty-prints log info objects using Node.js util.inspect for development and debugging.
107

108
```javascript { .api }
109
/**
110
 * Creates a pretty-print format using util.inspect
111
 * @param {Object} opts - Pretty print options
112
 * @param {number} opts.depth - Maximum depth for object inspection (default: 2)
113
 * @param {boolean} opts.colorize - Enable colorization (default: false)
114
 * @returns {Format} Pretty print format instance
115
 */
116
function prettyPrint(opts);
117
```
118

119
**Note**: The pretty print format should not be used in production as it may impact performance and block the event loop.
120

121
**Usage Examples:**
122

123
```javascript
124
const { format } = require('logform');
125
const { MESSAGE, LEVEL, SPLAT } = require('triple-beam');
126

127
// Basic pretty print
128
const prettyFormat = format.prettyPrint();
129
const result = prettyFormat.transform({
130
  [LEVEL]: 'info',
131
  level: 'info',
132
  message: 'Complex object',
133
  data: {
134
    users: [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }],
135
    settings: { theme: 'dark', language: 'en' }
136
  }
137
});
138

139
// With custom depth and colors
140
const coloredPretty = format.prettyPrint({
141
  depth: 3,
142
  colorize: true
143
});
144

145
// Symbols are automatically stripped from output
146
const complexResult = prettyFormat.transform({
147
  [LEVEL]: 'info',
148
  [MESSAGE]: 'This will be stripped',
149
  [SPLAT]: ['This too'],
150
  level: 'info',
151
  message: 'Visible message',
152
  metadata: { key: 'value' }
153
});
154
console.log(complexResult[MESSAGE]);
155
// "{ level: 'info', message: 'Visible message', metadata: { key: 'value' } }"
156
```
157

158
## JSON Format Options
159

160
### Safe-Stable-Stringify Options
161

162
The JSON format uses safe-stable-stringify internally, providing these additional options:
163

164
```javascript { .api }
165
interface JsonOptions {
166
  /** Function that influences stringification */
167
  replacer?: (key: string, value: any) => any;
168
  
169
  /** Number of white spaces for formatting */
170
  space?: number;
171
  
172
  /** Convert bigint to number (default: true) */
173
  bigint?: boolean;
174
  
175
  /** Value for circular references (default: "[Circular]") */
176
  circularValue?: string | null | ErrorConstructor;
177
  
178
  /** Guarantee deterministic key order (default: true) */
179
  deterministic?: boolean;
180
  
181
  /** Maximum properties per object (default: Infinity) */
182
  maximumBreadth?: number;
183
  
184
  /** Maximum nesting levels (default: Infinity) */
185
  maximumDepth?: number;
186
}
187
```