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
```