0
# Process Warning
1

2
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.
3

4
## Package Information 
5

6
- **Package Name**: process-warning
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install process-warning`
10

11
## Core Imports
12

13
```javascript
14
const { createWarning, createDeprecation } = require('process-warning');
15
```
16

17
For destructuring from default export:
18
```javascript
19
const processWarning = require('process-warning');
20
const { createWarning, createDeprecation } = processWarning;
21
```
22

23
Alternative access via processWarning export:
24
```javascript
25
const { processWarning } = require('process-warning');
26
const { createWarning, createDeprecation } = processWarning;
27
```
28

29
## Basic Usage
30

31
```javascript
32
const { createWarning, createDeprecation } = require('process-warning');
33

34
// Create a standard warning
35
const warning = createWarning({
36
  name: 'ExampleWarning',
37
  code: 'EXP_WRN_001',
38
  message: 'Hello %s',
39
  unlimited: true
40
});
41
warning('world'); // Emits: ExampleWarning [EXP_WRN_001]: Hello world
42

43
// Create a deprecation warning
44
const deprecation = createDeprecation({
45
  code: 'DEP_001',
46
  message: 'This feature is deprecated'
47
});
48
deprecation(); // Emits: DeprecationWarning [DEP_001]: This feature is deprecated
49
```
50

51
## Capabilities
52

53
### Warning Creation
54

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

57
```javascript { .api }
58
/**
59
 * Creates a warning item
60
 * @param {Object} params - Warning configuration
61
 * @param {string} params.name - The warning name  
62
 * @param {string} params.code - The warning code (converted to uppercase)
63
 * @param {string} params.message - The warning message template (supports interpolation)
64
 * @param {boolean} [params.unlimited=false] - Allow unlimited emissions
65
 * @returns {WarningItem} The created warning item
66
 * @throws {Error} If name, code, or message is empty, or if unlimited is not boolean
67
 */
68
function createWarning({ name, code, message, unlimited = false });
69
```
70

71
### Deprecation Creation
72

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

75
```javascript { .api }
76
/**
77
 * Creates a deprecation warning item
78
 * @param {Object} params - Deprecation configuration
79
 * @param {string} params.code - The warning code (converted to uppercase)
80
 * @param {string} params.message - The warning message template (supports interpolation)
81
 * @param {boolean} [params.unlimited=false] - Allow unlimited emissions
82
 * @returns {WarningItem} The created deprecation warning item
83
 * @throws {Error} If code or message is empty, or if unlimited is not boolean
84
 */
85
function createDeprecation(params);
86
```
87

88
### Process Warning Module Interface
89

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

92
```javascript { .api }
93
/**
94
 * Process warning module interface
95
 */
96
const processWarning = {
97
  createWarning: function(params),
98
  createDeprecation: function(params)
99
};
100
```
101

102
### Warning Item Interface
103

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

106
```javascript { .api }
107
/**
108
 * Warning item - callable function with properties
109
 * @param {*} [a] - First interpolation parameter
110
 * @param {*} [b] - Second interpolation parameter  
111
 * @param {*} [c] - Third interpolation parameter
112
 */
113
function WarningItem(a, b, c);
114

115
// Properties
116
WarningItem.name;        // string - The warning name
117
WarningItem.code;        // string - The warning code (uppercase)
118
WarningItem.message;     // string - The warning message template
119
WarningItem.emitted;     // boolean - Whether warning has been emitted
120
WarningItem.unlimited;   // boolean - Whether unlimited emissions are allowed
121

122
/**
123
 * Formats the warning message with interpolation values
124
 * @param {*} [a] - First interpolation parameter
125
 * @param {*} [b] - Second interpolation parameter
126
 * @param {*} [c] - Third interpolation parameter
127
 * @returns {string} The formatted warning message
128
 */
129
WarningItem.format(a, b, c);
130
```
131

132
## Types
133

134
```javascript { .api }
135
/**
136
 * Warning item interface - callable function with properties
137
 */
