modern-errors-winston

modern-errors plugin for Winston.

This adds BaseError.fullFormat() and BaseError.shortFormat() which return a Winston format.

Features

Improved error logging with Winston:

• Error class/instance-specific log level or verbosity
• The full format includes all properties
• The short format includes only the error's name, message and stack
• Works with uncaught exceptions

Unlike Winston's default error format:

• The error name is logged
• The full format logs nested errors, including cause and aggregate errors
• The full format is JSON-safe
• The short format optionally logs the stack trace
• The error instance is not modified

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'

import modernErrorsWinston from 'modern-errors-winston'

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsWinston],
})
export const InputError = BaseError.subclass('InputError')
// ...

Using the full format with Winston.

import { createLogger, format, transports } from 'winston'

const logger = createLogger({
  format: format.combine(BaseError.fullFormat(), format.json()),
  transports: [new transports.Http(httpOptions)],
})

const error = new InputError('Could not read file.', { props: { filePath } })
logger.error(error)
// Sent via HTTP:
// {
//   level: 'error',
//   name: 'InputError',
//   message: 'Could not read file.',
//   stack: `InputError: Could not read file.
//     at ...`,
//   filePath: '/...',
// }

Using the short format with Winston.

import { createLogger, format, transports } from 'winston'

const logger = createLogger({
  format: format.combine(BaseError.shortFormat(), format.cli()),
  transports: [new transports.Console()],
})

const error = new InputError('Could not read file.', { props: { filePath } })
logger.error(error)
// Printed on the console:
// error: InputError: Could not read file.
//     at ...

Install

npm install modern-errors-winston

This package requires installing Winston separately.

npm install winston

This package works in Node.js >=18.18.0.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

modernErrorsWinston

Type: Plugin

Plugin object to pass to the plugins option of ErrorClass.subclass().

BaseError.fullFormat()

Return value: Format

Returns a logger format to combine with format.json() or format.prettyPrint(). This logs all error properties, making it useful with transports like HTTP.

Errors should be logged using logger.*(error).

BaseError.shortFormat()

Return value: Format

Returns a logger format to combine with format.simple() or format.cli(). This logs only the error name, message and stack, making it useful with transports like the console.

Errors should be logged using logger.*(error).

Options

Type: object

stack

Type: boolean
Default: true

Whether to log the stack trace.

level

Type: string

Override the log level.

Configuration

Options can apply to (in priority order):

• Any error: second argument to ModernError.subclass()

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsWinston],
  winston: options,
})

• Any error of a specific class (and its subclasses): second argument to ErrorClass.subclass()

export const InputError = BaseError.subclass('InputError', { winston: options })

• A specific error: second argument to new ErrorClass()

throw new InputError('...', { winston: options })

• A specific BaseError.fullFormat() or BaseError.shortFormat() call

BaseError.fullFormat(options)

Related projects

• winston: A logger for just about everything
• modern-errors: Handle errors in a simple, stable, consistent way
• winston-error-format: Log errors with Winston
• error-serializer: Convert errors to/from plain objects
• modern-errors-cli: Handle errors in CLI modules
• modern-errors-process: Handle process errors
• modern-errors-bugs: Print where to report bugs
• modern-errors-serialize: Serialize/parse errors
• modern-errors-clean: Clean stack traces
• modern-errors-http: Create HTTP error responses
• modern-errors-switch: Execute class-specific logic

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!