0
# Utility Functions
1

2
Helper functions for logger validation and type checking in applications that need to verify logger instances or ensure proper logger usage.
3

4
## Capabilities
5

6
### Logger Validation
7

8
Function to check if an object is a valid logger instance.
9

10
```javascript { .api }
11
/**
12
 * Validates if an object is a logger instance
13
 * @param {*} logger - Object to validate
14
 * @returns {boolean} True if object is a valid logger
15
 */
16
function isLogger(logger);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const isLogger = require("log/is-logger");
23
const log = require("log");
24

25
// Valid logger instances
26
console.log(isLogger(log));              // true
27
console.log(isLogger(log.error));        // true
28
console.log(isLogger(log.get("app")));   // true
29

30
// Invalid objects
31
console.log(isLogger(null));            // false
32
console.log(isLogger({}));              // false
33
console.log(isLogger("log"));           // false
34
console.log(isLogger(console.log));     // false
35

36
// Function checks
37
function processLogger(logger) {
38
  if (isLogger(logger)) {
39
    logger.info("Processing with valid logger");
40
  } else {
41
    console.error("Invalid logger provided");
42
  }
43
}
44
```
45

46
### Logger Enforcement
47

48
Function that validates a logger or throws an error if invalid.
49

50
```javascript { .api }
51
/**
52
 * Validates logger or throws TypeError if invalid
53
 * @param {*} logger - Object to validate
54
 * @returns {Logger} The validated logger instance
55
 * @throws {TypeError} If object is not a valid logger
56
 */
57
function ensureLogger(logger);
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const ensureLogger = require("log/ensure-logger");
64
const log = require("log");
65

66
// Valid logger - returns the logger
67
const validLogger = ensureLogger(log);
68
console.log(validLogger === log); // true
69

70
// Valid namespaced logger
71
const appLogger = ensureLogger(log.get("app"));
72
appLogger.info("Validated logger works");
73

74
// Invalid object - throws TypeError
75
try {
76
  ensureLogger("not a logger");
77
} catch (error) {
78
  console.log(error instanceof TypeError); // true
79
  console.log(error.message); // "'not a logger' is not a logger"
80
}
81

82
try {
83
  ensureLogger(null);
84
} catch (error) {
85
  console.log(error.message); // "null is not a logger"
86
}
87

88
// Usage in function parameters
89
function logWithValidation(logger, message) {
90
  const validLogger = ensureLogger(logger);
91
  validLogger.info(message);
92
}
93

94
// Safe usage
95
logWithValidation(log, "This works");           // ✓ Success
96
logWithValidation(log.error, "This works too"); // ✓ Success
97

98
// Unsafe usage
99
try {
100
  logWithValidation({}, "This fails");          // ✗ Throws TypeError
101
} catch (error) {
102
  console.log("Validation failed:", error.message);
103
}
104
```
105

106
## Validation Criteria
107

108
### Logger Requirements
109

110
For an object to be considered a valid logger, it must satisfy these criteria:
111

112
```javascript
113
// 1. Must be a plain function (callable)
114
typeof logger === 'function' && logger.constructor === Function
115

116
// 2. Must have a 'level' property that is a string
117
typeof logger.level === 'string'
118

119
// 3. Must have an 'isNamespaceInitialized' method that is a function
120
typeof logger.isNamespaceInitialized === 'function'
121
```
122

123
**Validation Examples:**
124

125
```javascript
126
const isLogger = require("log/is-logger");
127

128
// Valid logger characteristics
129
const log = require("log");
130

131
console.log(typeof log);                           // "function"
132
console.log(typeof log.level);                     // "string"
133
console.log(typeof log.isNamespaceInitialized);    // "function"
134
console.log(isLogger(log));                        // true
135

136
// Invalid objects and why they fail:
137

138
// Not a function
139
const notFunction = { level: "info", isNamespaceInitialized: () => {} };
140
console.log(isLogger(notFunction)); // false - not a function
141

142
// Missing level property  
143
const noLevel = function() {};
144
noLevel.isNamespaceInitialized = () => {};
145
console.log(isLogger(noLevel)); // false - no level property
146

147
// Level is not a string
148
const badLevel = function() {};
149
badLevel.level = 123;
150
badLevel.isNamespaceInitialized = () => {};
151
console.log(isLogger(badLevel)); // false - level not string
152

153
// Missing isNamespaceInitialized method
154
const noMethod = function() {};
155
noMethod.level = "info";
156
console.log(isLogger(noMethod)); // false - missing method
157
```
158

