[Bug]: Document that format: customFormatter() won't work and/or provide a more informative error when the mistake is made

[DanKaplanSES]

🔎 Search Terms

logform, custom formats, createLogger

The problem

The Creating custom formats section implies that you can assign your custom format to the createLogger.format key, but this is not the case. This is the entire code example given:

const { format } = require('winston');

const volume = format((info, opts) => {
  if (opts.yell) {
    info.message = info.message.toUpperCase();
  } else if (opts.whisper) {
    info.message = info.message.toLowerCase();
  }

  return info;
});

// `volume` is now a function that returns instances of the format.
const scream = volume({ yell: true });
console.dir(scream.transform({
  level: 'info',
  message: `sorry for making you YELL in your head!`
}, scream.options));
// {
//   level: 'info'
//   message: 'SORRY FOR MAKING YOU YELL IN YOUR HEAD!'
// }

// `volume` can be used multiple times to create different formats.
const whisper = volume({ whisper: true });
console.dir(whisper.transform({
  level: 'info',
  message: `WHY ARE THEY MAKING US YELL SO MUCH!`
}, whisper.options));
// {
//   level: 'info'
//   message: 'why are they making us yell so much!'
// }

This does not show how to use scream or whisper with createLogger, so this would be the natural expectation:

const logger = createLogger({
  format: scream, // or whisper
  transports: [new transports.Console()]
});

Not only does this fail to work, it prints undefined for every log message, making it difficult to troubleshoot. Here's my guess for why this is wrong: winston requires a "base" format of some kind—e.g., format.simple(), format.json(), etc.—to be format.combined with the custom format. So while the above will print undefined for every log, this will print the log as expected:

const logger = createLogger({
  format: format.combine(
    scream, // or whisper
    format.simple()
  ),
  transports: [new transports.Console()]
});

This should be mentioned somewhere in the documentation so users can troubleshoot this mistake without looking at the source code.

What version of Winston presents the issue?

v3.12.0

What version of Node are you using?

v20.10.0

If this worked in a previous version of Winston, which was it?

No response

Minimum Working Example

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

const logPrefix = format((info, opts) => {
return info;
});

const logger = createLogger({
level: 'debug',
format: logPrefix(), // compare to this line instead: format: format.combine(logPrefix(), format.simple()),
transports: new transports.Console(),
exceptionHandlers: new transports.Console(),
rejectionHandlers: new transports.Console(),
exitOnError: false,
});

logger.debug(foobar);

Additional information

No response

[absolution54321]

Thanks for opening this, I can vouch for this, does not work for Winston 3.15 & Node 20.15 either, combine fails too.

[DABH]

Happy to review a PR for this