diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 59232512d4c..630ae8fd5b9 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2712,6 +2712,39 @@ The `repl` module exports a `_builtinLibs` property that contains an array with native modules. It was incomplete so far and instead it's better to rely upon `require('module').builtinModules`. + +### DEP0143: `module.parent` + + +Type: Documentation-only (supports [`--pending-deprecation`][]) + +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)); +``` + [`--pending-deprecation`]: cli.html#cli_pending_deprecation [`--throw-deprecation`]: cli.html#cli_throw_deprecation [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size diff --git a/doc/api/modules.md b/doc/api/modules.md index c57aa69c6d0..0718809d99b 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -690,7 +690,6 @@ Module { id: '.', path: '/absolute/path/to', exports: {}, - parent: null, filename: '/absolute/path/to/entry.js', loaded: false, children: [], @@ -894,11 +893,17 @@ loading. ### `module.parent` -* {module} +> Stability: 0 - Deprecated: Please use [`require.main`][] and +> [`module.children`][] instead. -The module that first required this one. +* {module | null | undefined} + +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`). Read only. ### `module.path`