module: expose resolveLoadAndCache API

doc/api/module.md

@@ -216,6 +216,71 @@ resolution and loading behavior. See [Customization hooks][].
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
+### `module.resolve(specifier, parentURL[, importAttributes]])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `specifier` {string|URL} Module to resolve and load; this should be
+  the same string that would be passed to `import()`, except that if it is
+  relative, it is resolved relative to `parentURL`.
+* `parentURL` {string|URL|undefined} The base URL to resolve `specifier` from,
+  such as `import.meta.url`.
+* `importAttributes` {Object} **Default:** an empty object.
+* Returns: {Promise} fulfills with a string containing the full URL of the
+  potential module corresponding to the given specifier.
+
+Analogous to `import.meta.resolve`, but asynchronous, accessible from CommonJS
+modules, and with additional parameters.
+
+### `module.load(url[, importAttributes[, conditions]]])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `url` {string|URL|undefined} The URL of the module to load.
+* `importAttributes` {Object} **Default:** an empty object.
+* `conditions` {Array}
+* Returns: {Promise} fulfills with an object with the following properties:
+  * `url` {string} The absolute URL for that module
+  * `format` {string} The format this module will be parsed as.
+  * `source` {null|TypedArray}
+
+This API tells you how the passed URL would be loaded by the module loader if
+it was imported in the current process – or, if `conditions` is provided, how
+would it be loaded in a process with such configuration.
+
+### `module.resolveLoadAndCache(specifier, parentURL[, importAttributes[, conditions]]])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `specifier` {string|URL} Module to resolve and load; this should be
+  the same string that would be passed to `import()`, except that if it is
+  relative, it is resolved relative to `parentURL`.
+* `parentURL` {string|URL|undefined} The base URL to resolve `specifier` from,
+  such as `import.meta.url`.
+* `importAttributes` {Object} **Default:** an empty object.
+* `conditions` {Array}
+* Returns: {Promise} fulfills with an object with the following properties:
+  * `url` {string} The absolute URL for that module
+  * `format` {string} The format this module will be parsed as.
+  * `source` {null|TypedArray}
+
+This API tells you how the passed specifier would be loaded by the module loader if
+it was imported from the `parentURL` in the current process – or, if
+`conditions` is provided, how would it be loaded in a process with such
+configuration.
+
 ### `module.registerHooks(options)`
 
 <!-- YAML

lib/internal/modules/helpers.js

@@ -26,7 +26,7 @@
 const assert = require('internal/assert');
 
 const { getOptionValue } = require('internal/options');
-const { setOwnProperty, getLazy } = require('internal/util');
+const { setOwnProperty, getLazy, kEmptyObject } = require('internal/util');
 const { inspect } = require('internal/util/inspect');
 
 const lazyTmpdir = getLazy(() => require('os').tmpdir());
@@ -391,6 +391,41 @@
 const constants = { __proto__: null, compileCacheStatus };
 ObjectFreeze(constants);
 
