tessl/npm-winston

A comprehensive, multi-transport logging library for Node.js applications providing flexible and extensible logging capabilities.

—

Pending

Overview

Eval results

Files

Transports

Name: tessl/npm-winston
Author: tessl

Transport classes for outputting logs to various destinations including console, files, HTTP endpoints, and arbitrary streams.

Capabilities

Console Transport

Transport for outputting log messages to the console with configurable output streams and formatting.

/**
 * Console transport for outputting to console/terminal
 */
class Console extends TransportStream {
  constructor(options?: ConsoleTransportOptions);
}

interface ConsoleTransportOptions {
  /** Transport name for identification */
  name?: string;
  /** Minimum log level for this transport */
  level?: string;
  /** Suppress all output from this transport */
  silent?: boolean;
  /** End of line character(s) */
  eol?: string;
  /** Array of levels to output to stderr instead of stdout */
  stderrLevels?: string[];
  /** Array of levels to use console.warn instead of console.log */
  consoleWarnLevels?: string[];
  /** Force console output even when not in a TTY */
  forceConsole?: boolean;
  /** Log message formatting */
  format?: Format;
}

Usage Examples:

const winston = require('winston');

// Basic console transport
const logger = winston.createLogger({
  transports: [
    new winston.transports.Console()
  ]
});

// Console with custom options
const logger2 = winston.createLogger({
  transports: [
    new winston.transports.Console({
      level: 'debug',
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      ),
      stderrLevels: ['error'],
      consoleWarnLevels: ['warn']
    })
  ]
});

File Transport

Transport for outputting log messages to files with support for rotation, compression, and custom streams.

/**
 * File transport for outputting to log files
 */
class File extends TransportStream {
  constructor(options: FileTransportOptions);
}

interface FileTransportOptions {
  /** Target file path (required) */
  filename: string;
  /** Directory for log files */
  dirname?: string;
  /** Transport name for identification */
  name?: string;
  /** Minimum log level for this transport */
  level?: string;
  /** Suppress all output from this transport */
  silent?: boolean;
  /** End of line character(s) */
  eol?: string;
  /** Maximum file size in bytes before rotation */
  maxsize?: number;
  /** Maximum number of files to keep */
  maxFiles?: number;
  /** Function to generate rotation filename */
  rotationFormat?: Function;
  /** Compress rotated files with gzip */
  zippedArchive?: boolean;
  /** File stream options */
  options?: object;
  /** Custom writable stream */
  stream?: Stream;
  /** Whether the log file is tailable */
  tailable?: boolean;
  /** Whether to lazy-open the file stream */
  lazy?: boolean;
  /** Create directory if it doesn't exist */
  handleExceptions?: boolean;
  /** Handle uncaught exceptions */
  handleRejections?: boolean;
  /** Log message formatting */
  format?: Format;
}

Usage Examples:

const winston = require('winston');

// Basic file transport
const logger = winston.createLogger({
  transports: [
    new winston.transports.File({ filename: 'app.log' })
  ]
});

// File with rotation and compression
const logger2 = winston.createLogger({
  transports: [
    new winston.transports.File({
      filename: 'error.log',
      level: 'error',
      maxsize: 5242880, // 5MB
      maxFiles: 5,
      zippedArchive: true
    }),
    new winston.transports.File({
      filename: 'combined.log',
      maxsize: 5242880,
      maxFiles: 10
    })
  ]
});

HTTP Transport

Transport for sending log messages to HTTP endpoints with support for batching and authentication.

/**
 * HTTP transport for sending logs to HTTP endpoints
 */
class Http extends TransportStream {
  constructor(options?: HttpTransportOptions);
}

interface HttpTransportOptions {
  /** Target hostname */
  host?: string;
  /** Target port number */
  port?: number;
  /** HTTP path */
  path?: string;
  /** HTTP method */
  method?: string;
  /** Use HTTPS instead of HTTP */
  ssl?: boolean;
  /** HTTP headers object */
  headers?: object;
  /** Authentication credentials */
  auth?: object;
  /** HTTP agent for connection pooling */
  agent?: object;
  /** Transport name for identification */
  name?: string;
  /** Minimum log level for this transport */
  level?: string;
  /** Suppress all output from this transport */
  silent?: boolean;
  /** Enable request batching */
  batch?: boolean;
  /** Batch interval in milliseconds */
  batchInterval?: number;
  /** Maximum batch size */
  batchCount?: number;
  /** Log message formatting */
  format?: Format;
}

Usage Examples:

