Core Logging

/**
 * Main logger class with platform-aware initialization
 * @template LogObj - Type for log object structure
 */
class Logger<LogObj> extends BaseLogger<LogObj> {
  /**
   * Creates a new Logger instance with platform detection
   * @param settings - Optional logger configuration
   * @param logObj - Optional base log object for all messages
   */
  constructor(settings?: ISettingsParam<LogObj>, logObj?: LogObj);
}

import { Logger } from "tslog";

// Basic logger
const logger = new Logger();

// Logger with configuration
const configuredLogger = new Logger({
  name: "MyApp",
  type: "pretty",
  minLevel: 2, // Debug level and above
});

// Logger with base log object
const contextLogger = new Logger(
  { name: "UserService" },
  { service: "user-management", version: "1.0.0" }
);

/**
 * Log a silly message (level 0) - most verbose
 * @param args - Multiple log attributes to be logged
 * @returns Log object with metadata or undefined if below minLevel
 */
silly(...args: unknown[]): (LogObj & ILogObjMeta) | undefined;

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

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

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

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

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

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

import { Logger } from "tslog";

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

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

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

// Logging with objects and errors
try {
  // some operation
} catch (error) {
  logger.error("Operation failed", error, { operation: "processData" });
}

/**
 * Log a message with a custom log level
 * @param logLevelId - Numeric log level identifier (0-6 for standard levels)
 * @param logLevelName - String name for the log level
 * @param args - Multiple log attributes to be logged
 * @returns Log object with metadata or undefined if below minLevel
 */
log(logLevelId: number, logLevelName: string, ...args: unknown[]): (LogObj & ILogObjMeta & ILogObj) | undefined;

import { Logger } from "tslog";

const logger = new Logger();

// Custom log levels
logger.log(3, "NOTICE", "System maintenance scheduled");
logger.log(7, "CRITICAL", "System failure detected");
logger.log(1, "VERBOSE", "Detailed operation trace");

/**
 * Create a child logger inheriting from current instance
 * @param settings - Optional settings to override parent settings
 * @param logObj - Optional base log object to override parent logObj
 * @returns New Logger instance inheriting parent configuration
 */
getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): Logger<LogObj>;

import { Logger } from "tslog";

// Parent logger
const parentLogger = new Logger({
  name: "MyApp",
  type: "pretty",
  minLevel: 1
});

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

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

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

/**
 * Base logger class providing core functionality
 * @template LogObj - Type for log object structure
 */
class BaseLogger<LogObj> {
  /**
   * Logger configuration settings
   */
  settings: ISettings<LogObj>;

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

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

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

  /**
   * Create child logger inheriting current settings
   * @param settings - Optional settings to override
   * @param logObj - Optional log object to override
   * @returns New BaseLogger instance
   */
  getSubLogger(settings?: ISettingsParam<LogObj>, logObj?: LogObj): BaseLogger<LogObj>;
}

import { BaseLogger } from "tslog";

// Direct BaseLogger usage
const baseLogger = new BaseLogger({
  name: "BaseApp",
  type: "json",
  minLevel: 1
});

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

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

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

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

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;
}