0
# Text Formatting
1

2
Basic text formatting operations for messages and levels, providing simple text transformations and custom templating.
3

4
## Capabilities
5

6
### Align Format
7

8
Adds a tab delimiter before the message to align it in the same place.
9

10
```javascript { .api }
11
/**
12
 * Creates an align format that adds tab indentation
13
 * @returns {Format} Align format instance
14
 */
15
function align();
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
const { format } = require('logform');
22

23
const alignFormat = format.align();
24
const result = alignFormat.transform({
25
  level: 'info',
26
  message: 'my message'
27
});
28
// Result: { level: 'info', message: '\tmy message' }
29
```
30

31
### Simple Format
32

33
Creates a simple text representation of log entries in the format `level: message` with optional metadata.
34

35
```javascript { .api }
36
/**
37
 * Creates a simple text format
38
 * @returns {Format} Simple format instance
39
 */
40
function simple();
41
```
42

43
The simple format produces output in this structure:
44
- `${level}: ${message}` if no additional metadata
45
- `${level}: ${message} ${JSON.stringify(metadata)}` if additional properties exist
46

47
**Usage Examples:**
48

49
```javascript
50
const { format } = require('logform');
51
const { MESSAGE } = require('triple-beam');
52

53
const simpleFormat = format.simple();
54

55
// Basic usage
56
const result1 = simpleFormat.transform({
57
  level: 'info',
58
  message: 'Hello world'
59
});
60
console.log(result1[MESSAGE]); // "info: Hello world"
61

62
// With metadata
63
const result2 = simpleFormat.transform({
64
  level: 'error',
65
  message: 'Something failed',
66
  errorCode: 500,
67
  timestamp: '2023-01-01T00:00:00Z'
68
});
69
console.log(result2[MESSAGE]); 
70
// "error: Something failed {\"errorCode\":500,\"timestamp\":\"2023-01-01T00:00:00Z\"}"
71
```
72

73
### Printf Format
74

75
Creates a custom logging format using a template function.
76

77
```javascript { .api }
78
/**
79
 * Creates a printf-style format with custom template function
80
 * @param {Function} templateFn - Function that receives info object and returns formatted string
81
 * @returns {Format} Printf format instance
82
 */
83
function printf(templateFn);
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
const { format } = require('logform');
90

91
// Basic template
92
const myFormat = format.printf((info) => {
93
  return `${info.level}: ${info.message}`;
94
});
95

96
const result = myFormat.transform({
97
  level: 'info',
98
  message: 'Hello world'
99
});
100

101
// With timestamp and metadata
102
const detailedFormat = format.printf((info) => {
103
  const { level, message, timestamp, ...meta } = info;
104
  const metaStr = Object.keys(meta).length ? JSON.stringify(meta, null, 2) : '';
105
  return `[${timestamp}] ${level}: ${message} ${metaStr}`;
106
});
107

108
// Combined with other formats
109
const combinedFormat = format.combine(
110
  format.timestamp(),
111
  format.printf((info) => {
112
    return `${info.timestamp} [${info.level}]: ${info.message}`;
113
  })
114
);
115
```
116

117
### Printf Class
118

119
The internal class used by the printf format.
120

121
```javascript { .api }
122
/**
123
 * Internal Printf class that handles template formatting
124
 */
125
class Printf {
126
  /**
127
   * @param {Function} templateFn - Template function for formatting
128
   */
129
  constructor(templateFn);
130
  
131
  /** Template function that formats info objects */
132
  template: Function;
133
  
134
  /**
135
   * Transform method that applies the template
136
   * @param {Object} info - Log info object
137
   * @returns {Object} Info object with MESSAGE symbol set
138
   */
139
  transform(info);
140
}
141
```