ps-chronicle/dist/cjs/index.d.ts

eGain PS logging wrapper utility on Winston

import { transport as WinstonTransport } from "winston";
/**
 * Supported log levels.
 */
export declare enum LogLevel {
    ERROR = "error",
    WS_PAYLOAD = "wspayload",
    WARN = "warn",
    INFO = "info",
    DEBUG = "debug"
}
/**
 * Supported log output formats.
 */
export declare enum LogFormat {
    JSON = "json",
    SIMPLE = "simple"
}
/**
 * Logger configuration options.
 */
export interface LoggerOptions {
    /**
     * File name to include in logs.
     */
    fileName?: string;
    /**
     * Minimum log level.
     */
    logLevel?: LogLevel;
    /**
     * Log output format.
     */
    format?: LogFormat;
    /**
     * Custom Winston transports.
     */
    transports?: WinstonTransport[];
    /**
     * List of sensitive keys to redact from log metadata (case-insensitive).
     * These will be merged with the default list: ['password', 'token', 'secret', 'apikey', 'authorization']
     */
    sensitiveKeys?: string[];
    /**
     * Enable colorized console output (for development/debugging). Only applies to LogFormat.SIMPLE. Default: false
     */
    colorize?: boolean;
    /**
     * String to use for redacted sensitive fields. Default: '***'
     */
    redactionString?: string;
}
/**
 * Metadata for log entries.
 */
export interface LogMeta {
    [key: string]: unknown;
}
/**
 * PsChronicleLogger: Extensible Winston logger wrapper.
 */
export declare class PsChronicleLogger {
    /**
     * Winston logger instance.
     */
    private logger;
    /**
     * Log output format.
     */
    private outputFormat;
    /**
     * Method name.
     */
    private methodName;
    /**
     * Default log level.
     */
    private defaultLogLevel;
    /**
     * File name.
     */
    private fileName?;
    /**
     * List of sensitive keys to redact from log metadata (case-insensitive).
     */
    private sensitiveKeys;
    /**
     * Set for fast sensitive key lookup (case-insensitive).
     */
    private sensitiveKeySet;
    /**
     * Enable colorized console output.
     */
    private colorize;
    /**
     * String to use for redacted sensitive fields.
     */
    private redactionString;
    /**
     * Global customer name (applies to all logger instances).
     */
    private static globalCustomerName?;
    /**
     * Global request ID (applies to all logger instances).
     */
    private static globalRequestId?;
    /**
     * Convert bytes to a human-readable string (e.g., MB, GB).
     * @param bytes Number of bytes
     * @returns Human-readable string
     */
    private static formatBytes;
    /**
     * Create a new logger instance.
     * @param options Logger configuration options
     */
    constructor(options?: LoggerOptions);
    /**
     * Recursively redacts sensitive fields in an object.
     * Key comparison is case-insensitive.
     * @param obj The object to redact
     * @returns A new object with sensitive fields redacted (using this.redactionString)
     */
    private redactSensitiveData;
    /**
     * Set the method name for the next log.
     */
    setMethodName(methodName: string): void;
    /**
     * Get the current method name.
     */
    getMethodName(): string;
    /**
     * Serialize an Error object to a structured object with name, message, stack, status, code, and primitive custom fields.
     * Nested objects/arrays are summarized as '[Object]' or '[Array]' to avoid logging large or sensitive data.
     * @param err The error object to serialize
     * @returns A plain object with error details
     */
    private serializeError;
    /**
     * Recursively serialize Error objects in metadata to structured objects.
     * @param obj The metadata object
     * @returns The metadata with all Error objects serialized
     */
    private serializeErrorsInMeta;
    /**
     * Log a message with the given level and metadata.
     * Sensitive fields in metadata will be redacted.
     * Error objects in metadata will be serialized to structured objects (name, message, stack, status, ...).
     * @param level Log level
     * @param message Log message
     * @param xadditionalInfo Additional metadata objects
     */
    log(level: LogLevel, message: string, ...xadditionalInfo: LogMeta[]): void;
    /**
     * Add details to the log entry.
     */
    private addDetailsFormat;
    /**
     * Wait for the logger to finish processing logs (useful for async shutdown).
     */
    waitForLogger(): Promise<unknown>;
    /**
     * Start a timer for performance measurement.
     * @returns The current timestamp in milliseconds.
     */
    startTimer(): number;
    /**
     * Log the duration of an operation.
     * @param operation Name of the operation
     * @param startTime Timestamp from startTimer()
     * @param extraMeta Additional metadata to include
     * @returns The duration in seconds
     */
    logPerformance(operation: string, startTime: number, extraMeta?: LogMeta): number;
    /**
     * Measure and log the duration of an async function.
     * Logs duration and errors if thrown.
     * @param operation Name of the operation
     * @param fn Async function to measure
     * @param extraMeta Additional metadata to include
     */
    measurePerformance<T>(operation: string, fn: () => Promise<T>, extraMeta?: LogMeta): Promise<T>;
    /**
     * Log current memory usage in a human-readable format.
     * @param label Optional label for the log entry
     */
    logMemoryUsage(label?: string): void;
    /**
     * Dynamically set the log level for this logger instance.
     * Updates all transports and the defaultLogLevel field.
     * @param level The new log level (must be a valid LogLevel)
     */
    setLogLevel(level: LogLevel): void;
    /**
     * Get the current log level for this logger instance.
     * @returns The current log level
     */
    getLogLevel(): LogLevel;
    /**
     * Check if a log level is enabled for this logger instance.
     * Use before doing expensive work for logs.
     * @param level Log level to check
     * @returns true if enabled, false otherwise
     */
    isLevelEnabled(level: LogLevel): boolean;
    /**
     * Set the global customer name for all logger instances.
     */
    setCustomerName(customerName: string): void;
    /**
     * Get the global customer name for all logger instances.
     */
    getCustomerName(): string | undefined;
    /**
     * Set the global request ID for all logger instances.
     */
    setRequestId(requestId: string): void;
    /**
     * Get the global request ID for all logger instances.
     */
    getRequestId(): string | undefined;
}