0
# Enable/Disable Control
1

2
Runtime control over log visibility with restore functionality. Allows temporarily disabling logs and restoring previous state, useful for testing, debugging, and conditional logging scenarios.
3

4
## Capabilities
5

6
### Enable State Property
7

8
Each logger has an `isEnabled` property that controls whether its logs are actually output.
9

10
```javascript { .api }
11
/**
12
 * Whether logger logs are exposed/visible
13
 * @type {boolean}
14
 */
15
log.isEnabled;
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
const log = require("log");
22

23
// Check current state
24
console.log(log.isEnabled); // true (default)
25

26
// Manually set enabled state
27
log.isEnabled = false;
28
log("This won't be logged");
29

30
log.isEnabled = true;  
31
log("This will be logged");
32

33
// Check namespace logger state
34
const appLogger = log.get("myapp");
35
console.log(appLogger.isEnabled); // true (inherits from parent)
36
```
37

38
### Enable Method
39

40
Re-enables logging for a logger and all its namespaced children.
41

42
```javascript { .api }
43
/**
44
 * Enables logger and all its namespaced children
45
 * @returns {RestoreObject} Object with restore() method to revert changes
46
 */
47
log.enable();
48

49
interface RestoreObject {
50
  /**
51
   * Restores the previous enabled/disabled state
52
   */
53
  restore(): void;
54
}
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
const log = require("log");
61

62
// Disable logger first
63
log.isEnabled = false;
64

65
// Enable with restore capability
66
const { restore } = log.enable();
67

68
console.log(log.isEnabled); // true
69
log("This will be logged");
70

71
// Restore previous state
72
restore();
73
console.log(log.isEnabled); // false
74
```
75

76
### Disable Method
77

78
Disables logging for a logger and all its namespaced children.
79

80
```javascript { .api }
81
/**
82
 * Disables logger and all its namespaced children  
83
 * @returns {RestoreObject} Object with restore() method to revert changes
84
 */
85
log.disable();
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
const log = require("log");
92

93
// Disable with restore capability
94
const { restore } = log.disable();
95

96
console.log(log.isEnabled); // false
97
log("This won't be logged");
98

99
// Restore previous state
100
restore();
101
console.log(log.isEnabled); // true
102
log("This will be logged again");
103
```
104

105
## Hierarchical Control
106

107
### Parent-Child Relationships
108

109
Enabling or disabling a logger affects all its namespaced children.
110

111
```javascript
112
const log = require("log");
113

114
// Create namespaced loggers
115
const appLogger = log.get("myapp");
116
const dbLogger = appLogger.get("database"); // "myapp:database"
117

118
// Disable root logger affects all children
119
const { restore } = log.disable();
120

121
console.log(log.isEnabled);       // false
122
console.log(appLogger.isEnabled); // false  
123
console.log(dbLogger.isEnabled);  // false
124

125
// Restore affects all children
126
restore();
127

128
console.log(log.isEnabled);       // true
129
console.log(appLogger.isEnabled); // true
130
console.log(dbLogger.isEnabled);  // true
131
```
132

133
### Granular Control
134

135
Individual namespace loggers can be controlled independently.
136

137
```javascript
138
const log = require("log");
139

140
const appLogger = log.get("myapp");
141
const dbLogger = log.get("database");
142

143
// Disable only app logger
144
const { restore: restoreApp } = appLogger.disable();
145

146
console.log(log.isEnabled);       // true (root still enabled)
147
console.log(appLogger.isEnabled); // false
148
console.log(dbLogger.isEnabled);  // true (different namespace)
149

150
// App logger children are also disabled
151
const authLogger = appLogger.get("auth");
152
console.log(authLogger.isEnabled); // false
153

154
// Restore only app logger
155
restoreApp();
156
console.log(appLogger.isEnabled); // true
157
```
158

159
## State Management
160

161
### Multiple Disable/Enable Calls
162

163
Multiple calls to enable/disable create nested restore points.
164

165
```javascript
166
const log = require("log");
167

168
// First disable
169
const { restore: restore1 } = log.disable();
170
console.log(log.isEnabled); // false
171

172
// Second disable (already disabled)
173
const { restore: restore2 } = log.disable();
174
console.log(log.isEnabled); // still false
175

176
// Enable while disabled
177
const { restore: restore3 } = log.enable();
178
console.log(log.isEnabled); // true
179

180
// Restore in reverse order
181
restore3(); // Back to disabled state from restore2
182
console.log(log.isEnabled); // false
183

184
restore2(); // Back to disabled state from restore1
185
console.log(log.isEnabled); // false
186

187
restore1(); // Back to original state
188
console.log(log.isEnabled); // true
189
```
190

191
### Restore Object Behavior
192

193
Restore objects can only be used once and become no-ops after first use.
194

195
```javascript
196
const log = require("log");
197

198
const { restore } = log.disable();
199
console.log(log.isEnabled); // false
200

201
// First restore call works
202
restore();
203
console.log(log.isEnabled); // true
204

205
// Subsequent calls are no-ops
206
restore(); // Does nothing
207
console.log(log.isEnabled); // still true
208
```
209

210
### Direct Property vs Methods
211

212
Direct property assignment doesn't provide restore capability.
213

214
```javascript
215
const log = require("log");
216

217
// Direct assignment - no restore
218
log.isEnabled = false;
219
// No way to restore previous state
220

221
// Method call - provides restore
222
const { restore } = log.disable();
223
// Can restore previous state
224
restore();
225
```
226

227
## Use Cases
228

229
### Testing Scenarios
230

231
```javascript
232
const log = require("log");
233

234
describe("MyModule", () => {
235
  let restoreLog;
236
  
237
  beforeEach(() => {
238
    // Disable logs during tests
239
    restoreLog = log.disable();
240
  });
241
  
242
  afterEach(() => {
243
    // Restore logs after each test
244
    restoreLog.restore();
245
  });
246
  
247
  it("should work without log output", () => {
248
    // Test code here - no log output
249
  });
250
});
251
```
252

253
### Conditional Logging
254

255
```javascript
256
const log = require("log");
257

258
function debugFunction(enableDebugLogs = false) {
259
  const debugLogger = log.get("debug");
260
  
261
  let restore;
262
  if (!enableDebugLogs) {
263
    restore = debugLogger.disable();
264
  }
265
  
266
  // Function logic with debug logs
267
  debugLogger.info("Debug info here");
268
  
269
  // Restore if disabled
270
  if (restore) {
271
    restore.restore();
272
  }
273
}
274
```
275

276
### Temporary Silence
277

278
```javascript
279
const log = require("log");
280

281
function performQuietOperation() {
282
  // Temporarily disable all logging
283
  const { restore } = log.disable();
284
  
285
  try {
286
    // Perform operation that would normally log
287
    noisyOperation();
288
  } finally {
289
    // Always restore logging
290
    restore();
291
  }
292
}
293
```
294

295
### Namespace-Specific Control
296

297
```javascript
298
const log = require("log");
299

300
// Disable specific noisy components
301
const thirdPartyRestore = log.get("third-party").disable();
302
const verboseRestore = log.get("verbose-module").disable();
303

304
// Application continues with reduced log output
305
runApplication();
306

307
// Re-enable when needed
308
thirdPartyRestore.restore();
309
verboseRestore.restore();
310
```