fastify / process-warning

A small utility for creating warnings and emitting them.

process-warning

A small utility for generating consistent warning objects across your codebase. It also exposes a utility for emitting those warnings, guaranteeing that they are issued only once (unless configured otherwise).

This module is used by the Fastify framework and it was called fastify-warning prior to version 1.0.0.

Install

npm i process-warning

Usage

The module exports two builder functions for creating warnings.

const {
  createWarning,
  createDeprecation
} = require('process-warning')

const warning = createWarning({
  name: 'ExampleWarning',
  code: 'EXP_WRN_001',
  message: 'Hello %s',
  unlimited: true
})
warning('world')

Methods

createWarning({ name, code, message[, unlimited] })

• name (string, required) - The error name, you can access it later with error.name. For consistency, we recommend prefixing module error names with {YourModule}Warning
• code (string, required) - The warning code, you can access it later with error.code. For consistency, we recommend prefixing plugin error codes with {ThreeLetterModuleName}_, e.g. FST_. NOTE: codes should be all uppercase.
• message (string, required) - The warning message. You can also use interpolated strings for formatting the message.
• options (object, optional) - Optional options with the following properties:
  • unlimited (boolean, optional) - Should the warning be emitted more than once? Defaults to false.

createDeprecation({code, message[, options]})

This is a wrapper for createWarning. It is equivalent to invoking createWarning with the name parameter set to "DeprecationWarning".

Deprecation warnings have extended support for the Node.js CLI options: --throw-deprecation, --no-deprecation, and --trace-deprecation.

warning([, a [, b [, c]]])

The returned warning function can used for emitting warnings. A warning is guaranteed to be emitted at least once.

• [, a [, b [, c]]] (any, optional) - Parameters for string interpolation.

const { createWarning } = require('process-warning')
const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'message' })
FST_ERROR_CODE()

How to use an interpolated string:

const { createWarning } = require('process-warning')
const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s'})
FST_ERROR_CODE('world')

The warning object has methods and properties for managing the warning's state. Useful for testing.

const { createWarning } = require('process-warning')
const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s'})
console.log(FST_ERROR_CODE.emitted) // false
FST_ERROR_CODE('world')
console.log(FST_ERROR_CODE.emitted) // true

const FST_ERROR_CODE_2 = createWarning('MyAppWarning', 'FST_ERROR_CODE_2', 'Hello %s')
FST_ERROR_CODE_2.emitted = true
FST_ERROR_CODE_2('world') // will not be emitted because it is not unlimited

How to use an unlimited warning:

const { createWarning } = require('process-warning')
const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s', unlimited: true })
FST_ERROR_CODE('world') // will be emitted
FST_ERROR_CODE('world') // will be emitted again

Suppressing warnings

It is possible to suppress warnings by utilizing one of node's built-in warning suppression mechanisms.

Warnings can be suppressed:

• by setting the NODE_NO_WARNINGS environment variable to 1
• by passing the --no-warnings flag to the node process
• by setting '--no-warnings' in the NODE_OPTIONS environment variable

For more information see node's documentation.

License

Licensed under MIT.

process-warning's Issues

Reimplementation

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

If I would need to implement this function I would implement it differently. E.g. calling warning.emit('XYZ') makes it necessary to lookup the existing warnings.

From the API usage I would do it like this:

const warning = require('process-warning')()

const FSTWRN001 = warning.create('FastifyWarning', 'FSTWRN001', 'The %s schema for %s: %s is missing. This may indicate the schema is not well specified.', { unlimited: true })

FSTWRN001.emit()

All the warnings are either "fire once" or "unlimited" based on the flag passed to last "create" method

Basically, due to this piece of code:

process-warning/index.js

Line 94 in c0649f8

Object.assign(opts, { unlimited })

The last created warning decides wether all the created warnings are limited or unlimited. Thus in fastify, since last created warning is made unlimited:
https://github.com/fastify/fastify/blob/99a405a4e347629595ac5062c74d91675b1b34e5/lib/warnings.js#L58

warning.create('FastifyWarning', 'FSTWRN002', 'The %s plugin being registered mixes async and callback styles, which will result in an error in `fastify@5`', { unlimited: true })

All the declared warnings are spamming the application :)

Should either move opts inside "create" or add a new hashmap for the unlimited flag

Issue a v1.0.0 release

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

pinojs/pino#1269

The time has long passed for a v1.0.0 release. We really shouldn't be shipping major, non-RC, versions of Fastify with 0.y.z dependencies; especially not dependencies we control.

Deprecate fastify-warning

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

After the rename to process-warning, I plan to deprecate fastify-warning.

The main dependents of this module are:

• fastify fastify/fastify#3576
• pino v6 pinojs/pino#1283
• pino v7 pinojs/pino#1282
• verdaccio verdaccio/verdaccio#2821

I'll deprecate fastify-warning as soon as those are migrated.

Motivation

No response

Example

No response

Disable process warnings per Environment variable

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

It should be possible to disable warnings per environment variable, e.g. PROCESS_WARNING_DISABLE=1, or maybe specify which warnings to disable, e.g. PROCESS_WARNING_DISABLE=FSTDEP018,FSTDEP015

Motivation

It could be useful to disable process warnings, especially now that we are deprecating more and more functionality in fastify v4.

If we would decide to allow specifying which warnings should not be emitted anymore, then a dev could be empowered to "acknowledge" the warning and realize that there is a potential technical debt, but maybe does not want to solve the warning immediatly.

Example

No response

FastifyWarning not an instance of Error

I am running into an issue using typescript, fastify, and jest.
A plugin I am using is throwing a FastifyWarning.
Jest blows up with:

    TypeError [ERR_INVALID_ARG_TYPE]: The "warning" argument must be of type string or an instance of Error. Received an instance of FastifyWarning
        at process.emitWarning (internal/process/warning.js)