0
# Namespace Management
1

2
Debug-lib style namespacing system for organizing logs by module, component, or feature area. Supports nested namespaces with colon separation and provides methods for namespace inspection and management.
3

4
## Capabilities
5

6
### Creating Namespaced Loggers
7

8
Create or retrieve loggers for specific namespaces to organize log output by logical boundaries.
9

10
```javascript { .api }
11
/**
12
 * Creates or retrieves a namespaced logger
13
 * @param {string} namespace - Namespace string using colon separation (e.g., "module:component")
14
 * @returns {Logger} Logger instance for the specified namespace
15
 * @throws {TypeError} If namespace contains invalid characters
16
 */
17
log.get(namespace);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const log = require("log");
24

25
// Create single-level namespace
26
const dbLogger = log.get("database");
27
dbLogger.info("Connection established");
28

29
// Create nested namespace
30
const userServiceLogger = log.get("service:user");
31
userServiceLogger.error("User not found: %d", userId);
32

33
// Further nesting
34
const authLogger = userServiceLogger.get("auth");
35
authLogger.debug("Token validated for user %s", username);
36

37
// Equivalent to:
38
const authLogger2 = log.get("service:user:auth");
39
console.log(authLogger === authLogger2); // true - same instance returned
40
```
41

42
### Namespace Properties
43

44
Each logger exposes properties describing its namespace configuration.
45

46
```javascript { .api }
47
/**
48
 * Full namespace string or null for root logger
49
 * @type {string|null}
50
 */
51
log.namespace;
52

53
/**
54
 * Array of namespace components
55
 * @type {string[]}
56
 */
57
log.namespaceTokens;
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const log = require("log");
64

65
// Root logger properties
66
console.log(log.namespace);        // null
67
console.log(log.namespaceTokens);  // []
68

69
// Namespaced logger properties
70
const nsLogger = log.get("service:user:auth");
71
console.log(nsLogger.namespace);       // "service:user:auth"
72
console.log(nsLogger.namespaceTokens); // ["service", "user", "auth"]
73

74
// Single namespace
75
const dbLogger = log.get("database");
76
console.log(dbLogger.namespace);       // "database"
77
console.log(dbLogger.namespaceTokens); // ["database"]
78
```
79

80
### Namespace Validation
81

82
Namespace strings must follow specific rules for valid tokens.
83

84
```javascript { .api }
85
/**
86
 * Valid namespace tokens contain only: a-z, 0-9, hyphen (-)
87
 * Multiple tokens separated by colon (:)
88
 * Examples of valid namespaces:
89
 * - "app"
90
 * - "user-service"  
91
 * - "api:v1:users"
92
 * - "db:connection:pool"
93
 * 
94
 * Invalid examples:
95
 * - "User" (uppercase not allowed)
96
 * - "api_v1" (underscore not allowed)
97
 * - "test::double" (empty token not allowed)
98
 */
99
```
100

101
**Validation Examples:**
102

103
```javascript
104
const log = require("log");
105

106
// Valid namespaces
107
log.get("app");                    // ✓ Valid
108
log.get("user-service");           // ✓ Valid  
109
log.get("api:v1:users");           // ✓ Valid
110
log.get("db:connection:pool");     // ✓ Valid
111

112
// Invalid namespaces (throw TypeError)
113
try {
114
  log.get("User");                 // ✗ Uppercase not allowed
115
} catch (e) {
116
  console.log(e.message); // TypeError with validation details
117
}
118

119
try {
120
  log.get("api_v1");               // ✗ Underscore not allowed  
121
} catch (e) {
122
  console.log(e.message);
123
}
124
```
125

126
### Namespace Inspection
127

128
Methods for checking namespace initialization and retrieving namespace loggers.
129

