0
# prettyjson
1
2
prettyjson is a Node.js package that transforms JSON data into a colorized, YAML-style output format, perfect for command-line interfaces and console applications. It provides both programmatic API access and a command-line interface with extensive customization options for colors, indentation, and formatting styles.
3
4
## Package Information
5
6
- **Package Name**: prettyjson
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install prettyjson` (or `npm install -g prettyjson` for CLI)
10
11
## Core Imports
12
13
```javascript
14
const prettyjson = require('prettyjson');
15
```
16
17
ESM import (if supported):
18
```javascript
19
import prettyjson from 'prettyjson';
20
```
21
22
## Basic Usage
23
24
```javascript
25
const prettyjson = require('prettyjson');
26
27
const data = {
28
username: 'alice',
29
projects: ['web-app', 'mobile-app'],
30
settings: {
31
theme: 'dark',
32
notifications: true
33
}
34
};
35
36
// Basic rendering
37
console.log(prettyjson.render(data));
38
39
// With custom options
40
console.log(prettyjson.render(data, {
41
keysColor: 'rainbow',
42
dashColor: 'magenta',
43
stringColor: 'white',
44
noColor: false
45
}));
46
47
// Parse and render JSON string
48
const jsonString = '{"name": "Bob", "age": 30}';
49
console.log(prettyjson.renderString(jsonString));
50
51
// Access version information
52
console.log('Using prettyjson version:', prettyjson.version);
53
```
54
55
## Architecture
56
57
prettyjson is built around a simple, focused architecture:
58
59
- **Core Rendering Engine**: Recursive data structure traversal with type-specific formatting
60
- **Color System**: Integration with colors.js for terminal color output
61
- **CLI Interface**: Complete command-line tool with argument parsing and multiple input methods
62
- **Configuration System**: Extensive options for customizing output appearance and behavior
63
64
## Capabilities
65
66
### Data Rendering
67
68
Core function for converting JavaScript data structures into formatted, colorized YAML-style output.
69
70
```javascript { .api }
71
/**
72
* Renders data as formatted, colorized YAML-style output
73
* @param data - Data to render (any type)
74
* @param options - Configuration options (optional, object)
75
* @param indentation - Base indentation level (optional, number, default: 0)
76
* @returns string - Formatted string output
77
*/
78
function render(data: any, options?: Options, indentation?: number): string;
79
```
80
81
### String Parsing and Rendering
82
83
Function for parsing JSON strings and rendering them with formatting.
84
85
```javascript { .api }
86
/**
87
* Parses JSON string and renders it with formatting
88
* @param data - JSON string to parse and render
89
* @param options - Configuration options (optional, object)
90
* @param indentation - Base indentation level (optional, number, default: 0)
91
* @returns string - Formatted string output or error message if invalid JSON
92
*/
93
function renderString(data: string, options?: Options, indentation?: number): string;
94
```
95
96
### Version Information
97
98
Access to the package version.
99
100
```javascript { .api }
101
/**
102
* Package version string accessed from the module
103
*/
104
const prettyjson = require('prettyjson');
105
const version: string = prettyjson.version;
106
```
107
108
### Command Line Interface
109
110
Complete CLI tool for processing JSON files and streams.
111
112
**Usage:**
113
```bash
114
# Render a JSON file
115
prettyjson package.json
116
117
# Process stdin
118
curl https://api.github.com/users/alice | prettyjson
119
120
# Interactive mode (no arguments)
121
prettyjson
122
```
123
124
**CLI Options:**
125
```bash
126
--keys COLOR # Set color for object keys
127
--dash COLOR # Set color for array dashes
128
--string COLOR # Set color for strings
129
--multiline_string COLOR # Set color for multiline strings
130
--number COLOR # Set color for numbers
131
--indent NUMBER # Set indentation spaces
132
--nocolor # Disable colors
133
--noalign # Disable value alignment
134
--escape # Escape conflicting characters
135
--inline-arrays # Render simple arrays inline
136
```
137
138
**Environment Variables:**
139
- `PRETTYJSON_KEYS` - Default keys color
140
- `PRETTYJSON_DASH` - Default dash color
141
- `PRETTYJSON_STRING` - Default string color
142
- `PRETTYJSON_MULTILINE_STRING` - Default multiline string color
143
- `PRETTYJSON_NUMBER` - Default number color
144
- `PRETTYJSON_NUMBER_POSITIVE` - Default positive number color
145
- `PRETTYJSON_NUMBER_NEGATIVE` - Default negative number color
146
- `PRETTYJSON_INDENT` - Default indentation
147
- `PRETTYJSON_NOCOLOR` - Disable colors
148
- `PRETTYJSON_NOALIGN` - Disable alignment
149
- `PRETTYJSON_ESCAPE` - Enable escaping
150
- `PRETTYJSON_INLINE_ARRAYS` - Enable inline arrays
151
152
## Configuration Options
153
154
```javascript { .api }
155
interface Options {
156
/** Message displayed for empty arrays (default: '(empty array)') */
157
emptyArrayMsg?: string;
158
159
/** Color for object keys using colors.js syntax (default: 'green') */
160
keysColor?: string;
161
162
/** Color for array item dashes (default: 'green') */
163
dashColor?: string;
164
165
/** Color for all numbers (default: 'blue') */
166
numberColor?: string;
167
168
/** Color for positive numbers (default: uses numberColor) */
169
positiveNumberColor?: string;
170
171
/** Color for negative numbers (default: uses numberColor) */
172
negativeNumberColor?: string;
173
174
/** Color for strings (default: null - no coloring) */
175
stringColor?: string | null;
176
177
/** Color for multiline strings (default: null - no coloring) */
178
multilineStringColor?: string | null;
179
180
/** Indentation for nested objects in spaces (default: 2) */
181
defaultIndentation?: number;
182
183
/** Disable all coloring (default: false) */
184
noColor?: boolean;
185
186
/** Disable value alignment (default: false) */
187
noAlign?: boolean;
188
189
/** Escape conflicting characters with JSON.stringify (default: false) */
190
escape?: boolean;
191
192
/** Render undefined values instead of ignoring them (default: false) */
193
renderUndefined?: boolean;
194
195
/** Render simple arrays inline instead of multi-line (default: false) */
196
inlineArrays?: boolean;
197
}
198
```
199
200
## Data Type Support
201
202
prettyjson handles all JavaScript data types:
203
204
- **Primitives**: strings, numbers, booleans, null, undefined
205
- **Objects**: Plain objects with proper key formatting and indentation
206
- **Arrays**: Multi-line with dash prefixes, or inline mode for simple arrays
207
- **Functions**: Rendered as `"function() {}"`
208
- **Dates**: Rendered using default toString() representation
209
- **Errors**: Special handling to display message and stack trace
210
- **Multiline Strings**: Triple-quote formatting with proper indentation
211
212
## Color System
213
214
Colors are specified using [colors.js](https://github.com/Marak/colors.js) syntax:
215
216
**Standard Colors**: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, `grey`
217
218
**Bright Colors**: `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
219
220
**Special Effects**: `rainbow`, `zebra`, `america`, `trap`, `random`
221
222
**Styles**: `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
223
224
## Error Handling
225
226
- **Invalid JSON**: `renderString()` returns `"Error: Not valid JSON!"` in red text when JSON parsing fails
227
- **Empty String Input**: `renderString()` with empty string returns empty string
228
- **Non-string Input**: `renderString()` with non-string input returns empty string
229
- **File Not Found**: CLI displays error message in red and exits with code 1
230
- **Undefined Values**: Ignored by default unless `renderUndefined: true` option is set
231
- **Function Values**: Rendered as `"function() {}"` string representation
232
- **Circular References**: May cause stack overflow (not explicitly handled)
233
- **Error Objects**: Special handling to display message and stack trace properties