util: emit deprecation code only once

If another function has already emitted the deprecation warning with the
same code as the warning that is about to be emitted, do not emit the
warning.

This is a breaking change. Previously, different functions could emit
the same deprecation warning multiple times. This was a known bug rather
than a feature, but this change is being treated as a breaking change
out of caution. Identical deprecation warnings should not be emitted.

PR-URL: https://github.com/nodejs/node/pull/16393
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

1 files changed, 21 insertions, 8 deletions

diff --git a/doc/api/util.md b/doc/api/util.md
index e100971af9..d790319862 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -110,6 +110,9 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`.
 ## util.deprecate(fn, msg[, code])
 <!-- YAML
 added: v0.8.0
+changes:
+  - version: REPLACEME
+    description: Deprecation warnings are only emitted once for each code.
 -->
 
 * `fn` {Function} The function that is being deprecated.
@@ -122,21 +125,31 @@ added: v0.8.0
 The `util.deprecate()` method wraps `fn` (which may be a function or class) in
 such a way that it is marked as deprecated.
 
-<!-- eslint-disable prefer-rest-params -->
 ```js
 const util = require('util');
 
-exports.puts = util.deprecate(function() {
-  for (let i = 0, len = arguments.length; i < len; ++i) {
-    process.stdout.write(arguments[i] + '\n');
-  }
-}, 'util.puts: Use console.log instead');
+exports.obsoleteFunction = util.deprecate(function() {
+  // Do something here.
+}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
 ```
 
 When called, `util.deprecate()` will return a function that will emit a
 `DeprecationWarning` using the `process.on('warning')` event. The warning will
-be emitted and printed to `stderr` exactly once, the first time it is called.
-After the warning is emitted, the wrapped function is called.
+be emitted and printed to `stderr` the first time the returned function is
+called. After the warning is emitted, the wrapped function is called without
+emitting a warning.
+
+If the same optional `code` is supplied in multiple calls to `util.deprecate()`,
+the warning will be emitted only once for that `code`.
+
+```js
+const util = require('util');
+
+const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
+const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
+fn1(); // emits a deprecation warning with code DEP0001
+fn2(); // does not emit a deprecation warning because it has the same code
+```
 
 If either the `--no-deprecation` or `--no-warnings` command line flags are
 used, or if the `process.noDeprecation` property is set to `true` *prior* to