0
# Log
1

2
Universal pluggable logging utility that provides structured, configurable logging with level support and debug-style namespacing. Designed for maximum reusability across Node.js applications, libraries, and serverless environments.
3

4
## Package Information
5

6
- **Package Name**: log
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install log`
10

11
## Core Imports
12

13
```javascript
14
const log = require("log");
15
```
16

17
For ES modules:
18

19
```javascript
20
import log from "log";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const log = require("log");
27

28
// Log at different levels
29
log("Basic info message");
30
log.error("Something went wrong");
31
log.warning("This is a warning");
32
log.debug("Debug information");
33

34
// Create namespaced loggers
35
const myLibLog = log.get("my-lib");
36
myLibLog.info("Info message in my-lib namespace");
37

38
// Nested namespaces
39
const funcLog = myLibLog.get("func");
40
funcLog.error("Error in my-lib:func namespace");
41

42
// Enable/disable logging
43
const { restore } = log.disable();
44
log("This won't be logged");
45
restore();
46
log("This will be logged again");
47
```
48

49
## Architecture
50

51
The log package is built around several key components:
52

53
- **Logger Prototype**: Core logger functionality with level management and method chaining
54
- **Level System**: Five syslog-compatible levels (error, warning, notice, info, debug) with severity ordering
55
- **Namespace System**: Debug-lib style namespacing with colon separation for organized log categorization
56
- **Event System**: Global event emitter for 'init' and 'log' events that writers can subscribe to
57
- **Writer System**: Pluggable architecture where separate writer modules handle actual log output
58
- **Visibility Control**: Runtime enable/disable functionality with restore capability
59

60
## Capabilities
61

62
### Core Logging
63

64
Primary logging functionality with five severity levels and printf-style message formatting. Supports both direct logging and level-specific methods.
65

66
```javascript { .api }
67
// Main logger function (callable at 'info' level)
68
function log(message, ...args);
69

70
// Level-specific loggers
71
log.debug(message, ...args);    // Debug level (hidden by default)
72
log.info(message, ...args);     // Info level  
73
log.notice(message, ...args);   // Notice level
74
log.warning(message, ...args);  // Warning level
75
log.warn(message, ...args);     // Alias for warning
76
log.error(message, ...args);    // Error level
77
```
78

79
[Core Logging](./core-logging.md)
80

81
### Namespace Management
82

83
Debug-lib style namespacing system for organizing logs by module, component, or feature area. Supports nested namespaces with colon separation.
84

85
```javascript { .api }
86
// Create/get namespaced logger
87
log.get(namespace);
88

89
// Check namespace initialization
90
log.isNamespaceInitialized(namespace);
91

92
// Get all initialized namespaces  
93
log.getAllInitializedNamespaces();
94
```
95

96
[Namespace Management](./namespace-management.md)
97

98
### Enable/Disable Control
99

100
Runtime control over log visibility with restore functionality. Allows temporarily disabling logs and restoring previous state.
101

102
```javascript { .api }
103
// Control properties and methods
104
log.isEnabled;           // boolean property
105
log.enable();           // returns restore object
106
log.disable();          // returns restore object
107
```
108

109
[Enable/Disable Control](./enable-disable-control.md)
110

111
### Log Writer System
112

113
Abstract writer system for creating custom log output handlers. Writers subscribe to log events and handle actual output formatting and destination.
114

115
```javascript { .api }
116
// Abstract writer constructor
117
new LogWriter(env, options);
118

119
// Writer registration
120
getMasterWriter();
121
getMasterWriter.register(writer);
122
```
123

124
[Log Writer System](./log-writer-system.md)
125

126
### Utility Functions
127

128
Helper functions for logger validation and type checking in applications that need to verify logger instances.
129

130
```javascript { .api }
131
// Validation functions
132
isLogger(logger);      // boolean check
133
ensureLogger(logger);  // throws if invalid
134
```
135

136
[Utility Functions](./utility-functions.md)
137

138
## Types
139

140
```javascript { .api }
141
// Logger instance properties
142
interface Logger {
143
  // Callable function
144
  (message, ...args): void;
145
  
146
  // Level properties
147
  level: string;          // e.g., 'info', 'error'
148
  levelIndex: number;     // severity index (0=error, 4=debug)
149
  levelRoot: Logger;      // root logger for this level
150
  
151
  // Namespace properties  
152
  namespace: string | null;     // full namespace or null
153
  namespaceTokens: string[];    // namespace components
154
  
155
  // Control properties
156
  isEnabled: boolean;     // visibility state
157
  
158
  // Level loggers
159
  debug: Logger;
160
  info: Logger; 
161
  notice: Logger;
162
  warning: Logger;
163
  warn: Logger;    // alias for warning
164
  error: Logger;
165
  
166
  // Methods (see capability docs for details)
167
  get(namespace: string): Logger;
168
  isNamespaceInitialized(namespace: string): boolean;
169
  getAllInitializedNamespaces(): Logger[];
170
  isLevelInitialized(level: string): boolean;
171
  getAllInitializedLevels(): Logger[];
172
  enable(): RestoreObject;
173
  disable(): RestoreObject;
174
}
175

176
interface RestoreObject {
177
  restore(): void;
178
}
179

180
interface LogWriter {
181
  constructor(env: object, options?: object);
182
  writeMessage(event: LogEvent): void;
183
  isLoggerEnabled(logger: Logger): boolean;
184
  setupLevelLogger(logger: Logger): void;
185
}
186

187
interface LogEvent {
188
  logger: Logger;
189
  messageTokens: any[];
190
  message?: string;
191
}
192
```