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