0
# loglevel
1

2
Minimal lightweight logging for JavaScript, adding reliable log level methods to any available console.log methods across all environments (browsers, Node.js, etc.) with zero dependencies.
3

4
## Package Information
5

6
- **Package Name**: loglevel
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install loglevel`
10

11
## Core Imports
12

13
ES6 imports:
14

15
```javascript
16
import log from 'loglevel';
17
```
18

19
For some tools, wildcard import:
20

21
```javascript
22
import * as log from 'loglevel';
23
```
24

25
CommonJS:
26

27
```javascript
28
const log = require('loglevel');
29
```
30

31
Direct usage (browser):
32

33
```html
34
<script src="loglevel.min.js"></script>
35
<script>
36
  // Available as global 'log'
37
</script>
38
```
39

40
## Basic Usage
41

42
```javascript
43
import log from 'loglevel';
44

45
// Set the logging level (defaults to "warn")
46
log.setLevel("info");
47

48
// Use different logging levels
49
log.trace("Very detailed debug info");
50
log.debug("Debug information");
51
log.info("General information");
52
log.warn("Warning message");
53
log.error("Error occurred!");
54

55
// Disable all logging
56
log.disableAll();
57

58
// Enable all logging
59
log.enableAll();
60
```
61

62
## Architecture
63

64
loglevel provides a simple yet powerful architecture with these key components:
65

66
- **Root Logger**: The default logger instance with global methods
67
- **Named Loggers**: Independent logger instances for modular applications
68
- **Level System**: Hierarchical filtering (TRACE → DEBUG → INFO → WARN → ERROR → SILENT)
69
- **Plugin System**: Extensible method factory for custom logging behavior
70
- **Persistence**: Automatic level persistence via localStorage/cookies
71
- **Environment Adaptation**: Graceful fallbacks across all JavaScript environments
72

73
## Capabilities
74

75
### Basic Logging
76

77
Core logging methods that provide reliable output across all JavaScript environments with proper fallbacks and line number preservation.
78

79
```javascript { .api }
80
/**
81
 * Output trace message with full stack trace
82
 * @param {...any} msg - Any data to log to the console
83
 */
84
trace(...msg: any[]): void;
85

86
/**
87
 * Output debug message (alias: log)
88
 * @param {...any} msg - Any data to log to the console
89
 */
90
debug(...msg: any[]): void;
91

92
/**
93
 * Alias for debug method
94
 * @param {...any} msg - Any data to log to the console
95
 */
96
log(...msg: any[]): void;
97

98
/**
99
 * Output info message
100
 * @param {...any} msg - Any data to log to the console
101
 */
102
info(...msg: any[]): void;
103

104
/**
105
 * Output warning message
106
 * @param {...any} msg - Any data to log to the console
107
 */
108
warn(...msg: any[]): void;
109

110
/**
111
 * Output error message
112
 * @param {...any} msg - Any data to log to the console
113
 */
114
error(...msg: any[]): void;
115
```
116

117
[Basic Logging Documentation](./basic-logging.md)
118

119
### Level Control
120

121
Manage logging levels with persistence, providing fine-grained control over which messages are displayed.
122

123
```javascript { .api }
124
/**
125
 * Log level constants
126
 */
127
interface LogLevel {
128
  TRACE: 0;
129
  DEBUG: 1;
130
  INFO: 2;
131
  WARN: 3;
132
  ERROR: 4;
133
  SILENT: 5;
134
}
135

136
/**
137
 * Possible log level numbers
138
 */
139
type LogLevelNumbers = 0 | 1 | 2 | 3 | 4 | 5;
140

141
/**
142
 * Possible log level names (lowercase)
143
 */
144
type LogLevelNames = 'trace' | 'debug' | 'info' | 'warn' | 'error';
145

146
/**
147
 * Valid log level descriptors
148
 * Accepts numbers, lowercase strings, uppercase strings, or 'silent'
149
 */
150
type LogLevelDesc = LogLevelNumbers | LogLevelNames | 'silent' | keyof LogLevel;
151

152
/**
153
 * Set the current logging level
154
 * @param {LogLevelDesc} level - Level name, number, or constant
155
 * @param {boolean} persist - Whether to persist the level (default: true)
156
 */
157
setLevel(level: LogLevelDesc, persist?: boolean): void;
158

159
/**
160
 * Get current logging level as number
161
 * @returns {LogLevelNumbers} Current level (0-5)
162
 */
163
getLevel(): LogLevelNumbers;
164
```
165

166
[Level Control Documentation](./level-control.md)
167

168
### Multi-Logger System
169

170
Create and manage multiple independent logger instances for modular applications.
171

172
```javascript { .api }
173
/**
174
 * Create or retrieve a named logger instance
175
 * @param {string | symbol} name - Logger name (non-empty string or symbol)
176
 * @returns {Logger} Logger instance with independent level settings
177
 */
178
getLogger(name: string | symbol): Logger;
179

180
/**
181
 * Get dictionary of all created loggers
182
 * @returns {Object} Object with logger names as keys and Logger instances as values
183
 */
184
getLoggers(): { [name: string]: Logger };
185

186
/**
187
 * Release global 'log' variable and return loglevel instance
188
 * @returns {RootLogger} The loglevel root logger instance
189
 */
190
noConflict(): RootLogger;
191

192
/**
193
 * ES6 default export compatibility property
194
 * Points to the root logger instance for consistent import behavior
195
 */
196
default: RootLogger;
197
```
198

199
[Multi-Logger Documentation](./multi-logger.md)
200

201
### Plugin System
202

203
Extend loglevel with custom logging behavior through the method factory system.
204

205
```javascript { .api }
206
/**
207
 * Method factory function type for creating logging methods
208
 * @param {string} methodName - Logging method name ('trace', 'debug', 'info', 'warn', 'error')
209
 * @param {number} level - Current logging level (0-5)
210
 * @param {string | symbol | undefined} loggerName - Name of the logger instance (undefined for root logger)
211
 * @returns {Function} Logging method implementation
212
 */
213
type MethodFactory = (methodName: string, level: number, loggerName: string | symbol | undefined) => (...message: any[]) => void;
214

215
/**
216
 * Plugin API entry point for custom method factories
217
 */
218
methodFactory: MethodFactory;
219

220
/**
221
 * Rebuild logging methods (for plugin developers)
222
 */
223
rebuild(): void;
224
```
225

226
[Plugin System Documentation](./plugins.md)