0
# Core Format System
1

2
The core format system provides the foundation for creating custom formats and managing format instances.
3

4
## Capabilities
5

6
### Format Constructor
7

8
Creates a new format from a transformation function.
9

10
```javascript { .api }
11
/**
12
 * Creates a new format from a transformation function
13
 * @param {Function} transformFn - Function that takes (info, opts) and returns modified info or falsy value
14
 * @returns {Function} Format constructor function that creates format instances
15
 */
16
function format(transformFn);
17
```
18

19
The transformation function must have exactly 2 parameters and should:
20
- Accept an `info` object and `opts` object
21
- Return a modified `info` object or falsy value to filter the log entry
22
- Handle the transformation synchronously
23

24
**Usage Examples:**
25

26
```javascript
27
const { format } = require('logform');
28

29
// Custom format that uppercases messages
30
const upperFormat = format((info, opts) => {
31
  if (opts.enable) {
32
    info.message = info.message.toUpperCase();
33
  }
34
  return info;
35
});
36

37
// Create format instance
38
const upperInstance = upperFormat({ enable: true });
39

40
// Use the format
41
const result = upperInstance.transform({
42
  level: 'info',
43
  message: 'hello world'
44
});
45
// Result: { level: 'info', message: 'HELLO WORLD' }
46

47
// Filtering example
48
const filterFormat = format((info, opts) => {
49
  if (info.private) {
50
    return false; // Filter out private messages
51
  }
52
  return info;
53
});
54
```
55

56
### Level Configuration
57

58
Registers color configurations for log levels with the Colorizer class.
59

60
```javascript { .api }
61
/**
62
 * Registers color configurations for log levels
63
 * @param {Object} config - Configuration object with colors property or direct color mapping
64
 * @returns {Object} The configuration object
65
 */
66
function levels(config);
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
const { levels } = require('logform');
73

74
// Register custom colors
75
const config = levels({
76
  colors: {
77
    info: 'blue',
78
    warn: 'yellow',
79
    error: 'red',
80
    debug: 'green'
81
  }
82
});
83

84
// Or directly with color mapping
85
levels({
86
  info: 'blue',
87
  warn: 'yellow'
88
});
89
```
90

91
### Format Base Class
92

93
The base class that all format instances inherit from.
94

95
```javascript { .api }
96
/**
97
 * Base format class with transform method
98
 */
99
class Format {
100
  /**
101
   * @param {Object} opts - Configuration options for the format
102
   */
103
  constructor(opts);
104
  
105
  /** Configuration options passed to constructor */
106
  options: Object;
107
  
108
  /**
109
   * Transform function that processes info objects
110
   * @param {Object} info - Log info object to transform
111
   * @param {Object} opts - Transform options
112
   * @returns {Object|boolean} Modified info object or false to filter
113
   */
114
  transform: Function;
115
}
116
```
117

118
### Invalid Format Error
119

120
Error thrown when format functions have incorrect signatures.
121

122
```javascript { .api }
123
/**
124
 * Error thrown when format function has invalid signature
125
 * Format functions must take exactly 2 arguments: (info, opts)
126
 */
127
class InvalidFormatError extends Error {
128
  constructor(formatFn);
129
}
130
```
131

132
## Info Object Structure
133

134
The info object is the data structure that flows through format transformations:
135

136
```javascript { .api }
137
/**
138
 * Basic info object structure
139
 */
140
interface InfoObject {
141
  /** Log level (required) */
142
  level: string;
143
  /** Log message (required) */
144
  message: any;
145
  /** Additional metadata properties */
146
  [key: string]: any;
147
}
148

149
/**
150
 * Symbol properties for internal state
151
 */
152
const SYMBOLS = {
153
  /** Read-only level symbol - Symbol.for('level') */
154
  LEVEL: Symbol,
155
  /** Formatted message symbol - Symbol.for('message') */
156
  MESSAGE: Symbol,
157
  /** Splat arguments symbol - Symbol.for('splat') */
158
  SPLAT: Symbol
159
};
160
```
161

162
Several formats add standard properties to info objects:
163

164
| Property | Added By | Description |
165
|----------|----------|-------------|
166
| `splat` | `splat()` | String interpolation arguments |
167
| `timestamp` | `timestamp()` | Timestamp when message was received |
168
| `label` | `label()` | Custom label for the message |
169
| `ms` | `ms()` | Milliseconds since previous log |