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/esm.ts

@@ -11,6 +11,7 @@ import {
   UrlWithStringQuery,
   fileURLToPath,
   pathToFileURL,
+  URL,
 } from 'url';
 import { extname } from 'path';
 import * as assert from 'assert';
@@ -159,12 +160,49 @@ export function createEsmHooks(tsNodeService: Service) {
       return defer();
     }
 
-    // pathname is the path to be resolved
+    let candidateSpecifiers: string[] = [specifier];
+
+    if (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()
+          );
+        }
+      }
+    }
+
+    for (let i = 0; i < candidateSpecifiers.length; i++) {
+      try {
+        return await nodeResolveImplementation.defaultResolve(
+          candidateSpecifiers[i],
+          context,
+          defaultResolve
+        );
+      } catch (err) {
+        const isNotFoundError = (err as any).code === 'ERR_MODULE_NOT_FOUND';
+        if (!isNotFoundError) {
+          throw err;
+        } else if (i == candidateSpecifiers.length - 1) {
+          throw new MappedModuleNotFound(
+            specifier,
+            context.parentURL,
+            candidateSpecifiers
+          );
+        } else {
+          continue;
+        }
+      }
+    }
 
-    return nodeResolveImplementation.defaultResolve(
-      specifier,
-      context,
-      defaultResolve
+    // This code should be unreachable: The for-loop always returns or
+    // throws.
+    throw new Error(
+      `Unreachable code mapping ${specifier} in ${context.parentURL}`
     );
   }
 
@@ -302,3 +340,19 @@ export function createEsmHooks(tsNodeService: Service) {
     return { source: emittedJs };
   }
 }
