util: prepending (node) to the deprecation messages

thefourtheye · thefourtheye · commit 416a134e541a · 2015-06-18T18:53:22.000Z
Changes included in this commit are

   1. Making the deprecation messages consistent. The messages will be in
      the following format

           x is deprecated. Use y instead.

      If there is no alternative for `x`, then the ` Use y instead.` part
      will not be there in the message.

   2. All the internal deprecation messages are printed with the prefix
      `(node) `, except when the `--trace-deprecation` flag is set.
diff --git a/lib/_http_outgoing.js b/lib/_http_outgoing.js
@@ -4,6 +4,7 @@ const assert = require('assert').ok;
 const Stream = require('stream');
 const timers = require('timers');
 const util = require('util');
+const internalUtil = require('internal/util');
 const Buffer = require('buffer').Buffer;
 const common = require('_http_common');
 
@@ -644,6 +645,6 @@ OutgoingMessage.prototype.flushHeaders = function() {
   this._send('');
 };
 
-OutgoingMessage.prototype.flush = util.deprecate(function() {
+OutgoingMessage.prototype.flush = internalUtil.deprecate(function() {
   this.flushHeaders();
-}, 'flush is deprecated. Use flushHeaders instead.');
+}, 'OutgoingMessage.flush is deprecated. Use flushHeaders instead.');
diff --git a/lib/_stream_writable.js b/lib/_stream_writable.js
@@ -8,6 +8,7 @@ module.exports = Writable;
 Writable.WritableState = WritableState;
 
 const util = require('util');
+const internalUtil = require('internal/util');
 const Stream = require('stream');
 const Buffer = require('buffer').Buffer;
 
@@ -120,10 +121,10 @@ WritableState.prototype.getBuffer = function writableStateGetBuffer() {
 };
 
 Object.defineProperty(WritableState.prototype, 'buffer', {
-  get: util.deprecate(function() {
+  get: internalUtil.deprecate(function() {
     return this.getBuffer();
-  }, '_writableState.buffer is deprecated. Use ' +
-      '_writableState.getBuffer() instead.')
+  }, '_writableState.buffer is deprecated. Use _writableState.getBuffer ' +
+     'instead.')
 });
 
 function Writable(options) {
diff --git a/lib/buffer.js b/lib/buffer.js
@@ -461,7 +461,7 @@ Buffer.prototype.get = internalUtil.deprecate(function get(offset) {
   if (offset < 0 || offset >= this.length)
     throw new RangeError('index out of range');
   return this[offset];
-}, '.get() is deprecated. Access using array indexes instead.');
+}, 'Buffer.get is deprecated. Use array indexes instead.');
 
 
 // XXX remove in v0.13
@@ -470,14 +470,15 @@ Buffer.prototype.set = internalUtil.deprecate(function set(offset, v) {
   if (offset < 0 || offset >= this.length)
     throw new RangeError('index out of range');
   return this[offset] = v;
-}, '.set() is deprecated. Set using array indexes instead.');
+}, 'Buffer.set is deprecated. Use array indexes instead.');
 
 
 // TODO(trevnorris): fix these checks to follow new standard
 // write(string, offset = 0, length = buffer.length, encoding = 'utf8')
 var writeWarned = false;