130
```javascript { .api }
131
/**
132
 * Check if a namespace has been initialized (logger created)
133
 * @param {string} namespace - Namespace string to check
134
 * @returns {boolean} True if namespace logger exists
135
 */
136
log.isNamespaceInitialized(namespace);
137

138
/**
139
 * Get all initialized namespace loggers for the current level
140
 * @returns {Logger[]} Array of initialized namespace logger instances
141
 */
142
log.getAllInitializedNamespaces();
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const log = require("log");
149

150
// Check before creation
151
console.log(log.isNamespaceInitialized("myapp"));        // false
152

153
// Create namespace logger
154
const appLogger = log.get("myapp");
155

156
// Check after creation
157
console.log(log.isNamespaceInitialized("myapp"));        // true
158

159
// Nested namespace checking
160
console.log(log.isNamespaceInitialized("myapp:auth"));   // false
161
const authLogger = log.get("myapp:auth");
162
console.log(log.isNamespaceInitialized("myapp:auth"));   // true
163

164
// Get all initialized namespaces for current level
165
const namespaces = log.getAllInitializedNamespaces();
166
console.log(namespaces.map(logger => logger.namespace)); // ["myapp", "myapp:auth"]
167

168
// Different levels have separate namespace tracking
169
const errorLogger = log.error.get("service");
170
console.log(log.error.getAllInitializedNamespaces().length); // 1
171
console.log(log.info.getAllInitializedNamespaces().length);  // Still 2
172
```
173

174
## Namespace Behavior
175

176
### Logger Instance Reuse
177

178
Namespace loggers are singletons - calling `get()` with the same namespace always returns the same instance.
179

180
```javascript
181
const log = require("log");
182

183
const logger1 = log.get("service");
184
const logger2 = log.get("service"); 
185
console.log(logger1 === logger2); // true - same instance
186

187
// Works across different access patterns
188
const logger3 = log.info.get("service");
189
console.log(logger1 === logger3); // true - same instance
190
```
191

192
### Level Inheritance
193

194
Namespaced loggers inherit all level methods from their parent logger.
195

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

199
const appLogger = log.get("myapp");
200

201
// All level methods available
202
appLogger.error("Critical error in myapp");
203
appLogger.warning("Warning in myapp");
204
appLogger.info("Info from myapp");
205
appLogger.debug("Debug info from myapp");
206

207
// Level properties maintained
208
console.log(appLogger.level);      // "info" (same as parent)
209
console.log(appLogger.levelIndex); // 3 (same as parent)
210
```
211

212
### Cross-Level Namespace Access
213

214
Each log level maintains its own namespace registry, but namespaces can be accessed across levels.
215

216
```javascript
217
const log = require("log");
218

219
// Create namespace in info level
220
const infoAppLogger = log.get("myapp");
221

222
// Access same namespace in error level
223
const errorAppLogger = log.error.get("myapp");
224

225
// Different instances but same namespace
226
console.log(infoAppLogger === errorAppLogger);           // false
227
console.log(infoAppLogger.namespace === errorAppLogger.namespace); // true
228
console.log(infoAppLogger.level);                        // "info"
229
console.log(errorAppLogger.level);                       // "error"
230
```
231

232
## Namespace Usage Patterns
233

234
### Module-Based Organization
235

236
```javascript
237
// lib/database.js
238
const log = require("log").get("database");
239

240
log.info("Database module loaded");
241

242
function connect() {
243
  const connLogger = log.get("connection");
244
  connLogger.info("Attempting connection...");
245
}
246

247
// lib/api.js  
248
const log = require("log").get("api");
249

250
log.info("API module loaded");
251

252
function handleRequest() {
253
  const reqLogger = log.get("request");
254
  reqLogger.debug("Processing request");
255
}
256
```
257

258
### Feature-Based Organization
259

260
```javascript
261
// Features organized by capability
262
const authLog = log.get("auth");
263
const userLog = log.get("user:management");
264
const paymentLog = log.get("payment:processing");
265

266
authLog.info("User authentication successful");
267
userLog.warning("User profile incomplete");
268
paymentLog.error("Payment processing failed");
269
```
270

271
### Hierarchical Organization
272

273
```javascript
274
// Service layer
275
const serviceLog = log.get("service");
276

277
// Individual services
278
const userServiceLog = serviceLog.get("user");     // "service:user"
279
const orderServiceLog = serviceLog.get("order");   // "service:order"
280

281
// Service components
282
const userAuthLog = userServiceLog.get("auth");    // "service:user:auth"
283
const userProfileLog = userServiceLog.get("profile"); // "service:user:profile"
284
```