0
# Core Logging
1

2
Core logging functionality providing the main Logger class and BaseLogger foundation with platform-aware initialization, standard log levels, and sub-logger support.
3

4
## Capabilities
5

6
### Logger Class
7

8
Main logging interface with automatic platform detection for Node.js and Browser environments. Provides all standard log levels and inherits advanced functionality from BaseLogger.
9

10
```typescript { .api }
11
/**
12
 * Main logger class with platform-aware initialization
13
 * @template LogObj - Type for log object structure
14
 */
15
class Logger<LogObj> extends BaseLogger<LogObj> {
16
  /**
17
   * Creates a new Logger instance with platform detection
18
   * @param settings - Optional logger configuration
19
   * @param logObj - Optional base log object for all messages
20
   */
21
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj);
22
}
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { Logger } from "tslog";
29

30
// Basic logger
31
const logger = new Logger();
32

33
// Logger with configuration
34
const configuredLogger = new Logger({
35
  name: "MyApp",
36
  type: "pretty",
37
  minLevel: 2, // Debug level and above
38
});
39

40
// Logger with base log object
41
const contextLogger = new Logger(
42
  { name: "UserService" },
43
  { service: "user-management", version: "1.0.0" }
44
);
45
```
46

47
### Standard Log Levels
48

49
Pre-defined logging methods for each standard log level, from most verbose (silly) to most critical (fatal).
50

51
```typescript { .api }
52
/**
53
 * Log a silly message (level 0) - most verbose
54
 * @param args - Multiple log attributes to be logged
55
 * @returns Log object with metadata or undefined if below minLevel
56
 */
57
silly(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
58

59
/**
60
 * Log a trace message (level 1) - for tracing program flow
61
 * @param args - Multiple log attributes to be logged
62
 * @returns Log object with metadata or undefined if below minLevel
63
 */
64
trace(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
65

66
/**
67
 * Log a debug message (level 2) - for debugging information
68
 * @param args - Multiple log attributes to be logged
69
 * @returns Log object with metadata or undefined if below minLevel
70
 */
71
debug(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
72

73
/**
74
 * Log an info message (level 3) - for general information
75
 * @param args - Multiple log attributes to be logged
76
 * @returns Log object with metadata or undefined if below minLevel
77
 */
78
info(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
79

80
/**
81
 * Log a warn message (level 4) - for warnings
82
 * @param args - Multiple log attributes to be logged
83
 * @returns Log object with metadata or undefined if below minLevel
84
 */
85
warn(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
86

87
/**
88
 * Log an error message (level 5) - for errors
89
 * @param args - Multiple log attributes to be logged
90
 * @returns Log object with metadata or undefined if below minLevel
91
 */
92
error(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
93

94
/**
95
 * Log a fatal message (level 6) - for fatal errors
96
 * @param args - Multiple log attributes to be logged
97
 * @returns Log object with metadata or undefined if below minLevel
98
 */
99
fatal(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { Logger } from "tslog";
106

107
const logger = new Logger({ name: "MyApp" });
108

109
// Simple logging
110
logger.info("Application started");
111
logger.error("Database connection failed");
112

113
// Logging with multiple arguments
114
logger.debug("Processing user data", { userId: 123, action: "login" });
115
logger.warn("High memory usage", { usage: "85%", threshold: "80%" });
116

117
// Logging with objects and errors
118
try {
119
  // some operation
120
} catch (error) {
121
  logger.error("Operation failed", error, { operation: "processData" });
122
}
123
```
124

125
### Custom Log Levels
126

127
Generic logging method allowing custom log levels with user-defined level IDs and names.
128

129
```typescript { .api }
130
/**
131
 * Log a message with a custom log level
132
 * @param logLevelId - Numeric log level identifier (0-6 for standard levels)
133
 * @param logLevelName - String name for the log level
134
 * @param args - Multiple log attributes to be logged
135
 * @returns Log object with metadata or undefined if below minLevel
136
 */
137
log(logLevelId: number, logLevelName: string, ...args: unknown[]): (LogObj & ILogObjMeta & ILogObj) | undefined;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
import { Logger } from "tslog";
144

145
const logger = new Logger();
146

147
// Custom log levels
148
logger.log(3, "NOTICE", "System maintenance scheduled");
149
logger.log(7, "CRITICAL", "System failure detected");
150
logger.log(1, "VERBOSE", "Detailed operation trace");
151
```
152

