0
# Logging System
1

2
Cross-browser logging system with configurable log levels, multiple output targets, and automatic console integration. The logging system provides structured logging with category-based filtering and level-based message prioritization.
3

4
## Capabilities
5

6
### Log Levels and Functions
7

8
Pre-configured logging functions for different message severity levels.
9

10
```javascript { .api }
11
/**
12
 * Log an error message
13
 * @param category - String identifier for the logging category
14
 * @param message - Primary message string (supports % formatting)
15
 * @param args - Additional arguments for message interpolation
16
 */
17
forge.log.error(category: string, message: string, ...args: any[]): void;
18

19
/**
20
 * Log a warning message
21
 * @param category - String identifier for the logging category
22
 * @param message - Primary message string (supports % formatting)
23
 * @param args - Additional arguments for message interpolation
24
 */
25
forge.log.warning(category: string, message: string, ...args: any[]): void;
26

27
/**
28
 * Log an informational message
29
 * @param category - String identifier for the logging category
30
 * @param message - Primary message string (supports % formatting)
31
 * @param args - Additional arguments for message interpolation
32
 */
33
forge.log.info(category: string, message: string, ...args: any[]): void;
34

35
/**
36
 * Log a debug message
37
 * @param category - String identifier for the logging category
38
 * @param message - Primary message string (supports % formatting)
39
 * @param args - Additional arguments for message interpolation
40
 */
41
forge.log.debug(category: string, message: string, ...args: any[]): void;
42

43
/**
44
 * Log a verbose message
45
 * @param category - String identifier for the logging category
46
 * @param message - Primary message string (supports % formatting)
47
 * @param args - Additional arguments for message interpolation
48
 */
49
forge.log.verbose(category: string, message: string, ...args: any[]): void;
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
// Basic logging
56
forge.log.info('myapp', 'Application started');
57
forge.log.error('network', 'Connection failed');
58

59
// Formatted logging with arguments
60
forge.log.debug('crypto', 'Generated key with %d bits', 2048);
61
forge.log.warning('validation', 'Invalid input: %s', inputValue);
62
```
63

64
### Logger Management
65

66
Create and manage custom loggers with specific output functions and levels.
67

68
```javascript { .api }
69
/**
70
 * Create a custom logger with specified logging function
71
 * @param logFunction - Function that receives logger and message objects
72
 * @returns Logger instance with configurable level and flags
73
 */
74
forge.log.makeLogger(logFunction: (logger: Logger, message: LogMessage) => void): Logger;
75

76
/**
77
 * Set the maximum log level for a logger
78
 * @param logger - Target logger instance
79
 * @param level - Maximum level ('none', 'error', 'warning', 'info', 'debug', 'verbose', 'max')
80
 * @returns true if level was set successfully
81
 */
82
forge.log.setLevel(logger: Logger, level: string): boolean;
83

84
/**
85
 * Lock a logger at its current level to prevent changes
86
 * @param logger - Target logger instance
87
 * @param lock - Whether to lock (default: true) or unlock the level
88
 */
89
forge.log.lock(logger: Logger, lock?: boolean): void;
90

91
/**
92
 * Add a logger to the global logging system
93
 * @param logger - Logger instance to add
94
 */
95
forge.log.addLogger(logger: Logger): void;
96

97
interface Logger {
98
  level: string;        // Current log level
99
  flags: number;        // Logger configuration flags
100
  f: function;          // Logging function
101
}
102

103
interface LogMessage {
104
  timestamp: Date;      // When the message was created
105
  level: string;        // Message log level
106
  category: string;     // Message category
107
  message: string;      // Primary message content
108
  arguments: any[];     // Additional arguments
109
  standard?: string;    // Formatted standard message
110
  full?: string;        // Interpolated full message
111
}
112
```
113

114
### Logger Configuration Flags
115

116
Constants for configuring logger behavior.
117

118
```javascript { .api }
119
// Lock the level at current value
120
forge.log.LEVEL_LOCKED: number;
121

122
// Always call log function regardless of level check
123
forge.log.NO_LEVEL_CHECK: number;
124

125
// Perform message interpolation with arguments
126
forge.log.INTERPOLATE: number;
127
```
128

129
### Available Log Levels
130

131
```javascript { .api }
132
// Available log levels in order of verbosity
133
forge.log.levels: string[]; // ['none', 'error', 'warning', 'info', 'debug', 'verbose', 'max']
134
```
135

136
### Console Logger Access
137

138
```javascript { .api }
139
// Built-in console logger (may be null if console unavailable)
140
forge.log.consoleLogger: Logger | null;
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// Create a custom logger that writes to a file
147
const fileLogger = forge.log.makeLogger((logger, message) => {
148
  const formatted = `${message.timestamp.toISOString()} [${message.level.toUpperCase()}] ${message.category}: ${message.message}`;
149
  writeToLogFile(formatted);
150
});
151

152
// Set the logger to only show warnings and errors
153
forge.log.setLevel(fileLogger, 'warning');
154

155
// Add to the global logging system
156
forge.log.addLogger(fileLogger);
157

158
// Lock the console logger at debug level
159
if (forge.log.consoleLogger) {
160
  forge.log.setLevel(forge.log.consoleLogger, 'debug');
161
  forge.log.lock(forge.log.consoleLogger);
162
}
163
```
164

165
### Message Processing Utilities
166

167
Utilities for processing and formatting log messages.
168

169
```javascript { .api }
170
/**
171
 * Format message with standard prefix: "LEVEL [category] message"
172
 * @param message - Log message object to format
173
 */
174
forge.log.prepareStandard(message: LogMessage): void;
175

176
/**
177
 * Interpolate message arguments using % formatting
178
 * @param message - Log message object to interpolate
179
 */
180
forge.log.prepareFull(message: LogMessage): void;
181

182
/**
183
 * Apply both standard and full formatting
184
 * @param message - Log message object to format
185
 */
186
forge.log.prepareStandardFull(message: LogMessage): void;
187
```
188

189
## Configuration
190

191
The logging system automatically detects and configures console logging based on browser capabilities. Query string parameters can control console logger behavior:
192

193
- `console.level=<level>` - Set console log level
194
- `console.lock=<true|false>` - Lock console log level