0
# Custom Loggers
1

2
Create and configure custom logger types with personalized badges, colors, labels, and behavior. Custom loggers allow you to extend Signale with domain-specific logging types while maintaining consistent styling and functionality.
3

4
## Capabilities
5

6
### Signale Constructor
7

8
Create custom Signale instances with personalized logger types and configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Signale instance with custom configuration
13
 * @param options - Configuration object for the instance
14
 */
15
const { Signale } = require('signale');
16

17
const customLogger = new Signale(options);
18

19
interface SignaleOptions {
20
  disabled?: boolean;                           // Disable all logging (default: false)
21
  interactive?: boolean;                        // Enable interactive mode (default: false) 
22
  logLevel?: LogLevel;                         // Set minimum log level (default: 'info')
23
  scope?: string | string[];                   // Set logger scope name(s)
24
  secrets?: (string | number)[];               // Array of secrets to filter from logs
25
  stream?: WritableStream | WritableStream[];  // Output stream(s) (default: process.stdout)
26
  types?: Record<string, LoggerType>;          // Custom logger type definitions
27
  timers?: Map<string, number>;                // Pre-existing timers map
28
}
29

30
type LogLevel = 'info' | 'timer' | 'debug' | 'warn' | 'error';
31
type WritableStream = NodeJS.WritableStream;
32
```
33

34
### Custom Logger Type Definition
35

36
Define custom logger types with specific visual styling and behavior.
37

38
```javascript { .api }
39
interface LoggerType {
40
  badge?: string;                              // Icon/symbol for the logger (Unicode supported)
41
  color?: ChalkColor;                         // Color name from chalk library
42
  label?: string;                             // Text label displayed next to badge
43
  logLevel?: LogLevel;                        // Minimum level for this logger to output
44
  stream?: WritableStream | WritableStream[]; // Custom output stream(s) for this logger
45
}
46

47
// Supported chalk colors
48
type ChalkColor = 
49
  | 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white'
50
  | 'gray' | 'grey' | 'blackBright' | 'redBright' | 'greenBright' | 'yellowBright'
51
  | 'blueBright' | 'magentaBright' | 'cyanBright' | 'whiteBright';
52
```
53

54
### Creating Custom Loggers
55

56
**Usage Examples:**
57

58
```javascript
59
const { Signale } = require('signale');
60

61
// Define custom logger types
62
const options = {
63
  types: {
64
    remind: {
65
      badge: '**',
66
      color: 'yellow',
67
      label: 'reminder',
68
      logLevel: 'info'
69
    },
70
    santa: {
71
      badge: '🎅',
72
      color: 'red', 
73
      label: 'santa',
74
      logLevel: 'info'
75
    },
76
    rocket: {
77
      badge: '🚀',
78
      color: 'cyan',
79
      label: 'launch',
80
      logLevel: 'info'
81
    }
82
  }
83
};
84

85
const custom = new Signale(options);
86

87
// Use custom loggers (automatically added as methods)
88
custom.remind('Update the documentation');
89
custom.santa('Ho ho ho! Check your code on line 42');
90
custom.rocket('Deployment initiated');
91
```
92

93
### Overriding Default Loggers
94

95
Customize existing default logger types by redefining them in the `types` option.
96

97
**Usage Examples:**
98

99
```javascript
100
const { Signale } = require('signale');
101

102
// Override default error and success loggers
103
const options = {
104
  types: {
105
    error: {
106
      badge: '!!',
107
      color: 'red',
108
      label: 'FATAL ERROR'
109
    },
110
    success: {
111
      badge: '++',
112
      color: 'green', 
113
      label: 'HUGE SUCCESS'
114
    }
115
  }
116
};
117

118
const custom = new Signale(options);
119

120
// Compare default vs custom
121
const defaultLogger = new Signale();
122
defaultLogger.error('Default error message');    // ✖  error    Default error message
123
defaultLogger.success('Default success message'); // ✔  success  Default success message
124

125
custom.error('Custom error message');             // !!  FATAL ERROR     Custom error message  
126
custom.success('Custom success message');         // ++  HUGE SUCCESS    Custom success message
127
```
128

129
### Logger-Specific Streams
130

131
Configure different output streams for individual logger types.
132

133
**Usage Examples:**
134

135
```javascript
136
const { Signale } = require('signale');
137
const fs = require('fs');
138

139
// Create custom streams
140
const errorStream = fs.createWriteStream('errors.log');
141
const debugStream = fs.createWriteStream('debug.log');
142

143
const options = {
144
  stream: process.stderr,  // Default stream for all loggers
145
  types: {
146
    error: {
147
      // Error logs go to both console and file
148
      stream: [process.stderr, errorStream]
149
    },
150
    debug: {
151
      // Debug logs only go to file
152
      stream: debugStream,
153
      color: 'gray',
154
      label: 'debug'
155
    },
156
    custom: {
157
      badge: '🔧',
158
      color: 'blue',
159
      label: 'custom',
160
      // Uses default stream (process.stderr)
161
    }
162
  }
163
};
164

165
const logger = new Signale(options);
166

167
logger.error('This appears in console AND errors.log');
168
logger.debug('This appears only in debug.log');  
169
logger.custom('This appears in console only');
170
```
171

172
### Mixed Default and Custom Types
173

174
Combine default loggers with custom ones in a single instance.
175

176
**Usage Examples:**
177

178
```javascript  
179
const { Signale } = require('signale');
180

181
const options = {
182
  types: {
183
    // Add custom loggers alongside defaults
184
    deploy: {
185
      badge: '🚀',
186
      color: 'magenta',
187
      label: 'deploy',
188
      logLevel: 'info'
189
    },
190
    security: {
191
      badge: '🔒',
192
      color: 'red',
193
      label: 'security',
194
      logLevel: 'warn'
195
    }
196
  }
197
};
198

199
const logger = new Signale(options);
200

201
// Use both default and custom loggers
202
logger.info('Application started');           // Default logger
203
logger.deploy('Deploying to production');    // Custom logger  
204
logger.success('Deployment completed');      // Default logger
205
logger.security('Suspicious activity detected'); // Custom logger
206
logger.error('Deployment failed');           // Default logger
207
```
208

209
### Dynamic Logger Creation
210

211
Access and modify logger types at runtime through the instance properties.
212

213
**Usage Examples:**
214

215
```javascript
216
const { Signale } = require('signale');
217

218
const logger = new Signale();
219

220
// Access current options (readonly)
221
console.log(logger.currentOptions);
222
// {
223
//   config: {...},
224
//   disabled: false,
225
//   types: {...},
226
//   interactive: false,
227
//   timers: Map {},
228
//   stream: [object Object],
229
//   secrets: [],
230
//   logLevel: 'info'
231
// }
232

233
// Create new instance with additional types
234
const extendedOptions = {
235
  ...logger.currentOptions,
236
  types: {
237
    ...logger.currentOptions.types,
238
    newType: {
239
      badge: '⭐',
240
      color: 'yellow',
241
      label: 'special'
242
    }
243
  }
244
};
245

246
const extended = new Signale(extendedOptions);
247
extended.newType('This is a new logger type');
248
```