0
# tslog
1

2
tslog is an extensible TypeScript logger for Node.js and Browser environments. It provides a powerful, fast, and expressive logging library with customizable log levels, pretty or JSON output formatting, support for circular structures, custom pluggable loggers, object and error interpolation, stack trace handling, sub-logger inheritance, secret masking capabilities, and both CommonJS and ESM module support with tree shaking.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Logger } from "tslog";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Logger } = require("tslog");
21
```
22

23
Additional imports:
24

25
```typescript
26
import { 
27
  BaseLogger, 
28
  ISettingsParam,
29
  ISettings,
30
  ILogObj, 
31
  ILogObjMeta,
32
  IErrorObject,
33
  IErrorObjectStringifiable,
34
  Runtime
35
} from "tslog";
36
```
37

38
BaseLogger can be imported and used directly for more control:
39

40
```typescript
41
import { BaseLogger } from "tslog";
42

43
const baseLogger = new BaseLogger({ name: "MyBaseLogger" });
44
```
45

46
## Basic Usage
47

48
```typescript
49
import { Logger } from "tslog";
50

51
// Create a new logger instance
52
const logger = new Logger();
53

54
// Log messages at different levels
55
logger.silly("This is a silly message");
56
logger.trace("Tracing application flow");
57
logger.debug("Debug information");
58
logger.info("General information");
59
logger.warn("Warning message");
60
logger.error("Error occurred");
61
logger.fatal("Fatal error");
62

63
// Log with multiple arguments
64
logger.info("User login", { userId: 123, email: "user@example.com" });
65

66
// Log with custom log level
67
logger.log(3, "CUSTOM", "Custom log level message");
68
```
69

70
## Architecture
71

72
tslog is built around several key components:
73

74
- **Logger Class**: Main logging interface with platform detection for Node.js/Browser
75
- **BaseLogger Class**: Core logging functionality with transport and masking support
76
- **Settings System**: Comprehensive configuration options for output formatting and behavior
77
- **Transport System**: Pluggable external logging destinations
78
- **Runtime Abstraction**: Platform-specific functionality for Node.js and Browser environments
79
- **Type System**: Full TypeScript integration with generic log object support
80

81
## Capabilities
82

83
### Core Logging
84

85
Main Logger class providing logging methods for all standard log levels with platform-aware initialization and automatic browser/Node.js detection.
86

87
```typescript { .api }
88
class Logger<LogObj> extends BaseLogger<LogObj> {
89
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj);
90
  
91
  silly(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
92
  trace(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
93
  debug(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
94
  info(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
95
  warn(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
96
  error(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
97
  fatal(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
98
  log(logLevelId: number, logLevelName: string, ...args: unknown[]): (LogObj & ILogObjMeta & ILogObj) | undefined;
99
  
100
  getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): Logger<LogObj>;
101
}
102
```
103

104
[Core Logging](./core-logging.md)
105

106
### Configuration
107

108
Comprehensive settings system for customizing logger behavior, output formatting, styling, and masking capabilities.
109

110
```typescript { .api }
111
interface ISettingsParam<LogObj> {
112
  type?: "json" | "pretty" | "hidden";
113
  name?: string;
114
  minLevel?: number;
115
  prettyLogTemplate?: string;
116
  stylePrettyLogs?: boolean;
117
  prettyLogTimeZone?: "UTC" | "local";
118
  maskValuesOfKeys?: string[];
119
  prefix?: unknown[];
120
  overwrite?: ConfigurationOverrides<LogObj>;
121
}
122
```
123

124
[Configuration](./configuration.md)
125

126
### Transports
127

128
External logging system for integrating with log services, file systems, databases, and other logging destinations.
129

130
```typescript { .api }
131
interface TransportLogger<LogObj> {
132
  (transportLogger: LogObj & ILogObjMeta): void;
133
}
134

135
// BaseLogger methods
136
attachTransport(transportLogger: TransportLogger<LogObj>): void;
137
```
138

139
[Transports](./transports.md)
140

141
## Core Types
142

143
```typescript { .api }
144
interface ILogObj {
145
  [name: string]: unknown;
146
}
147

148
interface ILogObjMeta {
149
  [name: string]: IMeta;
150
}
151

152
interface IMeta {
153
  date: Date;
154
  logLevelId: number;
155
  logLevelName: string;
156
  path?: IStackFrame;
157
  name?: string;
158
  parentNames?: string[];
159
  runtime: string;
160
}
161

162
interface IStackFrame {
163
  fullFilePath?: string;
164
  fileName?: string;
165
  fileNameWithLine?: string;
166
  filePath?: string;
167
  fileLine?: string;
168
  fileColumn?: string;
169
  filePathWithLine?: string;
170
  method?: string;
171
}
172

173
interface IErrorObject {
174
  name: string;
175
  message: string;
176
  nativeError: Error;
177
  stack: IStackFrame[];
178
}
179

180
interface IErrorObjectStringifiable extends IErrorObject {
181
  nativeError: never;
182
  errorString: string;
183
}
184

185
interface ISettingsParam<LogObj> {
186
  type?: "json" | "pretty" | "hidden";
187
  name?: string;
188
  minLevel?: number;
189
  overwrite?: ConfigurationOverrides<LogObj>;
190
  // See configuration.md for complete interface
191
}
192

193
interface ConfigurationOverrides<LogObj> {
194
  // See configuration.md for complete interface
195
}
196

197
type TStyle = 
198
  | null 
199
  | string 
200
  | string[] 
201
  | {
202
      [value: string]: null | string | string[];
203
    };
204

205
interface ISettings<LogObj> extends ISettingsParam<LogObj> {
206
  // Resolved settings with all defaults applied
207
  // See configuration.md for complete interface
208
}
209

210
const Runtime: IRuntime;
211

212
interface IRuntime {
213
  getMeta(
214
    logLevelId: number,
215
    logLevelName: string,
216
    stackDepthLevel: number,
217
    hideLogPositionForPerformance: boolean,
218
    name?: string,
219
    parentNames?: string[]
220
  ): IMeta;
221
  getCallerStackFrame(stackDepthLevel: number, error: Error): IStackFrame;
222
  getErrorTrace(error: Error): IStackFrame[];
223
  isError(e: Error | unknown): boolean;
224
  prettyFormatLogObj<LogObj>(maskedArgs: unknown[], settings: ISettings<LogObj>): { args: unknown[]; errors: string[] };
225
  prettyFormatErrorObj<LogObj>(error: Error, settings: ISettings<LogObj>): string;
226
  transportFormatted<LogObj>(logMetaMarkup: string, logArgs: unknown[], logErrors: string[], settings: ISettings<LogObj>): void;
227
  transportJSON<LogObj>(json: LogObj & ILogObjMeta): void;
228
  isBuffer(b: unknown): boolean;
229
}
230
```
231

232
The Runtime export provides platform-specific implementations for Node.js and Browser environments. It handles metadata generation, stack trace extraction, object formatting, and output transport. The Runtime is automatically selected based on the execution environment but can be imported directly for advanced use cases.