Process Warning Utility

5.0.0 · active · verified Sun Apr 19

process-warning is a lightweight utility designed to standardize the creation and emission of warnings within JavaScript and TypeScript applications, particularly for the Fastify ecosystem. It ensures that warnings, including deprecation warnings, are consistently formatted and, by default, emitted only once to prevent log spam. The current stable version is 5.0.0. The package maintains a regular release cadence, often aligning with Node.js version updates and Fastify development, with minor releases for bug fixes and dependency bumps and occasional major releases for refactoring or dropping older Node.js support. Its key differentiators include built-in one-time emission, support for Node.js's native deprecation warning CLI options, and a clear API for defining warning codes and messages.

Common errors

```
TypeError: createWarning is not a function
```
cause Attempting to import `createWarning` or `createDeprecation` using CommonJS `require` syntax in an ESM module, or vice-versa, or incorrect destructuring.

fix For ESM, use `import { createWarning } from 'process-warning';`. For CommonJS, use `const { createWarning } = require('process-warning');`. Ensure correct destructuring and module type configuration in `package.json` if using hybrid modules.
```
Error: The "code" argument must be of type string. Received undefined
```
cause The `code` property is missing or `undefined` in the options object passed to `createWarning` or `createDeprecation`.

fix Ensure that the `code` property, a unique string identifier, is provided and correctly spelled in the options object for `createWarning` or `createDeprecation`.
```
Warning: (node:12345) MyModuleWarning: This is a warning for value: someValue
```
cause A warning is being emitted, but it's unexpected or occurs in a context where warnings should be suppressed (e.g., in tests).

fix Use Node.js's `--no-warnings` CLI flag to suppress all warnings, or specifically configure `process-warning` to suppress the particular warning by interacting with its `emitted` state for testing, e.g., `MyModuleWarning.emitted = true` to prevent future emissions.

Warnings

breaking Version 3.0.0 introduced a significant refactoring (Pull Request #96) which might have breaking changes for how warnings are configured or behave, although the changelog does not detail specific API changes beyond 'Refactoring (v3)'. Users upgrading from v2.x should carefully review their warning implementations.
Fix: Review `createWarning` and `createDeprecation` usage against v3.0.0 documentation. Test warning emission and suppression thoroughly after upgrade.
breaking As of v5.0.0, support for older Node.js versions (Node.js 16 and 18) has been removed from the test matrix, implying that these versions may no longer be officially supported or tested. While the library might still function, compatibility is not guaranteed, and future issues may not be addressed.
Fix: Ensure your project runs on Node.js 20 or newer. Upgrade your Node.js runtime if you are still on Node.js 16 or 18.
gotcha By default, warnings created with `createWarning` are emitted only once per unique warning function call, even if called with different interpolation arguments. To emit a warning multiple times, the `unlimited: true` option must be explicitly set during warning creation.
Fix: If a warning needs to be emitted repeatedly, pass `{ unlimited: true }` in the options object to `createWarning` or `createDeprecation`.
gotcha When using `createDeprecation`, the warning integrates with Node.js's native `--throw-deprecation`, `--no-deprecation`, and `--trace-deprecation` CLI options. Developers should be aware of these Node.js flags as they can alter the behavior of deprecation warnings, potentially throwing errors instead of just logging.
Fix: Be mindful of Node.js CLI flags when developing or deploying applications using `createDeprecation`. Communicate these potential environmental impacts to users or other developers if your module emits deprecation warnings.

Install

npm install process-warning npm
yarn add process-warning yarn
pnpm add process-warning pnpm

Imports

createWarning
wrong:
```
const { createWarning } = require('process-warning')
```
correct:
```
import { createWarning } from 'process-warning'
```
ESM is preferred. CommonJS `require` is also supported but not recommended for new projects.
createDeprecation
wrong:
```
const { createDeprecation } = require('process-warning')
```
correct:
```
import { createDeprecation } from 'process-warning'
```
Specifically for creating deprecation warnings that interact with Node.js's built-in deprecation handling.
WarningFunction
```
import type { WarningFunction } from 'process-warning'
```
Type import for the warning function returned by createWarning/createDeprecation.

Quickstart

Demonstrates creating and emitting both standard and deprecation warnings, including the 'unlimited' option.

import { createWarning, createDeprecation } from 'process-warning';

const MyModuleWarning = createWarning({
  name: 'MyModuleWarning',
  code: 'MYMOD_001',
  message: 'This is a warning for value: %s'
});

const MyModuleDeprecation = createDeprecation({
  code: 'MYMOD_DEP_002',
  message: 'The %s method is deprecated, use %s instead.'
});

console.log('Emitting first warning...');
MyModuleWarning('someValue'); // Emits the warning

console.log('Attempting to emit same warning again...');
MyModuleWarning('anotherValue'); // Will not emit by default (unlimited: false)

console.log('Emitting deprecation warning...');
MyModuleDeprecation('oldMethod', 'newMethod'); // Emits a deprecation warning

const UnlimitedWarning = createWarning({
  name: 'UnlimitedWarning',
  code: 'UNL_003',
  message: 'This warning will always emit for %s',
  unlimited: true
});

console.log('Emitting unlimited warning...');
UnlimitedWarning('first call'); // Emits
UnlimitedWarning('second call'); // Emits again

view raw JSON →