-const writeMsg = '.write(string, encoding, offset, length) is deprecated.' +
-                 ' Use write(string[, offset[, length]][, encoding]) instead.';
+const writeMsg = 'Buffer.write(string, encoding, offset, length) is ' +
+                 'deprecated. Use write(string[, offset[, length]]' +
+                 '[, encoding]) instead.';
 Buffer.prototype.write = function(string, offset, length, encoding) {
   // Buffer#write(string);
   if (offset === undefined) {
diff --git a/lib/child_process.js b/lib/child_process.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const util = require('util');
+const internalUtil = require('internal/util');
 const debug = util.debuglog('child_process');
 const constants = require('constants');
 
@@ -269,11 +270,12 @@ exports.execFile = function(file /* args, options, callback */) {
   return child;
 };
 
-var _deprecatedCustomFds = util.deprecate(function(options) {
+var _deprecatedCustomFds = internalUtil.deprecate(function(options) {
   options.stdio = options.customFds.map(function(fd) {
     return fd === -1 ? 'pipe' : fd;
   });
-}, 'child_process: customFds option is deprecated, use stdio instead.');
+}, 'child_process: options.customFds option is deprecated. ' +
+   'Use options.stdio instead.');
 
 function _convertCustomFds(options) {
   if (options && options.customFds && !options.stdio) {
diff --git a/lib/crypto.js b/lib/crypto.js
@@ -19,6 +19,7 @@ const Buffer = require('buffer').Buffer;
 const constants = require('constants');
 const stream = require('stream');
 const util = require('util');
+const internalUtil = require('internal/util');
 
 const DH_GENERATOR = 2;
 
@@ -682,10 +683,13 @@ function filterDuplicates(names) {
 }
 
 // Legacy API
-exports.__defineGetter__('createCredentials', util.deprecate(function() {
-  return require('tls').createSecureContext;
-}, 'createCredentials() is deprecated, use tls.createSecureContext instead'));
+exports.__defineGetter__('createCredentials',
+  internalUtil.deprecate(function() {
+    return require('tls').createSecureContext;
+  }, 'crypto.createCredentials is deprecated. ' +
+     'Use tls.createSecureContext instead.'));
 
-exports.__defineGetter__('Credentials', util.deprecate(function() {
+exports.__defineGetter__('Credentials', internalUtil.deprecate(function() {
   return require('tls').SecureContext;
-}, 'Credentials is deprecated, use tls.createSecureContext instead'));
+}, 'crypto.Credentials is deprecated. ' +
+   'Use tls.createSecureContext instead.'));
diff --git a/lib/http.js b/lib/http.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const util = require('util');
+const internalUtil = require('internal/util');
 const EventEmitter = require('events').EventEmitter;
 
 
@@ -91,9 +92,8 @@ Client.prototype.request = function(method, path, headers) {
   return c;
 };
 
-exports.Client = util.deprecate(Client,
-    'http.Client will be removed soon. Do not use it.');
+exports.Client = internalUtil.deprecate(Client, 'http.Client is deprecated.');
 
-exports.createClient = util.deprecate(function(port, host) {
+exports.createClient = internalUtil.deprecate(function(port, host) {
   return new Client(port, host);
-}, 'http.createClient is deprecated. Use `http.request` instead.');
+}, 'http.createClient is deprecated. Use http.request instead.');
diff --git a/lib/internal/util.js b/lib/internal/util.js
@@ -1,6 +1,20 @@
 'use strict';
 
+const prefix = '(node) ';
+
+// 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, `${prefix}${msg}`);
+};
+
+// All the internal deprecations have to use this function only, as this will
+// prepend the prefix to the actual message.
 exports.printDeprecationMessage = function(msg, warned) {
+  return exports._printDeprecationMessage(`${prefix}${msg}`, warned);
+};
+
+exports._printDeprecationMessage = function(msg, warned) {
   if (process.noDeprecation)
     return true;
 
@@ -10,7 +24,7 @@ exports.printDeprecationMessage = function(msg, warned) {
   if (process.throwDeprecation)
     throw new Error(msg);
   else if (process.traceDeprecation)
-    console.trace(msg);
+    console.trace(msg.startsWith(prefix) ? msg.replace(prefix, '') : msg);
   else
     console.error(msg);
 
@@ -20,11 +34,11 @@ exports.printDeprecationMessage = function(msg, warned) {
 // 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) {
   // Allow for deprecating things in the process of starting up.
   if (global.process === undefined) {
     return function() {
-      return exports.deprecate(fn, msg).apply(this, arguments);
+      return exports._deprecate(fn, msg).apply(this, arguments);
     };
   }
 
@@ -34,7 +48,7 @@ exports.deprecate = function(fn, msg) {
 
   var warned = false;
   function deprecated() {
-    warned = exports.printDeprecationMessage(msg, warned);
+    warned = exports._printDeprecationMessage(msg, warned);
     return fn.apply(this, arguments);
   }
 
diff --git a/lib/module.js b/lib/module.js
@@ -2,6 +2,7 @@
 
 const NativeModule = require('native_module');
 const util = require('util');
+const internalUtil = require('internal/util');
 const runInThisContext = require('vm').runInThisContext;
 const assert = require('assert').ok;
 const fs = require('fs');
@@ -120,12 +121,7 @@ function tryExtensions(p, exts) {
   return false;
 }
 
-
-const noopDeprecateRequireDot = util.deprecate(function() {},
-    'warning: require(\'.\') resolved outside the package directory. ' +
-    'This functionality is deprecated and will be removed soon.');
-
-
+var warned = false;
 Module._findPath = function(request, paths) {
   var exts = Object.keys(Module._extensions);
 
@@ -170,7 +166,13 @@ Module._findPath = function(request, paths) {
 
     if (filename) {
       // Warn once if '.' resolved outside the module dir
-      if (request === '.' && i > 0) noopDeprecateRequireDot();
+      if (request === '.' && i > 0) {
+        warned = internalUtil.printDeprecationMessage(
+          'warning: require(\'.\') resolved outside the package ' +
+          'directory. This functionality is deprecated and will be removed ' +
+          'soon.', warned);
+      }
+
       Module._pathCache[cacheKey] = filename;
       return filename;
     }
diff --git a/lib/net.js b/lib/net.js
@@ -4,6 +4,7 @@ const events = require('events');
 const stream = require('stream');
 const timers = require('timers');
 const util = require('util');
+const internalUtil = require('internal/util');
 const assert = require('assert');
 const cares = process.binding('cares_wrap');
 const uv = process.binding('uv');
@@ -1075,16 +1076,17 @@ function Server(options, connectionListener) {
   this._connections = 0;
 
   Object.defineProperty(this, 'connections', {
-    get: util.deprecate(function() {
+    get: internalUtil.deprecate(function() {
 
       if (self._usingSlaves) {
         return null;
       }
       return self._connections;
-    }, 'connections property is deprecated. Use getConnections() method'),
-    set: util.deprecate(function(val) {
+    }, 'Server.connections property is deprecated. ' +
+       'Use Server.getConnections method instead.'),
+    set: internalUtil.deprecate(function(val) {
       return (self._connections = val);
-    }, 'connections property is deprecated. Use getConnections() method'),
+    }, 'Server.connections property is deprecated.'),
     configurable: true, enumerable: false
   });
 
@@ -1496,9 +1498,9 @@ function emitCloseNT(self) {
 }
 
 
-Server.prototype.listenFD = util.deprecate(function(fd, type) {
+Server.prototype.listenFD = internalUtil.deprecate(function(fd, type) {
   return this.listen({ fd: fd });
-}, 'listenFD is deprecated. Use listen({fd: <number>}).');
+}, 'Server.listenFD is deprecated. Use Server.listen({fd: <number>}) instead.');
 
 Server.prototype._setupSlave = function(socketList) {
   this._usingSlaves = true;
diff --git a/lib/os.js b/lib/os.js
@@ -2,6 +2,7 @@
 
 const binding = process.binding('os');
 const util = require('util');
+const internalUtil = require('internal/util');
 const isWindows = process.platform === 'win32';
 
 exports.hostname = binding.getHostname;
@@ -46,9 +47,10 @@ exports.tmpdir = function() {
 
 exports.tmpDir = exports.tmpdir;
 
-exports.getNetworkInterfaces = util.deprecate(function() {
+exports.getNetworkInterfaces = internalUtil.deprecate(function() {
   return exports.networkInterfaces();
-}, 'getNetworkInterfaces is now called `os.networkInterfaces`.');
+}, 'os.getNetworkInterfaces is deprecated. ' +
+   'Use os.networkInterfaces instead.');
 
 exports.EOL = isWindows ? '\r\n' : '\n';
 
diff --git a/lib/readline.js b/lib/readline.js
@@ -9,6 +9,7 @@
 const kHistorySize = 30;
 
 const util = require('util');
+const internalUtil = require('internal/util');
 const inherits = util.inherits;
 const Buffer = require('buffer').Buffer;
 const EventEmitter = require('events').EventEmitter;
@@ -1417,8 +1418,9 @@ function codePointAt(str, index) {
   }
   return code;
 }
-exports.codePointAt = util.deprecate(codePointAt,
-    'codePointAt() is deprecated. Use String.prototype.codePointAt');
+exports.codePointAt = internalUtil.deprecate(codePointAt,
+    'readline.codePointAt is deprecated. ' +
+    'Use String.prototype.codePointAt instead.');
 
 
 /**
diff --git a/lib/smalloc.js b/lib/smalloc.js
@@ -3,4 +3,5 @@
 const util = require('internal/util');
 
 module.exports = require('internal/smalloc');
-util.printDeprecationMessage('smalloc is deprecated.');
+util.printDeprecationMessage('smalloc is deprecated. ' +
+                             'Use typed arrays instead.');
diff --git a/lib/tty.js b/lib/tty.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const util = require('util');
+const internalUtil = require('internal/util');
 const net = require('net');
 const TTY = process.binding('tty_wrap').TTY;
 const isTTY = process.binding('tty_wrap').isTTY;
@@ -14,12 +15,13 @@ exports.isatty = function(fd) {
 
 
 // backwards-compat
-exports.setRawMode = util.deprecate(function(flag) {
+exports.setRawMode = internalUtil.deprecate(function(flag) {
   if (!process.stdin.isTTY) {
     throw new Error('can\'t set raw mode on non-tty');
   }
   process.stdin.setRawMode(flag);
-}, 'tty.setRawMode: Use `process.stdin.setRawMode()` instead.');
+}, 'tty.setRawMode is deprecated. ' +
+   'Use process.stdin.setRawMode instead.');
 
 
 function ReadStream(fd, options) {
diff --git a/lib/util.js b/lib/util.js
diff --git a/test/fixtures/deprecated-userland-function.js b/test/fixtures/deprecated-userland-function.js
diff --git a/test/sequential/test-deprecation-flags.js b/test/sequential/test-deprecation-flags.js
