A small utility for generating consistent warning objects across a 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.
name (string, required) - The error name, accessible through
error.name. For consistency, prefix module error names with
{ModuleName}Warning.
code (string, required) - The warning code, accessible through
error.code. For consistency, prefix plugin error codes with
{ThreeLetterModuleName}_, e.g. FST_. Note: Codes should be all uppercase.
message (string, required) - The warning message. Interpolated strings
can also be used to format 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 be used to emit warnings.
A warning is guaranteed to be emitted at least once.
[, a [, b [, c]]] (any, optional) - Parameters for string interpolation.
The warning object has methods and properties for managing the warning's state. These are 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) // falseFST_ERROR_CODE('world')console.log(FST_ERROR_CODE.emitted) // trueconst FST_ERROR_CODE_2 = createWarning('MyAppWarning', 'FST_ERROR_CODE_2', 'Hello %s')FST_ERROR_CODE_2.emitted = trueFST_ERROR_CODE_2('world') // Will not be emitted because it is not unlimited
Using 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 emittedFST_ERROR_CODE('world') // Will be emitted again
spyWarning(warning)
Spy on the created warning function for testing purposes.
const { test } = require('node:test')const { createWarning, spyWarning } = require('process-warning')const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s' })test('spy warning', t => { const spyData = spyWarning(FST_ERROR_CODE) // Call after spying const emitted = FST_ERROR_CODE('world') t.assert.strictEqual(emitted, true) // Restore the warning function // This must be called when spying is no longer required // Otherwise, the call data will accumulate
Suppressing warnings
Warnings can be suppressed by using one of Node.js's built-in warning suppression mechanisms:
Setting the NODE_NO_WARNINGS environment variable to 1
Passing the --no-warnings flag to the Node.js process
Setting --no-warnings in the NODE_OPTIONS environment variable