Providing additional functionality to customPrettifiers and messageFormat

[FoxxMD]

This PR is combined changes from #493 and #494 (see these comments 1 2). Summary of changes:

Extend/Normalize all "format" functions with extras object

All "format" functions -- customPrettifiers, level, and messageFormat -- now have an additional parameter, extras that is an object of Record<string, any>. This allows for additional data and future (optional) functionality to be provided to these functions without having to change function signature again.

This change is backward compatible but the examples in the documentation for these functions has been updated to include the existing, full, list of parameters that were available instead of just the first parameter. EX

Previous:

{
  customPrettifiers: {
    caller: caller => `My Caller: ${caller}`
  }
}

{
  messageFormat: (log, messageKey, levelLabel) => {
    return customized_message;
  }
}

New:

{
  customPrettifiers: {
    caller: (caller, key, log, extras) => `My Caller: ${caller}`,
  }
}

{
  messageFormat: (log, messageKey, levelLabel, extras) => {
    return `This is a custom message: ${log[messageKey]}`;
  }
}

Provide Colorette colors to all "format" functions #494

Enables users to use available colors based on colorize context of the pino-pretty instance.

Currently if a user wants to color their messages they need to create their own instances of Colorette and implement logic, outside of pino-pretty, to make sure the useColors option passed matches what was given to pino-pretty as colorize. However pino-pretty already has this object available...this PR provides colors to the extras object for all format functions so that the user doesn't need to do that extra work.

{
  customPrettifiers: {
    caller: (caller, key, log, { colors } ) => `${colors.greenBright(caller)}`,
  },
  messageFormat: (log, messageKey, levelLabel, { colors }) => {
    // do some log message customization
    //
    // `colors` is a Colorette object with colors enabled based on `colorize` option
    return `This is a ${color.red('colorized')}, custom message: ${log[messageKey]}`;
  }
}

Add context to level customPrettifier #493

Currently the customPrettifier for level only returns the numeric level value (if levelKey is not used) which means that anyone who wants to modify value returned has to re-implement the levels pino-pretty already has access to as well as calculate the label to use, which pino-pretty also already does.

This PR include both the "final" log label as well as the colorized output, if applicable, to level prettifier function to give users more control over level output. These values are included in the extras object:

{
  customPrettifiers: {
  // level provides additional data in `extras`:
  // * label => derived level label string
  // * labelColorized => derived level label string with colorette colors applied based on customColors and whether colors are supported
  level: (logLevel, key, log, { label, labelColorized, colors }) => `LEVEL: ${logLevel} LABEL: ${levelLabel} COLORIZED LABEL: ${labelColorized}`,
  }
}

It has the additional benefit of enabling users to handle their own level alignment (#489 #140) since they have access to the final string values for level. As example implementation for aligning with spaces:

{
  customPrettifiers: {
        level: (logLevel, key, log, { label, labelColorized }) => {
            // pad to fix alignment
            // assuming longest level is VERBOSE
            // and may be colorized
            const paddedLabel = label.padEnd(8)
            if(labelColorized !== label) {
                const padDiff = paddedLabel.length - label.length;
                return labelColorized.padEnd(labelColorized.length + padDiff);
            }
            return paddedLabel;
        }
    },
}

[FoxxMD]

Please hold off...there's a bug somewhere that is showing up in my app but not in tests.

[FoxxMD]

Fixed :+1:

[mcollina]

@jsumners I think it's safer to bump a major on this one.

[FoxxMD]

@mcollina thank you for the effort on getting pino-roll updated! Any chance this can move forward too? :)

[FoxxMD]

Thank you! :heart: