buffer: add pending deprecation warning

The pending deprecation warning is off by default.
Launch the node process with --pending-deprecation
or NODE_PENDING_DEPRECATION=1 env var set.

PR-URL: https://github.com/nodejs/node/pull/11968
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

lib/buffer.js

@@ -22,18 +22,20 @@
 'use strict';
 
 const binding = process.binding('buffer');
+const config = process.binding('config');
 const { compare: compare_, compareOffset } = binding;
 const { isAnyArrayBuffer, isUint8Array } = process.binding('util');
 const bindingObj = {};
 const internalUtil = require('internal/util');
+const pendingDeprecation = !!config.pendingDeprecation;
 
 class FastBuffer extends Uint8Array {
   constructor(arg1, arg2, arg3) {
     super(arg1, arg2, arg3);
   }
 }
-
 FastBuffer.prototype.constructor = Buffer;
+
 Buffer.prototype = FastBuffer.prototype;
 
 exports.Buffer = Buffer;
@@ -83,6 +85,28 @@ function alignPool() {
   }
 }
 
+var bufferWarn = true;
+const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' +
+                      'recommended for use due to security and usability ' +
+                      'concerns. Please use the new Buffer.alloc(), ' +
+                      'Buffer.allocUnsafe(), or Buffer.from() construction ' +
+                      'methods instead.';
+
+function showFlaggedDeprecation() {
+  if (bufferWarn) {
+    // This is a *pending* deprecation warning. It is not emitted by
+    // default unless the --pending-deprecation command-line flag is
+    // used or the NODE_PENDING_DEPRECATION=1 envvar is set.
+    process.emitWarning(bufferWarning, 'DeprecationWarning', 'DEP0005');
+    bufferWarn = false;
+  }
+}
+
+const doFlaggedDeprecation =
+  pendingDeprecation ?
+    showFlaggedDeprecation :
+    function() {};
+
 /**
  * The Buffer() construtor is deprecated in documentation and should not be
  * used moving forward. Rather, developers should use one of the three new
@@ -94,6 +118,7 @@ function alignPool() {
  * Deprecation Code: DEP0005
  **/
 function Buffer(arg, encodingOrOffset, length) {
+  doFlaggedDeprecation();
   // Common case.
   if (typeof arg === 'number') {
     if (typeof encodingOrOffset === 'string') {
@@ -106,6 +131,12 @@ function Buffer(arg, encodingOrOffset, length) {
   return Buffer.from(arg, encodingOrOffset, length);
 }
 
+Object.defineProperty(Buffer, Symbol.species, {
+  enumerable: false,
+  configurable: true,
+  get() { return FastBuffer; }
+});
+
 /**
  * Functionally equivalent to Buffer(arg, encoding) but throws a TypeError
  * if value is a number.

test/parallel/test-buffer-nopendingdep-map.js

@@ -0,0 +1,14 @@
+// Flags: --no-warnings --pending-deprecation
+'use strict';
+
+const common = require('../common');
+const Buffer = require('buffer').Buffer;
+
+process.on('warning', common.mustNotCall('A warning should not be emitted'));
+
+// With the --pending-deprecation flag, the deprecation warning for
+// new Buffer() should not be emitted when Uint8Array methods are called.
+
+Buffer.from('abc').map((i) => i);
+Buffer.from('abc').filter((i) => i);
+Buffer.from('abc').slice(1, 2);

test/parallel/test-buffer-pending-deprecation.js

@@ -0,0 +1,15 @@
+// Flags: --pending-deprecation --no-warnings
+'use strict';
+
+const common = require('../common');
+const Buffer = require('buffer').Buffer;
+
+const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' +
+                      'recommended for use due to security and usability ' +
+                      'concerns. Please use the new Buffer.alloc(), ' +
+                      'Buffer.allocUnsafe(), or Buffer.from() construction ' +
+                      'methods instead.';
+
+common.expectWarning('DeprecationWarning', bufferWarning);
+
+new Buffer(10);