From 9d1cc329b7fabfb77b3dc5a3f998962009da0093 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 31 Dec 2020 14:53:05 -0800 Subject: [PATCH] doc: document common warning types Fixes: https://github.com/nodejs/node/issues/24987 Signed-off-by: James M Snell --- doc/api/process.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/api/process.md b/doc/api/process.md index 8f7a98503a6d48..0cac80e03faed0 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -462,6 +462,29 @@ The `*-deprecation` command-line flags only affect warnings that use the name See the [`process.emitWarning()`][process_emit_warning] method for issuing custom or application-specific warnings. +#### Node.js warning names + +There are no strict guidelines for warning types (as identified by the `name` +property) emitted by Node.js. New types of warnings can be added at any time. +A few of the warning types that are most common include: + +* `'DeprecationWarning'` - Indicates use of a deprecated Node.js API or feature. + Such warnings must include a `'code'` property identifying the + [deprecation code][]. +* `'ExperimentalWarning'` - Indicates use of an experimental Node.js API or + feature. Such features must be used with caution as they may change at any + time and are not subject to the same strict semantic-versioning and long-term + support policies as supported features. +* `'MaxListenersExceededWarning'` - Indicates that too many listeners for a + given event have been registered on either an `EventEmitter` or `EventTarget`. + This is often an indication of a memory leak. +* `'TimeoutOverflowWarning'` - Indicates that a numeric value that cannot fit + within a 32-bit signed integer has been provided to either the `setTimeout()` + or `setInterval()` functions. +* `'UnsupportedWarning'` - Indicates use of an unsupported option or feature + that will be ignored rather than treated as an error. One example is use of + the HTTP response status message when using the HTTP/2 compatibility API. + ### Signal events @@ -2676,6 +2699,7 @@ cases: [`subprocess.kill()`]: child_process.md#child_process_subprocess_kill_signal [`v8.setFlagsFromString()`]: v8.md#v8_v8_setflagsfromstring_flags [debugger]: debugger.md +[deprecation code]: deprecations.md [note on process I/O]: process.md#process_a_note_on_process_i_o [process.cpuUsage]: #process_process_cpuusage_previousvalue [process_emit_warning]: #process_process_emitwarning_warning_type_code_ctor