From 5de3cf099cd01c84d1809dab90c041b76aa58d8e Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 4 Dec 2016 12:47:01 -0800 Subject: lib: add static identifier codes for all deprecations Assigns a static identifier code to all runtime and documentation only deprecations. The identifier code is included in the emitted DeprecationWarning. Also adds a deprecations.md to the API docs to provide a central location where deprecation codes can be referenced and explained. PR-URL: https://github.com/nodejs/node/pull/10116 Reviewed-By: Michael Dawson Reviewed-By: Michal Zasso Reviewed-By: Fedor Indutny --- lib/_http_outgoing.js | 2 +- lib/_linklist.js | 2 +- lib/_stream_writable.js | 2 +- lib/_tls_legacy.js | 1 + lib/buffer.js | 16 ++++++++-------- lib/child_process.js | 3 +-- lib/constants.js | 7 ++++--- lib/crypto.js | 6 +++--- lib/domain.js | 2 +- lib/fs.js | 4 ++-- lib/internal/bootstrap_node.js | 4 ++-- lib/internal/cluster/worker.js | 4 ++-- lib/internal/process.js | 3 ++- lib/internal/process/promises.js | 2 +- lib/internal/util.js | 15 +++++++++++---- lib/module.js | 2 +- lib/net.js | 8 +++++--- lib/os.js | 6 ++++-- lib/repl.js | 2 +- lib/sys.js | 2 +- lib/util.js | 8 ++++---- 21 files changed, 57 insertions(+), 44 deletions(-) (limited to 'lib') diff --git a/lib/_http_outgoing.js b/lib/_http_outgoing.js index 30011e0915..f9df781751 100644 --- a/lib/_http_outgoing.js +++ b/lib/_http_outgoing.js @@ -738,4 +738,4 @@ OutgoingMessage.prototype.flushHeaders = function flushHeaders() { OutgoingMessage.prototype.flush = internalUtil.deprecate(function() { this.flushHeaders(); -}, 'OutgoingMessage.flush is deprecated. Use flushHeaders instead.'); +}, 'OutgoingMessage.flush is deprecated. Use flushHeaders instead.', 'DEP0001'); diff --git a/lib/_linklist.js b/lib/_linklist.js index 1b709d6fbd..1d2e9fa4d4 100644 --- a/lib/_linklist.js +++ b/lib/_linklist.js @@ -3,4 +3,4 @@ module.exports = require('internal/linkedlist'); process.emitWarning( '_linklist module is deprecated. Please use a userland alternative.', - 'DeprecationWarning'); + 'DeprecationWarning', 'DEP0002'); diff --git a/lib/_stream_writable.js b/lib/_stream_writable.js index af97fc2d81..eedeb56e12 100644 --- a/lib/_stream_writable.js +++ b/lib/_stream_writable.js @@ -125,7 +125,7 @@ Object.defineProperty(WritableState.prototype, 'buffer', { get: internalUtil.deprecate(function() { return this.getBuffer(); }, '_writableState.buffer is deprecated. Use _writableState.getBuffer ' + - 'instead.') + 'instead.', 'DEP0003') }); // Test _writableState for inheritance to account for Duplex streams, diff --git a/lib/_tls_legacy.js b/lib/_tls_legacy.js index e765b2507e..83ee3e0f8f 100644 --- a/lib/_tls_legacy.js +++ b/lib/_tls_legacy.js @@ -479,6 +479,7 @@ CryptoStream.prototype._done = function() { // readyState is deprecated. Don't use it. +// Deprecation Code: DEP0004 Object.defineProperty(CryptoStream.prototype, 'readyState', { get: function() { if (this.connecting) { diff --git a/lib/buffer.js b/lib/buffer.js index 456580a5c0..0a8724bda4 100644 --- a/lib/buffer.js +++ b/lib/buffer.js @@ -65,14 +65,14 @@ function alignPool() { } /** - * The Buffer() construtor is "soft deprecated" ... that is, it is deprecated - * in the documentation and should not be used moving forward. Rather, - * developers should use one of the three new factory APIs: Buffer.from(), - * Buffer.allocUnsafe() or Buffer.alloc() based on their specific needs. There - * is no hard deprecation because of the extent to which the Buffer constructor - * is used in the ecosystem currently -- a hard deprecation would introduce too - * much breakage at this time. It's not likely that the Buffer constructors - * would ever actually be removed. + * The Buffer() construtor is deprecated in documentation and should not be + * used moving forward. Rather, developers should use one of the three new + * factory APIs: Buffer.from(), Buffer.allocUnsafe() or Buffer.alloc() based on + * their specific needs. There is no runtime deprecation because of the extent + * to which the Buffer constructor is used in the ecosystem currently -- a + * runtime deprecation would introduce too much breakage at this time. It's not + * likely that the Buffer constructors would ever actually be removed. + * Deprecation Code: DEP0005 **/ function Buffer(arg, encodingOrOffset, length) { // Common case. diff --git a/lib/child_process.js b/lib/child_process.js index b00e3829b4..409dfff170 100644 --- a/lib/child_process.js +++ b/lib/child_process.js @@ -324,8 +324,7 @@ const _deprecatedCustomFds = internalUtil.deprecate( return fd === -1 ? 'pipe' : fd; }); }, 'child_process: options.customFds option is deprecated. ' + - 'Use options.stdio instead.' -); + 'Use options.stdio instead.', 'DEP0006'); function _convertCustomFds(options) { if (options.customFds && !options.stdio) { diff --git a/lib/constants.js b/lib/constants.js index fec7e13d94..c1cbf2db3c 100644 --- a/lib/constants.js +++ b/lib/constants.js @@ -1,8 +1,9 @@ 'use strict'; -// This module is soft-deprecated. Users should be directed towards using -// the specific constants exposed by the individual modules on which they -// are most relevant. +// This module is deprecated in documentation only. Users should be directed +// towards using the specific constants exposed by the individual modules on +// which they are most relevant. +// Deprecation Code: DEP0008 const constants = process.binding('constants'); Object.assign(exports, constants.os.errno, diff --git a/lib/crypto.js b/lib/crypto.js index 9180ce70dc..2d4695dc97 100644 --- a/lib/crypto.js +++ b/lib/crypto.js @@ -539,7 +539,7 @@ ECDH.prototype.getPublicKey = function getPublicKey(encoding, format) { const pbkdf2DeprecationWarning = internalUtil.deprecate(() => {}, 'crypto.pbkdf2 without specifying' + - ' a digest is deprecated. Please specify a digest'); + ' a digest is deprecated. Please specify a digest', 'DEP0009'); exports.pbkdf2 = function(password, @@ -663,7 +663,7 @@ Object.defineProperty(exports, 'createCredentials', { get: internalUtil.deprecate(function() { return require('tls').createSecureContext; }, 'crypto.createCredentials is deprecated. ' + - 'Use tls.createSecureContext instead.') + 'Use tls.createSecureContext instead.', 'DEP0010') }); Object.defineProperty(exports, 'Credentials', { @@ -672,5 +672,5 @@ Object.defineProperty(exports, 'Credentials', { get: internalUtil.deprecate(function() { return require('tls').SecureContext; }, 'crypto.Credentials is deprecated. ' + - 'Use tls.SecureContext instead.') + 'Use tls.SecureContext instead.', 'DEP0011') }); diff --git a/lib/domain.js b/lib/domain.js index c86af75c86..f45a623e8a 100644 --- a/lib/domain.js +++ b/lib/domain.js @@ -315,4 +315,4 @@ Domain.prototype.dispose = util.deprecate(function() { // so that it can't be entered or activated. this._disposed = true; }, 'Domain.dispose is deprecated. Recover from failed I/O actions explicitly ' + - 'via error event handlers set on the domain instead.'); + 'via error event handlers set on the domain instead.', 'DEP0012'); diff --git a/lib/fs.js b/lib/fs.js index 573ffec059..27e1a2e79c 100644 --- a/lib/fs.js +++ b/lib/fs.js @@ -68,8 +68,7 @@ function rethrow() { // TODO(thefourtheye) Throw error instead of warning in major version > 7 process.emitWarning( 'Calling an asynchronous function without callback is deprecated.', - 'DeprecationWarning', - rethrow + 'DeprecationWarning', 'DEP0013', rethrow ); // Only enable in debug mode. A backtrace uses ~1000 bytes of heap space and @@ -1943,6 +1942,7 @@ WriteStream.prototype.destroySoon = WriteStream.prototype.end; // todo(jasnell): "Docs-only" deprecation for now. This was never documented // so there's no documentation to modify. In the future, add a runtime // deprecation. +// Deprecation ID: DEP0061 Object.defineProperty(fs, 'SyncWriteStream', { configurable: true, writable: true, diff --git a/lib/internal/bootstrap_node.js b/lib/internal/bootstrap_node.js index 71a6c52904..efdbc5d9e3 100644 --- a/lib/internal/bootstrap_node.js +++ b/lib/internal/bootstrap_node.js @@ -204,7 +204,7 @@ // getter const get = util.deprecate(function() { return this; - }, `'${name}' is deprecated, use 'global'`); + }, `'${name}' is deprecated, use 'global'`, 'DEP0016'); // setter const set = util.deprecate(function(value) { Object.defineProperty(this, name, { @@ -213,7 +213,7 @@ enumerable: true, value: value }); - }, `'${name}' is deprecated, use 'global'`); + }, `'${name}' is deprecated, use 'global'`, 'DEP0016'); // define property Object.defineProperty(global, name, { get, set, configurable: true }); }); diff --git a/lib/internal/cluster/worker.js b/lib/internal/cluster/worker.js index fd46ed5710..687e4c12fe 100644 --- a/lib/internal/cluster/worker.js +++ b/lib/internal/cluster/worker.js @@ -23,10 +23,10 @@ function Worker(options) { defineProperty(this, 'suicide', { get: internalUtil.deprecate( () => this.exitedAfterDisconnect, - suicideDeprecationMessage), + suicideDeprecationMessage, 'DEP0007'), set: internalUtil.deprecate( (val) => { this.exitedAfterDisconnect = val; }, - suicideDeprecationMessage), + suicideDeprecationMessage, 'DEP0007'), enumerable: true }); diff --git a/lib/internal/process.js b/lib/internal/process.js index 44f1370459..3f050b42ca 100644 --- a/lib/internal/process.js +++ b/lib/internal/process.js @@ -130,7 +130,8 @@ function setupConfig(_source) { 'See https://github.com/nodejs/node/wiki/Intl'); } return Reflect.construct(oldV8BreakIterator, arguments); - }, 'Intl.v8BreakIterator is deprecated and will be removed soon.'); + }, 'Intl.v8BreakIterator is deprecated and will be removed soon.', + 'DEP0017'); Object.defineProperty(Intl, 'v8BreakIterator', des); } // Don’t let icu_data_dir leak through. diff --git a/lib/internal/process/promises.js b/lib/internal/process/promises.js index 83dee491a5..0e382d11d5 100644 --- a/lib/internal/process/promises.js +++ b/lib/internal/process/promises.js @@ -70,7 +70,7 @@ function setupPromises(scheduleMicrotasks) { 'Unhandled promise rejections are deprecated. In the future, ' + 'promise rejections that are not handled will terminate the ' + 'Node.js process with a non-zero exit code.', - 'DeprecationWarning'); + 'DeprecationWarning', 'DEP0018'); } } var deprecationWarned = false; diff --git a/lib/internal/util.js b/lib/internal/util.js index 42a0922d30..10844b6454 100644 --- a/lib/internal/util.js +++ b/lib/internal/util.js @@ -15,8 +15,8 @@ exports.customInspectSymbol = Symbol('util.inspect.custom'); // All the internal deprecations have to use this function only, as this will // prepend the prefix to the actual message. -exports.deprecate = function(fn, msg) { - return exports._deprecate(fn, msg); +exports.deprecate = function(fn, msg, code) { + return exports._deprecate(fn, msg, code); }; exports.error = function(msg) { @@ -39,7 +39,7 @@ exports.trace = function(msg) { // Mark that a method should not be used. // Returns a modified function which warns once by default. // If --no-deprecation is set, then it is a no-op. -exports._deprecate = function(fn, msg) { +exports._deprecate = function(fn, msg, code) { // Allow for deprecating things in the process of starting up. if (global.process === undefined) { return function() { @@ -51,11 +51,18 @@ exports._deprecate = function(fn, msg) { return fn; } + if (code !== undefined && typeof code !== 'string') + throw new TypeError('`code` argument must be a string'); + var warned = false; function deprecated() { if (!warned) { warned = true; - process.emitWarning(msg, 'DeprecationWarning', deprecated); + if (code !== undefined) { + process.emitWarning(msg, 'DeprecationWarning', code, deprecated); + } else { + process.emitWarning(msg, 'DeprecationWarning', deprecated); + } } if (new.target) { return Reflect.construct(fn, arguments, new.target); diff --git a/lib/module.js b/lib/module.js index 09c4b85b9e..9a6b641a75 100644 --- a/lib/module.js +++ b/lib/module.js @@ -213,7 +213,7 @@ Module._findPath = function(request, paths, isMain) { 'warning: require(\'.\') resolved outside the package ' + 'directory. This functionality is deprecated and will be removed ' + 'soon.', - 'DeprecationWarning'); + 'DeprecationWarning', 'DEP0019'); } } diff --git a/lib/net.js b/lib/net.js index e4f97ab80d..1213098953 100644 --- a/lib/net.js +++ b/lib/net.js @@ -1131,9 +1131,10 @@ function Server(options, connectionListener) { } return this._connections; }, 'Server.connections property is deprecated. ' + - 'Use Server.getConnections method instead.'), + 'Use Server.getConnections method instead.', 'DEP0020'), set: internalUtil.deprecate((val) => (this._connections = val), - 'Server.connections property is deprecated.'), + 'Server.connections property is deprecated.', + 'DEP0020'), configurable: true, enumerable: false }); @@ -1546,7 +1547,8 @@ function emitCloseNT(self) { Server.prototype.listenFD = internalUtil.deprecate(function(fd, type) { return this.listen({ fd: fd }); -}, 'Server.listenFD is deprecated. Use Server.listen({fd: }) instead.'); +}, 'Server.listenFD is deprecated. Use Server.listen({fd: }) instead.', + 'DEP0021'); Server.prototype._setupSlave = function(socketList) { this._usingSlaves = true; diff --git a/lib/os.js b/lib/os.js index a59cc49bae..7ab0ec5fa4 100644 --- a/lib/os.js +++ b/lib/os.js @@ -53,12 +53,14 @@ exports.tmpdir = function() { const tmpDirDeprecationMsg = 'os.tmpDir() is deprecated. Use os.tmpdir() instead.'; -exports.tmpDir = internalUtil.deprecate(exports.tmpdir, tmpDirDeprecationMsg); +exports.tmpDir = internalUtil.deprecate(exports.tmpdir, + tmpDirDeprecationMsg, + 'DEP0022'); exports.getNetworkInterfaces = internalUtil.deprecate(function() { return exports.networkInterfaces(); }, 'os.getNetworkInterfaces is deprecated. ' + - 'Use os.networkInterfaces instead.'); + 'Use os.networkInterfaces instead.', 'DEP0023'); exports.EOL = isWindows ? '\r\n' : '\n'; diff --git a/lib/repl.js b/lib/repl.js index 29f25a5c37..fed89146dc 100644 --- a/lib/repl.js +++ b/lib/repl.js @@ -1356,7 +1356,7 @@ REPLServer.prototype.convertToContext = util.deprecate(function(cmd) { } return cmd; -}, 'replServer.convertToContext() is deprecated'); +}, 'replServer.convertToContext() is deprecated', 'DEP0024'); function bailOnIllegalToken(parser) { return parser._literal === null && diff --git a/lib/sys.js b/lib/sys.js index c94b032c64..4d7d305daa 100644 --- a/lib/sys.js +++ b/lib/sys.js @@ -6,4 +6,4 @@ module.exports = require('util'); process.emitWarning('sys is deprecated. Use util instead.', - 'DeprecationWarning'); + 'DeprecationWarning', 'DEP0025'); diff --git a/lib/util.js b/lib/util.js index 9d5909cdc7..46cde4d85b 100644 --- a/lib/util.js +++ b/lib/util.js @@ -993,26 +993,26 @@ exports.print = internalUtil.deprecate(function() { for (var i = 0, len = arguments.length; i < len; ++i) { process.stdout.write(String(arguments[i])); } -}, 'util.print is deprecated. Use console.log instead.'); +}, 'util.print is deprecated. Use console.log instead.', 'DEP0026'); exports.puts = internalUtil.deprecate(function() { for (var i = 0, len = arguments.length; i < len; ++i) { process.stdout.write(arguments[i] + '\n'); } -}, 'util.puts is deprecated. Use console.log instead.'); +}, 'util.puts is deprecated. Use console.log instead.', 'DEP0027'); exports.debug = internalUtil.deprecate(function(x) { process.stderr.write(`DEBUG: ${x}\n`); -}, 'util.debug is deprecated. Use console.error instead.'); +}, 'util.debug is deprecated. Use console.error instead.', 'DEP0028'); exports.error = internalUtil.deprecate(function(x) { for (var i = 0, len = arguments.length; i < len; ++i) { process.stderr.write(arguments[i] + '\n'); } -}, 'util.error is deprecated. Use console.error instead.'); +}, 'util.error is deprecated. Use console.error instead.', 'DEP0029'); exports._errnoException = function(err, syscall, original) { -- cgit v1.2.3