module: deprecate module.parent

This feature does not work when a module is imported using ECMAScript
modules specification, therefore it is deprecated.

Fixes: nodejs/modules#469

Backport-PR-URL: #33533
PR-URL: #32217
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

doc/api/deprecations.md

@@ -2707,6 +2707,39 @@ Type: Runtime
 `Transform._transformState` will be removed in future versions where it is
 no longer required due to simplification of the implementation.
 
+<a id="DEP0144"></a>
+### DEP0144: `module.parent`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/32217
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+A CommonJS module can access the first module that required it using
+`module.parent`. This feature is deprecated because it does not work
+consistently in the presence of ECMAScript modules and because it gives an
+inaccurate representation of the CommonJS module graph.
+
+Some modules use it to check if they are the entry point of the current process.
+Instead, it is recommended to compare `require.main` and `module`:
+
+```js
+if (require.main === module) {
+  // Code section that will run only if current file is the entry point.
+}
+```
+
+When looking for the CommonJS modules that have required the current one,
+`require.cache` and `module.children` can be used:
+
+```js
+const moduleParents = Object.values(require.cache)
+  .filter((m) => m.children.includes(module));
+```
+
 <a id="DEP0XXX"></a>
 ### DEP0XXX: `socket.bufferSize`
 <!-- YAML

doc/api/modules.md

@@ -905,11 +905,17 @@ loading.
 ### `module.parent`
 <!-- YAML
 added: v0.1.16
+deprecated: REPLACEME
 -->
 
-* {module}
+> Stability: 0 - Deprecated: Please use [`require.main`][] and
+> [`module.children`][] instead.
+
+* {module | null | undefined}
 
-The module that first required this one.
+The module that first required this one, or `null` if the current module is the
+entry point of the current process, or `undefined` if the module was loaded by
+something that is not a CommonJS module (E.G.: REPL or `import`).
 
 ### `module.path`
 <!-- YAML
@@ -1133,13 +1139,15 @@ consists of the following keys:
 [`createRequire()`]: #modules_module_createrequire_filename
 [`module` object]: #modules_the_module_object
 [`module.id`]: #modules_module_id
+[`module.children`]: #modules_module_children
 [`path.dirname()`]: path.html#path_path_dirname_path
 [ECMAScript Modules]: esm.html
 [an error]: errors.html#errors_err_require_esm
 [exports shortcut]: #modules_exports_shortcut
 [module resolution]: #modules_all_together
 [module wrapper]: #modules_the_module_wrapper
 [native addons]: addons.html
+[`require.main`]: #modules_require_main
 [source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
 [`--enable-source-maps`]: cli.html#cli_enable_source_maps
 [`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir

lib/internal/modules/cjs/loader.js

@@ -1247,7 +1247,8 @@ Module._extensions['.js'] = function(module, filename) {
     const pkg = readPackageScope(filename);
     // Function require shouldn't be used in ES modules.
     if (pkg && pkg.data && pkg.data.type === 'module') {
-      const parentPath = module.parent && module.parent.filename;
+      const { parent } = module;
+      const parentPath = parent && parent.filename;
       const packageJsonPath = path.resolve(pkg.path, 'package.json');
       throw new ERR_REQUIRE_ESM(filename, parentPath, packageJsonPath);
     }

test/common/index.js

@@ -59,12 +59,12 @@ if (process.argv.length === 2 &&
     !process.env.NODE_SKIP_FLAG_CHECK &&
     isMainThread &&
     hasCrypto &&
-    module.parent &&
+    require.main &&
     require('cluster').isMaster) {
   // The copyright notice is relatively big and the flags could come afterwards.
   const bytesToRead = 1500;
   const buffer = Buffer.allocUnsafe(bytesToRead);
-  const fd = fs.openSync(module.parent.filename, 'r');
+  const fd = fs.openSync(require.main.filename, 'r');
   const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead);
   fs.closeSync(fd);
   const source = buffer.toString('utf8', 0, bytesRead);

test/common/require-as.js

@@ -1,7 +1,7 @@
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 'use strict';
 
-if (module.parent) {
+if (require.main !== module) {
   const { spawnSync } = require('child_process');
 
   function runModuleAs(filename, flags, spawnOptions, role) {

test/js-native-api/test_instance_data/test.js

@@ -4,7 +4,7 @@
 const common = require('../../common');
 const assert = require('assert');
 
-if (module.parent) {
+if (module !== require.main) {
   // When required as a module, run the tests.
   const test_instance_data =
     require(`./build/${common.buildType}/test_instance_data`);

test/node-api/test_instance_data/test.js

@@ -3,7 +3,7 @@
 
 const common = require('../../common');
 
-if (module.parent) {
+if (module !== require.main) {
   // When required as a module, run the tests.
   const test_instance_data =
     require(`./build/${common.buildType}/test_instance_data`);

test/parallel/test-cli-eval.js

@@ -20,7 +20,7 @@
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 'use strict';
-if (module.parent) {
+if (module !== require.main) {
   // Signal we've been loaded as a module.
   // The following console.log() is part of the test.
   console.log('Loaded as a module, exiting with status code 42.');