Path mapping part 2

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, request];
+      }
+    }
+    // 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

@@ -382,6 +382,7 @@ function filterRecognizedTsConfigTsNodeOptions(jsonObject: any): {
     moduleTypes,
     experimentalReplAwait,
     swc,
+    experimentalPathMapping,
     experimentalResolverFeatures,
     esm,
     ...unrecognized
@@ -407,6 +408,7 @@ function filterRecognizedTsConfigTsNodeOptions(jsonObject: any): {
     scopeDir,
     moduleTypes,
     swc,
+    experimentalPathMapping,
     experimentalResolverFeatures,
     esm,
   };

src/esm.ts

@@ -11,6 +11,7 @@ import {
   UrlWithStringQuery,
   fileURLToPath,
   pathToFileURL,
+  URL,
 } from 'url';
 import { extname } from 'path';
 import * as assert from 'assert';
@@ -222,15 +223,55 @@ export function createEsmHooks(tsNodeService: Service) {
       return entrypointFallback(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()),
+            specifier,
+          ];
+        }
+      }
+    }
 
-    return entrypointFallback(() =>
-      nodeResolveImplementation.defaultResolve(
-        specifier,
-        context,
-        defaultResolve
-      )
-    );
+    return entrypointFallback(async () => {
+      // 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)
@@ -384,3 +425,32 @@ export function createEsmHooks(tsNodeService: Service) {
 
   return hooksAPI;
 }
+
+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,
@@ -368,6 +369,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';
   /**
    * Enable native ESM support.
    *
@@ -519,6 +531,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;
   /** @internal */
   projectLocalResolveHelper: ProjectLocalResolveHelper;
 }
@@ -771,6 +795,21 @@ export function createFromPreloadedConfig(
     };
   }
 
+  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.
@@ -1375,6 +1414,8 @@ export function createFromPreloadedConfig(
     });
   }
 
+  const mapPath = createPathMapper(config.options);
+
   return {
     [TS_NODE_SERVICE_BRAND]: true,
     ts,
@@ -1392,6 +1433,9 @@ export function createFromPreloadedConfig(
     installSourceMapSupport,
     enableExperimentalEsmLoaderInterop,
     transpileOnly,
+    mapPath,
+    commonjsPathMapping,
+    esmPathMapping,
     projectLocalResolveHelper,
   };
 }