+
+class MappedModuleNotFound extends Error {
+  // Same code as other module not found errors.
+  static code = 'ERR_MODULE_NOT_FOUND';
+
+  constructor(specifier: string, base: string, candidates: string[]) {
+    super(
+      [
+        `Cannot find '${specifier}' imported from ${base} using TypeScript path mapping`,
+        'Candidates attempted:',
+        ...candidates.map((candidate) => `- ${candidate}`),
+      ].join('\n')
+    );
+    this.name = `Error [${MappedModuleNotFound.code}]`;
+  }
+}

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';
 
 export { TSCommon };
 export {
@@ -482,6 +483,14 @@ 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;
 }
 
 /**
@@ -1318,6 +1327,8 @@ export function create(rawOptions: CreateOptions = {}): Service {
     });
   }
 
+  const mapPath = createPathMapper(config.options);
+
   return {
     [TS_NODE_SERVICE_BRAND]: true,
     ts,
@@ -1334,6 +1345,7 @@ export function create(rawOptions: CreateOptions = {}): Service {
     installSourceMapSupport,
     enableExperimentalEsmLoaderInterop,
     transpileOnly,
+    mapPath,
   };
 }
 

src/path-mapping.ts

@@ -0,0 +1,131 @@
+import type * as ts from 'typescript';
+import { join as joinPath } from 'path';
+
+// Path mapper returns a list of mapped specifiers or `null` if the
+// given `specifier` was not mapped.
+type PathMapper = (specifier: string) => string[] | null;
+
+export function createPathMapper(
+  compilerOptions: ts.CompilerOptions
+): PathMapper {
+  if (compilerOptions.paths) {
+    if (!compilerOptions.baseUrl) {
+      throw new Error(`Compiler option 'baseUrl' required when 'paths' is set`);
+    }
+
+    const mappings = Object.entries(compilerOptions.paths).map(
+      ([patternString, outputs]) => ({
+        pattern: parsePattern(patternString),
+        outputs,
+      })
+    );
+    const mappingConfig = { mappings, baseUrl: compilerOptions.baseUrl };
+
+    return function map(specifier: string): string[] | null {
+      return mapPath(mappingConfig, specifier);
+    };
+  } else {
+    return () => null;
+  }
+}
+
+interface MappingConfig {
+  mappings: Mapping[];
+  baseUrl: string;
+}
+
+interface Mapping {
+  pattern: Pattern;
+  outputs: string[];
+}
+
+type Pattern =
+  | {
+      type: 'wildcard';
+      prefix: string;
+      suffix: string;
+    }
+  | { type: 'static'; value: string };
+
+function mapPath(mappingConfig: MappingConfig, path: string): string[] | null {
+  let bestMatchWeight = -Infinity;
+  let bestMatch: [Mapping, string] | null = null;
+
+  for (const mapping of mappingConfig.mappings) {
+    if (patternWeight(mapping.pattern) > bestMatchWeight) {
+      const match = matchPattern(mapping.pattern, path);
+      if (match !== null) {
+        bestMatch = [mapping, match];
+        bestMatchWeight = patternWeight(mapping.pattern);
+      }
+    }
+  }
+
+  if (bestMatch) {
+    const [mapping, match] = bestMatch;
+    return mapping.outputs.map((output) =>
+      joinPath(mappingConfig.baseUrl, output.replace('*', match))
+    );
+  } else {
+    return null;
+  }
+}
+
+// Return the submatch when the pattern matches.
+//
+// For the wildcard pattern string `a*z` and candidate `afooz` this
+// returns `foo`. For the static pattern `bar` and the candidate `bar`
+// this returns `bar`.
+function matchPattern(pattern: Pattern, candidate: string): string | null {
+  switch (pattern.type) {
+    case 'wildcard':
+      if (
+        candidate.length >= pattern.prefix.length + pattern.suffix.length &&
+        candidate.startsWith(pattern.prefix) &&
+        candidate.endsWith(pattern.suffix)
+      ) {
+        return candidate.substring(
+          pattern.prefix.length,
+          candidate.length - pattern.suffix.length
+        );
+      } else {
+        return null;
+      }
+    case 'static':
+      if (pattern.value === candidate) {
+        return candidate;
+      } else {
+        return null;
+      }
+  }
+}
+
+// Pattern weight to sort best matches.
+//
+// Static patterns have the highest weight. For wildcard patterns the
+// weight is determined by the length of the prefix before the glob
+// `*`.
+function patternWeight(pattern: Pattern): number {
+  if (pattern.type === 'wildcard') {
+    return pattern.prefix.length;
+  } else {
+    return Infinity;
+  }
+}
+
+function parsePattern(patternString: string): Pattern {
+  const indexOfStar = patternString.indexOf('*');
+  if (indexOfStar === -1) {
+    return { type: 'static', value: patternString };
+  }
+
+  if (patternString.indexOf('*', indexOfStar + 1) !== -1) {
+    throw new Error(`Path pattern ${patternString} contains two wildcards '*'`);
+  }
+
+  return {
+    type: 'wildcard',
+    prefix: patternString.substring(0, indexOfStar),
+    suffix: patternString.substring(indexOfStar + 1),
+  };
+}

src/test/index.spec.ts

@@ -1224,6 +1224,32 @@ test.suite('ts-node', (test) => {
         if (semver.gte(process.version, '14.13.1'))
           await runModuleTypeTest('override-to-esm', 'mjs');
       });
+
+      test('path mapping', async () => {
+        const { err } = await exec(
+          `${CMD_ESM_LOADER_WITHOUT_PROJECT} index.ts`,
+          {
+            cwd: join(TEST_DIR, './esm-path-mapping'),
+          }
+        );
+        expect(err).toBe(null);
+      });
+
+      test('path mapping error candidates', async () => {
+        const { stderr, err } = await exec(
+          `${CMD_ESM_LOADER_WITHOUT_PROJECT} mapped-not-found.ts`,
+          {
+            cwd: join(TEST_DIR, './esm-path-mapping'),
+          }
+        );
+        expect(err).toBeTruthy();
+        expect(stderr).toMatch(
+          "[ERR_MODULE_NOT_FOUND]: Cannot find 'map2/does-not-exist.ts'"
+        );
+        // Expect tried candidates to be listed
+        expect(stderr).toMatch(/- file:\/\/.*mapped\/2-does-not-exist.ts/);
+        expect(stderr).toMatch(/- file:\/\/.*mapped\/2a-does-not-exist.ts/);
+      });
     }
 
     if (semver.gte(process.version, '12.0.0')) {

tests/esm-path-mapping/index-js.js

@@ -0,0 +1,4 @@
+import * as assert from 'assert';
+
+import map1foo from 'map1/foo.js';
+assert.equal(map1foo, 'mapped/1-foo');

tests/esm-path-mapping/index-tsx.tsx

@@ -0,0 +1,4 @@
+import * as assert from 'assert';
+
+import map1foo from 'map1/foo.js';
+assert.equal(map1foo, 'mapped/1-foo');

tests/esm-path-mapping/index.ts

@@ -0,0 +1,36 @@
+import * as assert from 'assert';
+
+// Path is mapped
+import map1foo from 'map1/foo.js';
+
+// Path is mapped using `.jsx` extension
+import map1jsx from 'map1/jsx.js';
+
+// Path is mapped using the first candidate `mapped/2-foo` and not `mapped/2a-foo`
+import map2foo from 'map2/foo.js';
+
+// Path is mapped using the second candidate because the first `mapped/2-bar.ts`
+// does not exist
+import map2bar from 'map2/bar.js';
+
+// Path is mapped using `.js` extension
+import map2js from 'map2/js.js';
+
+// Path is mapped using the more specific pattern instead of
+// `mapped/2-specific/foo
+import map2specific from 'map2/specific/foo.js';
+
+// Path is mapped when using no wildcard
+import mapStatic from 'static';
+
+// Test path mapping in `.tsx` and `.js` files.
+import './index-tsx.tsx';
+import './index-js.js';
+
+assert.equal(map1foo, 'mapped/1-foo');
+assert.equal(map1jsx, 'mapped/1-jsx');
+assert.equal(map2foo, 'mapped/2-foo');
+assert.equal(map2bar, 'mapped/2a-bar');
+assert.equal(map2js, 'mapped/2a-js');
+assert.equal(map2specific, 'mapped/2-specific-foo');
+assert.equal(mapStatic, 'mapped/static');

tests/esm-path-mapping/mapped-not-found.ts

@@ -0,0 +1 @@
+import 'map2/does-not-exist.ts';

tests/esm-path-mapping/mapped/1-foo.ts

@@ -0,0 +1 @@
+export default 'mapped/1-foo';

tests/esm-path-mapping/mapped/1-jsx.jsx

@@ -0,0 +1,6 @@
+export default 'mapped/1-jsx';
+
+const React = {
+  createElement() {},
+};
+const div = <div></div>;