module: expose getPackageJSON utility

doc/api/module.md

@@ -217,6 +217,48 @@ added: v22.8.0
 * Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled,
   or `undefined` otherwise.
 
+### `module.getPackageJSON(startLocation[, everything])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+* `startLocation` {string} A fully resolved FS path or file URL to start looking
+* `everything` {boolean} Whether to return the full contents of the found package.json
+* Returns: {Object | undefined}
+  * data: {Object}
+    * name: {string | undefined}
+    * type: {string | undefined}
+    * exports: string | string\[] | Record\<string, unknown> | undefined
+    * imports: string | string\[] | Record\<string, unknown> | undefined
+    * …
+  * path: {string}
+
+Retreives the contents and location of the package.json closest to the supplied `startLocation`;
+this behaves identically to node's own lookup and consumption of package.json for a given module.
+
+```mjs
+import { getPackageJSON } from 'node:module';
+
+const somePackage = getPackageJSON(import.meta.resolve('some-package'), true);
+
+somePackage?.path; // '/…/node_modules/some-package/package.json'
+somePackage?.data.name; // 'some-package-real-name'
+somePackage?.data.types; // './index.d.ts'
+
+const thisParentPackage = getPackageJSON(import.meta.resolve('..'));
+
+thisParentPackage?.path; // '../../package.json'
+thisParentPackage?.data.type; // 'module'
+
+const thisSubPackage = getPackageJSON(import.meta.url);
+
+thisSubPackage?.path; // './package.json'
+thisSubPackage?.data.type; // 'commonjs'
+```
+
 ### `module.isBuiltin(moduleName)`
 
 <!-- YAML

lib/internal/modules/cjs/loader.js