const winston = require('winston');

// Basic HTTP transport
const logger = winston.createLogger({
  transports: [
    new winston.transports.Http({
      host: 'logs.example.com',
      port: 80,
      path: '/api/logs'
    })
  ]
});

// HTTPS with authentication and batching
const logger2 = winston.createLogger({
  transports: [
    new winston.transports.Http({
      host: 'secure-logs.example.com',
      port: 443,
      path: '/logs',
      ssl: true,
      auth: {
        username: 'user',
        password: 'pass'
      },
      headers: {
        'Authorization': 'Bearer token123'
      },
      batch: true,
      batchInterval: 5000,
      batchCount: 10
    })
  ]
});

Stream Transport

Transport for outputting log messages to arbitrary writable streams.

/**
 * Stream transport for outputting to any writable stream
 */
class Stream extends TransportStream {
  constructor(options: StreamTransportOptions);
}

interface StreamTransportOptions {
  /** Target writable stream (required) */
  stream: Stream;
  /** Transport name for identification */
  name?: string;
  /** Minimum log level for this transport */
  level?: string;
  /** Suppress all output from this transport */
  silent?: boolean;
  /** End of line character(s) */
  eol?: string;
  /** Log message formatting */
  format?: Format;
}

Usage Examples:

const winston = require('winston');
const fs = require('fs');

// Stream to file
const fileStream = fs.createWriteStream('./logs/app.log');
const logger = winston.createLogger({
  transports: [
    new winston.transports.Stream({
      stream: fileStream
    })
  ]
});

// Stream to process stdout
const logger2 = winston.createLogger({
  transports: [
    new winston.transports.Stream({
      stream: process.stdout,
      format: winston.format.simple()
    })
  ]
});

Transport Base Classes

Base classes that all transports extend, providing common functionality and streaming capabilities.

/**
 * Base transport class
 */
class Transport {
  constructor(options?: TransportOptions);
  
  /** Transport name */
  name: string;
  /** Minimum log level */
  level: string;
  /** Silent mode flag */
  silent: boolean;
  /** Log message formatting */
  format?: Format;
}

/**
 * Stream-based transport class (extends Node.js Writable stream)
 */
abstract class TransportStream extends Transport {
  constructor(options?: TransportOptions);
  
  /** Log method that must be implemented by subclasses */
  abstract log(info: TransformableInfo, callback: () => void): void;
  
  /** Handle logging errors */
  handleError(err: Error): void;
  
  /** Close the transport and clean up resources */
  close(): void;
  
  /** Query historical logs (if supported) */
  query?(options: QueryOptions, callback: (err: Error, results: any) => void): void;
  
  /** Create log stream (if supported) */
  stream?(options: StreamOptions): ReadableStream;
}

interface TransportOptions {
  /** Transport name for identification */
  name?: string;
  /** Minimum log level for this transport */
  level?: string;
  /** Suppress all output from this transport */
  silent?: boolean;
  /** Log message formatting */
  format?: Format;
  /** Handle exceptions through this transport */
  handleExceptions?: boolean;
  /** Handle rejections through this transport */
  handleRejections?: boolean;
}

interface TransformableInfo {
  /** Log level */
  level: string;
  /** Log message */
  message: string;
  /** Timestamp if present */
  timestamp?: string;
  /** Stack trace if error */
  stack?: string;
  /** Additional metadata */
  [key: string]: any;
}

interface QueryOptions {
  rows?: number;
  limit?: number;
  start?: number;
  from?: Date;
  until?: Date;
  order?: 'asc' | 'desc';
  fields?: any;
}

interface StreamOptions {
  start?: number;
  [key: string]: any;
}

Common Transport Usage Patterns

Multiple transports with different levels:

const winston = require('winston');

const logger = winston.createLogger({
  level: 'debug',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    // Error logs to separate file
    new winston.transports.File({
      filename: 'error.log',
      level: 'error'
    }),
    // All logs to combined file
    new winston.transports.File({
      filename: 'combined.log'
    }),
    // Console output in development
    new winston.transports.Console({
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      )
    })
  ]
});

Dynamic transport management:

const winston = require('winston');

const logger = winston.createLogger({
  transports: [
    new winston.transports.Console()
  ]
});

// Add file transport in production
if (process.env.NODE_ENV === 'production') {
  logger.add(new winston.transports.File({
    filename: 'production.log'
  }));
}

// Remove console transport in production
if (process.env.NODE_ENV === 'production') {
  logger.remove(winston.transports.Console);
}

Install with Tessl CLI