0
# Colorization
1

2
Color-related formatting for terminal and CLI output, providing ANSI color codes for levels and messages.
3

4
## Capabilities
5

6
### Colorize Format
7

8
Adds ANSI color codes to log levels and/or messages based on the log level.
9

10
```javascript { .api }
11
/**
12
 * Creates a colorize format with configurable color options
13
 * @param {Object} opts - Colorization options
14
 * @param {boolean} opts.level - Apply color to level (default: false)
15
 * @param {boolean} opts.all - Apply color to both level and message (default: false)
16
 * @param {boolean} opts.message - Apply color to message (default: false)
17
 * @param {Object} opts.colors - Color mappings for log levels
18
 * @returns {Colorizer} Colorizer format instance
19
 */
20
function colorize(opts);
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
const { format } = require('logform');
27
const { LEVEL, MESSAGE } = require('triple-beam');
28

29
// Colorize just the level
30
const levelColorizer = format.colorize({ 
31
  level: true,
32
  colors: { info: 'blue', error: 'red' }
33
});
34

35
const result1 = levelColorizer.transform({
36
  [LEVEL]: 'info',
37
  level: 'info',
38
  message: 'Hello world'
39
});
40

41
// Colorize everything
42
const allColorizer = format.colorize({ 
43
  all: true,
44
  colors: { info: 'blue' }
45
});
46

47
const result2 = allColorizer.transform({
48
  [LEVEL]: 'info',
49
  level: 'info',
50
  message: 'Hello world'
51
}, { all: true });
52

53
// Multiple colors for a single level
54
const multiColorizer = format.colorize({
55
  colors: {
56
    info: 'blue bold',
57
    error: 'red underline'
58
  }
59
});
60
```
61

62
### Colorizer Class
63

64
The advanced colorizer class with static and instance methods for color management.
65

66
```javascript { .api }
67
/**
68
 * Colorizer class that handles ANSI color application
69
 */
70
class Colorizer extends Format {
71
  /**
72
   * @param {Object} opts - Colorizer options
73
   */
74
  constructor(opts);
75
  
76
  /**
77
   * Static method to add colors to all colorizer instances
78
   * @param {Object} colors - Color mappings object
79
   * @returns {Object} Updated color mappings
80
   */
81
  static addColors(colors);
82
  
83
  /**
84
   * Instance method to add colors to this colorizer
85
   * @param {Object} colors - Color mappings object
86
   * @returns {Object} Updated color mappings
87
   */
88
  addColors(colors);
89
  
90
  /**
91
   * Apply colors to text based on lookup key
92
   * @param {string} lookup - Level to look up colors for
93
   * @param {string} level - Level string (used if message not provided)
94
   * @param {string} message - Message to colorize (optional)
95
   * @returns {string} Colorized text
96
   */
97
  colorize(lookup, level, message);
98
  
99
  /**
100
   * Transform info object by applying colors
101
   * @param {Object} info - Log info object
102
   * @param {Object} opts - Transform options
103
   * @returns {Object} Colorized info object
104
   */
105
  transform(info, opts);
106
}
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
const { format } = require('logform');
113

114
// Add global colors
115
format.colorize.addColors({
116
  info: 'blue',
117
  warn: 'yellow',
118
  error: 'red bold',
119
  debug: 'green dim'
120
});
121

122
// Create colorizer instance
123
const colorizer = format.colorize({ level: true });
124

125
// Use colorizer methods directly
126
const colorizedText = colorizer.colorize('info', 'info', 'Hello world');
127
```
128

129
### Uncolorize Format
130

131
Strips ANSI color codes from log info objects.
132

133
```javascript { .api }
134
/**
135
 * Creates an uncolorize format that strips ANSI color codes
136
 * @param {Object} opts - Uncolorize options
137
 * @param {boolean} opts.level - Process level field (default: true)
138
 * @param {boolean} opts.message - Process message field (default: true)
139
 * @param {boolean} opts.raw - Process MESSAGE symbol field (default: true)
140
 * @returns {Format} Uncolorize format instance
141
 */
142
function uncolorize(opts);
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const { format } = require('logform');
149
const { MESSAGE } = require('triple-beam');
150

151
const uncolorizeFormat = format.uncolorize();
152

153
// Strip colors from all fields
154
const result = uncolorizeFormat.transform({
155
  level: '\u001b[34minfo\u001b[39m', // Blue 'info'
156
  message: '\u001b[34mHello world\u001b[39m', // Blue 'Hello world'
157
  [MESSAGE]: '\u001b[34minfo: Hello world\u001b[39m' // Blue formatted message
158
});
159
// Result: { level: 'info', message: 'Hello world', [MESSAGE]: 'info: Hello world' }
160

161
// Selective uncolorizing
162
const selectiveUncolorize = format.uncolorize({
163
  level: true,
164
  message: false, // Keep message colors
165
  raw: true
166
});
167
```
168

169
### CLI Format
170

171
Combines colorization and level padding for CLI-style output.
172

173
```javascript { .api }
174
/**
175
 * Creates a CLI format combining colorization and padding
176
 * @param {Object} opts - CLI format options (combines ColorizeOptions and PadLevelsOptions)
177
 * @param {Object} opts.levels - Level configuration (default: configs.cli.levels)
178
 * @param {Object} opts.colors - Color mappings for levels
179
 * @param {boolean} opts.level - Apply color to level
180
 * @param {boolean} opts.all - Apply color to both level and message
181
 * @param {boolean} opts.message - Apply color to message
182
 * @returns {CliFormat} CLI format instance
183
 */
184
function cli(opts);
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
const { format } = require('logform');
191
const { LEVEL, MESSAGE } = require('triple-beam');
192

193
const cliFormat = format.cli({ 
194
  colors: { info: 'blue' },
195
  all: true
196
});
197

198
const result = cliFormat.transform({
199
  [LEVEL]: 'info',
200
  level: 'info',
201
  message: 'Hello world'
202
}, { all: true });
203

204
console.log(result[MESSAGE]);
205
// Colorized output: "info:    Hello world" (with blue coloring and padding)
206
```
207

208
### CLI Format Class
209

210
The internal CLI format class that combines colorization and padding.
211

212
```javascript { .api }
213
/**
214
 * CLI format class that handles colorization and padding
215
 */
216
class CliFormat {
217
  /**
218
   * @param {Object} opts - CLI format options
219
   */
220
  constructor(opts);
221
  
222
  /** Colorizer instance for color application */
223
  colorizer: Colorizer;
224
  
225
  /** Padder instance for level padding */
226
  padder: Padder;
227
  
228
  /** Configuration options */
229
  options: Object;
230
  
231
  /**
232
   * Transform method that applies both padding and colors
233
   * @param {Object} info - Log info object
234
   * @param {Object} opts - Transform options
235
   * @returns {Object} Formatted info object
236
   */
237
  transform(info, opts);
238
}
239
```
240

241
## Color Configuration
242

243
Colors can be specified as:
244
- Single color names: `'blue'`, `'red'`, `'green'`
245
- Space-separated multiple colors: `'blue bold'`, `'red underline'`
246
- Arrays: `['blue', 'bold']`
247

248
Available colors include standard ANSI colors and styles from the @colors/colors package.