or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-logging.mdindex.mdtransports.md
tile.json

tessl/npm-tslog

Extensible TypeScript Logger for Node.js and Browser with customizable log levels, pretty or JSON output formatting, and universal compatibility.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tslog@4.9.x

To install, run

npx @tessl/cli install tessl/npm-tslog@4.9.0

index.mddocs/

tslog

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.

Package Information

  • Package Name: tslog
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install tslog

Core Imports

import { Logger } from "tslog";

For CommonJS:

const { Logger } = require("tslog");

Additional imports:

import { 
  BaseLogger, 
  ISettingsParam,
  ISettings,
  ILogObj, 
  ILogObjMeta,
  IErrorObject,
  IErrorObjectStringifiable,
  Runtime
} from "tslog";

BaseLogger can be imported and used directly for more control:

import { BaseLogger } from "tslog";

const baseLogger = new BaseLogger({ name: "MyBaseLogger" });

Basic Usage

import { Logger } from "tslog";

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

// Log messages at different levels
logger.silly("This is a silly message");
logger.trace("Tracing application flow");
logger.debug("Debug information");
logger.info("General information");
logger.warn("Warning message");
logger.error("Error occurred");
logger.fatal("Fatal error");

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

// Log with custom log level
logger.log(3, "CUSTOM", "Custom log level message");

Architecture

tslog is built around several key components:

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

Capabilities

Core Logging

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

class Logger<LogObj> extends BaseLogger<LogObj> {
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj);
  
  silly(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  trace(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  debug(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  info(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  warn(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  error(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  fatal(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;
  log(logLevelId: number, logLevelName: string, ...args: unknown[]): (LogObj & ILogObjMeta & ILogObj) | undefined;
  
  getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): Logger<LogObj>;
}

Core Logging

Configuration

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

interface ISettingsParam<LogObj> {
  type?: "json" | "pretty" | "hidden";
  name?: string;
  minLevel?: number;
  prettyLogTemplate?: string;
  stylePrettyLogs?: boolean;
  prettyLogTimeZone?: "UTC" | "local";
  maskValuesOfKeys?: string[];
  prefix?: unknown[];
  overwrite?: ConfigurationOverrides<LogObj>;
}

Configuration

Transports

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

interface TransportLogger<LogObj> {
  (transportLogger: LogObj & ILogObjMeta): void;
}

// BaseLogger methods
attachTransport(transportLogger: TransportLogger<LogObj>): void;

Transports

Core Types

interface ILogObj {
  [name: string]: unknown;
}

interface ILogObjMeta {
  [name: string]: IMeta;
}

interface IMeta {
  date: Date;
  logLevelId: number;
  logLevelName: string;
  path?: IStackFrame;
  name?: string;
  parentNames?: string[];
  runtime: string;
}

interface IStackFrame {
  fullFilePath?: string;
  fileName?: string;
  fileNameWithLine?: string;
  filePath?: string;
  fileLine?: string;
  fileColumn?: string;
  filePathWithLine?: string;
  method?: string;
}

interface IErrorObject {
  name: string;
  message: string;
  nativeError: Error;
  stack: IStackFrame[];
}

interface IErrorObjectStringifiable extends IErrorObject {
  nativeError: never;
  errorString: string;
}

interface ISettingsParam<LogObj> {
  type?: "json" | "pretty" | "hidden";
  name?: string;
  minLevel?: number;
  overwrite?: ConfigurationOverrides<LogObj>;
  // See configuration.md for complete interface
}

interface ConfigurationOverrides<LogObj> {
  // See configuration.md for complete interface
}

type TStyle = 
  | null 
  | string 
  | string[] 
  | {
      [value: string]: null | string | string[];
    };

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

const Runtime: IRuntime;

interface IRuntime {
  getMeta(
    logLevelId: number,
    logLevelName: string,
    stackDepthLevel: number,
    hideLogPositionForPerformance: boolean,
    name?: string,
    parentNames?: string[]
  ): IMeta;
  getCallerStackFrame(stackDepthLevel: number, error: Error): IStackFrame;
  getErrorTrace(error: Error): IStackFrame[];
  isError(e: Error | unknown): boolean;
  prettyFormatLogObj<LogObj>(maskedArgs: unknown[], settings: ISettings<LogObj>): { args: unknown[]; errors: string[] };
  prettyFormatErrorObj<LogObj>(error: Error, settings: ISettings<LogObj>): string;
  transportFormatted<LogObj>(logMetaMarkup: string, logArgs: unknown[], logErrors: string[], settings: ISettings<LogObj>): void;
  transportJSON<LogObj>(json: LogObj & ILogObjMeta): void;
  isBuffer(b: unknown): boolean;
}

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.