0
# Level Control
1

2
Manage logging levels with persistence, providing fine-grained control over which messages are displayed across different environments.
3

4
## Capabilities
5

6
### setLevel
7

8
```javascript { .api }
9
/**
10
 * Set the current logging level
11
 * Disables all logging below the specified level
12
 * @param {LogLevelDesc} level - Level as string, number, or constant
13
 * @param {boolean} persist - Whether to persist level (default: true)
14
 * @throws {TypeError} When invalid level is provided
15
 */
16
setLevel(level: LogLevelDesc, persist?: boolean): void;
17

18
// Valid level descriptors
19
type LogLevelDesc = 
20
  | 0 | 1 | 2 | 3 | 4 | 5  // Numbers
21
  | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'  // Lowercase strings
22
  | 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT';  // Uppercase strings
23

24
// Level constants
25
interface LogLevel {
26
  TRACE: 0;
27
  DEBUG: 1;
28
  INFO: 2;
29
  WARN: 3;
30
  ERROR: 4;
31
  SILENT: 5;
32
}
33

34
// Level number type
35
type LogLevelNumbers = 0 | 1 | 2 | 3 | 4 | 5;
36
```
37

38
**Usage Examples:**
39

40
```javascript
41
import log from 'loglevel';
42

43
// String levels (case-insensitive)
44
log.setLevel("warn");
45
log.setLevel("ERROR");
46

47
// Numeric levels
48
log.setLevel(2); // INFO level
49

50
// Level constants
51
log.setLevel(log.levels.DEBUG);
52

53
// Disable persistence
54
log.setLevel("info", false);
55

56
// After setting to "warn", only warn and error messages show
57
log.debug("This won't appear");
58
log.warn("This will appear");
59
log.error("This will appear");
60
```
61

62
### getLevel
63

64
```javascript { .api }
65
/**
66
 * Get current logging level as number
67
 * Useful for level-based conditional logic
68
 * @returns {LogLevelNumbers} Current level (0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=SILENT)
69
 */
70
getLevel(): LogLevelNumbers;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
import log from 'loglevel';
77

78
log.setLevel("info");
79
const currentLevel = log.getLevel(); // Returns 2
80

81
// Conditional logging based on level
82
if (log.getLevel() <= log.levels.DEBUG) {
83
  const expensiveDebugData = generateDebugInfo();
84
  log.debug("Debug data:", expensiveDebugData);
85
}
86

87
// Level comparison
88
if (log.getLevel() < log.levels.ERROR) {
89
  log.warn("Non-critical warning message");
90
}
91
```
92

93
### setDefaultLevel
94

95
```javascript { .api }
96
/**
97
 * Set default level without affecting persisted settings
98
 * Used for initial configuration that users can override
99
 * @param {LogLevelDesc} level - Level as string, number, or constant
100
 */
101
setDefaultLevel(level: LogLevelDesc): void;
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
import log from 'loglevel';
108

109
// Application initialization
110
log.setDefaultLevel("warn"); // Default for production
111

112
// If user previously set a level, it stays active
113
// If no persisted level exists, uses "warn"
114

115
// Useful for library initialization
116
function initializeLibrary() {
117
  log.setDefaultLevel("error"); // Libraries should be quiet by default
118
}
119
```
120

121
### resetLevel
122

123
```javascript { .api }
124
/**
125
 * Reset to default level and clear persisted level
126
 * Restores initial logging configuration
127
 */
128
resetLevel(): void;
129
```
130

131
**Usage Examples:**
132

133
```javascript
134
import log from 'loglevel';
135

136
// User sets custom level
137
log.setLevel("trace");
138

139
// Later, reset to default
140
log.resetLevel(); // Returns to "warn" (or setDefaultLevel value)
141

142
// Clears localStorage/cookie persistence
143
// Useful for logout or session reset
144
function resetUserSession() {
145
  log.resetLevel();
146
}
147
```
148

149
### enableAll
150

151
```javascript { .api }
152
/**
153
 * Enable all logging (equivalent to setLevel("trace"))
154
 * Shows maximum detail for debugging
155
 * @param {boolean} persist - Whether to persist setting (default: true)
156
 */
157
enableAll(persist?: boolean): void;
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
import log from 'loglevel';
164

165
// Development debugging
166
log.enableAll();
167

168
// Temporary debugging without persistence
169
log.enableAll(false);
170

171
// Console debugging session
172
// log.enableAll() - run this in browser console for full logging
173
```
174

175
### disableAll
176

177
```javascript { .api }
178
/**
179
 * Disable all logging (equivalent to setLevel("silent"))
180
 * Completely suppresses log output
181
 * @param {boolean} persist - Whether to persist setting (default: true)
182
 */
183
disableAll(persist?: boolean): void;
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
import log from 'loglevel';
190

191
// Production silence
192
log.disableAll();
193

194
// Temporary quiet mode
195
log.disableAll(false);
196

197
// Performance-critical sections
198
function performanceCriticalOperation() {
199
  log.disableAll(false);
200
  // ... intensive operations ...
201
  log.setLevel("warn"); // Restore normal level
202
}
203
```
204

205
## Level Hierarchy
206

207
Levels follow a strict hierarchy where higher levels include all lower levels:
208

209
```
210
TRACE (0) ← Most verbose
211
  ↓
212
DEBUG (1)
213
  ↓
214
INFO (2)
215
  ↓
216
WARN (3) ← Default level
217
  ↓
218
ERROR (4)
219
  ↓
220
SILENT (5) ← No output
221
```
222

223
**Usage Examples:**
224

225
```javascript
226
import log from 'loglevel';
227

228
// Set to INFO level
229
log.setLevel("info");
230

231
// These will output:
232
log.info("Info message");    // ✓ Level 2
233
log.warn("Warning");         // ✓ Level 3  
234
log.error("Error");          // ✓ Level 4
235

236
// These will be silent:
237
log.trace("Trace message");  // ✗ Level 0
238
log.debug("Debug info");     // ✗ Level 1
239
```
240

241
## Persistence
242

243
Levels are automatically persisted across page reloads and sessions:
244

245
- **Primary**: localStorage (when available)
246
- **Fallback**: Session cookies
247
- **Node.js**: No persistence (manual configuration required)
248

249
```javascript
250
import log from 'loglevel';
251

252
// Persisted by default
253
log.setLevel("debug"); 
254
// Level survives page reload
255

256
// Temporary level (not persisted)
257
log.setLevel("trace", false);
258
// Resets to previous persistent level on reload
259

260
// Clear persistence
261
log.resetLevel();
262
// Removes stored level setting
263
```