0
# Logform
1
2
Logform is a mutable object-based log format library designed for chaining and objectMode streams. It serves as the core formatting engine for the winston logging library, providing a comprehensive set of composable formatting functions that transform log info objects through customizable pipelines.
3
4
## Package Information
5
6
- **Package Name**: logform
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install logform`
10
11
## Core Imports
12
13
```javascript
14
const { format } = require('logform');
15
```
16
17
For ES modules:
18
19
```javascript
20
import { format } from 'logform';
21
```
22
23
Individual formats can be imported directly:
24
25
```javascript
26
const { format: { combine, timestamp, json } } = require('logform');
27
```
28
29
## Basic Usage
30
31
```javascript
32
const { format } = require('logform');
33
34
// Simple format usage
35
const timestampFormat = format.timestamp();
36
const info = timestampFormat.transform({
37
level: 'info',
38
message: 'Hello world'
39
});
40
41
// Combining multiple formats
42
const combinedFormat = format.combine(
43
format.timestamp(),
44
format.colorize(),
45
format.simple()
46
);
47
48
const formattedInfo = combinedFormat.transform({
49
level: 'info',
50
message: 'Hello world'
51
});
52
```
53
54
## Architecture
55
56
Logform is built around several key concepts:
57
58
- **Info Objects**: Mutable objects containing `level`, `message`, and optional metadata
59
- **Format Functions**: Transformation functions that accept `(info, opts)` and return modified info or falsy values
60
- **Format Instances**: Created by calling format functions with options, contain a `transform` method
61
- **Format Combining**: Multiple formats can be chained together using `format.combine()`
62
- **Symbol Properties**: Internal state maintained using symbols from the `triple-beam` package
63
64
The library follows a functional approach where formats are composable transformation functions that can be combined to create sophisticated logging pipelines.
65
66
## Capabilities
67
68
### Core Format Creation
69
70
The main entry point for creating custom formats and accessing built-in formats.
71
72
```javascript { .api }
73
/**
74
* Creates a new format from a transformation function
75
* @param {Function} transformFn - Function that takes (info, opts) and returns modified info
76
* @returns {Function} Format constructor function
77
*/
78
function format(transformFn);
79
80
/**
81
* Registers color configurations for log levels
82
* @param {Object} config - Configuration object with colors property
83
* @returns {Object} The configuration object
84
*/
85
function levels(config);
86
```
87
88
[Core Format System](./core-formats.md)
89
90
### Text Formatting
91
92
Basic text formatting operations for messages and levels.
93
94
```javascript { .api }
95
// Simple text formatting
96
function align();
97
function simple();
98
function printf(templateFn);
99
```
100
101
[Text Formatting](./text-formatting.md)
102
103
### JSON and Structured Output
104
105
Formats for structured data output including JSON and Logstash formats.
106
107
```javascript { .api }
108
function json(opts);
109
function logstash();
110
function prettyPrint(opts);
111
```
112
113
[JSON and Structured Formats](./json-formats.md)
114
115
### Colorization and Visual Enhancement
116
117
Color-related formatting for terminal and CLI output.
118
119
```javascript { .api }
120
function colorize(opts);
121
function uncolorize(opts);
122
function cli(opts);
123
```
124
125
[Colorization](./colorization.md)
126
127
### Data Enhancement and Metadata
128
129
Formats that add or organize metadata in log entries.
130
131
```javascript { .api }
132
function timestamp(opts);
133
function label(opts);
134
function metadata(opts);
135
function ms();
136
```
137
138
[Data Enhancement](./data-enhancement.md)
139
140
### String Processing and Error Handling
141
142
Advanced text processing and error handling capabilities.
143
144
```javascript { .api }
145
function splat();
146
function errors(opts);
147
function padLevels(opts);
148
```
149
150
[String Processing](./string-processing.md)
151
152
### Format Composition
153
154
Utilities for combining and organizing multiple formats.
155
156
```javascript { .api }
157
function combine(...formats);
158
```
159
160
[Format Composition](./format-composition.md)
161
162
## Core Types
163
164
```javascript { .api }
165
// Info object structure (from TypeScript definitions)
166
interface TransformableInfo {
167
level: string;
168
message: unknown;
169
[LEVEL]?: string;
170
[MESSAGE]?: unknown;
171
[SPLAT]?: unknown;
172
[key: string | symbol]: unknown;
173
}
174
175
// Transform function signature
176
type TransformFunction = (info: TransformableInfo, opts?: unknown) => TransformableInfo | boolean;
177
178
// Format constructor function
179
type FormatWrap = (opts?: unknown) => Format;
180
181
// Base format class
182
class Format {
183
constructor(opts?: object);
184
options?: object;
185
transform: TransformFunction;
186
}
187
```
188
189
## Symbols and Constants
190
191
Logform uses symbols from the `triple-beam` package for internal state:
192
193
```javascript { .api }
194
const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');
195
196
// Symbol.for('level') - Read-only level property
197
// Symbol.for('message') - Complete formatted message string
198
// Symbol.for('splat') - String interpolation arguments
199
```