or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-process-warning

A small utility for creating warnings and emitting them.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/process-warning@5.0.x

To install, run

npx @tessl/cli install tessl/npm-process-warning@5.0.0

index.mddocs/

Process Warning

Process Warning is a small utility for generating consistent warning objects across Node.js codebases. It provides functions to create both regular warnings and deprecation warnings with structured error codes, custom messages, and configurable emission control.

Package Information

  • Package Name: process-warning
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install process-warning

Core Imports

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

For destructuring from default export:

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

Alternative access via processWarning export:

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

Basic Usage

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

// Create a standard warning
const warning = createWarning({
  name: 'ExampleWarning',
  code: 'EXP_WRN_001',
  message: 'Hello %s',
  unlimited: true
});
warning('world'); // Emits: ExampleWarning [EXP_WRN_001]: Hello world

// Create a deprecation warning
const deprecation = createDeprecation({
  code: 'DEP_001',
  message: 'This feature is deprecated'
});
deprecation(); // Emits: DeprecationWarning [DEP_001]: This feature is deprecated

Capabilities

Warning Creation

Creates a warning item with specified parameters that can be called to emit Node.js process warnings.

/**
 * Creates a warning item
 * @param {Object} params - Warning configuration
 * @param {string} params.name - The warning name  
 * @param {string} params.code - The warning code (converted to uppercase)
 * @param {string} params.message - The warning message template (supports interpolation)
 * @param {boolean} [params.unlimited=false] - Allow unlimited emissions
 * @returns {WarningItem} The created warning item
 * @throws {Error} If name, code, or message is empty, or if unlimited is not boolean
 */
function createWarning({ name, code, message, unlimited = false });

Deprecation Creation

Creates a deprecation warning item (wrapper around createWarning with name set to 'DeprecationWarning').

/**
 * Creates a deprecation warning item
 * @param {Object} params - Deprecation configuration
 * @param {string} params.code - The warning code (converted to uppercase)
 * @param {string} params.message - The warning message template (supports interpolation)
 * @param {boolean} [params.unlimited=false] - Allow unlimited emissions
 * @returns {WarningItem} The created deprecation warning item
 * @throws {Error} If code or message is empty, or if unlimited is not boolean
 */
function createDeprecation(params);

Process Warning Module Interface

The module also exports a processWarning object that provides access to both main functions.

/**
 * Process warning module interface
 */
const processWarning = {
  createWarning: function(params),
  createDeprecation: function(params)
};

Warning Item Interface

The warning item returned by both createWarning and createDeprecation is a callable function with additional properties and methods.

/**
 * Warning item - callable function with properties
 * @param {*} [a] - First interpolation parameter
 * @param {*} [b] - Second interpolation parameter  
 * @param {*} [c] - Third interpolation parameter
 */
function WarningItem(a, b, c);

// Properties
WarningItem.name;        // string - The warning name
WarningItem.code;        // string - The warning code (uppercase)
WarningItem.message;     // string - The warning message template
WarningItem.emitted;     // boolean - Whether warning has been emitted
WarningItem.unlimited;   // boolean - Whether unlimited emissions are allowed

/**
 * Formats the warning message with interpolation values
 * @param {*} [a] - First interpolation parameter
 * @param {*} [b] - Second interpolation parameter
 * @param {*} [c] - Third interpolation parameter
 * @returns {string} The formatted warning message
 */
WarningItem.format(a, b, c);

Types

/**
 * Warning item interface - callable function with properties
 */
interface WarningItem {
  (a?: any, b?: any, c?: any): void;  // Callable function
  name: string;           // The warning name
  code: string;           // The warning code (uppercase)
  message: string;        // The warning message template
  emitted: boolean;       // Whether warning has been emitted
  unlimited: boolean;     // Whether unlimited emissions are allowed
  format(a?: any, b?: any, c?: any): string;  // Format function
}

/**
 * Options for creating a process warning
 */
interface WarningOptions {
  name: string;           // The name of the warning
  code: string;           // The code associated with the warning  
  message: string;        // The warning message template
  unlimited?: boolean;    // If true, allows unlimited emissions (default: false)
}

/**
 * Options for creating a deprecation warning (omits name)
 */
type DeprecationOptions = Omit<WarningOptions, 'name'>;

/**
 * Process warning options
 */
interface ProcessWarningOptions {
  unlimited?: boolean;    // If true, allows unlimited emissions
}

/**
 * Process warning module interface
 */
interface ProcessWarning {
  createWarning(params: WarningOptions): WarningItem;
  createDeprecation(params: DeprecationOptions): WarningItem;
}

Usage Examples

Basic Warning with Interpolation

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

const FST_ERROR_CODE = createWarning({
  name: 'MyAppWarning', 
  code: 'FST_ERROR_CODE', 
  message: 'Hello %s'
});

FST_ERROR_CODE('world'); // Emits: MyAppWarning [FST_ERROR_CODE]: Hello world

State Management for Testing

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

const warning = createWarning({
  name: 'TestWarning',
  code: 'TEST_001',
  message: 'Test message'
});

console.log(warning.emitted); // false
warning(); // Emits warning
console.log(warning.emitted); // true

// Manually control emission state
warning.emitted = false;
warning(); // Will emit again

Unlimited Warnings

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

const unlimitedWarning = createWarning({
  name: 'UnlimitedWarning',
  code: 'UNL_001', 
  message: 'This can be emitted multiple times',
  unlimited: true
});

unlimitedWarning(); // Emits warning
unlimitedWarning(); // Emits warning again

Deprecation Warnings

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

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

deprecation('oldMethod', 'newMethod'); 
// Emits: DeprecationWarning [DEP_FEATURE_001]: The oldMethod method is deprecated, use newMethod instead

Message Formatting

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

const multiParamWarning = createWarning({
  name: 'FormattingWarning',
  code: 'FMT_001',
  message: 'Processing %s with options %j at %d'
});

// Format without emitting
const formatted = multiParamWarning.format('data', { debug: true }, Date.now());
console.log(formatted);

// Emit with parameters
multiParamWarning('data', { debug: true }, Date.now());

Error Handling

The functions throw errors for invalid parameters:

  • Empty name: "Warning name must not be empty"
  • Empty code: "Warning code must not be empty"
  • Empty message: "Warning message must not be empty"
  • Invalid unlimited: "Warning opts.unlimited must be a boolean"

Node.js Integration

Warning Suppression

Warnings can be suppressed using Node.js built-in mechanisms:

  • Set NODE_NO_WARNINGS=1 environment variable
  • Pass --no-warnings flag to node process
  • Set --no-warnings in NODE_OPTIONS environment variable

Deprecation Handling

Deprecation warnings support Node.js CLI options:

  • --throw-deprecation: Throw errors instead of emitting warnings
  • --no-deprecation: Suppress deprecation warnings
  • --trace-deprecation: Show stack traces for deprecation warnings

Process Warning Events

All warnings are emitted through process.emitWarning() and can be captured:

process.on('warning', (warning) => {
  console.log(warning.name);    // Warning name
  console.log(warning.code);    // Warning code  
  console.log(warning.message); // Formatted message
});