159
## Use Cases
160

161
### Library Parameter Validation
162

163
```javascript
164
const ensureLogger = require("log/ensure-logger");
165

166
class DatabaseConnection {
167
  constructor(config, logger) {
168
    this.config = config;
169
    this.logger = ensureLogger(logger); // Ensures valid logger
170
  }
171
  
172
  connect() {
173
    this.logger.info("Connecting to database...");
174
    // Connection logic
175
  }
176
  
177
  query(sql) {
178
    this.logger.debug("Executing query: %s", sql);
179
    // Query logic
180
  }
181
}
182

183
// Usage with validation
184
const log = require("log");
185
const db = new DatabaseConnection(config, log.get("database")); // ✓ Valid
186

187
try {
188
  const badDb = new DatabaseConnection(config, console); // ✗ Throws
189
} catch (error) {
190
  console.log("Invalid logger provided to DatabaseConnection");
191
}
192
```
193

194
### Middleware Validation
195

196
```javascript
197
const isLogger = require("log/is-logger");
198

199
function createLoggingMiddleware(logger) {
200
  if (!isLogger(logger)) {
201
    throw new Error("Logging middleware requires a valid logger instance");
202
  }
203
  
204
  return function loggingMiddleware(req, res, next) {
205
    logger.info("%s %s", req.method, req.url);
206
    next();
207
  };
208
}
209

210
// Usage
211
const log = require("log");
212
const middleware = createLoggingMiddleware(log.get("http")); // ✓ Valid
213

214
try {
215
  const badMiddleware = createLoggingMiddleware(console.log); // ✗ Throws
216
} catch (error) {
217
  console.log("Middleware creation failed");
218
}
219
```
220

221
### Optional Logger Parameters
222

223
```javascript
224
const isLogger = require("log/is-logger");
225

226
function processData(data, logger) {
227
  // Use provided logger or create default
228
  const log = isLogger(logger) ? logger : require("log").get("processor");
229
  
230
  log.info("Processing %d items", data.length);
231
  
232
  // Processing logic
233
  data.forEach((item, index) => {
234
    log.debug("Processing item %d: %j", index, item);
235
  });
236
  
237
  log.info("Processing complete");
238
}
239

240
// Usage with logger
241
processData(items, log.get("custom")); // Uses custom logger
242

243
// Usage without logger  
244
processData(items); // Uses default logger
245

246
// Usage with invalid logger
247
processData(items, "invalid"); // Uses default logger (graceful fallback)
248
```
249

250
### Configuration Validation
251

252
```javascript
253
const ensureLogger = require("log/ensure-logger");
254

255
function setupApplication(config) {
256
  // Validate logger configuration
257
  if (config.logger) {
258
    try {
259
      config.logger = ensureLogger(config.logger);
260
    } catch (error) {
261
      throw new Error(`Invalid logger in configuration: ${error.message}`);
262
    }
263
  } else {
264
    // Provide default logger
265
    config.logger = require("log").get("app");
266
  }
267
  
268
  // Application setup continues with validated logger
269
  config.logger.info("Application setup complete");
270
}
271

272
// Usage
273
const log = require("log");
274

275
setupApplication({ 
276
  logger: log.get("myapp")  // ✓ Valid logger
277
});
278

279
try {
280
  setupApplication({ 
281
    logger: { fake: "logger" }  // ✗ Invalid logger
282
  });
283
} catch (error) {
284
  console.log("Configuration validation failed");
285
}
286
```