From 72644d62e7f073468a79586630512a4e2482465e Mon Sep 17 00:00:00 2001 From: Antoine du Hamel <duhamelantoine1995@gmail.com> Date: Sun, 1 Oct 2023 08:26:56 +0100 Subject: [PATCH] esm: improve JSDoc annotation of internal functions Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com> PR-URL: https://github.com/nodejs/node/pull/49959 Backport-PR-URL: https://github.com/nodejs/node/pull/50669 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> --- lib/internal/modules/run_main.js | 11 ++++++----- lib/internal/process/pre_execution.js | 10 ++++++++++ 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js index bdf24983e56503..fed8fc5e969174 100644 --- a/lib/internal/modules/run_main.js +++ b/lib/internal/modules/run_main.js @@ -10,7 +10,7 @@ const path = require('path'); /** * Get the absolute path to the main entry point. - * @param {string} main Entry point path + * @param {string} main - Entry point path */ function resolveMainPath(main) { // Note extension resolution for the main entry point can be deprecated in a @@ -31,7 +31,7 @@ function resolveMainPath(main) { /** * Determine whether the main entry point should be loaded through the ESM Loader. - * @param {string} mainPath Absolute path to the main entry point + * @param {string} mainPath - Absolute path to the main entry point */ function shouldUseESMLoader(mainPath) { /** @@ -63,7 +63,7 @@ function shouldUseESMLoader(mainPath) { /** * Run the main entry point through the ESM Loader. - * @param {string} mainPath Absolute path to the main entry point + * @param {string} mainPath - Absolute path for the main entry point */ function runMainESM(mainPath) { const { loadESM } = require('internal/process/esm_loader'); @@ -78,7 +78,7 @@ function runMainESM(mainPath) { /** * Handle process exit events around the main entry point promise. - * @param {Promise} promise Main entry point promise + * @param {Promise} promise - Main entry point promise */ async function handleMainPromise(promise) { const { @@ -96,7 +96,8 @@ async function handleMainPromise(promise) { * Parse the CLI main entry point string and run it. * For backwards compatibility, we have to run a bunch of monkey-patchable code that belongs to the CJS loader (exposed * by `require('module')`) even when the entry point is ESM. - * @param {string} main CLI main entry point string + * Because of backwards compatibility, this function is exposed publicly via `import { runMain } from 'node:module'`. + * @param {string} main - Resolved absolute path for the main entry point, if found */ function executeUserEntryPoint(main = process.argv[1]) { const resolvedMain = resolveMainPath(main); diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js index 882fc9f92bd3ec..5cebbe0860d085 100644 --- a/lib/internal/process/pre_execution.js +++ b/lib/internal/process/pre_execution.js @@ -141,12 +141,20 @@ function refreshRuntimeOptions() { refreshOptions(); } +/** + * Patch the process object with legacy properties and normalizations. + * Replace `process.argv[0]` with `process.execPath`, preserving the original `argv[0]` value as `process.argv0`. + * Replace `process.argv[1]` with the resolved absolute file path of the entry point, if found. + * @param {boolean} expandArgv1 - Whether to replace `process.argv[1]` with the resolved absolute file path of + * the main entry point. + */ function patchProcessObject(expandArgv1) { const binding = internalBinding('process_methods'); binding.patchProcessObject(process); require('internal/process/per_thread').refreshHrtimeBuffer(); + // Since we replace process.argv[0] below, preserve the original value in case the user needs it. ObjectDefineProperty(process, 'argv0', { __proto__: null, enumerable: true, @@ -159,6 +167,8 @@ function patchProcessObject(expandArgv1) { process._exiting = false; process.argv[0] = process.execPath; + // If requested, update process.argv[1] to replace whatever the user provided with the resolved absolute file path of + // the entry point. if (expandArgv1 && process.argv[1] && !StringPrototypeStartsWith(process.argv[1], '-')) { // Expand process.argv[1] into a full path.