src: add --pending-deprecation and NODE_PENDING_DEPRECATION

Command line flag and environment variable that can be used to
indicate that pending deprecations should be emitted.

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>

doc/api/cli.md

@@ -137,6 +137,20 @@ added: v0.11.14
 
 Throw errors for deprecations.
 
+### `--pending-deprecation`
+<!-- YAML
+added: REPLACEME
+-->
+
+Emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `--no-warnings`
 <!-- YAML
 added: v6.0.0
@@ -383,6 +397,20 @@ added: v7.5.0
 
 When set to `1`, process warnings are silenced.
 
+### `NODE_PENDING_DEPRECATION=1`
+<!-- YAML
+added: REPLACEME
+-->
+
+When set to `1`, emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `NODE_PRESERVE_SYMLINKS=1`
 <!-- YAML
 added: v7.1.0

doc/node.1

@@ -115,6 +115,10 @@ Print stack traces for deprecations.
 .BR \-\-throw\-deprecation
 Throw errors for deprecations.
 
+.TP
+.BR \-\-pending\-deprecation
+Emit pending deprecation warnings.
+
 .TP
 .BR \-\-no\-warnings
 Silence all process warnings (including deprecations).
@@ -259,6 +263,10 @@ When set to \fI1\fR, process warnings are silenced.
 .BR NODE_PATH =\fIpath\fR[:\fI...\fR]
 \':\'\-separated list of directories prefixed to the module search path.
 
+.TP
+.BR NODE_PENDING_DEPRECATION = \fI1\fR
+When set to \fI1\fR, emit pending deprecation warnings.
+
 .TP
 .BR NODE_REPL_HISTORY =\fIfile\fR
 Path to the file used to store the persistent REPL history. The default path

src/node.cc

@@ -209,6 +209,10 @@ bool trace_warnings = false;
 // that is used by lib/module.js
 bool config_preserve_symlinks = false;
 
+// Set by ParseArgs when --pending-deprecation or NODE_PENDING_DEPRECATION
+// is used.
+bool config_pending_deprecation = false;
+
 // Set in node.cc by ParseArgs when --redirect-warnings= is used.
 std::string config_warning_file;  // NOLINT(runtime/string)
 
@@ -3768,6 +3772,8 @@ static void ParseArgs(int* argc,
       short_circuit = true;
     } else if (strcmp(arg, "--zero-fill-buffers") == 0) {
       zero_fill_all_buffers = true;
+    } else if (strcmp(arg, "--pending-deprecation") == 0) {
+      config_pending_deprecation = true;
     } else if (strcmp(arg, "--v8-options") == 0) {
       new_v8_argv[new_v8_argc] = "--help";
       new_v8_argc += 1;
@@ -4187,6 +4193,12 @@ void Init(int* argc,
   V8::SetFlagsFromString(NODE_V8_OPTIONS, sizeof(NODE_V8_OPTIONS) - 1);
 #endif
 
+  {
+    std::string text;
+    config_pending_deprecation =
+        SafeGetenv("NODE_PENDING_DEPRECATION", &text) && text[0] == '1';
+  }
+
   // Allow for environment set preserving symlinks.
   {
     std::string text;

src/node_config.cc

@@ -49,6 +49,9 @@ static void InitConfig(Local<Object> target,
   if (config_preserve_symlinks)
     READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
 
+  if (config_pending_deprecation)
+    READONLY_BOOLEAN_PROPERTY("pendingDeprecation");
+
   if (!config_warning_file.empty()) {
     Local<String> name = OneByteString(env->isolate(), "warningFile");
     Local<String> value = String::NewFromUtf8(env->isolate(),

src/node_internals.h

@@ -76,6 +76,10 @@ extern bool config_expose_internals;
 // it to stderr.
 extern std::string config_warning_file;  // NOLINT(runtime/string)
 
+// Set in node.cc by ParseArgs when --pending-deprecation or
+// NODE_PENDING_DEPRECATION is used
+extern bool config_pending_deprecation;
+
 // Tells whether it is safe to call v8::Isolate::GetCurrent().
 extern bool v8_initialized;
 

test/parallel/test-pending-deprecation.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// Tests that --pending-deprecation and NODE_PENDING_DEPRECATION both
+// set the process.binding('config').pendingDeprecation flag that is
+// used to determine if pending deprecation messages should be shown.
+// The test is performed by launching two child processes that run
+// this same test script with different arguments. If those exit with
+// code 0, then the test passes. If they don't, it fails.
+
+const common = require('../common');
+
+const assert = require('assert');
+const config = process.binding('config');
+const fork = require('child_process').fork;
+
+function message(name) {
+  return `${name} did not set the process.binding('config').` +
+         'pendingDeprecation flag.';
+}
+
+switch (process.argv[2]) {
+  case 'env':
+  case 'switch':
+    assert.strictEqual(config.pendingDeprecation, true);
+    break;
+  default:
+    // Verify that the flag is off by default.
+    assert.strictEqual(config.pendingDeprecation, undefined);
+
+    // Test the --pending-deprecation command line switch.
+    fork(__filename, ['switch'], {
+      execArgv: ['--pending-deprecation'],
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('--pending-deprecation'));
+    }));
+
+    // Test the NODE_PENDING_DEPRECATION environment var.
+    fork(__filename, ['env'], {
+      env: {NODE_PENDING_DEPRECATION: 1},
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('NODE_PENDING_DEPRECATION'));
+    }));
+}