0
# String Processing
1

2
Advanced text processing and error handling capabilities including string interpolation, error object handling, and level padding.
3

4
## Capabilities
5

6
### Splat Format
7

8
Transforms log messages by performing string interpolation using util.format, similar to printf-style formatting.
9

10
```javascript { .api }
11
/**
12
 * Creates a splat format for string interpolation
13
 * @returns {Format} Splat format instance
14
 */
15
function splat();
16
```
17

18
The splat format processes string interpolation tokens like `%s`, `%d`, `%j`, etc., using Node.js util.format internally.
19

20
**Usage Examples:**
21

22
```javascript
23
const { format } = require('logform');
24
const { SPLAT } = require('triple-beam');
25

26
const splatFormat = format.splat();
27

28
// Basic string interpolation
29
const result1 = splatFormat.transform({
30
  level: 'info',
31
  message: 'User %s logged in with ID %d',
32
  [SPLAT]: ['Alice', 123]
33
});
34
// Result: { level: 'info', message: 'User Alice logged in with ID 123', [SPLAT]: ['Alice', 123] }
35

36
// With metadata objects
37
const result2 = splatFormat.transform({
38
  level: 'info',
39
  message: 'Processing %s',
40
  [SPLAT]: ['payment', { userId: 456, amount: 99.99 }]
41
});
42
// Result: {
43
//   level: 'info',
44
//   message: 'Processing payment',
45
//   userId: 456,
46
//   amount: 99.99,
47
//   [SPLAT]: ['payment']
48
// }
49

50
// Format tokens
51
const examples = [
52
  '%s - string',
53
  '%d - number',
54
  '%j - JSON',
55
  '%% - literal percent'
56
];
57
```
58

59
### Splatter Class
60

61
The internal class that handles string interpolation logic.
62

63
```javascript { .api }
64
/**
65
 * Splatter class that handles string interpolation
66
 */
67
class Splatter {
68
  /**
69
   * @param {Object} opts - Splatter options
70
   */
71
  constructor(opts);
72
  
73
  /** Configuration options */
74
  options: Object;
75
  
76
  /**
77
   * Transform method that processes string interpolation
78
   * @param {Object} info - Log info object
79
   * @returns {Object} Info object with interpolated message
80
   */
81
  transform(info);
82
  
83
  /**
84
   * Internal method that performs actual string interpolation
85
   * @param {Object} info - Log info object
86
   * @param {string[]} tokens - Array of format tokens found in message
87
   * @returns {Object} Info object with interpolated message and metadata
88
   * @private
89
   */
90
  _splat(info, tokens);
91
}
92
```
93

94
### Errors Format
95

96
Handles JavaScript Error objects in log entries, optionally including stack traces and error causes.
97

98
```javascript { .api }
99
/**
100
 * Creates an errors format for handling Error objects
101
 * @param {Object} opts - Error handling options
102
 * @param {boolean} opts.stack - Include error stack trace
103
 * @param {boolean} opts.cause - Include error cause
104
 * @returns {Format} Errors format instance
105
 */
106
function errors(opts);
107
```
108

109
**Usage Examples:**
110

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

114
// Basic error handling
115
const errorsFormat = format.errors({ stack: true });
116

117
// Error as info object
118
const error = new Error('Something went wrong');
119
const result1 = errorsFormat.transform(error);
120
// Converts Error to info object with message and optional stack
121

122
// Error in message property
123
const result2 = errorsFormat.transform({
124
  level: 'error',
125
  message: new Error('Database connection failed')
126
});
127

128
// With stack trace and cause
129
const errorWithDetails = format.errors({ 
130
  stack: true, 
131
  cause: true 
132
});
133

134
const nestedError = new Error('Connection timeout');
135
const mainError = new Error('Database operation failed');
136
mainError.cause = nestedError;
137

