0
# Signale
1
2
Signale is a hackable and configurable console logger for Node.js applications that provides 17 out-of-the-box logger types with clean and beautiful output formatting. It offers advanced features including integrated timers, custom pluggable loggers, interactive and regular modes, secrets filtering, filename/date/timestamp support, scoped loggers, scaled logging levels, string interpolation, multiple configurable writable streams, and global configuration through package.json.
3
4
## Package Information
5
6
- **Package Name**: signale
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install signale`
10
11
## Core Imports
12
13
```javascript
14
const signale = require('signale');
15
```
16
17
For accessing the Signale class constructor:
18
19
```javascript
20
const { Signale } = require('signale');
21
```
22
23
## Basic Usage
24
25
```javascript
26
const signale = require('signale');
27
28
// Use built-in loggers
29
signale.success('Operation successful');
30
signale.error('Something went wrong');
31
signale.warn('This is a warning');
32
signale.info('Informational message');
33
signale.debug('Debug information');
34
35
// String interpolation support
36
signale.pending('Processing %s items...', 42);
37
signale.complete({
38
prefix: '[task]',
39
message: 'Fix issue #59',
40
suffix: '(@username)'
41
});
42
43
// Handle Error objects
44
signale.fatal(new Error('Critical failure'));
45
```
46
47
## Architecture
48
49
Signale is built around several key components:
50
51
- **Default Logger Instance**: Pre-configured instance with 17 built-in logger types for immediate use
52
- **Signale Class**: Constructor for creating custom logger instances with configurable options
53
- **Logger Types System**: Pluggable logger type definitions with badges, colors, and labels
54
- **Configuration System**: Global (package.json) and per-instance configuration options
55
- **Scoped Loggers**: Hierarchical logger scoping with inheritance for organized logging
56
- **Timer System**: Integrated timing functionality with automatic label management
57
- **Secrets Filtering**: Built-in filtering system for sensitive information protection
58
- **Stream Management**: Multiple configurable writable streams for flexible output control
59
60
## Capabilities
61
62
### Core Logging
63
64
Built-in logger types with pre-configured styling and behavior. Includes 16 default loggers for common logging scenarios.
65
66
```javascript { .api }
67
// Default logger methods (available on signale instance)
68
signale.await(message);
69
signale.complete(message);
70
signale.debug(message);
71
signale.error(message);
72
signale.fatal(message);
73
signale.fav(message);
74
signale.info(message);
75
signale.log(message);
76
signale.note(message);
77
signale.pause(message);
78
signale.pending(message);
79
signale.star(message);
80
signale.start(message);
81
signale.success(message);
82
signale.wait(message);
83
signale.warn(message);
84
signale.watch(message);
85
86
// Message types supported
87
type LogMessage = string | string[] | {prefix?: string, message: string | string[], suffix?: string} | Error;
88
```
89
90
[Core Logging](./core-logging.md)
91
92
### Custom Loggers
93
94
Create and configure custom logger types with personalized badges, colors, labels, and behavior.
95
96
```javascript { .api }
97
const { Signale } = require('signale');
98
99
// Constructor options
100
interface SignaleOptions {
101
disabled?: boolean;
102
interactive?: boolean;
103
logLevel?: 'info' | 'timer' | 'debug' | 'warn' | 'error';
104
scope?: string | string[];
105
secrets?: (string | number)[];
106
stream?: NodeJS.WritableStream | NodeJS.WritableStream[];
107
types?: Record<string, LoggerType>;
108
}
109
110
interface LoggerType {
111
badge?: string;
112
color?: string;
113
label?: string;
114
logLevel?: 'info' | 'timer' | 'debug' | 'warn' | 'error';
115
stream?: NodeJS.WritableStream | NodeJS.WritableStream[];
116
}
117
118
const customLogger = new Signale(options);
119
```
120
121
[Custom Loggers](./custom-loggers.md)
122
123
### Scoped Loggers
124
125
Create hierarchical scoped loggers with inheritance for organized logging across different modules and components.
126
127
```javascript { .api }
128
// Create scoped logger
129
function scope(...name: string[]): Signale;
130
131
// Remove scope
132
function unscope(): void;
133
134
// Properties
135
readonly scopeName: string;
136
```
137
138
[Scoped Loggers](./scoped-loggers.md)
139
140
### Timers
141
142
Integrated timer functionality for measuring operation duration with automatic labeling and formatted output.
143
144
```javascript { .api }
145
// Timer methods
146
function time(label?: string): string;
147
function timeEnd(label?: string): {label: string, span: number} | undefined;
148
```
149
150
[Timers](./timers.md)
151
152
### Configuration & Settings
153
154
Global and instance-level configuration options for customizing logger behavior, appearance, and output format.
155
156
```javascript { .api }
157
// Configuration method
158
function config(settingsObj: ConfigOptions): void;
159
160
interface ConfigOptions {
161
displayScope?: boolean;
162
displayBadge?: boolean;
163
displayDate?: boolean;
164
displayFilename?: boolean;
165
displayLabel?: boolean;
166
displayTimestamp?: boolean;
167
underlineLabel?: boolean;
168
underlineMessage?: boolean;
169
underlinePrefix?: boolean;
170
underlineSuffix?: boolean;
171
uppercaseLabel?: boolean;
172
}
173
```
174
175
[Configuration & Settings](./configuration.md)
176
177
### Advanced Features
178
179
Interactive mode, secrets filtering, stream management, and state control for advanced logging scenarios.
180
181
```javascript { .api }
182
// State control
183
function disable(): void;
184
function enable(): void;
185
function isEnabled(): boolean;
186
187
// Secrets management
188
function addSecrets(secrets: (string | number)[]): void;
189
function clearSecrets(): void;
190
191
// Properties
192
readonly currentOptions: SignaleOptions;
193
readonly date: string;
194
readonly timestamp: string;
195
readonly filename: string;
196
readonly packageConfiguration: object;
197
```
198
199
[Advanced Features](./advanced-features.md)
200
201
## Global Types
202
203
```javascript { .api }
204
// Built-in logger type names
205
type DefaultLoggerType =
206
| 'await' | 'complete' | 'debug' | 'error' | 'fatal' | 'fav'
207
| 'info' | 'log' | 'note' | 'pause' | 'pending' | 'star'
208
| 'start' | 'success' | 'wait' | 'warn' | 'watch';
209
210
// Log levels for filtering
211
type LogLevel = 'info' | 'timer' | 'debug' | 'warn' | 'error';
212
213
// Scope definition
214
type ScopeNames = string | string[];
215
216
// Writable stream types (Node.js)
217
type WritableStream = NodeJS.WritableStream;
218
type StreamTarget = WritableStream | WritableStream[];
219
```