0
# Core Logging
1

2
Primary logging functionality with five severity levels based on syslog standards. Supports printf-style message formatting and provides both callable logger functions and level-specific methods.
3

4
## Capabilities
5

6
### Main Logger Function
7

8
The default export is a callable logger function operating at 'info' level.
9

10
```javascript { .api }
11
/**
12
 * Main logger function - logs at 'info' level
13
 * @param {*} message - Primary message (string with printf placeholders or any value)
14
 * @param {...*} args - Arguments for printf-style formatting
15
 */
16
function log(message, ...args);
17
```
18

19
**Usage Examples:**
20

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

24
// Simple string logging
25
log("Application started");
26
log("User logged in");
27

28
// Printf-style formatting
29
log("User %s logged in with ID %d", "alice", 123);
30
log("Processing %d items", 42);
31
log("Config: %j", { debug: true, port: 3000 });
32
```
33

34
### Level-Specific Loggers
35

36
Each logger provides access to all five logging levels as properties/methods.
37

38
```javascript { .api }
39
/**
40
 * Debug level logger - for debugging information (hidden by default)
41
 * @param {*} message - Message to log
42
 * @param {...*} args - Arguments for formatting
43
 */
44
log.debug(message, ...args);
45

46
/**
47
 * Info level logger - for informational messages (hidden by default)  
48
 * @param {*} message - Message to log
49
 * @param {...*} args - Arguments for formatting
50
 */
51
log.info(message, ...args);
52

53
/**
54
 * Notice level logger - for significant conditions (visible by default)
55
 * @param {*} message - Message to log
56
 * @param {...*} args - Arguments for formatting
57
 */
58
log.notice(message, ...args);
59

60
/**
61
 * Warning level logger - for warning conditions (visible by default)
62
 * @param {*} message - Message to log  
63
 * @param {...*} args - Arguments for formatting
64
 */
65
log.warning(message, ...args);
66

67
/**
68
 * Warn level logger - alias for warning level
69
 * @param {*} message - Message to log
70
 * @param {...*} args - Arguments for formatting
71
 */
72
log.warn(message, ...args);
73

74
/**
75
 * Error level logger - for error conditions (visible by default)
76
 * @param {*} message - Message to log
77
 * @param {...*} args - Arguments for formatting
78
 */
79
log.error(message, ...args);
80
```
81

82
**Usage Examples:**
83

84
```javascript
85
const log = require("log");
86

87
// Different severity levels
88
log.error("Database connection failed: %s", error.message);
89
log.warning("Deprecated API used in %s", functionName);
90
log.notice("Server started on port %d", 3000);
91
log.info("Processing request %s", requestId);
92
log.debug("Variable state: %j", debugObject);
93

94
// Level chaining - all return the same logger instance
95
log.info === log;           // true
96
log.error.info === log;     // true
97
log.warning.debug.error === log.error;  // true
98
```
99

100
### Level Properties
101

102
Each logger exposes properties describing its level configuration.
103

104
```javascript { .api }
105
/**
106
 * Current logger level name
107
 * @type {string}
108
 */
109
log.level;
110

111
/**
112
 * Numeric index of logger level (0=error, 1=warning, 2=notice, 3=info, 4=debug)
113
 * @type {number}
114
 */
115
log.levelIndex;
116

117
/**
118
 * Reference to the root logger for this level
119
 * @type {Logger}
120
 */
121
log.levelRoot;
122
```
123

124
**Usage Examples:**
125

126
```javascript
127
const log = require("log");
128

129
console.log(log.level);        // "info"
130
console.log(log.levelIndex);   // 3
131

132
console.log(log.error.level);      // "error" 
133
console.log(log.error.levelIndex); // 0
134

135
// Root logger reference
136
const nsLogger = log.get("mylib");
137
console.log(nsLogger.levelRoot === log);  // true
138
```
139

140
### Level Management
141

142
Methods for inspecting and managing logger level initialization.
143

144
```javascript { .api }
145
/**
146
 * Check if a logger for the specified level has been initialized
147
 * @param {string} level - Level name to check
148
 * @returns {boolean} True if level logger exists
149
 */
150
log.isLevelInitialized(level);
151

152
/**
153
 * Get all initialized level loggers for the current namespace
154
 * @returns {Logger[]} Array of initialized logger instances
155
 */
156
log.getAllInitializedLevels();
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
const log = require("log");
163

164
// Check level initialization
165
console.log(log.isLevelInitialized("info"));    // true
166
console.log(log.isLevelInitialized("debug"));   // false (until first access)
167
console.log(log.isLevelInitialized("custom"));  // false (not a valid level)
168

169
// Access debug logger to initialize it
170
log.debug("test");
171

172
// Now debug is initialized  
173
console.log(log.isLevelInitialized("debug"));   // true
174

175
// Get all initialized levels
176
const levels = log.getAllInitializedLevels();
177
console.log(levels.map(l => l.level)); // ["info", "debug"]
178
```
179

180
## Message Formatting
181

182
The log package supports printf-style message formatting with the following placeholders:
183

184
- `%s` - String
185
- `%d` - Number (integer or floating point value)
186
- `%i` - Integer
187
- `%f` - Floating point value
188
- `%j` - JSON (with circular reference handling)
189
- `%o` - Object representation with hidden properties
190
- `%O` - Object representation without hidden properties  
191
- `%%` - Literal percent sign
192

193
**Formatting Examples:**
194

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

198
// String formatting
199
log("Hello %s", "world");                    // "Hello world"
200

201
// Number formatting  
202
log("Count: %d, Price: %f", 42, 19.99);      // "Count: 42, Price: 19.99"
203

204
// JSON formatting
205
log("Config: %j", { port: 3000, debug: true }); // "Config: {"port":3000,"debug":true}"
206

207
// Object formatting
208
log("User: %o", user);                       // Detailed object output
209
log("Simple: %O", user);                     // Simple object output
210

211
// Literal percent
212
log("Progress: 50%%");                       // "Progress: 50%"
213
```
214

215
## Level Visibility
216

217
By default, the log package follows syslog severity ordering:
218

219
- **error** (0) - Always visible
220
- **warning** (1) - Always visible
221
- **notice** (2) - Always visible (default threshold)
222
- **info** (3) - Hidden by default
223
- **debug** (4) - Hidden by default
224

225
The visibility threshold can be configured via environment variables or programmatically through log writers.