138
const result3 = errorWithDetails.transform({
139
  message: mainError
140
});
141
// Result includes stack trace and cause information
142
```
143

144
### Pad Levels Format
145

146
Pads log level names to uniform length for aligned output.
147

148
```javascript { .api }
149
/**
150
 * Creates a pad levels format for uniform level width
151
 * @param {Object} opts - Padding options
152
 * @param {Object} opts.levels - Level configuration (default: configs.npm.levels)
153
 * @param {string} opts.filler - Padding character (default: ' ')
154
 * @returns {Format} Pad levels format instance
155
 */
156
function padLevels(opts);
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
const { format } = require('logform');
163
const { LEVEL, MESSAGE } = require('triple-beam');
164

165
const padLevelsFormat = format.padLevels();
166

167
const result1 = padLevelsFormat.transform({
168
  [LEVEL]: 'info',
169
  message: 'Short level'
170
});
171
// Result: { message: '    Short level', [LEVEL]: 'info' }
172

173
const result2 = padLevelsFormat.transform({
174
  [LEVEL]: 'error',
175
  message: 'Longer level'
176
});
177
// Result: { message: '   Longer level', [LEVEL]: 'error' }
178

179
// Custom filler and levels
180
const customPadding = format.padLevels({
181
  filler: '.',
182
  levels: {
183
    info: 0,
184
    warn: 1,
185
    error: 2,
186
    debug: 3
187
  }
188
});
189
```
190

191
### Padder Class
192

193
The internal class that handles level padding calculations and application.
194

195
```javascript { .api }
196
/**
197
 * Padder class that handles level padding
198
 */
199
class Padder {
200
  /**
201
   * @param {Object} opts - Padder options
202
   */
203
  constructor(opts);
204
  
205
  /** Padding mappings for each level */
206
  paddings: Object;
207
  
208
  /** Configuration options */
209
  options: Object;
210
  
211
  /**
212
   * Static method to get longest level name length
213
   * @param {Object} levels - Level configuration object
214
   * @returns {number} Maximum level name length
215
   */
216
  static getLongestLevel(levels);
217
  
218
  /**
219
   * Static method to calculate padding for a specific level
220
   * @param {string} level - Level name
221
   * @param {string} filler - Padding character
222
   * @param {number} maxLength - Maximum level length
223
   * @returns {string} Padding string
224
   */
225
  static paddingForLevel(level, filler, maxLength);
226
  
227
  /**
228
   * Static method to create padding mappings for all levels
229
   * @param {Object} levels - Level configuration
230
   * @param {string} filler - Padding character (default: ' ')
231
   * @returns {Object} Mapping of level to padding string
232
   */
233
  static paddingForLevels(levels, filler);
234
  
235
  /**
236
   * Transform method that applies padding to messages
237
   * @param {Object} info - Log info object
238
   * @param {Object} opts - Transform options
239
   * @returns {Object} Info object with padded message
240
   */
241
  transform(info, opts);
242
}
243
```
244

245
## String Interpolation Tokens
246

247
The splat format supports these util.format tokens:
248

249
| Token | Type | Description |
250
|-------|------|-------------|
251
| `%s` | String | String conversion |
252
| `%d` | Number | Number conversion |
253
| `%i` | Integer | Integer conversion |
254
| `%f` | Float | Float conversion |
255
| `%j` | JSON | JSON.stringify() |
256
| `%o` | Object | Object inspection |
257
| `%O` | Object | Object inspection with options |
258
| `%%` | Literal | Literal percent sign |
259
260
## Error Handling Options
261

262
```javascript { .api }
263
interface ErrorOptions {
264
  /** Include error stack trace in output */
265
  stack?: boolean;
266
  
267
  /** Include error cause in output */
268
  cause?: boolean;
269
}
270
```
271

272
## Pad Levels Options
273

274
```javascript { .api }
275
interface PadLevelsOptions {
276
  /** Level configuration object (default: configs.npm.levels) */
277
  levels?: Record<string, number>;
278
  
279
  /** Character used for padding (default: ' ') */
280
  filler?: string;
281
}
282
```