{"id":11586,"library":"process-warning","title":"Process Warning Utility","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/fastify/process-warning","tags":["javascript","fastify","error","warning","utility","plugin","emit","once","typescript"],"install":[{"cmd":"npm install process-warning","lang":"bash","label":"npm"},{"cmd":"yarn add process-warning","lang":"bash","label":"yarn"},{"cmd":"pnpm add process-warning","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is preferred. CommonJS `require` is also supported but not recommended for new projects.","wrong":"const { createWarning } = require('process-warning')","symbol":"createWarning","correct":"import { createWarning } from 'process-warning'"},{"note":"Specifically for creating deprecation warnings that interact with Node.js's built-in deprecation handling.","wrong":"const { createDeprecation } = require('process-warning')","symbol":"createDeprecation","correct":"import { createDeprecation } from 'process-warning'"},{"note":"Type import for the warning function returned by createWarning/createDeprecation.","symbol":"WarningFunction","correct":"import type { WarningFunction } from 'process-warning'"}],"quickstart":{"code":"import { createWarning, createDeprecation } from 'process-warning';\n\nconst MyModuleWarning = createWarning({\n  name: 'MyModuleWarning',\n  code: 'MYMOD_001',\n  message: 'This is a warning for value: %s'\n});\n\nconst MyModuleDeprecation = createDeprecation({\n  code: 'MYMOD_DEP_002',\n  message: 'The %s method is deprecated, use %s instead.'\n});\n\nconsole.log('Emitting first warning...');\nMyModuleWarning('someValue'); // Emits the warning\n\nconsole.log('Attempting to emit same warning again...');\nMyModuleWarning('anotherValue'); // Will not emit by default (unlimited: false)\n\nconsole.log('Emitting deprecation warning...');\nMyModuleDeprecation('oldMethod', 'newMethod'); // Emits a deprecation warning\n\nconst UnlimitedWarning = createWarning({\n  name: 'UnlimitedWarning',\n  code: 'UNL_003',\n  message: 'This warning will always emit for %s',\n  unlimited: true\n});\n\nconsole.log('Emitting unlimited warning...');\nUnlimitedWarning('first call'); // Emits\nUnlimitedWarning('second call'); // Emits again\n","lang":"typescript","description":"Demonstrates creating and emitting both standard and deprecation warnings, including the 'unlimited' option."},"warnings":[{"fix":"Review `createWarning` and `createDeprecation` usage against v3.0.0 documentation. Test warning emission and suppression thoroughly after upgrade.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If a warning needs to be emitted repeatedly, pass `{ unlimited: true }` in the options object to `createWarning` or `createDeprecation`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `createWarning` or `createDeprecation` using CommonJS `require` syntax in an ESM module, or vice-versa, or incorrect destructuring.","error":"TypeError: createWarning is not a function"},{"fix":"Ensure that the `code` property, a unique string identifier, is provided and correctly spelled in the options object for `createWarning` or `createDeprecation`.","cause":"The `code` property is missing or `undefined` in the options object passed to `createWarning` or `createDeprecation`.","error":"Error: The \"code\" argument must be of type string. Received undefined"},{"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.","cause":"A warning is being emitted, but it's unexpected or occurs in a context where warnings should be suppressed (e.g., in tests).","error":"Warning: (node:12345) MyModuleWarning: This is a warning for value: someValue"}],"ecosystem":"npm"}