process-warning - npm Package Compare versions

Comparing version 2.2.0 to 2.3.0

index.js

 'use strict'
 
-const { format } = require('util')
+const { format } = require('node:util')
 
+/**
+ * An object that provides methods for creating process warning, emitting them,
+ * and inspecting/managing the emission state of warning.
+ *
+ * @typedef {object} ProcessWarningManager
+ */
+
+/**
+ * @typedef {object} CreateOptions
+ * @property {boolean} [unlimited=false] Indicates if the warning should be
+ * emitted every time (`true`) or only the first time (`false`).
+ */
+
+/**
+ * An error instance representing a process warning. This is what will be
+ * emitted to listeners when the warning is emitted.
+ *
+ * @typedef {Error} ProcessWarning
+ * @property {string} code
+ * @property {string} name
+ * @property {string} message
+ */
+
+/**
+ * A function used to create new {@link ProcessWarning} instances.
+ *
+ * @callback ProcessWarningBuilder
+ * @param {*} [param1] First possible string interpolation value.
+ * @param {*} [param2] Second possible string interpolation value.
+ * @param {*} [param3] Third possible string interpolation value.
+ * @returns ProcessWarning
+ */
+
+/**
+ * Factory that builds a new {@link ProcessWarningManager} and returns it.
+ *
+ * @returns ProcessWarningManager
+ */
 function processWarning () {
@@ -10,2 +48,16 @@ const codes = {}
 
+  /**
+   * Builds a new {@link ProcessWarning} and adds it to the
+   * {@link ProcessWarningManager} such that it can be emitted through the
+   * {@link ProcessWarningManager#emit} method.
+   *
+   * @memberof! ProcessWarningManager
+   * @instance
+   *
+   * @param {string} name Warning name, e.g. `'MyCustomWarning'`.
+   * @param {string} code A unique code for the warning, e.g. `'WARN_001'`.
+   * @param {string} message The body of the warning.
+   * @param {CreateOptions} [options]
+   * @returns {ProcessWarningBuilder}
+   */
   function create (name, code, message, { unlimited = false } = {}) {
@@ -50,2 +102,40 @@ if (!name) throw new Error('Warning name must not be empty')
 
+  /**
+   * A wrapper for {@link ProcessWarningManager#create} that builds a new
+   * deprecation warning. This method is equivalent to passing
+   * `name = 'DeprecationWarning'` to the create method.
+   *
+   * Deprecation warnings have extended support for the Node.js CLI options:
+   * `--throw-deprecation`, `--no-deprecation`, and `--trace-deprecation`.
+   *
+   * @memberof! ProcessWarningManager
+   * @instance
+   *
+   * @param {string} code
+   * @param {string} message
+   * @param {CreateOptions} opts
+   * @returns {ProcessWarningBuilder}
+   */
+  function createDeprecation (code, message, opts = {}) {
+    return create('DeprecationWarning', code, message, opts)
+  }
+
+  /**
+   * Emits a registered warning associated with the given `code`. If the
+   * warning message has interpolation strings present, up to the first three
+   * of them can be supplied values with the optional interpolation value
+   * parameters.
+   *
+   * If a warning is set to `unlimited: false`, and has already been emitted
+   * once, invoking this method is a no-operation.
+   *
+   * @memberof! ProcessWarningManager
+   * @instance
+   *
+   * @param {string} code The code for the error to emit, e.g. `'WARN_001'`.
+   * This is the same code that was provided to {@link ProcessWarningManager#create}.
+   * @param {*} [a] Possible message interpolation value.
+   * @param {*} [b] Possible message interpolation value.
+   * @param {*} [c] Possible message interpolation value.
+   */
   function emit (code, a, b, c) {
@@ -62,2 +152,3 @@ if (emitted.get(code) === true && opts.unlimited === false) return
     create,
+    createDeprecation,
     emit,
@@ -64,0 +155,0 @@ emitted

package.json

 {
   "name": "process-warning",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A small utility for creating warnings and emitting them.",
   "main": "index.js",
+  "type": "commonjs",
   "types": "types/index.d.ts",
@@ -39,4 +40,4 @@ "scripts": {
     "tap": "^16.3.0",
-    "tsd": "^0.28.0"
+    "tsd": "^0.29.0"
   }
 }

README.md

@@ -28,18 +28,32 @@ # process-warning
 
-```
-warning.create(name, code, message[, options])
-```
+##### `warning.create(name, code, message[, options])`
 
-- `name` (`string`, required) - The error name, you can access it later with `error.name`. For consistency, we recommend prefixing module error names with `{YourModule}Warning`
-- `code` (`string`, required) - The warning code, you can access it later with `error.code`. For consistency, we recommend prefixing plugin error codes with `{ThreeLetterModuleName}_`, e.g. `FST_`. NOTE: codes should be all uppercase.
-- `message` (`string`, required) - The warning message. You can also use interpolated strings for formatting the message.
-- `options` (`object`, optional) - Optional options with the following properties:
-  - `unlimited` (`boolean`, optional) - Should the warning be emitted more than once? Defaults to `false`.
+- `name` (`string`, required) - The error name, you can access it later with
+`error.name`. For consistency, we recommend prefixing module error names
+with `{YourModule}Warning`
+- `code` (`string`, required) - The warning code, you can access it later with
+`error.code`. For consistency, we recommend prefixing plugin error codes with
+`{ThreeLetterModuleName}_`, e.g. `FST_`. NOTE: codes should be all uppercase.
+- `message` (`string`, required) - The warning message. You can also use
+interpolated strings for formatting the message.
+- `options` (`object`, optional) - Optional options with the following
+properties:
+  + `unlimited` (`boolean`, optional) - Should the warning be emitted more than
+  once? Defaults to `false`.
 
-The utility also contains an `emit` function that you can use for emitting the warnings you have previously created by passing their respective code. A warning is guaranteed to be emitted only once.
 
-```
-warning.emit(code [, a [, b [, c]]])
-```
+##### `warning.createDeprecation(code, message[, options])`
 
+This is a wrapper for `warning.create`. It is equivalent to invoking
+`warning.create` with the `name` parameter set to "DeprecationWarning".
+
+Deprecation warnings have extended support for the Node.js CLI options:
+`--throw-deprecation`, `--no-deprecation`, and `--trace-deprecation`.
+
+##### `warning.emit(code [, a [, b [, c]]])`
+
+The utility also contains an `emit` function that you can use for emitting the
+warnings you have previously created by passing their respective code.
+A warning is guaranteed to be emitted at least once.
+
 - `code` (`string`, required) - The warning code you intend to emit.
@@ -78,4 +92,16 @@ - `[, a [, b [, c]]]` (`any`, optional) - Parameters for string interpolation.
 
+#### Suppressing warnings
+
+It is possible to suppress warnings by utilizing one of node's built-in warning suppression mechanisms.
+
+Warnings can be suppressed:
+
+- by setting the `NODE_NO_WARNINGS` environment variable to `1`
+- by passing the `--no-warnings` flag to the node process
+- by setting 'no-warnings' in the `NODE_OPTIONS` environment variable
+
+For more information see [node's documentation](https://nodejs.org/api/cli.html).
+
 ## License
 
 Licensed under [MIT](./LICENSE).

test/index.test.js

@@ -52,2 +52,13 @@ 'use strict'
 
+test('Creates a deprecation warning', t => {
+  t.plan(3)
+
+  const manager = build()
+  const builder = manager.createDeprecation('CODE', 'hello %s')
+  const warning = builder('world')
+  t.equal(warning.name, 'DeprecationWarning')
+  t.equal(warning.message, 'hello world')
+  t.equal(warning.code, 'CODE')
+})
+
 test('Should throw when error code has no fastify name', t => {
@@ -54,0 +65,0 @@ t.plan(1)

New alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20928

42.35%

Number of package files

18

20%

Lines of code

424

63.71%

Number of lines in readme file

106

32.5%

Worsened metrics

Number of medium supply chain risk alerts

1

Infinity%

No dependency changes