module: expose module.format

To help users relying on require.cache determine the format of a
cached module.

Refs: #59868

Author: joyeecheung

doc/api/modules.md

@@ -1152,6 +1152,20 @@ added: v0.1.16
 
 The fully resolved filename of the module.
 
+### `module.format`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string|undefined}
+
+The [detected format][Determining module system] of the module. Possible values are documented
+in [`load` customization hooks][].
+
+This property is not guaranteed to be defined on the `module` object, nor to be accurate. If
+it's undefined, it's likely that Node.js does not yet know the module format.
+
 ### `module.id`
 
 <!-- YAML
@@ -1277,6 +1291,7 @@ This section was moved to
 [`__dirname`]: #__dirname
 [`__filename`]: #__filename
 [`import()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import
+[`load` customization hooks]: module.md#loadurl-context-nextload
 [`module.builtinModules`]: module.md#modulebuiltinmodules
 [`module.children`]: #modulechildren
 [`module.id`]: #moduleid

lib/internal/modules/cjs/loader.js

@@ -338,6 +338,12 @@ function Module(id = '', parent) {
   this.filename = null;
   this.loaded = false;
   this.children = [];
+  ObjectDefineProperty(this, 'format', {
+    __proto__: null,
+    enumerable: true,
+    configurable: true,
+    get() { return this[kFormat]; },
+  });
 }
 
 /** @type {Record<string, Module>} */
@@ -1702,43 +1708,51 @@ function wrapSafe(filename, content, cjsModuleInstance, format) {
  * `exports`) to the file. Returns exception, if any.
  * @param {string} content The source code of the module
  * @param {string} filename The file path of the module
- * @param {'module'|'commonjs'|'commonjs-typescript'|'module-typescript'|'typescript'} format
+ * @param {'module'|'commonjs'|'commonjs-typescript'|'module-typescript'|'typescript'} fileFormat
  *   Intended format of the module.
  * @returns {any}
  */
-Module.prototype._compile = function(content, filename, format) {
-  if (format === 'commonjs-typescript' || format === 'module-typescript' || format === 'typescript') {
+Module.prototype._compile = function(content, filename, fileFormat) {
+  let runFormat = fileFormat;
+  if (fileFormat === 'commonjs-typescript' || fileFormat === 'module-typescript' || fileFormat === 'typescript') {
     content = stripTypeScriptModuleTypes(content, filename);
-    switch (format) {
+    switch (fileFormat) {
       case 'commonjs-typescript': {
-        format = 'commonjs';
+        runFormat = 'commonjs';
         break;
       }
       case 'module-typescript': {
-        format = 'module';
+        runFormat = 'module';
         break;
       }
       // If the format is still unknown i.e. 'typescript', detect it in
       // wrapSafe using the type-stripped source.
       default:
-        format = undefined;
+        runFormat = undefined;
         break;
     }
   }
 
   let redirects;
 
   let compiledWrapper;
-  if (format !== 'module') {
-    const result = wrapSafe(filename, content, this, format);
+  // If the format is unknown, or it's commonjs.
+  if (runFormat !== 'module') {
+    const result = wrapSafe(filename, content, this, runFormat);
     compiledWrapper = result.function;
     if (result.canParseAsESM) {
-      format = 'module';
+      runFormat = 'module';
     }
   }
 
-  if (format === 'module') {
-    loadESMFromCJS(this, filename, format, content);
+  runFormat ??= 'commonjs';
+  this[kFormat] ??= fileFormat || runFormat;
+  if (this[kFormat] === 'typescript') {
+    this[kFormat] = runFormat === 'module' ? 'module-typescript' : 'commonjs-typescript';
+  }
+
+  if (runFormat === 'module') {
+    loadESMFromCJS(this, filename, runFormat, content);
     return;
   }
 
@@ -1916,6 +1930,7 @@ Module._extensions['.json'] = function(module, filename) {
  */
 Module._extensions['.node'] = function(module, filename) {
   // Be aware this doesn't use `content`
+  this[kFormat] = 'addon';
   return process.dlopen(module, path.toNamespacedPath(filename));
 };
 

test/parallel/test-module-format-from-import.mjs

@@ -0,0 +1,8 @@
+// Similar to ./test-module-format.mjs but imports a CJS file instead.
+
+import '../common/index.mjs';
+// FIXME(https://github.com/nodejs/node/issues/59666): this only works
+// when there are no customization hooks or the hooks do no override the
+// source. Otherwise the re-invented require() kicks in which does not
+// properly initialize all the properties of the CJS cache entry.
+await import('./test-module-format.js');

test/parallel/test-module-format.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// This file tests that the `format` property is correctly set on
+// `cache` entries when loading CommonJS and ES modules.
+
+require('../common');
+const assert = require('assert');
+const fixtures = require('../common/fixtures.js');
+const cache = require('module')._cache;
+assert.strictEqual(cache[__filename].format, 'commonjs');
+
+const list = [
+  {
+    filename: fixtures.path('es-modules/package-without-type/commonjs.js'),
+    format: 'commonjs',
+  },
+  {
+    filename: fixtures.path('es-modules/package-without-type/imports-commonjs.cjs'),
+    format: 'commonjs',
+  },
+  {
+    filename: fixtures.path('es-modules/package-without-type/module.js'),
+    format: 'module',
+  },
+  {
+    filename: fixtures.path('es-modules/package-without-type/imports-esm.mjs'),
+    format: 'module',
+  },
+  {
+    filename: fixtures.path('es-modules/package-type-module/esm.js'),
+    format: 'module',
+  },
+  {
+    filename: fixtures.path('es-modules/package-type-commonjs/index.js'),
+    format: 'commonjs',
+  },
+  {
+    filename: fixtures.path('es-modules/package-type-module/package.json'),
+    format: 'json',
+  },
+  {
+    filename: fixtures.path('typescript/ts/module-logger.ts'),
+    format: 'module-typescript',
+  },
+  {
+    filename: fixtures.path('typescript/mts/test-mts-export-foo.mts'),
+    format: 'module-typescript',
+  },
+  {
+    filename: fixtures.path('typescript/mts/test-module-export.ts'),
+    format: 'module-typescript',
+  },
+  {
+    filename: fixtures.path('typescript/cts/test-cts-export-foo.cts'),
+    format: 'commonjs-typescript',
+  },
+  {
+    filename: fixtures.path('typescript/cts/test-commonjs-export.ts'),
+    format: 'commonjs-typescript',
+  },
+];
+
+for (const { filename, format } of list) {
+  assert(!cache[filename], `Expected ${filename} to not be in cache yet`);
+  require(filename);
+  assert.strictEqual(cache[filename].format, format, `Unexpected format for ${filename}`);
+}