@@ -604,11 +604,11 @@ function trySelf(parentPath, request) {
   try {
     const { packageExportsResolve } = require('internal/modules/esm/resolve');
     return finalizeEsmResolution(packageExportsResolve(
-      pathToFileURL(pkg.path + '/package.json'), expansion, pkg.data,
+      pathToFileURL(pkg.path), expansion, pkg.data,
       pathToFileURL(parentPath), getCjsConditions()), parentPath, pkg.path);
   } catch (e) {
     if (e.code === 'ERR_MODULE_NOT_FOUND') {
-      throw createEsmNotFoundErr(request, pkg.path + '/package.json');
+      throw createEsmNotFoundErr(request, pkg.path);
     }
     throw e;
   }
@@ -1214,14 +1214,15 @@ Module._resolveFilename = function(request, parent, isMain, options) {
 
   if (request[0] === '#' && (parent?.filename || parent?.id === '<repl>')) {
     const parentPath = parent?.filename ?? process.cwd() + path.sep;
-    const pkg = packageJsonReader.getNearestParentPackageJSON(parentPath) || { __proto__: null };
-    if (pkg.data?.imports != null) {
+    const pkg = packageJsonReader.getNearestParentPackageJSON(parentPath);
+    if (pkg?.data.imports != null) {
       try {
         const { packageImportsResolve } = require('internal/modules/esm/resolve');
         return finalizeEsmResolution(
-          packageImportsResolve(request, pathToFileURL(parentPath),
-                                getCjsConditions()), parentPath,
-          pkg.path);
+          packageImportsResolve(request, pathToFileURL(parentPath), getCjsConditions()),
+          parentPath,
+          pkg.path,
+        );
       } catch (e) {
         if (e.code === 'ERR_MODULE_NOT_FOUND') {
           throw createEsmNotFoundErr(request);
@@ -1281,8 +1282,7 @@ function finalizeEsmResolution(resolved, parentPath, pkgPath) {
   if (actual) {
     return actual;
   }
-  const err = createEsmNotFoundErr(filename,
-                                   path.resolve(pkgPath, 'package.json'));
+  const err = createEsmNotFoundErr(filename, pkgPath);
   throw err;
 }
 
@@ -1614,7 +1614,7 @@ function loadTS(module, filename) {
 
     const parent = module[kModuleParent];
     const parentPath = parent?.filename;
-    const packageJsonPath = path.resolve(pkg.path, 'package.json');
+    const packageJsonPath = pkg.path;
     const usesEsm = containsModuleSyntax(content, filename);
     const err = new ERR_REQUIRE_ESM(filename, usesEsm, parentPath,
                                     packageJsonPath);
@@ -1673,7 +1673,7 @@ Module._extensions['.js'] = function(module, filename) {
       // This is an error path because `require` of a `.js` file in a `"type": "module"` scope is not allowed.
       const parent = module[kModuleParent];
       const parentPath = parent?.filename;
-      const packageJsonPath = path.resolve(pkg.path, 'package.json');
+      const packageJsonPath = pkg.path;
       const usesEsm = containsModuleSyntax(content, filename);
       const err = new ERR_REQUIRE_ESM(filename, usesEsm, parentPath,
                                       packageJsonPath);

lib/internal/modules/esm/resolve.js

@@ -191,7 +191,7 @@ const legacyMainResolveExtensionsIndexes = {
  * 4. TRY(pkg_url/index.js, pkg_url/index.json, pkg_url/index.node)
  * 5. NOT_FOUND
  * @param {URL} packageJSONUrl
- * @param {import('typings/internalBinding/modules').PackageConfig} packageConfig
+ * @param {import('typings/internalBinding/modules').RecognizedPackageConfig} packageConfig
  * @param {string | URL | undefined} base
  * @returns {URL}
  */

lib/internal/modules/package_json_reader.js

@@ -2,31 +2,48 @@
 
 const {
   ArrayIsArray,
+  ArrayPrototypeJoin,
   JSONParse,
   ObjectDefineProperty,
-  StringPrototypeLastIndexOf,
-  StringPrototypeSlice,
+  StringPrototypeEndsWith,
 } = primordials;
+const {
+  codes: {
+    ERR_INVALID_ARG_VALUE,
+  },
+} = require('internal/errors');
 const modulesBinding = internalBinding('modules');
-const { resolve, sep } = require('path');
+const path = require('path');
 const { kEmptyObject } = require('internal/util');
+const { fileURLToPath, URL } = require('internal/url');
+const {
+  validateBoolean,
+  validateString,
+} = require('internal/validators');
+
+/**
+ * @typedef {import('typings/internalBinding/modules').DeserializedPackageConfig} DeserializedPackageConfig
+ * @typedef {import('typings/internalBinding/modules').FullPackageConfig} FullPackageConfig
+ * @typedef {import('typings/internalBinding/modules').RecognizedPackageConfig} RecognizedPackageConfig
+ * @typedef {import('typings/internalBinding/modules').SerializedPackageConfig} SerializedPackageConfig
+ */
 
 /**
  * @param {string} path
- * @param {import('typings/internalBinding/modules').SerializedPackageConfig} contents
- * @returns {import('typings/internalBinding/modules').PackageConfig}
+ * @param {SerializedPackageConfig} contents
+ * @returns {DeserializedPackageConfig}
  */
 function deserializePackageJSON(path, contents) {
   if (contents === undefined) {
     return {
-      __proto__: null,
-      exists: false,
-      pjsonPath: path,
-      type: 'none', // Ignore unknown types for forwards compatibility
+      data: {
+        __proto__: null,
+        type: 'none', // Ignore unknown types for forwards compatibility
+      },
+      path,
     };
   }
 
-  let pjsonPath = path;
   const {
     0: name,
     1: main,
@@ -37,36 +54,39 @@ function deserializePackageJSON(path, contents) {
   } = contents;
 
   // This is required to be used in getPackageScopeConfig.
-  if (optionalFilePath) {
-    pjsonPath = optionalFilePath;
-  }
-
-  // The imports and exports fields can be either undefined or a string.
-  // - If it's a string, it's either plain string or a stringified JSON string.
-  // - If it's a stringified JSON string, it starts with either '[' or '{'.
-  const requiresJSONParse = (value) => (value !== undefined && (value[0] === '[' || value[0] === '{'));
+  const pjsonPath = optionalFilePath ?? path;
 
   return {
-    __proto__: null,
-    exists: true,
-    pjsonPath,
-    name,
-    main,
-    type,
-    // This getters are used to lazily parse the imports and exports fields.
-    get imports() {
-      const value = requiresJSONParse(plainImports) ? JSONParse(plainImports) : plainImports;
-      ObjectDefineProperty(this, 'imports', { __proto__: null, value });
-      return this.imports;
-    },
-    get exports() {
-      const value = requiresJSONParse(plainExports) ? JSONParse(plainExports) : plainExports;
-      ObjectDefineProperty(this, 'exports', { __proto__: null, value });
-      return this.exports;
+    data: {
+      __proto__: null,
+      ...(name !== null && { name }),
+      ...(main != null && { main }),
+      ...(type != null && { type }),
+      ...(plainImports != null && {
+        // This getters are used to lazily parse the imports and exports fields.
+        get imports() {
+          const value = requiresJSONParse(plainImports) ? JSONParse(plainImports) : plainImports;
+          ObjectDefineProperty(this, 'imports', { __proto__: null, value });
+          return this.imports;
+        },
+      }),
+      ...(plainExports != null && {
+        get exports() {
+          const value = requiresJSONParse(plainExports) ? JSONParse(plainExports) : plainExports;
+          ObjectDefineProperty(this, 'exports', { __proto__: null, value });
+          return this.exports;
+        },
+      }),
     },
+    path: pjsonPath,
   };
 }
 
+// The imports and exports fields can be either undefined or a string.
+// - If it's a string, it's either plain string or a stringified JSON string.
+// - If it's a stringified JSON string, it starts with either '[' or '{'.
+const requiresJSONParse = (value) => (value !== undefined && (value[0] === '[' || value[0] === '{'));
+
 /**
  * Reads a package.json file and returns the parsed contents.
  * @param {string} jsonPath
@@ -75,7 +95,7 @@ function deserializePackageJSON(path, contents) {
  *   specifier?: URL | string,
  *   isESM?: boolean,
  * }} options
- * @returns {import('typings/internalBinding/modules').PackageConfig}
+ * @returns {RecognizedPackageConfig}
  */
 function read(jsonPath, { base, specifier, isESM } = kEmptyObject) {
   // This function will be called by both CJS and ESM, so we need to make sure
@@ -87,52 +107,93 @@ function read(jsonPath, { base, specifier, isESM } = kEmptyObject) {
     specifier == null ? undefined : `${specifier}`,
   );
 
-  return deserializePackageJSON(jsonPath, parsed);
+  const result = deserializePackageJSON(jsonPath, parsed);
+
+  return {
+    ...result.data,
+    exists: result.data !== 'none',
+    pjsonPath: result.path,
+  };
 }
 
 /**
  * @deprecated Expected to be removed in favor of `read` in the future.
  * Behaves the same was as `read`, but appends package.json to the path.
  * @param {string} requestPath
- * @return {PackageConfig}
+ * @return {RecognizedPackageConfig}
  */
 function readPackage(requestPath) {
   // TODO(@anonrig): Remove this function.
-  return read(resolve(requestPath, 'package.json'));
+  return read(path.resolve(requestPath, 'package.json'));
 }
 
 /**
  * Get the nearest parent package.json file from a given path.
  * Return the package.json data and the path to the package.json file, or undefined.
- * @param {string} checkPath The path to start searching from.
- * @returns {undefined | {data: import('typings/internalBinding/modules').PackageConfig, path: string}}
+ * @param {URL['href'] | URL['pathname']} startLocation The path to start searching from.
+ * @param {boolean} everything Whether to include the full contents of the package.json.
+ * @returns {undefined | DeserializedPackageConfig<everything>}
  */
-function getNearestParentPackageJSON(checkPath) {
-  const result = modulesBinding.getNearestParentPackageJSON(checkPath);
+function getNearestParentPackageJSON(startLocation, everything = false) {
+  let startPath = URL.canParse(startLocation) ? fileURLToPath(startLocation) : startLocation;
+
+  validateString(startPath, 'startPath');
+  validateBoolean(everything, 'everything');
+
+  if (!path.isAbsolute(startPath)) {
+    throw new ERR_INVALID_ARG_VALUE(
+      'startLocation',
+      startLocation,
+      ArrayPrototypeJoin([
+        'must be a fully resolved location. To use a relative location, first wrap with',
+        '`import.meta.resolve(startLocation)` in ESM',
+        'or',
+        '`path.resolve(__dirname, startLocation) in CJS',
+      ], ' '),
+    );
+  }
 
-  if (result === undefined) {
-    return undefined;
+  if (!StringPrototypeEndsWith(startPath, path.sep)) { startPath += path.sep; }
+
+  if (everything) {
+    const result = modulesBinding.getNearestRawParentPackageJSON(startPath);
+
+    return {
+      data: {
+        __proto__: null,
+        ...JSONParse(result?.[0]),
+      },
+      path: result?.[1],
+    };
   }
 
-  const data = deserializePackageJSON(checkPath, result);
+  const result = modulesBinding.getNearestParentPackageJSON(startPath);
 
-  // Path should be the root folder of the matched package.json
-  // For example for ~/path/package.json, it should be ~/path
-  const path = StringPrototypeSlice(data.pjsonPath, 0, StringPrototypeLastIndexOf(data.pjsonPath, sep));
+  if (result === undefined) {
+    return undefined;
+  }
 
-  return { data, path };
+  return deserializePackageJSON(startPath, result);
 }
 
 /**
  * Returns the package configuration for the given resolved URL.
  * @param {URL | string} resolved - The resolved URL.
- * @returns {import('typings/internalBinding/modules').PackageConfig} - The package configuration.
+ * @returns {RecognizedPackageConfig & {
+ *  exists: boolean,
+ *  pjsonPath: DeserializedPackageConfig['path'],
+ * }} - The package configuration.
  */
 function getPackageScopeConfig(resolved) {
   const result = modulesBinding.getPackageScopeConfig(`${resolved}`);
 
   if (ArrayIsArray(result)) {
-    return deserializePackageJSON(`${resolved}`, result);
+    const { data, path } = deserializePackageJSON(`${resolved}`, result);
+    return {
+      __proto__: null,
+      ...data,
+      pjsonPath: path,
+    };
   }
 
   // This means that the response is a string

lib/module.js

@@ -10,6 +10,9 @@ const {
   flushCompileCache,
   getCompileCacheDir,
 } = require('internal/modules/helpers');
+const {
+  getNearestParentPackageJSON,
+} = require('internal/modules/package_json_reader');
 
 Module.findSourceMap = findSourceMap;
 Module.register = register;
@@ -19,4 +22,5 @@ Module.enableCompileCache = enableCompileCache;
 Module.flushCompileCache = flushCompileCache;
 
 Module.getCompileCacheDir = getCompileCacheDir;
+Module.getPackageJSON = getNearestParentPackageJSON;
 module.exports = Module;