Add path mapping support to ESM and CJS loaders

dist-raw/node-errors.js

@@ -1,30 +1,29 @@
-exports.codes = {
-  ERR_INPUT_TYPE_NOT_ALLOWED: createErrorCtor(joinArgs('ERR_INPUT_TYPE_NOT_ALLOWED')),
-  ERR_INVALID_ARG_VALUE: createErrorCtor(joinArgs('ERR_INVALID_ARG_VALUE')),
-  ERR_INVALID_MODULE_SPECIFIER: createErrorCtor(joinArgs('ERR_INVALID_MODULE_SPECIFIER')),
-  ERR_INVALID_PACKAGE_CONFIG: createErrorCtor(joinArgs('ERR_INVALID_PACKAGE_CONFIG')),
-  ERR_INVALID_PACKAGE_TARGET: createErrorCtor(joinArgs('ERR_INVALID_PACKAGE_TARGET')),
-  ERR_MANIFEST_DEPENDENCY_MISSING: createErrorCtor(joinArgs('ERR_MANIFEST_DEPENDENCY_MISSING')),
-  ERR_MODULE_NOT_FOUND: createErrorCtor((path, base, type = 'package') => {
-    return `Cannot find ${type} '${path}' imported from ${base}`
-  }),
-  ERR_PACKAGE_IMPORT_NOT_DEFINED: createErrorCtor(joinArgs('ERR_PACKAGE_IMPORT_NOT_DEFINED')),
-  ERR_PACKAGE_PATH_NOT_EXPORTED: createErrorCtor(joinArgs('ERR_PACKAGE_PATH_NOT_EXPORTED')),
-  ERR_UNSUPPORTED_DIR_IMPORT: createErrorCtor(joinArgs('ERR_UNSUPPORTED_DIR_IMPORT')),
-  ERR_UNSUPPORTED_ESM_URL_SCHEME: createErrorCtor(joinArgs('ERR_UNSUPPORTED_ESM_URL_SCHEME')),
-  ERR_UNKNOWN_FILE_EXTENSION: createErrorCtor(joinArgs('ERR_UNKNOWN_FILE_EXTENSION')),
-}
+exports.codes = {}
 
