0
# Core Logging
1

2
Built-in logger types with pre-configured styling and behavior for common logging scenarios. Signale provides 17 default loggers, each with unique visual styling and semantic meaning.
3

4
## Capabilities
5

6
### Default Logger Methods
7

8
All default loggers are available as methods on the main signale instance and follow the same calling pattern.
9

10
```javascript { .api }
11
/**
12
 * Built-in logger methods available on signale instance
13
 * Each method accepts the same message parameter types
14
 */
15

16
// Status and progress loggers
17
signale.await(message);     // Waiting/loading states with blue ellipsis
18
signale.complete(message);  // Completed tasks with cyan checkbox
19
signale.pending(message);   // Pending tasks with magenta empty checkbox
20
signale.start(message);     // Started processes with green play symbol
21
signale.pause(message);     // Paused processes with yellow square
22
signale.watch(message);     // Watching/monitoring with yellow ellipsis
23
signale.wait(message);      // General waiting with blue ellipsis
24

25
// Result and feedback loggers  
26
signale.success(message);   // Successful operations with green checkmark
27
signale.error(message);     // Error conditions with red cross
28
signale.fatal(message);     // Fatal errors with red cross
29
signale.warn(message);      // Warnings with yellow warning symbol
30
signale.info(message);      // Information with blue info symbol
31
signale.debug(message);     // Debug information with red dot
32
signale.note(message);      // Notes with blue bullet
33
signale.star(message);      // Starred/important with yellow star
34
signale.fav(message);       // Favorites with magenta heart
35
signale.log(message);       // Plain logging (no badge/color)
36

37
// Message parameter types
38
type LogMessage = 
39
  | string                    // Simple string message
40
  | string[]                  // Multiple string arguments (joined with spaces)
41
  | MessageObject             // Object with prefix/suffix
42
  | Error;                    // Error object (displays stack trace)
43

44
interface MessageObject {
45
  prefix?: string;    // Text shown before the badge/label
46
  message: string | string[];  // Main message content
47
  suffix?: string;    // Text shown after the message
48
}
49
```
50

51
### String Interpolation
52

53
All loggers support Node.js `util.format()` style string interpolation with placeholders.
54

55
**Usage Examples:**
56

57
```javascript
58
const signale = require('signale');
59

60
// Basic string interpolation
61
signale.info('Processing %d files', 42);
62
signale.success('User %s logged in successfully', 'alice');
63
signale.pending('Loading %s data from %s...', 'user', 'database');
64

65
// Multiple arguments (automatically joined)
66
signale.debug('Database', 'connection', 'established');
67
// Output: ⬤  debug    Database connection established
68

69
// Complex interpolation
70
signale.warn('Invalid config value: %j', { timeout: -1 });
71
signale.error('Failed to connect to %s:%d after %d attempts', 'localhost', 3000, 3);
72
```
73

74
### Message Object Format
75

76
Use message objects for structured output with prefixes and suffixes.
77

78
**Usage Examples:**
79

80
```javascript
81
const signale = require('signale');
82

83
// Basic message object
84
signale.complete({
85
  prefix: '[task]',
86
  message: 'Fix issue #59',
87
  suffix: '(@username)'
88
});
89
// Output: [task] ☒  complete  Fix issue #59 (@username)
90

91
// Array message with formatting
92
signale.pending({
93
  prefix: '[deploy]',
94
  message: ['Uploading', 'files', 'to', 'server'],
95
  suffix: '(3/5)'
96
});
97
// Output: [deploy] ◯  pending  Uploading files to server (3/5)
98

99
// Interpolation in message objects
100
signale.success({
101
  message: 'Processed %d items successfully',
102
  suffix: '✨'
103
}, 150);
104
```
105

106
### Error Object Handling
107

108
Error objects receive special formatting with stack trace display.
109

110
**Usage Examples:**
111

112
```javascript
113
const signale = require('signale');
114

115
// Error object logging
116
try {
117
  throw new Error('Database connection failed');
118
} catch (err) {
119
  signale.error(err);
120
  // Output: ✖  error  Error: Database connection failed
121
  //                    at Object.<anonymous> (/path/to/file.js:3:9)
122
  //                    at Module._compile (module.js:660:30)
123
  //                    ... (full stack trace)
124
}
125

126
// Fatal error logging
127
signale.fatal(new TypeError('Invalid configuration object'));
128
```
129

130
### Logger Properties
131

132
Each built-in logger has specific visual and behavioral properties:
133

134
```javascript { .api }
135
// Logger configurations (from types.js)
136
const loggerTypes = {
137
  await: { badge: '⋯', color: 'blue', label: 'awaiting', logLevel: 'info' },
138
  complete: { badge: '☑', color: 'cyan', label: 'complete', logLevel: 'info' },
139
  debug: { badge: '⬤', color: 'red', label: 'debug', logLevel: 'debug' },
140
  error: { badge: '✖', color: 'red', label: 'error', logLevel: 'error' },
141
  fatal: { badge: '✖', color: 'red', label: 'fatal', logLevel: 'error' },
142
  fav: { badge: '❤', color: 'magenta', label: 'favorite', logLevel: 'info' },
143
  info: { badge: 'ℹ', color: 'blue', label: 'info', logLevel: 'info' },
144
  log: { badge: '', color: '', label: '', logLevel: 'info' },
145
  note: { badge: '∙', color: 'blue', label: 'note', logLevel: 'info' },
146
  pause: { badge: '■', color: 'yellow', label: 'pause', logLevel: 'info' },
147
  pending: { badge: '◯', color: 'magenta', label: 'pending', logLevel: 'info' },
148
  star: { badge: '✦', color: 'yellow', label: 'star', logLevel: 'info' },
149
  start: { badge: '▶', color: 'green', label: 'start', logLevel: 'info' },
150
  success: { badge: '✔', color: 'green', label: 'success', logLevel: 'info' },
151
  wait: { badge: '⋯', color: 'blue', label: 'waiting', logLevel: 'info' },
152
  warn: { badge: '⚠', color: 'yellow', label: 'warning', logLevel: 'warn' },
153
  watch: { badge: '⋯', color: 'yellow', label: 'watching', logLevel: 'info' }
154
};
155
```
156

157
### Log Level Filtering
158

159
Loggers respect the instance's `logLevel` setting for output filtering:
160

161
- **info**: Shows all loggers (default)
162
- **timer**: Shows timer, debug, warn, error, fatal loggers  
163
- **debug**: Shows debug, warn, error, fatal loggers
164
- **warn**: Shows warn, error, fatal loggers
165
- **error**: Shows error, fatal loggers only
166

167
**Usage Examples:**
168

169
```javascript
170
const { Signale } = require('signale');
171

172
const logger = new Signale({ logLevel: 'warn' });
173

174
logger.info('This will not appear');     // Filtered out
175
logger.debug('This will not appear');    // Filtered out  
176
logger.warn('This will appear');         // Shown
177
logger.error('This will appear');        // Shown
178
logger.fatal('This will appear');        // Shown
179
```