153
### Sub-Logger Creation
154

155
Create child loggers that inherit settings from parent loggers while allowing customization and maintaining parent-child relationships.
156

157
```typescript { .api }
158
/**
159
 * Create a child logger inheriting from current instance
160
 * @param settings - Optional settings to override parent settings
161
 * @param logObj - Optional base log object to override parent logObj
162
 * @returns New Logger instance inheriting parent configuration
163
 */
164
getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): Logger<LogObj>;
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
import { Logger } from "tslog";
171

172
// Parent logger
173
const parentLogger = new Logger({
174
  name: "MyApp",
175
  type: "pretty",
176
  minLevel: 1
177
});
178

179
// Child logger inheriting settings
180
const childLogger = parentLogger.getSubLogger({
181
  name: "DatabaseModule"
182
});
183

184
// Child logger with additional context
185
const userServiceLogger = parentLogger.getSubLogger(
186
  { name: "UserService" },
187
  { module: "authentication", version: "2.1.0" }
188
);
189

190
// Logs will show parent-child relationship
191
childLogger.info("Child logger message"); // Shows "MyApp:DatabaseModule"
192
```
193

194
### BaseLogger Class
195

196
Foundation class providing core logging functionality, transport system, and configuration management.
197

198
```typescript { .api }
199
/**
200
 * Base logger class providing core functionality
201
 * @template LogObj - Type for log object structure
202
 */
203
class BaseLogger<LogObj> {
204
  /**
205
   * Logger configuration settings
206
   */
207
  settings: ISettings<LogObj>;
208

209
  /**
210
   * Creates a base logger instance
211
   * @param settings - Optional logger configuration
212
   * @param logObj - Optional base log object
213
   * @param stackDepthLevel - Stack depth for caller detection (default: 4)
214
   */
215
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj, stackDepthLevel?: number);
216

217
  /**
218
   * Core logging method used by all log level methods
219
   * @param logLevelId - Numeric log level
220
   * @param logLevelName - String log level name
221
   * @param args - Arguments to log
222
   * @returns Log object with metadata or undefined if below minLevel
223
   */
224
  log(logLevelId: number, logLevelName: string, ...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
225

226
  /**
227
   * Attach external transport for log forwarding
228
   * @param transportLogger - Function to handle log objects
229
   */
230
  attachTransport(transportLogger: (transportLogger: LogObj & ILogObjMeta) => void): void;
231

232
  /**
233
   * Create child logger inheriting current settings
234
   * @param settings - Optional settings to override
235
   * @param logObj - Optional log object to override
236
   * @returns New BaseLogger instance
237
   */
238
  getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): BaseLogger<LogObj>;
239
}
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import { BaseLogger } from "tslog";
246

247
// Direct BaseLogger usage
248
const baseLogger = new BaseLogger({
249
  name: "BaseApp",
250
  type: "json",
251
  minLevel: 1
252
});
253

254
// Access settings property
255
console.log(baseLogger.settings.name); // "BaseApp"
256
console.log(baseLogger.settings.type); // "json"
257

258
// Attach transport
259
baseLogger.attachTransport((logObj) => {
260
  console.log("Transport received:", logObj);
261
});
262

263
// Use core log method
264
baseLogger.log(3, "INFO", "Base logger message");
265

266
// Create sub-logger
267
const subLogger = baseLogger.getSubLogger({ name: "SubModule" });
268
```
269

270
## Log Object Structure
271

272
```typescript { .api }
273
interface ILogObj {
274
  [name: string]: unknown;
275
}
276

277
interface ILogObjMeta {
278
  [name: string]: IMeta;
279
}
280

281
interface IMeta {
282
  date: Date;
283
  logLevelId: number;
284
  logLevelName: string;
285
  path?: IStackFrame;
286
  name?: string;
287
  parentNames?: string[];
288
  runtime: string;
289
}
290

291
interface IStackFrame {
292
  fullFilePath?: string;
293
  fileName?: string;
294
  fileNameWithLine?: string;
295
  filePath?: string;
296
  fileLine?: string;
297
  fileColumn?: string;
298
  filePathWithLine?: string;
299
  method?: string;
300
}
301
```