-function joinArgs(name) {
-  return (...args) => {
-    return [name, ...args].join(' ')
+function defineError(code, buildMessage) {
+  if (!buildMessage) {
+    buildMessage = (...args) => args.join(' ')
   }
-}
 
-function createErrorCtor(errorMessageCreator) {
-  return class CustomError extends Error {
+  exports.codes[code] = class CustomError extends Error {
     constructor(...args) {
-      super(errorMessageCreator(...args))
+      super(`${code}: ${buildMessage(...args)}`)
+      this.code = code
     }
   }
 }
+
+defineError("ERR_INPUT_TYPE_NOT_ALLOWED")
+defineError("ERR_INVALID_ARG_VALUE")
+defineError("ERR_INVALID_MODULE_SPECIFIER")
+defineError("ERR_INVALID_PACKAGE_CONFIG")
+defineError("ERR_INVALID_PACKAGE_TARGET")
+defineError("ERR_MANIFEST_DEPENDENCY_MISSING")
+defineError("ERR_MODULE_NOT_FOUND", (path, base, type = 'package') => {
+  return `Cannot find ${type} '${path}' imported from ${base}`
+})
+defineError("ERR_PACKAGE_IMPORT_NOT_DEFINED")
+defineError("ERR_PACKAGE_PATH_NOT_EXPORTED")
+defineError("ERR_UNSUPPORTED_DIR_IMPORT")
+defineError("ERR_UNSUPPORTED_ESM_URL_SCHEME")
+defineError("ERR_UNKNOWN_FILE_EXTENSION")

src/cjs-resolve-filename-hook.ts

@@ -45,6 +45,54 @@ export function installCommonjsResolveHookIfNecessary(tsNodeService: Service) {
         ...rest
       );
 
+    // #region path-mapping
+    // Note: [SYNC-PATH-MAPPING] keep this logic synced with the corresponding ESM implementation.
+    let candidateSpecifiers: string[] = [request];
+    const attemptPathMapping =
+      tsNodeService.commonjsPathMapping &&
+      parent?.filename &&
+      !tsNodeService.ignored(parent.filename);
+    if (attemptPathMapping) {
+      const mappedSpecifiers = tsNodeService.mapPath(request);
+      if (mappedSpecifiers) {
+        candidateSpecifiers = mappedSpecifiers;
+      }
+    }
+    // Attempt all resolutions.  Collect resolution failures and throw an
+    // aggregated error if they all fail.
+    const moduleNotFoundErrors = [];
+    for (let i = 0; i < candidateSpecifiers.length; i++) {
+      try {
+        // TODO does this break if `options.paths` is passed?  Should we bail if
+        // we receive `options.paths`?
+        return originalResolveFilename.call(
+          this,
+          candidateSpecifiers[i],
+          parent,
+          isMain,
+          options
+        );
+      } catch (err: any) {
+        const isNotFoundError = err.code === 'MODULE_NOT_FOUND';
+        if (!isNotFoundError) {
+          throw err;
+        }
+        moduleNotFoundErrors.push(err);
+      }
+    }
+    // If only one candidate, no need to wrap it.
+    if (candidateSpecifiers.length === 1) {
+      throw moduleNotFoundErrors[0];
+    } else {
+      throw new MappedCommonJSModuleNotFoundError(
+        request,
+        parent!.filename,
+        candidateSpecifiers,
+        moduleNotFoundErrors
+      );
+    }
+    // #endregion
+
     // This is a stub to support other pull requests that will be merged in the near future
     // Right now, it does nothing.
     return originalResolveFilename.call(
@@ -57,3 +105,42 @@ export function installCommonjsResolveHookIfNecessary(tsNodeService: Service) {
     );
   }
 }
+
+interface NodeCommonJSModuleNotFoundError extends Error {
+  requireStack?: string[];
+}
+
+class MappedCommonJSModuleNotFoundError extends Error {
+  // Same code as other module not found errors.
+  readonly code = 'MODULE_NOT_FOUND' as const;
+  readonly errors!: ReadonlyArray<Error>;
+  readonly requireStack?: string[];
+
+  constructor(
+    specifier: string,
+    parentFilename: string,
+    candidates: string[],
+    moduleNotFoundErrors: Error[]
+  ) {
+    super(
+      [
+        `Cannot find '${specifier}' imported from ${parentFilename} using TypeScript path mapping`,
+        'Candidates attempted:',
+        ...candidates.map((candidate) => `- ${candidate}`),
+      ].join('\n')
+    );
+    // TODO this differs slightly from nodejs errors; see if we can match them
+    this.name = `Error [${this.code}]`;
+    // Match shape of `AggregateError`
+    Object.defineProperty(this, 'errors', {
+      value: moduleNotFoundErrors,
+      configurable: true,
+      writable: true,
+    });
+    // Assume every `requireStack` is identical, and maybe downstream code is doing
+    // something with it
+    this.requireStack = (
+      moduleNotFoundErrors[0] as NodeCommonJSModuleNotFoundError | undefined
+    )?.requireStack;
+  }
+}

src/configuration.ts

@@ -277,6 +277,7 @@ function filterRecognizedTsConfigTsNodeOptions(jsonObject: any): {
     moduleTypes,
     experimentalReplAwait,
     swc,
+    experimentalPathMapping,
     experimentalResolverFeatures,
     ...unrecognized
   } = jsonObject as TsConfigOptions;
@@ -301,6 +302,7 @@ function filterRecognizedTsConfigTsNodeOptions(jsonObject: any): {
     scopeDir,
     moduleTypes,
     swc,
+    experimentalPathMapping,
     experimentalResolverFeatures,
   };
   // Use the typechecker to make sure this implementation has the correct set of properties

src/esm.ts

@@ -11,6 +11,7 @@ import {
   UrlWithStringQuery,
   fileURLToPath,
   pathToFileURL,
+  URL,
 } from 'url';
 import { extname } from 'path';
 import * as assert from 'assert';
@@ -159,13 +160,52 @@ export function createEsmHooks(tsNodeService: Service) {
       return defer();
     }
 
-    // pathname is the path to be resolved
+    // Note: [SYNC-PATH-MAPPING] keep this logic synced with the corresponding CJS implementation.
+    let candidateSpecifiers: string[] = [specifier];
+
+    if (tsNodeService.esmPathMapping && context.parentURL) {
+      const parentUrl = new URL(context.parentURL);
+      const parentPath =
+        parentUrl.protocol === 'file:' && fileURLToPath(parentUrl);
+      if (parentPath && !tsNodeService.ignored(parentPath)) {
+        const mappedSpecifiers = tsNodeService.mapPath(specifier);
+        if (mappedSpecifiers) {
+          candidateSpecifiers = mappedSpecifiers.map((path) =>
+            pathToFileURL(path).toString()
+          );
+        }
+      }
+    }
 
-    return nodeResolveImplementation.defaultResolve(
-      specifier,
-      context,
-      defaultResolve
-    );
+    // Attempt all resolutions.  Collect resolution failures and throw an
+    // aggregated error if they all fail.
+    const moduleNotFoundErrors = [];
+    for (let i = 0; i < candidateSpecifiers.length; i++) {
+      try {
+        return await nodeResolveImplementation.defaultResolve(
+          candidateSpecifiers[i],
+          context,
+          defaultResolve
+        );
+      } catch (err: any) {
+        const isNotFoundError = err.code === 'ERR_MODULE_NOT_FOUND';
+        if (!isNotFoundError) {
+          throw err;
+        }
+        moduleNotFoundErrors.push(err);
+      }
+    }
+    // If only one candidate, no need to wrap it.
+    if (candidateSpecifiers.length === 1) {
+      throw moduleNotFoundErrors[0];
+    } else {
+      throw new MappedModuleNotFoundError(
+        specifier,
+        context.parentURL,
+        candidateSpecifiers,
+        moduleNotFoundErrors
+      );
+    }
   }
 
   // `load` from new loader hook API (See description at the top of this file)
@@ -302,3 +342,32 @@ export function createEsmHooks(tsNodeService: Service) {
     return { source: emittedJs };
   }
 }