+async function resolve(specifier, base, importAttributes = kEmptyObject) {
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+  const { url, format: resolveFormat } = await cascadedLoader.resolve(`${specifier}`, `${base}`, importAttributes);
+  return url;
+}
+async function load(url, importAttributes = kEmptyObject, conditions) {
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+  const { format, source } = await cascadedLoader.load(url, {
+    __proto__: null,
+    importAttributes,
+    conditions,
+  });
+  return {
+    __proto__: null,
+    format,
+    source,
+  };
+}
+async function resolveAndLoad(specifier, base = undefined, importAttributes = kEmptyObject, conditions) {
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+  const { url, format: resolveFormat } = await cascadedLoader.resolve(`${specifier}`, `${base}`, importAttributes);
+  const { format, source } = await cascadedLoader.load(url, {
+    __proto__: null,
+    importAttributes,
+    format: resolveFormat,
+    conditions,
+  });
+  return {
+    __proto__: null,
+    format,
+    source,
+    url,
+  };
+}
+
 /**
  * Get the compile cache directory if on-disk compile cache is enabled.
  * @returns {string|undefined} Path to the module compile cache directory if it is enabled,
@@ -413,6 +448,9 @@
   loadBuiltinModule,
   makeRequireFunction,
   normalizeReferrerURL,
+  resolve,
+  load,
+  resolveAndLoad,
   stringify,
   stripBOM,
   toRealPath,

lib/module.js

@@ -15,18 +15,26 @@
   enableCompileCache,
   flushCompileCache,
   getCompileCacheDir,
+  resolve,
+  load,
+  resolveAndLoad,
 } = require('internal/modules/helpers');
 const {
   findPackageJSON,
 } = require('internal/modules/package_json_reader');
 const { stripTypeScriptTypes } = require('internal/modules/typescript');
 
-Module.register = register;
 Module.constants = constants;
 Module.enableCompileCache = enableCompileCache;
 Module.findPackageJSON = findPackageJSON;
+Module.findSourceMap = findSourceMap;
 Module.flushCompileCache = flushCompileCache;
 Module.getCompileCacheDir = getCompileCacheDir;
+Module.register = register;
+Module.resolve= resolve;
+Module.load = load;
+Module.resolveAndLoad= resolveAndLoad;
+Module.SourceMap = SourceMap;
 Module.stripTypeScriptTypes = stripTypeScriptTypes;
 
 // SourceMap APIs

test/fixtures/typescript/legacy-module/README.md

@@ -0,0 +1,5 @@
+# Legacy TypeScript Module
+
+When `tsconfig.json` is set to `module: "node16"` or any `node*`, the TypeScript compiler will
+produce the output in the format by the extension (e.g. `.cts` or `.mts`), or set by the
+`package.json#type` field, regardless of the syntax of the original source code.

test/fixtures/typescript/legacy-module/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

test/fixtures/typescript/legacy-module/test-module-export.cts

@@ -0,0 +1 @@
+export const foo: string = 'Hello, TypeScript!';

test/fixtures/typescript/legacy-module/test-module-export.mts

@@ -0,0 +1 @@
+export const foo: string = 'Hello, TypeScript!';

test/fixtures/typescript/legacy-module/test-module-export.ts

@@ -0,0 +1 @@
+export const foo: string = 'Hello, TypeScript!';

test/parallel/test-module-loadmodule-no-typescript.js

@@ -0,0 +1,24 @@
+// Flags: --no-experimental-strip-types
+
+'use strict';
+
+require('../common');
+const test = require('node:test');
+const assert = require('node:assert');
+const { pathToFileURL } = require('node:url');
+const fixtures = require('../common/fixtures');
+const { resolveLoadAndCache } = require('node:module');
+
+const parentURL = pathToFileURL(__filename);
+
+test('should reject a TypeScript module', async () => {
+  const fileUrl = fixtures.fileURL('typescript/legacy-module/test-module-export.ts');
+  await assert.rejects(
+    async () => {
+      await resolveLoadAndCache(fileUrl, parentURL);
+    },
+    {
+      code: 'ERR_UNKNOWN_FILE_EXTENSION',
+    }
+  );
+});

test/parallel/test-module-loadmodule-typescript.js

@@ -0,0 +1,49 @@
+// Flags: --experimental-strip-types
+
+'use strict';
+
+require('../common');
+const test = require('node:test');
+const assert = require('node:assert');
+const { pathToFileURL } = require('node:url');
+const fixtures = require('../common/fixtures');
+const { resolveLoadAndCache } = require('node:module');
+
+const parentURL = pathToFileURL(__filename);
+
+test('should load a TypeScript module source by package.json type', async () => {
+  // Even if the .ts file contains module syntax, it should be loaded as a CommonJS module
+  // because the package.json type is set to "commonjs".
+
+  const fileUrl = fixtures.fileURL('typescript/legacy-module/test-module-export.ts');
+  const { url, format, source } = await resolveLoadAndCache(fileUrl, parentURL);
+  assert.strictEqual(format, 'commonjs-typescript');
+  assert.strictEqual(url, fileUrl.href);
+
+  // Built-in TypeScript loader loads the source.
+  assert.ok(Buffer.isBuffer(source));
+});
+
+test('should load a TypeScript cts module source by extension', async () => {
+  // By extension, .cts files should be loaded as CommonJS modules.
+
+  const fileUrl = fixtures.fileURL('typescript/legacy-module/test-module-export.cts');
+  const { url, format, source } = await resolveLoadAndCache(fileUrl, parentURL);
+  assert.strictEqual(format, 'commonjs-typescript');
+  assert.strictEqual(url, fileUrl.href);
+
+  // Built-in TypeScript loader loads the source.
+  assert.ok(Buffer.isBuffer(source));
+});
+
+test('should load a TypeScript mts module source by extension', async () => {
+  // By extension, .mts files should be loaded as ES modules.
+
+  const fileUrl = fixtures.fileURL('typescript/legacy-module/test-module-export.mts');
+  const { url, format, source } = await resolveLoadAndCache(fileUrl, parentURL);
+  assert.strictEqual(format, 'module-typescript');
+  assert.strictEqual(url, fileUrl.href);
+
+  // Built-in TypeScript loader loads the source.
+  assert.ok(Buffer.isBuffer(source));
+});

test/parallel/test-module-loadmodule.js

@@ -0,0 +1,31 @@
+'use strict';
+
+require('../common');
+const test = require('node:test');
+const assert = require('node:assert');
+const { pathToFileURL } = require('node:url');
+const fixtures = require('../common/fixtures');
+const { resolveLoadAndCache } = require('node:module');
+
+const parentURL = pathToFileURL(__filename);
+
+test('should throw if the module is not found', async () => {
+  await assert.rejects(
+    async () => {
+      await resolveLoadAndCache('nonexistent-module', parentURL);
+    },
+    {
+      code: 'ERR_MODULE_NOT_FOUND',
+    }
+  );
+});
+
+test('should load a module', async () => {
+  const fileUrl = fixtures.fileURL('es-modules/cjs.js');
+  const { url, format, source } = await resolveLoadAndCache(fileUrl, parentURL);
+  assert.strictEqual(format, 'commonjs');
+  assert.strictEqual(url, fileUrl.href);
+
+  // `source` is null and the final builtin loader will read the file.
+  assert.strictEqual(source, null);
+});