138
interface WarningItem {
139
  (a?: any, b?: any, c?: any): void;  // Callable function
140
  name: string;           // The warning name
141
  code: string;           // The warning code (uppercase)
142
  message: string;        // The warning message template
143
  emitted: boolean;       // Whether warning has been emitted
144
  unlimited: boolean;     // Whether unlimited emissions are allowed
145
  format(a?: any, b?: any, c?: any): string;  // Format function
146
}
147

148
/**
149
 * Options for creating a process warning
150
 */
151
interface WarningOptions {
152
  name: string;           // The name of the warning
153
  code: string;           // The code associated with the warning  
154
  message: string;        // The warning message template
155
  unlimited?: boolean;    // If true, allows unlimited emissions (default: false)
156
}
157

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

163
/**
164
 * Process warning options
165
 */
166
interface ProcessWarningOptions {
167
  unlimited?: boolean;    // If true, allows unlimited emissions
168
}
169

170
/**
171
 * Process warning module interface
172
 */
173
interface ProcessWarning {
174
  createWarning(params: WarningOptions): WarningItem;
175
  createDeprecation(params: DeprecationOptions): WarningItem;
176
}
177
```
178

179
## Usage Examples
180

181
### Basic Warning with Interpolation
182

183
```javascript
184
const { createWarning } = require('process-warning');
185

186
const FST_ERROR_CODE = createWarning({
187
  name: 'MyAppWarning', 
188
  code: 'FST_ERROR_CODE', 
189
  message: 'Hello %s'
190
});
191

192
FST_ERROR_CODE('world'); // Emits: MyAppWarning [FST_ERROR_CODE]: Hello world
193
```
194

195
### State Management for Testing
196

197
```javascript
198
const { createWarning } = require('process-warning');
199

200
const warning = createWarning({
201
  name: 'TestWarning',
202
  code: 'TEST_001',
203
  message: 'Test message'
204
});
205

206
console.log(warning.emitted); // false
207
warning(); // Emits warning
208
console.log(warning.emitted); // true
209

210
// Manually control emission state
211
warning.emitted = false;
212
warning(); // Will emit again
213
```
214

215
### Unlimited Warnings
216

217
```javascript
218
const { createWarning } = require('process-warning');
219

220
const unlimitedWarning = createWarning({
221
  name: 'UnlimitedWarning',
222
  code: 'UNL_001', 
223
  message: 'This can be emitted multiple times',
224
  unlimited: true
225
});
226

227
unlimitedWarning(); // Emits warning
228
unlimitedWarning(); // Emits warning again
229
```
230

231
### Deprecation Warnings
232

233
```javascript
234
const { createDeprecation } = require('process-warning');
235

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

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

245
### Message Formatting
246

247
```javascript
248
const { createWarning } = require('process-warning');
249

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

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

260
// Emit with parameters
261
multiParamWarning('data', { debug: true }, Date.now());
262
```
263

264
## Error Handling
265

266
The functions throw errors for invalid parameters:
267

268
- **Empty name**: "Warning name must not be empty"
269
- **Empty code**: "Warning code must not be empty"
270
- **Empty message**: "Warning message must not be empty" 
271
- **Invalid unlimited**: "Warning opts.unlimited must be a boolean"
272

273
## Node.js Integration
274

275
### Warning Suppression
276

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

279
- Set `NODE_NO_WARNINGS=1` environment variable
280
- Pass `--no-warnings` flag to node process
281
- Set `--no-warnings` in `NODE_OPTIONS` environment variable
282

283
### Deprecation Handling
284

285
Deprecation warnings support Node.js CLI options:
286

287
- `--throw-deprecation`: Throw errors instead of emitting warnings  
288
- `--no-deprecation`: Suppress deprecation warnings
289
- `--trace-deprecation`: Show stack traces for deprecation warnings
290

291
### Process Warning Events
292

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

295
```javascript
296
process.on('warning', (warning) => {
297
  console.log(warning.name);    // Warning name
298
  console.log(warning.code);    // Warning code  
299
  console.log(warning.message); // Formatted message
300
});
301
```