+
+class MappedModuleNotFoundError extends Error {
+  // Same code as other module not found errors.
+  readonly code = 'ERR_MODULE_NOT_FOUND' as const;
+  readonly errors!: ReadonlyArray<Error>;
+
+  constructor(
+    specifier: string,
+    base: string,
+    candidates: string[],
+    moduleNotFoundErrors: Error[]
+  ) {
+    super(
+      [
+        `Cannot find '${specifier}' imported from ${base} using TypeScript path mapping`,
+        'Candidates attempted:',
+        ...candidates.map((candidate) => `- ${candidate}`),
+      ].join('\n')
+    );
+    // TODO this differs slightly from nodejs errors; see if we can match them
+    this.name = `Error [${this.code}]`;
+    // Match shape of `AggregateError`
+    Object.defineProperty(this, 'errors', {
+      value: moduleNotFoundErrors,
+      configurable: true,
+      writable: true,
+    });
+  }
+}

src/index.ts

@@ -25,6 +25,7 @@ import {
 } from './module-type-classifier';
 import { createResolverFunctions } from './resolver-functions';
 import type { createEsmHooks as createEsmHooksFn } from './esm';
+import { createPathMapper } from './path-mapping';
 import {
   installCommonjsResolveHookIfNecessary,
   ModuleConstructorWithInternals,
@@ -364,6 +365,17 @@ export interface CreateOptions {
    * @default console.log
    */
   tsTrace?: (str: string) => void;
+  /**
+   * Enable TypeScript path mapping in the ESM loader, CommonJS loader, or both.
+   * Today, the default is 'esm' to map paths in the experimental ESM loader but not
+   * CommonJS.  In the next major release, the default will become 'both'.
+   *
+   * Note: If you use tsconfig-paths, be sure to disable it before enabling ts-node's CommonJS path mapper.
+   * tsconfig-paths already maps paths in CommonJS but not ESM, and it may conflict with ts-node's mapper.
+   *
+   * See: https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping
+   */
+  experimentalPathMapping?: 'both' | 'esm' | 'cjs' | 'none';
 }
 
 /** @internal */
@@ -495,6 +507,18 @@ export interface Service {
   enableExperimentalEsmLoaderInterop(): void;
   /** @internal */
   transpileOnly: boolean;
+  /**
+   * @internal
+   *
+   * Map import paths to candidates according to the `paths` compiler
+   * option. Returns `null` if the specifier did not match and was not
+   * mapped.
+   */
+  mapPath(specifier: string): string[] | null;
+  /** @internal */
+  commonjsPathMapping: boolean;
+  /** @internal */
+  esmPathMapping: boolean;
 }
 
 /**
@@ -741,6 +765,21 @@ export function create(rawOptions: CreateOptions = {}): Service {
     });
   }
 
+  if (
+    ![undefined, null, 'both', 'esm', 'cjs', 'none'].includes(
+      options.experimentalPathMapping
+    )
+  ) {
+    throw new Error(
+      `experimentalPathMapping must be one of: "both", "esm", "cjs", "none"`
+    );
+  }
+  const experimentalPathMapping = options.experimentalPathMapping ?? 'esm';
+  const commonjsPathMapping =
+    experimentalPathMapping === 'both' || experimentalPathMapping === 'cjs';
+  const esmPathMapping =
+    experimentalPathMapping === 'both' || experimentalPathMapping === 'esm';
+
   /**
    * True if require() hooks should interop with experimental ESM loader.
    * Enabled explicitly via a flag since it is a breaking change.
@@ -1335,6 +1374,8 @@ export function create(rawOptions: CreateOptions = {}): Service {
     });
   }
 
+  const mapPath = createPathMapper(config.options);
+
   return {
     [TS_NODE_SERVICE_BRAND]: true,
     ts,
@@ -1351,6 +1392,9 @@ export function create(rawOptions: CreateOptions = {}): Service {
     installSourceMapSupport,
     enableExperimentalEsmLoaderInterop,
     transpileOnly,
+    mapPath,
+    commonjsPathMapping,
+    esmPathMapping,
   };
 }