0
# Data Enhancement
1

2
Formats that add or organize metadata in log entries, including timestamps, labels, metadata organization, and timing information.
3

4
## Capabilities
5

6
### Timestamp Format
7

8
Adds timestamp information to log info objects.
9

10
```javascript { .api }
11
/**
12
 * Creates a timestamp format that adds timestamp to info objects
13
 * @param {Object} opts - Timestamp options
14
 * @param {string|Function} opts.format - Date format string (fecha) or custom function
15
 * @param {string} opts.alias - Alternative property name for timestamp
16
 * @returns {Format} Timestamp format instance
17
 */
18
function timestamp(opts);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const { format } = require('logform');
25

26
// Default ISO timestamp
27
const timestampFormat = format.timestamp();
28
const result1 = timestampFormat.transform({
29
  level: 'info',
30
  message: 'Hello world'
31
});
32
// Adds: timestamp: '2023-01-01T12:00:00.000Z'
33

34
// Custom format using fecha
35
const customTimestamp = format.timestamp({
36
  format: 'YYYY-MM-DD HH:mm:ss'
37
});
38
const result2 = customTimestamp.transform({
39
  level: 'info',
40
  message: 'Hello world'
41
});
42
// Adds: timestamp: '2023-01-01 12:00:00'
43

44
// Custom function
45
const functionTimestamp = format.timestamp({
46
  format: () => new Date().toLocaleString()
47
});
48

49
// With alias
50
const aliasTimestamp = format.timestamp({
51
  alias: 'time'
52
});
53
const result3 = aliasTimestamp.transform({
54
  level: 'info',
55
  message: 'Hello world'
56
});
57
// Adds both: timestamp: '2023-01-01T12:00:00.000Z' and time: '2023-01-01T12:00:00.000Z'
58
```
59

60
### Label Format
61

62
Adds custom labels to log entries either as a separate property or inline with the message.
63

64
```javascript { .api }
65
/**
66
 * Creates a label format that adds labels to info objects
67
 * @param {Object} opts - Label options
68
 * @param {string} opts.label - Label string to add
69
 * @param {boolean} opts.message - Add label to message text vs separate property
70
 * @returns {Format} Label format instance
71
 */
72
function label(opts);
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
const { format } = require('logform');
79

80
// Label as separate property
81
const labelFormat = format.label({ label: 'my-service' });
82
const result1 = labelFormat.transform({
83
  level: 'info',
84
  message: 'Hello world'
85
});
86
// Result: { level: 'info', message: 'Hello world', label: 'my-service' }
87

88
// Label inline with message
89
const inlineLabelFormat = format.label({ 
90
  label: 'my-service',
91
  message: true 
92
});
93
const result2 = inlineLabelFormat.transform({
94
  level: 'info',
95
  message: 'Hello world'
96
});
97
// Result: { level: 'info', message: '[my-service] Hello world' }
98
```
99

100
### Metadata Format
101

102
Organizes extraneous data into a metadata object, similar to winston 2.x behavior.
103

104
```javascript { .api }
105
/**
106
 * Creates a metadata format that organizes extra properties
107
 * @param {Object} opts - Metadata options
108
 * @param {string} opts.key - Name of metadata property (default: 'metadata')
109
 * @param {string[]} opts.fillExcept - Keys to exclude from metadata
110
 * @param {string[]} opts.fillWith - Keys to include in metadata
111
 * @returns {Format} Metadata format instance
112
 */
113
function metadata(opts);
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
const { format } = require('logform');
120

121
// Default behavior - exclude level and message
122
const metadataFormat = format.metadata();
123
const result1 = metadataFormat.transform({
124
  level: 'info',
125
  message: 'Hello world',
126
  userId: 123,
127
  ip: '192.168.1.1',
128
  userAgent: 'Mozilla/5.0...'
129
});
130
// Result: {
131
//   level: 'info',
132
//   message: 'Hello world',
133
//   metadata: {
134
//     userId: 123,
135
//     ip: '192.168.1.1',
136
//     userAgent: 'Mozilla/5.0...'
137
//   }
138
// }
139

140
// Custom metadata key
141
const customKeyFormat = format.metadata({ key: 'meta' });
142

143
// Exclude specific fields
144
const excludeFormat = format.metadata({
145
  fillExcept: ['level', 'message', 'timestamp']
146
});
147

148
// Include only specific fields
149
const includeFormat = format.metadata({
150
  fillWith: ['userId', 'sessionId']
151
});
152
const result2 = includeFormat.transform({
153
  level: 'info',
154
  message: 'User action',
155
  userId: 123,
156
  sessionId: 'abc-def',
157
  ip: '192.168.1.1' // This won't be included
158
});
159
// Result: {
160
//   level: 'info',
161
//   message: 'User action',
162
//   ip: '192.168.1.1',
163
//   metadata: {
164
//     userId: 123,
165
//     sessionId: 'abc-def'
166
//   }
167
// }
168
```
169

170
### MS Format
171

172
Adds timing information showing milliseconds since the previous log message.
173

174
```javascript { .api }
175
/**
176
 * Creates an ms format that adds timing information
177
 * @returns {Format} MS format instance
178
 */
179
function ms();
180
```
181

182
**Usage Examples:**
183

184
```javascript
185
const { format } = require('logform');
186

187
const msFormat = format.ms();
188

189
// First log
190
const result1 = msFormat.transform({
191
  level: 'info',
192
  message: 'Starting process'
193
});
194
// Adds: ms: '+0ms' (or similar initial value)
195

196
// Wait some time...
197
setTimeout(() => {
198
  const result2 = msFormat.transform({
199
    level: 'info',
200
    message: 'Process step completed'
201
  });
202
  // Adds: ms: '+250ms' (actual time difference)
203
}, 250);
204

205
// Combined with other formats
206
const combinedFormat = format.combine(
207
  format.timestamp(),
208
  format.ms(),
209
  format.simple()
210
);
211
```
212

213
## Options Interfaces
214

215
### Timestamp Options
216

217
```javascript { .api }
218
interface TimestampOptions {
219
  /** Date format string (fecha) or custom function */
220
  format?: string | (() => string);
221
  
222
  /** Alternative property name for timestamp */
223
  alias?: string;
224
}
225
```
226

227
### Label Options
228

229
```javascript { .api }
230
interface LabelOptions {
231
  /** Label string to add */
232
  label?: string;
233
  
234
  /** Add label to message text vs separate property */
235
  message?: boolean;
236
}
237
```
238

239
### Metadata Options
240

241
```javascript { .api }
242
interface MetadataOptions {
243
  /** Name of metadata property (default: 'metadata') */
244
  key?: string;
245
  
246
  /** Keys to exclude from metadata */
247
  fillExcept?: string[];
248
  
249
  /** Keys to include in metadata */
250
  fillWith?: string[];
251
}
252
```