ts-node - npm Package Compare versions

Comparing version 10.7.0 to 10.9.1

dist-raw/node-primordials.js

@@ -23,2 +23,3 @@ module.exports = {
   SafeSet: Set,
+  SafeWeakMap: WeakMap,
   StringPrototypeEndsWith: (str, ...rest) => String.prototype.endsWith.apply(str, rest),
@@ -34,3 +35,5 @@ StringPrototypeIncludes: (str, ...rest) => String.prototype.includes.apply(str, rest),
   StringPrototypeSubstr: (str, ...rest) => String.prototype.substr.apply(str, rest),
+  StringPrototypeCharCodeAt: (str, ...rest) => String.prototype.charCodeAt.apply(str, rest),
+  StringPrototypeMatch: (str, ...rest) => String.prototype.match.apply(str, rest),
   SyntaxError: SyntaxError
 };

dist-raw/README.md

@@ -14,1 +14,24 @@ The `dist-raw` directory contains JS sources that are distributed verbatim, not compiled nor typechecked via TS.
 Users running node 12 may see that ts-node behaves like node 14, for example.
+
+## `raw` directory
+
+Within the `raw` directory, we keep unmodified copies of the node source files.  This allows us to use diffing tools to
+compare files in `raw` to those in `dist-raw`, which will highlight all of the changes we have made.  Hopefully, these
+changes are as minimal as possible.
+
+## Naming convention
+
+Not used consistently, but the idea is:
+
+`node-<directory>(...-<directory>)-<filename>.js`
+
+`node-internal-errors.js` -> `github.com/nodejs/node/blob/TAG/lib/internal/errors.js`
+
+So, take the path within node's `lib/` directory, and replace slashes with hyphens.
+
+In the `raw` directory, files are suffixed with the version number or revision from which
+they were downloaded.
+
+If they have a `stripped` suffix, this means they have large chunks of code deleted, but no other modifications.
+This is useful when diffing.  Sometimes our `dist-raw` files only have a small part of a much larger node source file.
+It is easier to diff `raw/*-stripped.js` against `dist-raw/*.js`.

dist/bin.js

@@ -12,3 +12,3 @@ #!/usr/bin/env node
 const index_1 = require("./index");
-const node_cjs_helpers_1 = require("../dist-raw/node-cjs-helpers");
+const node_internal_modules_cjs_helpers_1 = require("../dist-raw/node-internal-modules-cjs-helpers");
 const spawn_child_1 = require("./child/spawn-child");
@@ -30,3 +30,4 @@ const configuration_1 = require("./configuration");
         isInChildProcess: false,
-        entrypoint: __filename,
+        isCli: true,
+        tsNodeScript: __filename,
         parseArgvResult: args,
@@ -42,2 +43,4 @@ };
         if (state.shouldUseChildProcess && !state.isInChildProcess) {
+            // Note: When transitioning into the child-process after `phase2`,
+            // the updated working directory needs to be preserved.
             return (0, spawn_child_1.callInChild)(state);
@@ -49,2 +52,4 @@ }
         if (state.shouldUseChildProcess && !state.isInChildProcess) {
+            // Note: When transitioning into the child-process after `phase2`,
+            // the updated working directory needs to be preserved.
             return (0, spawn_child_1.callInChild)(state);
@@ -103,2 +108,3 @@ }
             '--noExperimentalReplAwait': Boolean,
+            '--experimentalSpecifierResolution': String,
             // Aliases.
@@ -135,2 +141,3 @@ '-e': '--eval',
             '--no-experimental-repl-await': '--noExperimentalReplAwait',
+            '--experimental-specifier-resolution': '--experimentalSpecifierResolution',
         }, {
@@ -144,3 +151,3 @@ argv,
     // defaults.
-    const { '--cwd': cwdArg, '--help': help = false, '--scriptMode': scriptMode, '--cwdMode': cwdMode, '--version': version = 0, '--showConfig': showConfig, '--require': argsRequire = [], '--eval': code = undefined, '--print': print = false, '--interactive': interactive = false, '--files': files, '--compiler': compiler, '--compilerOptions': compilerOptions, '--project': project, '--ignoreDiagnostics': ignoreDiagnostics, '--ignore': ignore, '--transpileOnly': transpileOnly, '--typeCheck': typeCheck, '--transpiler': transpiler, '--swc': swc, '--compilerHost': compilerHost, '--pretty': pretty, '--skipProject': skipProject, '--skipIgnore': skipIgnore, '--preferTsExts': preferTsExts, '--logError': logError, '--emit': emit, '--scope': scope = undefined, '--scopeDir': scopeDir = undefined, '--noExperimentalReplAwait': noExperimentalReplAwait, '--esm': esm, _: restArgs, } = args;
+    const { '--cwd': cwdArg, '--help': help = false, '--scriptMode': scriptMode, '--cwdMode': cwdMode, '--version': version = 0, '--showConfig': showConfig, '--require': argsRequire = [], '--eval': code = undefined, '--print': print = false, '--interactive': interactive = false, '--files': files, '--compiler': compiler, '--compilerOptions': compilerOptions, '--project': project, '--ignoreDiagnostics': ignoreDiagnostics, '--ignore': ignore, '--transpileOnly': transpileOnly, '--typeCheck': typeCheck, '--transpiler': transpiler, '--swc': swc, '--compilerHost': compilerHost, '--pretty': pretty, '--skipProject': skipProject, '--skipIgnore': skipIgnore, '--preferTsExts': preferTsExts, '--logError': logError, '--emit': emit, '--scope': scope = undefined, '--scopeDir': scopeDir = undefined, '--noExperimentalReplAwait': noExperimentalReplAwait, '--experimentalSpecifierResolution': experimentalSpecifierResolution, '--esm': esm, _: restArgs, } = args;
     return {
@@ -180,2 +187,3 @@ // Note: argv and restArgs may be overwritten by child process
         noExperimentalReplAwait,
+        experimentalSpecifierResolution,
         esm,
@@ -185,3 +193,3 @@ };
 function phase2(payload) {
-    const { help, version, code, interactive, cwdArg, restArgs, esm } = payload.parseArgvResult;
+    const { help, version, cwdArg, esm } = payload.parseArgvResult;
     if (help) {
@@ -226,2 +234,4 @@ console.log(`
   --noExperimentalReplAwait       Disable top-level await in REPL.  Equivalent to node's --no-experimental-repl-await
+  --experimentalSpecifierResolution [node|explicit]
+                                  Equivalent to node's --experimental-specifier-resolution
 `);
@@ -235,27 +245,21 @@ process.exit(0);
     }
-    // Figure out which we are executing: piped stdin, --eval, REPL, and/or entrypoint
-    // This is complicated because node's behavior is complicated
-    // `node -e code -i ./script.js` ignores -e
-    const executeEval = code != null && !(interactive && restArgs.length);
-    const executeEntrypoint = !executeEval && restArgs.length > 0;
-    const executeRepl = !executeEntrypoint &&
-        (interactive || (process.stdin.isTTY && !executeEval));
-    const executeStdin = !executeEval && !executeRepl && !executeEntrypoint;
-    const cwd = cwdArg || process.cwd();
-    /** Unresolved.  May point to a symlink, not realpath.  May be missing file extension */
-    const scriptPath = executeEntrypoint ? (0, path_1.resolve)(cwd, restArgs[0]) : undefined;
+    const cwd = cwdArg ? (0, path_1.resolve)(cwdArg) : process.cwd();
+    // If ESM is explicitly enabled through the flag, stage3 should be run in a child process
+    // with the ESM loaders configured.
     if (esm)
         payload.shouldUseChildProcess = true;
     return {
-        executeEval,
-        executeEntrypoint,
-        executeRepl,
-        executeStdin,
         cwd,
-        scriptPath,
     };
 }
 function phase3(payload) {
-    const { emit, files, pretty, transpileOnly, transpiler, noExperimentalReplAwait, typeCheck, swc, compilerHost, ignore, preferTsExts, logError, scriptMode, cwdMode, project, skipProject, skipIgnore, compiler, ignoreDiagnostics, compilerOptions, argsRequire, scope, scopeDir, } = payload.parseArgvResult;
-    const { cwd, scriptPath } = payload.phase2Result;
+    const { emit, files, pretty, transpileOnly, transpiler, noExperimentalReplAwait, typeCheck, swc, compilerHost, ignore, preferTsExts, logError, scriptMode, cwdMode, project, skipProject, skipIgnore, compiler, ignoreDiagnostics, compilerOptions, argsRequire, scope, scopeDir, esm, experimentalSpecifierResolution, } = payload.parseArgvResult;
+    const { cwd } = payload.phase2Result;
+    // NOTE: When we transition to a child process for ESM, the entry-point script determined
+    // here might not be the one used later in `phase4`. This can happen when we execute the
+    // original entry-point but then the process forks itself using e.g. `child_process.fork`.
+    // We will always use the original TS project in forked processes anyway, so it is
+    // expected and acceptable to retrieve the entry-point information here in `phase2`.
+    // See: https://github.com/TypeStrong/ts-node/issues/1812.
+    const { entryPointPath } = getEntryPointInfo(payload);
     const preloadedConfig = (0, configuration_1.findAndReadConfig)({
@@ -274,3 +278,3 @@ cwd,
         logError,
-        projectSearchDir: getProjectSearchDir(cwd, scriptMode, cwdMode, scriptPath),
+        projectSearchDir: getProjectSearchDir(cwd, scriptMode, cwdMode, entryPointPath),
         project,
@@ -286,3 +290,7 @@ skipProject,
         preferTsExts,
+        esm,
+        experimentalSpecifierResolution: experimentalSpecifierResolution,
     });
+    // If ESM is enabled through the parsed tsconfig, stage4 should be run in a child
+    // process with the ESM loaders configured.
     if (preloadedConfig.options.esm)
@@ -292,8 +300,53 @@ payload.shouldUseChildProcess = true;
 }
+/**
+ * Determines the entry-point information from the argv and phase2 result. This
+ * method will be invoked in two places:
+ *
+ *   1. In phase 3 to be able to find a project from the potential entry-point script.
+ *   2. In phase 4 to determine the actual entry-point script.
+ *
+ * Note that we need to explicitly re-resolve the entry-point information in the final
+ * stage because the previous stage information could be modified when the bootstrap
+ * invocation transitioned into a child process for ESM.
+ *
+ * Stages before (phase 4) can and will be cached by the child process through the Brotli
+ * configuration and entry-point information is only reliable in the final phase. More
+ * details can be found in here: https://github.com/TypeStrong/ts-node/issues/1812.
+ */
+function getEntryPointInfo(state) {
+    const { code, interactive, restArgs } = state.parseArgvResult;
+    const { cwd } = state.phase2Result;
+    const { isCli } = state;
+    // Figure out which we are executing: piped stdin, --eval, REPL, and/or entrypoint
+    // This is complicated because node's behavior is complicated
+    // `node -e code -i ./script.js` ignores -e
+    const executeEval = code != null && !(interactive && restArgs.length);
+    const executeEntrypoint = !executeEval && restArgs.length > 0;
+    const executeRepl = !executeEntrypoint &&
+        (interactive || (process.stdin.isTTY && !executeEval));
+    const executeStdin = !executeEval && !executeRepl && !executeEntrypoint;
+    /**
+     * Unresolved. May point to a symlink, not realpath. May be missing file extension
+     * NOTE: resolution relative to cwd option (not `process.cwd()`) is legacy backwards-compat; should be changed in next major: https://github.com/TypeStrong/ts-node/issues/1834
+     */
+    const entryPointPath = executeEntrypoint
+        ? isCli
+            ? (0, path_1.resolve)(cwd, restArgs[0])
+            : (0, path_1.resolve)(restArgs[0])
+        : undefined;
+    return {
+        executeEval,
+        executeEntrypoint,
+        executeRepl,
+        executeStdin,
+        entryPointPath,
+    };
+}
 function phase4(payload) {
     var _a, _b, _c, _d, _e, _f, _g;
-    const { isInChildProcess, entrypoint } = payload;
+    const { isInChildProcess, tsNodeScript } = payload;
     const { version, showConfig, restArgs, code, print, argv } = payload.parseArgvResult;
-    const { executeEval, cwd, executeStdin, executeRepl, executeEntrypoint, scriptPath, } = payload.phase2Result;
+    const { cwd } = payload.phase2Result;
     const { preloadedConfig } = payload.phase3Result;
+    const { entryPointPath, executeEntrypoint, executeEval, executeRepl, executeStdin, } = getEntryPointInfo(payload);
     let evalStuff;
@@ -414,10 +467,17 @@ let replStuff;
     // Prepend `ts-node` arguments to CLI for child processes.
-    process.execArgv.push(entrypoint, ...argv.slice(2, argv.length - restArgs.length));
-    // TODO this comes from BoostrapState
+    process.execArgv.push(tsNodeScript, ...argv.slice(2, argv.length - restArgs.length));
+    // TODO this comes from BootstrapState
     process.argv = [process.argv[1]]
-        .concat(executeEntrypoint ? [scriptPath] : [])
+        .concat(executeEntrypoint ? [entryPointPath] : [])
         .concat(restArgs.slice(executeEntrypoint ? 1 : 0));
     // Execute the main contents (either eval, script or piped).
     if (executeEntrypoint) {
-        Module.runMain();
+        if (payload.isInChildProcess &&
+            (0, util_2.versionGteLt)(process.versions.node, '18.6.0')) {
+            // HACK workaround node regression
+            require('../dist-raw/runmain-hack.js').run(entryPointPath);
+        }
+        else {
+            Module.runMain();
+        }
     }
@@ -428,3 +488,3 @@ else {
         if (executeEval) {
-            (0, node_cjs_helpers_1.addBuiltinLibsToObject)(global);
+            (0, node_internal_modules_cjs_helpers_1.addBuiltinLibsToObject)(global);
             evalAndExitOnTsError(evalStuff.repl, evalStuff.module, code, print, 'eval');
@@ -499,3 +559,3 @@ }
     // is end-of-life'd on 2022-04-30
-    const isSupportedNodeVersion = (0, index_1.versionGteLt)(process.versions.node, '12.2.0');
+    const isSupportedNodeVersion = (0, util_2.versionGteLt)(process.versions.node, '12.2.0');
     if (!isSupportedNodeVersion)
@@ -502,0 +562,0 @@ return require.resolve(absoluteModuleSpecifier);

dist/child/child-entrypoint.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const bin_1 = require("../bin");
-const zlib_1 = require("zlib");
+const argv_payload_1 = require("./argv-payload");
 const base64ConfigArg = process.argv[2];
-const argPrefix = '--brotli-base64-config=';
-if (!base64ConfigArg.startsWith(argPrefix))
+if (!base64ConfigArg.startsWith(argv_payload_1.argPrefix))
     throw new Error('unexpected argv');
-const base64Payload = base64ConfigArg.slice(argPrefix.length);
-const payload = JSON.parse((0, zlib_1.brotliDecompressSync)(Buffer.from(base64Payload, 'base64')).toString());
-payload.isInChildProcess = true;
-payload.entrypoint = __filename;
-payload.parseArgvResult.argv = process.argv;
-payload.parseArgvResult.restArgs = process.argv.slice(3);
-(0, bin_1.bootstrap)(payload);
+const base64Payload = base64ConfigArg.slice(argv_payload_1.argPrefix.length);
+const state = (0, argv_payload_1.decompress)(base64Payload);
+state.isInChildProcess = true;
+state.tsNodeScript = __filename;
+state.parseArgvResult.argv = process.argv;
+state.parseArgvResult.restArgs = process.argv.slice(3);
+// Modify and re-compress the payload delivered to subsequent child processes.
+// This logic may be refactored into bin.ts by https://github.com/TypeStrong/ts-node/issues/1831
+if (state.isCli) {
+    const stateForChildren = {
+        ...state,
+        isCli: false,
+    };
+    state.parseArgvResult.argv[2] = `${argv_payload_1.argPrefix}${(0, argv_payload_1.compress)(stateForChildren)}`;
+}
+(0, bin_1.bootstrap)(state);
 //# sourceMappingURL=child-entrypoint.js.map

dist/child/child-loader.js

 "use strict";
-// TODO same version check as ESM loader, but export stubs
-// Also export a binder function that allows re-binding where the stubs
-// delegate.
 var _a;
@@ -6,0 +3,0 @@ Object.defineProperty(exports, "__esModule", { value: true });

dist/child/child-require.js

@@ -13,3 +13,3 @@ "use strict";
 }
-const messageMatch = /--(?:experimental-)?loader\b/;
+const messageMatch = /(?:--(?:experimental-)?loader\b|\bCustom ESM Loaders\b)/;
 function onWarning(warning, ...rest) {
@@ -16,0 +16,0 @@ // Suppress warning about how `--loader` is experimental

dist/child/spawn-child.js

@@ -5,9 +5,13 @@ "use strict";
 const child_process_1 = require("child_process");
-const zlib_1 = require("zlib");
 const url_1 = require("url");
-const __1 = require("..");
-const argPrefix = '--brotli-base64-config=';
-/** @internal */
+const util_1 = require("../util");
+const argv_payload_1 = require("./argv-payload");
+/**
+ * @internal
+ * @param state Bootstrap state to be transferred into the child process.
+ * @param targetCwd Working directory to be preserved when transitioning to
+ *   the child process.
+ */
 function callInChild(state) {
-    if (!(0, __1.versionGteLt)(process.versions.node, '12.17.0')) {
+    if (!(0, util_1.versionGteLt)(process.versions.node, '12.17.0')) {
         throw new Error('`ts-node-esm` and `ts-node --esm` require node version 12.17.0 or newer.');
@@ -22,3 +26,3 @@ }
         require.resolve('./child-entrypoint.js'),
-        `${argPrefix}${(0, zlib_1.brotliCompressSync)(Buffer.from(JSON.stringify(state), 'utf8')).toString('base64')}`,
+        `${argv_payload_1.argPrefix}${(0, argv_payload_1.compress)(state)}`,
         ...state.parseArgvResult.restArgs,
@@ -25,0 +29,0 @@ ], {

dist/configuration.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadCompiler = exports.resolveAndLoadCompiler = exports.readConfig = exports.findAndReadConfig = void 0;
+exports.getTsConfigDefaults = exports.ComputeAsCommonRootOfFiles = exports.loadCompiler = exports.resolveAndLoadCompiler = exports.readConfig = exports.findAndReadConfig = void 0;
 const path_1 = require("path");
@@ -94,5 +94,10 @@ const index_1 = require("./index");
     if (!skipProject) {
-        configFilePath = project
-            ? (0, path_1.resolve)(cwd, project)
-            : ts.findConfigFile(projectSearchDir, fileExists);
+        if (project) {
+            const resolved = (0, path_1.resolve)(cwd, project);
+            const nested = (0, path_1.join)(resolved, 'tsconfig.json');
+            configFilePath = fileExists(nested) ? nested : resolved;
+        }
+        else {
+            configFilePath = ts.findConfigFile(projectSearchDir, fileExists);
+        }
         if (configFilePath) {
@@ -177,6 +182,2 @@ let pathToNextConfigInChain = configFilePath;
     const files = (_c = (_b = rawApiOptions.files) !== null && _b !== void 0 ? _b : tsNodeOptionsFromTsconfig.files) !== null && _c !== void 0 ? _c : index_1.DEFAULTS.files;
-    if (!files) {
-        config.files = [];
-        config.include = [];
-    }
     // Only if a config file is *not* loaded, load an implicit configuration from @tsconfig/bases
@@ -207,3 +208,5 @@ const skipDefaultCompilerOptions = configFilePath != null;
         readFile,
-        readDirectory: ts.sys.readDirectory,
+        // Only used for globbing "files", "include", "exclude"
+        // When `files` option disabled, we want to avoid the fs calls
+        readDirectory: files ? ts.sys.readDirectory : () => [],
         useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
@@ -247,3 +250,3 @@ }, basePath, undefined, configFilePath));
         return { recognized: {}, unrecognized: {} };
-    const { compiler, compilerHost, compilerOptions, emit, files, ignore, ignoreDiagnostics, logError, preferTsExts, pretty, require, skipIgnore, transpileOnly, typeCheck, transpiler, scope, scopeDir, moduleTypes, experimentalReplAwait, swc, experimentalResolverFeatures, esm, ...unrecognized } = jsonObject;
+    const { compiler, compilerHost, compilerOptions, emit, files, ignore, ignoreDiagnostics, logError, preferTsExts, pretty, require, skipIgnore, transpileOnly, typeCheck, transpiler, scope, scopeDir, moduleTypes, experimentalReplAwait, swc, experimentalResolver, esm, experimentalSpecifierResolution, experimentalTsImportSpecifiers, ...unrecognized } = jsonObject;
     const filteredTsConfigOptions = {
@@ -270,4 +273,6 @@ compiler,
         swc,
-        experimentalResolverFeatures,
+        experimentalResolver,
         esm,
+        experimentalSpecifierResolution,
+        experimentalTsImportSpecifiers,
     };
@@ -279,2 +284,31 @@ // Use the typechecker to make sure this implementation has the correct set of properties
 }
+/** @internal */
+exports.ComputeAsCommonRootOfFiles = Symbol();
+/**
+ * Some TS compiler options have defaults which are not provided by TS's config parsing functions.
+ * This function centralizes the logic for computing those defaults.
+ * @internal
+ */
+function getTsConfigDefaults(config, basePath, _files, _include, _exclude) {
+    const { composite = false } = config.options;
+    let rootDir = config.options.rootDir;
+    if (rootDir == null) {
+        if (composite)
+            rootDir = basePath;
+        // Return this symbol to avoid computing from `files`, which would require fs calls
+        else
+            rootDir = exports.ComputeAsCommonRootOfFiles;
+    }
+    const { outDir = rootDir } = config.options;
+    // Docs are wrong: https://www.typescriptlang.org/tsconfig#include
+    // Docs say **, but it's actually **/*; compiler throws error for **
+    const include = _files ? [] : ['**/*'];
+    const files = _files !== null && _files !== void 0 ? _files : [];
+    // Docs are misleading: https://www.typescriptlang.org/tsconfig#exclude
+    // Docs say it excludes node_modules, bower_components, jspm_packages, but actually those are excluded via behavior of "include"
+    const exclude = _exclude !== null && _exclude !== void 0 ? _exclude : [outDir]; // TODO technically, outDir is absolute path, but exclude should be relative glob pattern?
+    // TODO compute baseUrl
+    return { rootDir, outDir, include, files, exclude, composite };
+}
+exports.getTsConfigDefaults = getTsConfigDefaults;
 //# sourceMappingURL=configuration.js.map

dist/esm.d.ts

 /// <reference types="node" />
+/// <reference types="node" />
 import { Service } from './index';
@@ -32,2 +33,3 @@ export interface NodeLoaderHooksAPI1 {
         format?: NodeLoaderHooksFormat;
+        shortCircuit?: boolean;
     }>;
@@ -40,2 +42,3 @@ type LoadHook = (url: string, context: {
         source: string | Buffer | undefined;
+        shortCircuit?: boolean;
     }>;
@@ -42,0 +45,0 @@ type NodeImportConditions = unknown;

dist/esm.js

@@ -10,10 +10,4 @@ "use strict";
 const module_1 = require("module");
-const { createResolve, } = require('../dist-raw/node-esm-resolve-implementation');
-const { defaultGetFormat } = require('../dist-raw/node-esm-default-get-format');
 // The hooks API changed in node version X so we need to check for backwards compatibility.
-// TODO: When the new API is backported to v12, v14, update these version checks accordingly.
-const newHooksAPI = (0, index_1.versionGteLt)(process.versions.node, '17.0.0') ||
-    (0, index_1.versionGteLt)(process.versions.node, '16.12.0', '17.0.0') ||
-    (0, index_1.versionGteLt)(process.versions.node, '14.999.999', '15.0.0') ||
-    (0, index_1.versionGteLt)(process.versions.node, '12.999.999', '13.0.0');
+const newHooksAPI = (0, util_1.versionGteLt)(process.versions.node, '16.12.0');
 /** @internal */
@@ -39,6 +33,5 @@ function filterHooksByAPIVersion(hooks) {
     // Custom implementation that considers additional file extensions and automatically adds file extensions
-    const nodeResolveImplementation = createResolve({
-        ...(0, index_1.getExtensions)(tsNodeService.config),
-        preferTsExts: tsNodeService.options.preferTsExts,
-    });
+    const nodeResolveImplementation = tsNodeService.getNodeEsmResolver();
+    const nodeGetFormatImplementation = tsNodeService.getNodeEsmGetFormat();
+    const extensions = tsNodeService.extensions;
     const hooksAPI = filterHooksByAPIVersion({
@@ -101,41 +94,45 @@ resolve,
         }
-        const parsed = (0, url_1.parse)(specifier);
-        const { pathname, protocol, hostname } = parsed;
-        if (!isFileUrlOrNodeStyleSpecifier(parsed)) {
-            return entrypointFallback(defer);
-        }
-        if (protocol !== null && protocol !== 'file:') {
-            return entrypointFallback(defer);
-        }
-        // Malformed file:// URL?  We should always see `null` or `''`
-        if (hostname) {
-            // TODO file://./foo sets `hostname` to `'.'`.  Perhaps we should special-case this.
-            return entrypointFallback(defer);
-        }
-        // pathname is the path to be resolved
-        return entrypointFallback(() => nodeResolveImplementation.defaultResolve(specifier, context, defaultResolve));
+        return addShortCircuitFlag(async () => {
+            const parsed = (0, url_1.parse)(specifier);
+            const { pathname, protocol, hostname } = parsed;
+            if (!isFileUrlOrNodeStyleSpecifier(parsed)) {
+                return entrypointFallback(defer);
+            }
+            if (protocol !== null && protocol !== 'file:') {
+                return entrypointFallback(defer);
+            }
+            // Malformed file:// URL?  We should always see `null` or `''`
+            if (hostname) {
+                // TODO file://./foo sets `hostname` to `'.'`.  Perhaps we should special-case this.
+                return entrypointFallback(defer);
+            }
+            // pathname is the path to be resolved
+            return entrypointFallback(() => nodeResolveImplementation.defaultResolve(specifier, context, defaultResolve));
+        });
     }
     // `load` from new loader hook API (See description at the top of this file)
     async function load(url, context, defaultLoad) {
-        var _a;
-        // If we get a format hint from resolve() on the context then use it
-        // otherwise call the old getFormat() hook using node's old built-in defaultGetFormat() that ships with ts-node
-        const format = (_a = context.format) !== null && _a !== void 0 ? _a : (await getFormat(url, context, defaultGetFormat)).format;
-        let source = undefined;
-        if (format !== 'builtin' && format !== 'commonjs') {
-            // Call the new defaultLoad() to get the source
-            const { source: rawSource } = await defaultLoad(url, {
-                ...context,
-                format,
-            }, defaultLoad);
-            if (rawSource === undefined || rawSource === null) {
-                throw new Error(`Failed to load raw source: Format was '${format}' and url was '${url}''.`);
+        return addShortCircuitFlag(async () => {
+            var _a;
+            // If we get a format hint from resolve() on the context then use it
+            // otherwise call the old getFormat() hook using node's old built-in defaultGetFormat() that ships with ts-node
+            const format = (_a = context.format) !== null && _a !== void 0 ? _a : (await getFormat(url, context, nodeGetFormatImplementation.defaultGetFormat)).format;
+            let source = undefined;
+            if (format !== 'builtin' && format !== 'commonjs') {
+                // Call the new defaultLoad() to get the source
+                const { source: rawSource } = await defaultLoad(url, {
+                    ...context,
+                    format,
+                }, defaultLoad);
+                if (rawSource === undefined || rawSource === null) {
+                    throw new Error(`Failed to load raw source: Format was '${format}' and url was '${url}''.`);
+                }
+                // Emulate node's built-in old defaultTransformSource() so we can re-use the old transformSource() hook
+                const defaultTransformSource = async (source, _context, _defaultTransformSource) => ({ source });
+                // Call the old hook
+                const { source: transformedSource } = await transformSource(rawSource, { url, format }, defaultTransformSource);
+                source = transformedSource;
             }
-            // Emulate node's built-in old defaultTransformSource() so we can re-use the old transformSource() hook
-            const defaultTransformSource = async (source, _context, _defaultTransformSource) => ({ source });
-            // Call the old hook
-            const { source: transformedSource } = await transformSource(rawSource, { url, format }, defaultTransformSource);
-            source = transformedSource;
-        }
-        return { format, source };
+            return { format, source };
+        });
     }
@@ -163,10 +160,28 @@ async function getFormat(url, context, defaultGetFormat) {
         const nativePath = (0, url_1.fileURLToPath)(url);
-        // If file has .ts, .tsx, or .jsx extension, then ask node how it would treat this file if it were .js
+        let nodeSays;
+        // If file has extension not understood by node, then ask node how it would treat the emitted extension.
+        // E.g. .mts compiles to .mjs, so ask node how to classify an .mjs file.
         const ext = (0, path_1.extname)(nativePath);
-        let nodeSays;
-        if (ext !== '.js' && !tsNodeService.ignored(nativePath)) {
-            nodeSays = await entrypointFallback(() => defer((0, url_1.format)((0, url_1.pathToFileURL)(nativePath + '.js'))));
+        const tsNodeIgnored = tsNodeService.ignored(nativePath);
+        const nodeEquivalentExt = extensions.nodeEquivalents.get(ext);
+        if (nodeEquivalentExt && !tsNodeIgnored) {
+            nodeSays = await entrypointFallback(() => defer((0, url_1.format)((0, url_1.pathToFileURL)(nativePath + nodeEquivalentExt))));
         }
         else {
-            nodeSays = await entrypointFallback(defer);
+            try {
+                nodeSays = await entrypointFallback(defer);
+            }
+            catch (e) {
+                if (e instanceof Error &&
+                    tsNodeIgnored &&
+                    extensions.nodeDoesNotUnderstand.includes(ext)) {
+                    e.message +=
+                        `\n\n` +
+                            `Hint:\n` +
+                            `ts-node is configured to ignore this file.\n` +
+                            `If you want ts-node to handle this file, consider enabling the "skipIgnore" option or adjusting your "ignore" patterns.\n` +
+                            `https://typestrong.org/ts-node/docs/scope\n`;
+                }
+                throw e;
+            }
         }
@@ -176,3 +191,3 @@ // For files compiled by ts-node that node believes are either CJS or ESM, check if we should override that classification
             (nodeSays.format === 'commonjs' || nodeSays.format === 'module')) {
-            const { moduleType } = tsNodeService.moduleTypeClassifier.classifyModule((0, util_1.normalizeSlashes)(nativePath));
+            const { moduleType } = tsNodeService.moduleTypeClassifier.classifyModuleByModuleTypeOverrides((0, util_1.normalizeSlashes)(nativePath));
             if (moduleType === 'cjs') {
@@ -208,2 +223,12 @@ return { format: 'commonjs' };
 exports.createEsmHooks = createEsmHooks;
+async function addShortCircuitFlag(fn) {
+    const ret = await fn();
+    // Not sure if this is necessary; being lazy.  Can revisit in the future.
+    if (ret == null)
+        return ret;
+    return {
+        ...ret,
+        shortCircuit: true,
+    };
+}
 //# sourceMappingURL=esm.js.map

dist/index.d.ts

@@ -29,2 +29,4 @@ import { BaseError } from 'make-error';
  * Options for creating a new TypeScript compiler instance.
+
+ * @category Basic
  */
@@ -184,4 +186,5 @@ export interface CreateOptions {
      * Override certain paths to be compiled and executed as CommonJS or ECMAScript modules.
-     * When overridden, the tsconfig "module" and package.json "type" fields are overridden.
-     * This is useful because TypeScript files cannot use the .cjs nor .mjs file extensions;
+     * When overridden, the tsconfig "module" and package.json "type" fields are overridden, and
+     * the file extension is ignored.
+     * This is useful if you cannot use .mts, .cts, .mjs, or .cjs file extensions;
      * it achieves the same effect.
@@ -205,3 +208,5 @@ *
     /**
-     * TODO DOCS YAY
+     * Enable native ESM support.
+     *
+     * For details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules
      */
@@ -217,6 +222,26 @@ esm?: boolean;
     preferTsExts?: boolean;
+    /**
+     * Like node's `--experimental-specifier-resolution`, , but can also be set in your `tsconfig.json` for convenience.
+     *
+     * For details, see https://nodejs.org/dist/latest-v18.x/docs/api/esm.html#customizing-esm-specifier-resolution-algorithm
+     */
+    experimentalSpecifierResolution?: 'node' | 'explicit';
+    /**
+     * Allow using voluntary `.ts` file extension in import specifiers.
+     *
+     * Typically, in ESM projects, import specifiers must have an emit extension, `.js`, `.cjs`, or `.mjs`,
+     * and we automatically map to the corresponding `.ts`, `.cts`, or `.mts` source file.  This is the
+     * recommended approach.
+     *
+     * However, if you really want to use `.ts` in import specifiers, and are aware that this may
+     * break tooling, you can enable this flag.
+     */
+    experimentalTsImportSpecifiers?: boolean;
 }
-export declare type ModuleTypes = Record<string, 'cjs' | 'esm' | 'package'>;
+export declare type ModuleTypes = Record<string, ModuleTypeOverride>;
+export declare type ModuleTypeOverride = 'cjs' | 'esm' | 'package';
 /**
  * Options for registering a TypeScript compiler instance globally.
+
+ * @category Basic
  */
@@ -231,4 +256,5 @@ export interface RegisterOptions extends CreateOptions {
      */
-    experimentalResolverFeatures?: boolean;
+    experimentalResolver?: boolean;
 }
+export declare type ExperimentalSpecifierResolution = 'node' | 'explicit';
 /**
@@ -253,3 +279,4 @@ * Must be an interface to support `typescript-json-schema`.
     diagnosticText: string;
-    constructor(diagnosticText: string, diagnosticCodes: number[]);
+    diagnostics: ReadonlyArray<_ts.Diagnostic>;
+    constructor(diagnosticText: string, diagnosticCodes: number[], diagnostics?: ReadonlyArray<_ts.Diagnostic>);
 }
@@ -276,2 +303,4 @@ /**
  * Create a new TypeScript compiler instance and register it onto node.js
+ *
+ * @category Basic
  */
@@ -281,2 +310,4 @@ export declare function register(opts?: RegisterOptions): Service;
  * Register TypeScript compiler instance onto node.js
+
+ * @category Basic
  */
@@ -286,2 +317,4 @@ export declare function register(service: Service): Service;
  * Create TypeScript compiler instance.
+ *
+ * @category Basic
  */
@@ -298,3 +331,12 @@ export declare function create(rawOptions?: CreateOptions): Service;
  * detects your node version and returns the appropriate API.
+ *
+ * @category ESM Loader
  */
 export declare const createEsmHooks: typeof createEsmHooksFn;
+/**
+ * When using `module: nodenext` or `module: node12`, there are two possible styles of emit depending in file extension or package.json "type":
+ *
+ * - CommonJS with dynamic imports preserved (not transformed into `require()` calls)
+ * - ECMAScript modules with `import foo = require()` transformed into `require = createRequire(); const foo = require()`
+ */
+export declare type NodeModuleEmitKind = 'nodeesm' | 'nodecjs';

dist/index.js

 "use strict";
 var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEsmHooks = exports.createFromPreloadedConfig = exports.create = exports.register = exports.getExtensions = exports.TSError = exports.DEFAULTS = exports.VERSION = exports.debug = exports.INSPECT_CUSTOM = exports.env = exports.REGISTER_INSTANCE = exports.versionGteLt = exports.createRepl = void 0;
+exports.createEsmHooks = exports.createFromPreloadedConfig = exports.create = exports.register = exports.TSError = exports.DEFAULTS = exports.VERSION = exports.debug = exports.INSPECT_CUSTOM = exports.env = exports.REGISTER_INSTANCE = exports.createRepl = void 0;
 const path_1 = require("path");
@@ -14,3 +14,6 @@ const module_1 = require("module");
 const resolver_functions_1 = require("./resolver-functions");
-const cjs_resolve_filename_hook_1 = require("./cjs-resolve-filename-hook");
+const cjs_resolve_hooks_1 = require("./cjs-resolve-hooks");
+const node_module_type_classifier_1 = require("./node-module-type-classifier");
+const file_extensions_1 = require("./file-extensions");
+const ts_transpile_module_1 = require("./ts-transpile-module");
 var repl_1 = require("./repl");
@@ -23,23 +26,2 @@ Object.defineProperty(exports, "createRepl", { enumerable: true, get: function () { return repl_1.createRepl; } });
 const engineSupportsPackageTypeField = parseInt(process.versions.node.split('.')[0], 10) >= 12;
-/** @internal */
-function versionGteLt(version, gteRequirement, ltRequirement) {
-    const [major, minor, patch, extra] = parse(version);
-    const [gteMajor, gteMinor, gtePatch] = parse(gteRequirement);
-    const isGte = major > gteMajor ||
-        (major === gteMajor &&
-            (minor > gteMinor || (minor === gteMinor && patch >= gtePatch)));
-    let isLt = true;
-    if (ltRequirement) {
-        const [ltMajor, ltMinor, ltPatch] = parse(ltRequirement);
-        isLt =
-            major < ltMajor ||
-                (major === ltMajor &&
-                    (minor < ltMinor || (minor === ltMinor && patch < ltPatch)));
-    }
-    return isGte && isLt;
-    function parse(requirement) {
-        return requirement.split(/[\.-]/).map((s) => parseInt(s, 10));
-    }
-}
-exports.versionGteLt = versionGteLt;
 /**
@@ -52,3 +34,3 @@ * Assert that script can be loaded as CommonJS when we attempt to require it.
 let assertScriptCanLoadAsCJS = engineSupportsPackageTypeField
-    ? require('../dist-raw/node-cjs-loader-utils').assertScriptCanLoadAsCJSImpl
+    ? require('../dist-raw/node-internal-modules-cjs-loader').assertScriptCanLoadAsCJSImpl
     : () => {
@@ -119,3 +101,3 @@ /* noop */
 class TSError extends make_error_1.BaseError {
-    constructor(diagnosticText, diagnosticCodes) {
+    constructor(diagnosticText, diagnosticCodes, diagnostics = []) {
         super(`⨯ Unable to compile TypeScript:\n${diagnosticText}`);
@@ -129,2 +111,7 @@ this.diagnosticCodes = diagnosticCodes;
         });
+        Object.defineProperty(this, 'diagnostics', {
+            configurable: true,
+            writable: true,
+            value: diagnostics,
+        });
     }
@@ -140,21 +127,6 @@ /**
 const TS_NODE_SERVICE_BRAND = Symbol('TS_NODE_SERVICE_BRAND');
-/** @internal */
-function getExtensions(config) {
-    const tsExtensions = ['.ts'];
-    const jsExtensions = [];
-    // Enable additional extensions when JSX or `allowJs` is enabled.
-    if (config.options.jsx)
-        tsExtensions.push('.tsx');
-    if (config.options.allowJs)
-        jsExtensions.push('.js');
-    if (config.options.jsx && config.options.allowJs)
-        jsExtensions.push('.jsx');
-    return { tsExtensions, jsExtensions };
-}
-exports.getExtensions = getExtensions;
 function register(serviceOrOpts) {
-    var _a;
     // Is this a Service or a RegisterOptions?
     let service = serviceOrOpts;
-    if (!((_a = serviceOrOpts) === null || _a === void 0 ? void 0 : _a[TS_NODE_SERVICE_BRAND])) {
+    if (!(serviceOrOpts === null || serviceOrOpts === void 0 ? void 0 : serviceOrOpts[TS_NODE_SERVICE_BRAND])) {
         // Not a service; is options
@@ -164,9 +136,7 @@ service = create((serviceOrOpts !== null && serviceOrOpts !== void 0 ? serviceOrOpts : {}));
     const originalJsHandler = require.extensions['.js'];
-    const { tsExtensions, jsExtensions } = getExtensions(service.config);
-    const extensions = [...tsExtensions, ...jsExtensions];
     // Expose registered instance globally.
     process[exports.REGISTER_INSTANCE] = service;
     // Register the extensions.
-    registerExtensions(service.options.preferTsExts, extensions, service, originalJsHandler);
-    (0, cjs_resolve_filename_hook_1.installCommonjsResolveHookIfNecessary)(service);
+    registerExtensions(service.options.preferTsExts, service.extensions.compiled, service, originalJsHandler);
+    (0, cjs_resolve_hooks_1.installCommonjsResolveHooksIfNecessary)(service);
     // Require specified modules before start-up.
@@ -179,2 +149,4 @@ module_1.Module._preloadModules(service.options.require);
  * Create TypeScript compiler instance.
+ *
+ * @category Basic
  */
@@ -188,3 +160,3 @@ function create(rawOptions = {}) {
 function createFromPreloadedConfig(foundConfigResult) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d;
     const { configFilePath, cwd, options, config, compiler, projectLocalResolveDir, optionBasePaths, } = foundConfigResult;
@@ -199,3 +171,3 @@ const projectLocalResolveHelper = (0, util_1.createProjectLocalResolveHelper)(projectLocalResolveDir);
     // Top-level await was added in TS 3.8
-    const tsVersionSupportsTla = versionGteLt(ts.version, '3.8.0');
+    const tsVersionSupportsTla = (0, util_1.versionGteLt)(ts.version, '3.8.0');
     if (options.experimentalReplAwait === true && !tsVersionSupportsTla) {
@@ -242,2 +214,7 @@ throw new Error('Experimental REPL await is not compatible with TypeScript versions older than 3.8');
                 18003,
+                ...(options.experimentalTsImportSpecifiers
+                    ? [
+                        2691, // "An import path cannot end with a '.ts' extension. Consider importing '<specifier without ext>' instead."
+                    ]
+                    : []),
                 ...(options.ignoreDiagnostics || []),
@@ -261,2 +238,3 @@ ].map(Number),
         getCurrentDirectory: () => cwd,
+        // TODO switch to getCanonicalFileName we already create later in scope
         getCanonicalFileName: ts.sys.useCaseSensitiveFileNames
@@ -269,28 +247,33 @@ ? (x) => x
     }
-    let createTranspiler;
-    if (transpiler) {
-        if (!transpileOnly)
-            throw new Error('Custom transpiler can only be used when transpileOnly is enabled.');
-        const transpilerName = typeof transpiler === 'string' ? transpiler : transpiler[0];
-        const transpilerOptions = typeof transpiler === 'string' ? {} : (_d = transpiler[1]) !== null && _d !== void 0 ? _d : {};
-        const transpilerConfigLocalResolveHelper = transpilerBasePath
-            ? (0, util_1.createProjectLocalResolveHelper)(transpilerBasePath)
-            : projectLocalResolveHelper;
-        const transpilerPath = transpilerConfigLocalResolveHelper(transpilerName, true);
-        const transpilerFactory = require(transpilerPath)
-            .create;
-        createTranspiler = function (compilerOptions) {
-            return transpilerFactory({
-                service: {
-                    options,
-                    config: {
-                        ...config,
-                        options: compilerOptions,
+    let createTranspiler = initializeTranspilerFactory();
+    function initializeTranspilerFactory() {
+        var _a;
+        if (transpiler) {
+            if (!transpileOnly)
+                throw new Error('Custom transpiler can only be used when transpileOnly is enabled.');
+            const transpilerName = typeof transpiler === 'string' ? transpiler : transpiler[0];
+            const transpilerOptions = typeof transpiler === 'string' ? {} : (_a = transpiler[1]) !== null && _a !== void 0 ? _a : {};
+            const transpilerConfigLocalResolveHelper = transpilerBasePath
+                ? (0, util_1.createProjectLocalResolveHelper)(transpilerBasePath)
+                : projectLocalResolveHelper;
+            const transpilerPath = transpilerConfigLocalResolveHelper(transpilerName, true);
+            const transpilerFactory = require(transpilerPath)
+                .create;
+            return createTranspiler;
+            function createTranspiler(compilerOptions, nodeModuleEmitKind) {
+                return transpilerFactory === null || transpilerFactory === void 0 ? void 0 : transpilerFactory({
+                    service: {
+                        options,
+                        config: {
+                            ...config,
+                            options: compilerOptions,
+                        },
+                        projectLocalResolveHelper,
                     },
-                    projectLocalResolveHelper,
-                },
-                transpilerConfigLocalResolveHelper,
-                ...transpilerOptions,
-            });
-        };
+                    transpilerConfigLocalResolveHelper,
+                    nodeModuleEmitKind,
+                    ...transpilerOptions,
+                });
+            }
+        }
     }
@@ -341,3 +324,3 @@ /**
         const diagnosticCodes = diagnostics.map((x) => x.code);
-        return new TSError(diagnosticText, diagnosticCodes);
+        return new TSError(diagnosticText, diagnosticCodes, diagnostics);
     }
@@ -358,10 +341,31 @@ function reportTSError(configDiagnosticList) {
         reportTSError(configDiagnosticList);
+    const jsxEmitPreserve = config.options.jsx === ts.JsxEmit.Preserve;
     /**
      * Get the extension for a transpiled file.
+     * [MUST_UPDATE_FOR_NEW_FILE_EXTENSIONS]
      */
-    const getExtension = config.options.jsx === ts.JsxEmit.Preserve
-        ? (path) => (/\.[tj]sx$/.test(path) ? '.jsx' : '.js')
-        : (_) => '.js';
+    function getEmitExtension(path) {
+        const lastDotIndex = path.lastIndexOf('.');
+        if (lastDotIndex >= 0) {
+            const ext = path.slice(lastDotIndex);
+            switch (ext) {
+                case '.js':
+                case '.ts':
+                    return '.js';
+                case '.jsx':
+                case '.tsx':
+                    return jsxEmitPreserve ? '.jsx' : '.js';
+                case '.mjs':
+                case '.mts':
+                    return '.mjs';
+                case '.cjs':
+                case '.cts':
+                    return '.cjs';
+            }
+        }
+        return '.js';
+    }
     /**
-     * Create the basic required function using transpile mode.
+     * Get output from TS compiler w/typechecking.  `undefined` in `transpileOnly`
+     * mode.
      */
@@ -372,5 +376,6 @@ let getOutput;
     const moduleTypeClassifier = (0, module_type_classifier_1.createModuleTypeClassifier)({
-        basePath: (_e = options.optionBasePaths) === null || _e === void 0 ? void 0 : _e.moduleTypes,
+        basePath: (_d = options.optionBasePaths) === null || _d === void 0 ? void 0 : _d.moduleTypes,
         patterns: options.moduleTypes,
     });
+    const extensions = (0, file_extensions_1.getExtensions)(config, options, ts.version);
     // Use full language services when the fast option is disabled.
@@ -381,3 +386,3 @@ if (!transpileOnly) {
         const cachedReadFile = (0, util_1.cachedLookup)(debugFn('readFile', readFile));
-        // Use language services by default (TODO: invert next major version).
+        // Use language services by default
         if (!options.compilerHost) {
@@ -438,2 +443,4 @@ let projectVersion = 1;
                 projectLocalResolveHelper,
+                options,
+                extensions,
             });
@@ -498,4 +505,5 @@ serviceHost.resolveModuleNames = resolveModuleNames;
             getTypeInfo = (code, fileName, position) => {
-                updateMemoryCache(code, fileName);
-                const info = service.getQuickInfoAtPosition(fileName, position);
+                const normalizedFileName = (0, util_1.normalizeSlashes)(fileName);
+                updateMemoryCache(code, normalizedFileName);
+                const info = service.getQuickInfoAtPosition(normalizedFileName, position);
                 const name = ts.displayPartsToString(info ? info.displayParts : []);
@@ -550,2 +558,4 @@ const comment = ts.displayPartsToString(info ? info.documentation : []);
                 projectLocalResolveHelper,
+                options,
+                extensions,
             });
@@ -626,4 +636,5 @@ host.resolveModuleNames = resolveModuleNames;
             getTypeInfo = (code, fileName, position) => {
-                updateMemoryCache(code, fileName);
-                const sourceFile = builderProgram.getSourceFile(fileName);
+                const normalizedFileName = (0, util_1.normalizeSlashes)(fileName);
+                updateMemoryCache(code, normalizedFileName);
+                const sourceFile = builderProgram.getSourceFile(normalizedFileName);
                 if (!sourceFile)
@@ -658,3 +669,2 @@ throw new TypeError(`Unable to read file: ${fileName}`);
     else {
-        getOutput = createTranspileOnlyGetOutputFunction();
         getTypeInfo = () => {
@@ -664,7 +674,14 @@ throw new TypeError('Type information is unavailable in "--transpile-only"');
     }
-    function createTranspileOnlyGetOutputFunction(overrideModuleType) {
+    function createTranspileOnlyGetOutputFunction(overrideModuleType, nodeModuleEmitKind) {
         const compilerOptions = { ...config.options };
         if (overrideModuleType !== undefined)
             compilerOptions.module = overrideModuleType;
-        let customTranspiler = createTranspiler === null || createTranspiler === void 0 ? void 0 : createTranspiler(compilerOptions);
+        let customTranspiler = createTranspiler === null || createTranspiler === void 0 ? void 0 : createTranspiler(compilerOptions, nodeModuleEmitKind);
+        let tsTranspileModule = (0, util_1.versionGteLt)(ts.version, '4.7.0')
+            ? (0, ts_transpile_module_1.createTsTranspileModule)(ts, {
+                compilerOptions,
+                reportDiagnostics: true,
+                transformers: transformers,
+            })
+            : undefined;
         return (code, fileName) => {
@@ -677,2 +694,7 @@ let result;
             }
+            else if (tsTranspileModule) {
+                result = tsTranspileModule(code, {
+                    fileName,
+                }, nodeModuleEmitKind === 'nodeesm' ? 'module' : 'commonjs');
+            }
             else {
@@ -692,14 +714,22 @@ result = ts.transpileModule(code, {
     }
-    // When either is undefined, it means normal `getOutput` should be used
-    const getOutputForceCommonJS = config.options.module === ts.ModuleKind.CommonJS
-        ? undefined
-        : createTranspileOnlyGetOutputFunction(ts.ModuleKind.CommonJS);
+    // When true, these mean that a `moduleType` override will cause a different emit
+    // than the TypeScript compiler, so we *must* overwrite the emit.
+    const shouldOverwriteEmitWhenForcingCommonJS = config.options.module !== ts.ModuleKind.CommonJS;
     // [MUST_UPDATE_FOR_NEW_MODULEKIND]
-    const getOutputForceESM = config.options.module === ts.ModuleKind.ES2015 ||
+    const shouldOverwriteEmitWhenForcingEsm = !(config.options.module === ts.ModuleKind.ES2015 ||
         (ts.ModuleKind.ES2020 && config.options.module === ts.ModuleKind.ES2020) ||
         (ts.ModuleKind.ES2022 && config.options.module === ts.ModuleKind.ES2022) ||
-        config.options.module === ts.ModuleKind.ESNext
-        ? undefined
-        : // [MUST_UPDATE_FOR_NEW_MODULEKIND]
-            createTranspileOnlyGetOutputFunction(ts.ModuleKind.ES2022 || ts.ModuleKind.ES2020 || ts.ModuleKind.ES2015);
+        config.options.module === ts.ModuleKind.ESNext);
+    /**
+     * node16 or nodenext
+     * [MUST_UPDATE_FOR_NEW_MODULEKIND]
+     */
+    const isNodeModuleType = (ts.ModuleKind.Node16 && config.options.module === ts.ModuleKind.Node16) ||
+        (ts.ModuleKind.NodeNext &&
+            config.options.module === ts.ModuleKind.NodeNext);
+    const getOutputForceCommonJS = createTranspileOnlyGetOutputFunction(ts.ModuleKind.CommonJS);
+    const getOutputForceNodeCommonJS = createTranspileOnlyGetOutputFunction(ts.ModuleKind.NodeNext, 'nodecjs');
+    const getOutputForceNodeESM = createTranspileOnlyGetOutputFunction(ts.ModuleKind.NodeNext, 'nodeesm');
+    // [MUST_UPDATE_FOR_NEW_MODULEKIND]
+    const getOutputForceESM = createTranspileOnlyGetOutputFunction(ts.ModuleKind.ES2022 || ts.ModuleKind.ES2020 || ts.ModuleKind.ES2015);
     const getOutputTranspileOnly = createTranspileOnlyGetOutputFunction();
@@ -709,16 +739,34 @@ // Create a simple TypeScript compiler proxy.
         const normalizedFileName = (0, util_1.normalizeSlashes)(fileName);
-        const classification = moduleTypeClassifier.classifyModule(normalizedFileName);
-        // Must always call normal getOutput to throw typechecking errors
-        let [value, sourceMap, emitSkipped] = getOutput(code, normalizedFileName);
+        const classification = moduleTypeClassifier.classifyModuleByModuleTypeOverrides(normalizedFileName);
+        let value = '';
+        let sourceMap = '';
+        let emitSkipped = true;
+        if (getOutput) {
+            // Must always call normal getOutput to throw typechecking errors
+            [value, sourceMap, emitSkipped] = getOutput(code, normalizedFileName);
+        }
         // If module classification contradicts the above, call the relevant transpiler
-        if (classification.moduleType === 'cjs' && getOutputForceCommonJS) {
+        if (classification.moduleType === 'cjs' &&
+            (shouldOverwriteEmitWhenForcingCommonJS || emitSkipped)) {
             [value, sourceMap] = getOutputForceCommonJS(code, normalizedFileName);
         }
-        else if (classification.moduleType === 'esm' && getOutputForceESM) {
+        else if (classification.moduleType === 'esm' &&
+            (shouldOverwriteEmitWhenForcingEsm || emitSkipped)) {
             [value, sourceMap] = getOutputForceESM(code, normalizedFileName);
         }
         else if (emitSkipped) {
-            [value, sourceMap] = getOutputTranspileOnly(code, normalizedFileName);
+            // Happens when ts compiler skips emit or in transpileOnly mode
+            const classification = (0, node_module_type_classifier_1.classifyModule)(fileName, isNodeModuleType);
+            [value, sourceMap] =
+                classification === 'nodecjs'
+                    ? getOutputForceNodeCommonJS(code, normalizedFileName)
+                    : classification === 'nodeesm'
+                        ? getOutputForceNodeESM(code, normalizedFileName)
+                        : classification === 'cjs'
+                            ? getOutputForceCommonJS(code, normalizedFileName)
+                            : classification === 'esm'
+                                ? getOutputForceESM(code, normalizedFileName)
+                                : getOutputTranspileOnly(code, normalizedFileName);
         }
-        const output = updateOutput(value, normalizedFileName, sourceMap, getExtension);
+        const output = updateOutput(value, normalizedFileName, sourceMap, getEmitExtension);
         outputCache.set(normalizedFileName, { content: output });
@@ -729,3 +777,2 @@ return output;
     const enabled = (enabled) => enabled === undefined ? active : (active = !!enabled);
-    const extensions = getExtensions(config);
     const ignored = (fileName) => {
@@ -735,4 +782,3 @@ if (!active)
         const ext = (0, path_1.extname)(fileName);
-        if (extensions.tsExtensions.includes(ext) ||
-            extensions.jsExtensions.includes(ext)) {
+        if (extensions.compiled.includes(ext)) {
             return !isScoped(fileName) || shouldIgnore(fileName);
@@ -748,2 +794,13 @@ }
     }
+    const getNodeEsmResolver = (0, util_1.once)(() => require('../dist-raw/node-internal-modules-esm-resolve').createResolve({
+        extensions,
+        preferTsExts: options.preferTsExts,
+        tsNodeExperimentalSpecifierResolution: options.experimentalSpecifierResolution,
+    }));
+    const getNodeEsmGetFormat = (0, util_1.once)(() => require('../dist-raw/node-internal-modules-esm-get_format').createGetFormat(options.experimentalSpecifierResolution, getNodeEsmResolver()));
+    const getNodeCjsLoader = (0, util_1.once)(() => require('../dist-raw/node-internal-modules-cjs-loader').createCjsLoader({
+        extensions,
+        preferTsExts: options.preferTsExts,
+        nodeEsmResolver: getNodeEsmResolver(),
+    }));
     return {
@@ -767,2 +824,6 @@ [TS_NODE_SERVICE_BRAND]: true,
         projectLocalResolveHelper,
+        getNodeEsmResolver,
+        getNodeEsmGetFormat,
+        getNodeCjsLoader,
+        extensions,
     };
@@ -782,17 +843,18 @@ }
 /**
- * "Refreshes" an extension on `require.extensions`.
- *
- * @param {string} ext
- */
-function reorderRequireExtension(ext) {
-    const old = require.extensions[ext];
-    delete require.extensions[ext];
-    require.extensions[ext] = old;
-}
-/**
  * Register the extensions to support when importing files.
  */
 function registerExtensions(preferTsExts, extensions, service, originalJsHandler) {
+    const exts = new Set(extensions);
+    // Can't add these extensions cuz would allow omitting file extension; node requires ext for .cjs and .mjs
+    // Unless they're already registered by something else (nyc does this):
+    // then we *must* hook them or else our transformer will not be called.
+    for (const cannotAdd of ['.mts', '.cts', '.mjs', '.cjs']) {
+        if (exts.has(cannotAdd) && !(0, util_1.hasOwnProperty)(require.extensions, cannotAdd)) {
+            // Unrecognized file exts can be transformed via the `.js` handler.
+            exts.add('.js');
+            exts.delete(cannotAdd);
+        }
+    }
     // Register new extensions.
-    for (const ext of extensions) {
+    for (const ext of exts) {
         registerExtension(ext, service, originalJsHandler);
@@ -802,7 +864,11 @@ }
         const preferredExtensions = new Set([
-            ...extensions,
+            ...exts,
             ...Object.keys(require.extensions),
         ]);
-        for (const ext of preferredExtensions)
-            reorderRequireExtension(ext);
+        // Re-sort iteration order of Object.keys()
+        for (const ext of preferredExtensions) {
+            const old = Object.getOwnPropertyDescriptor(require.extensions, ext);
+            delete require.extensions[ext];
+            Object.defineProperty(require.extensions, ext, old);
+        }
     }
@@ -831,3 +897,3 @@ }
  */
-function updateOutput(outputText, fileName, sourceMap, getExtension) {
+function updateOutput(outputText, fileName, sourceMap, getEmitExtension) {
     const base64Map = Buffer.from(updateSourceMap(sourceMap, fileName), 'utf8').toString('base64');
@@ -841,3 +907,3 @@ const sourceMapContent = `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64Map}`;
     const extName = /*.tsx*/ (0, path_1.extname)(fileName);
-    const extension = /*.js*/ getExtension(fileName);
+    const extension = /*.js*/ getEmitExtension(fileName);
     const sourcemapFilename = baseName.slice(0, -extName.length) + extension + '.map';
@@ -916,2 +982,4 @@ const sourceMapLengthWithoutPercentEncoding = prefixLength + sourcemapFilename.length;
  * detects your node version and returns the appropriate API.
+ *
+ * @category ESM Loader
  */
@@ -918,0 +986,0 @@ const createEsmHooks = (tsNodeService) => require('./esm').createEsmHooks(tsNodeService);

dist/module-type-classifier.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createModuleTypeClassifier = void 0;
-require("path");
 const ts_internals_1 = require("./ts-internals");
@@ -24,3 +23,3 @@ const util_1 = require("./util");
         package: {
-            moduleType: 'package',
+            moduleType: 'auto',
         },
@@ -47,3 +46,3 @@ cjs: {
     return {
-        classifyModule: patternTypePairs.length
+        classifyModuleByModuleTypeOverrides: patternTypePairs.length
             ? classifyModule
@@ -50,0 +49,0 @@ : classifyModuleAuto,

dist/repl.d.ts

@@ -40,2 +40,3 @@ /// <reference types="node" />
 }
+/** @category REPL */
 export interface CreateReplOptions {
@@ -61,2 +62,4 @@ service?: Service;
  *     repl.start();
+ *
+ * @category REPL
  */
@@ -63,0 +66,0 @@ export declare function createRepl(options?: CreateReplOptions): ReplService;

dist/repl.js

@@ -19,3 +19,3 @@ "use strict";
             processTopLevelAwait: _processTopLevelAwait,
-        } = require('../dist-raw/node-repl-await'));
+        } = require('../dist-raw/node-internal-repl-await'));
     }
@@ -56,2 +56,4 @@ return _processTopLevelAwait;
  *     repl.start();
+ *
+ * @category REPL
  */
@@ -110,2 +112,3 @@ function createRepl(options = {}) {
             context,
+            overrideIsCompletion: false,
         });
@@ -346,5 +349,15 @@ assert(result.containsTopLevelAwait === false);
 function appendCompileAndEvalInput(options) {
-    const { service, state, input, enableTopLevelAwait = false, context, } = options;
+    const { service, state, wrappedErr, enableTopLevelAwait = false, context, overrideIsCompletion, } = options;
+    let { input } = options;
+    // It's confusing for `{ a: 1 }` to be interpreted as a block statement
+    // rather than an object literal. So, we first try to wrap it in
+    // parentheses, so that it will be interpreted as an expression.
+    // Based on https://github.com/nodejs/node/blob/c2e6822153bad023ab7ebd30a6117dcc049e475c/lib/repl.js#L413-L422
+    let wrappedCmd = false;
+    if (!wrappedErr && /^\s*{/.test(input) && !/;\s*$/.test(input)) {
+        input = `(${input.trim()})\n`;
+        wrappedCmd = true;
+    }
     const lines = state.lines;
-    const isCompletion = !/\n$/.test(input);
+    const isCompletion = overrideIsCompletion !== null && overrideIsCompletion !== void 0 ? overrideIsCompletion : !/\n$/.test(input);
     const undo = appendToEvalState(state, input);
@@ -363,2 +376,15 @@ let output;
         undo();
+        if (wrappedCmd) {
+            if (err instanceof index_1.TSError && err.diagnosticCodes[0] === 2339) {
+                // Ensure consistent and more sane behavior between { a: 1 }['b'] and ({ a: 1 }['b'])
+                throw err;
+            }
+            // Unwrap and try again
+            return appendCompileAndEvalInput({
+                ...options,
+                wrappedErr: err,
+            });
+        }
+        if (wrappedErr)
+            throw wrappedErr;
         throw err;
@@ -482,13 +508,24 @@ }
 /**
- * TS diagnostic codes which are recoverable, meaning that the user likely entered and incomplete line of code
+ * TS diagnostic codes which are recoverable, meaning that the user likely entered an incomplete line of code
  * and should be prompted for the next.  For example, starting a multi-line for() loop and not finishing it.
+ * null value means code is always recoverable.  `Set` means code is only recoverable when occurring alongside at least one
+ * of the other codes.
  */
-const RECOVERY_CODES = new Set([
-    1003,
-    1005,
-    1109,
-    1126,
-    1160,
-    1161,
-    2355, // "A function whose declared type is neither 'void' nor 'any' must return a value."
+const RECOVERY_CODES = new Map([
+    [1003, null],
+    [1005, null],
+    [1109, null],
+    [1126, null],
+    [
+        1136,
+        new Set([1005]), // happens when typing out an object literal or block scope across multiple lines: '{ foo: 123,'
+    ],
+    [1160, null],
+    [1161, null],
+    [2355, null],
+    [2391, null],
+    [
+        7010,
+        new Set([1005]), // happens when fn signature spread across multiple lines: 'function a(\nb: any\n) {'
+    ],
 ]);
@@ -510,3 +547,7 @@ /**
 function isRecoverable(error) {
-    return error.diagnosticCodes.every((code) => RECOVERY_CODES.has(code));
+    return error.diagnosticCodes.every((code) => {
+        const deps = RECOVERY_CODES.get(code);
+        return (deps === null ||
+            (deps && error.diagnosticCodes.some((code) => deps.has(code))));
+    });
 }
@@ -513,0 +554,0 @@ /**

dist/resolver-functions.js

@@ -10,3 +10,3 @@ "use strict";
 function createResolverFunctions(kwargs) {
-    const { host, ts, config, cwd, getCanonicalFileName, projectLocalResolveHelper, } = kwargs;
+    const { host, ts, config, cwd, getCanonicalFileName, projectLocalResolveHelper, options, extensions, } = kwargs;
     const moduleResolutionCache = ts.createModuleResolutionCache(cwd, getCanonicalFileName, config.options);
@@ -43,3 +43,4 @@ const knownInternalFilenames = new Set();
             return;
-        // .ts is always switched to internal
+        // [MUST_UPDATE_FOR_NEW_FILE_EXTENSIONS]
+        // .ts,.mts,.cts is always switched to internal
         // .js is switched on-demand
@@ -49,2 +50,6 @@ if (resolvedModule.isExternalLibraryImport &&
                 !resolvedFileName.endsWith('.d.ts')) ||
+                (resolvedFileName.endsWith('.cts') &&
+                    !resolvedFileName.endsWith('.d.cts')) ||
+                (resolvedFileName.endsWith('.mts') &&
+                    !resolvedFileName.endsWith('.d.mts')) ||
                 isFileKnownToBeInternal(resolvedFileName) ||
@@ -63,5 +68,21 @@ isFileInInternalBucket(resolvedFileName))) {
      */
-    const resolveModuleNames = (moduleNames, containingFile, reusedNames, redirectedReference, optionsOnlyWithNewerTsVersions) => {
-        return moduleNames.map((moduleName) => {
-            const { resolvedModule } = ts.resolveModuleName(moduleName, containingFile, config.options, host, moduleResolutionCache, redirectedReference);
+    const resolveModuleNames = (moduleNames, containingFile, reusedNames, redirectedReference, optionsOnlyWithNewerTsVersions, containingSourceFile) => {
+        return moduleNames.map((moduleName, i) => {
+            var _a, _b;
+            const mode = containingSourceFile
+                ? (_b = (_a = ts).getModeForResolutionAtIndex) === null || _b === void 0 ? void 0 : _b.call(_a, containingSourceFile, i)
+                : undefined;
+            let { resolvedModule } = ts.resolveModuleName(moduleName, containingFile, config.options, host, moduleResolutionCache, redirectedReference, mode);
+            if (!resolvedModule && options.experimentalTsImportSpecifiers) {
+                const lastDotIndex = moduleName.lastIndexOf('.');
+                const ext = lastDotIndex >= 0 ? moduleName.slice(lastDotIndex) : '';
+                if (ext) {
+                    const replacements = extensions.tsResolverEquivalents.get(ext);
+                    for (const replacementExt of replacements !== null && replacements !== void 0 ? replacements : []) {
+                        ({ resolvedModule } = ts.resolveModuleName(moduleName.slice(0, -ext.length) + replacementExt, containingFile, config.options, host, moduleResolutionCache, redirectedReference, mode));
+                        if (resolvedModule)
+                            break;
+                    }
+                }
+            }
             if (resolvedModule) {
@@ -74,4 +95,4 @@ fixupResolvedModule(resolvedModule);
     // language service never calls this, but TS docs recommend that we implement it
-    const getResolvedModuleWithFailedLookupLocationsFromCache = (moduleName, containingFile) => {
-        const ret = ts.resolveModuleNameFromCache(moduleName, containingFile, moduleResolutionCache);
+    const getResolvedModuleWithFailedLookupLocationsFromCache = (moduleName, containingFile, resolutionMode) => {
+        const ret = ts.resolveModuleNameFromCache(moduleName, containingFile, moduleResolutionCache, resolutionMode);
         if (ret && ret.resolvedModule) {
@@ -78,0 +99,0 @@ fixupResolvedModule(ret.resolvedModule);

dist/transpilers/swc.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.targetMapping = exports.create = void 0;
+exports.createSwcOptions = exports.targetMapping = exports.create = void 0;
 function create(createOptions) {
-    const { swc, service: { config, projectLocalResolveHelper }, transpilerConfigLocalResolveHelper, } = createOptions;
+    const { swc, service: { config, projectLocalResolveHelper }, transpilerConfigLocalResolveHelper, nodeModuleEmitKind, } = createOptions;
     // Load swc compiler
     let swcInstance;
+    // Used later in diagnostics; merely needs to be human-readable.
+    let swcDepName = 'swc';
     if (typeof swc === 'string') {
+        swcDepName = swc;
         swcInstance = require(transpilerConfigLocalResolveHelper(swc, true));
@@ -14,7 +17,9 @@ }
         try {
-            swcResolved = transpilerConfigLocalResolveHelper('@swc/core', true);
+            swcDepName = '@swc/core';
+            swcResolved = transpilerConfigLocalResolveHelper(swcDepName, true);
         }
         catch (e) {
             try {
-                swcResolved = transpilerConfigLocalResolveHelper('@swc/wasm', true);
+                swcDepName = '@swc/wasm';
+                swcResolved = transpilerConfigLocalResolveHelper(swcDepName, true);
             }
@@ -31,82 +36,3 @@ catch (e) {
     // Prepare SWC options derived from typescript compiler options
-    const compilerOptions = config.options;
-    const { esModuleInterop, sourceMap, importHelpers, experimentalDecorators, emitDecoratorMetadata, target, module, jsxFactory, jsxFragmentFactory, strict, alwaysStrict, noImplicitUseStrict, } = compilerOptions;
-    const nonTsxOptions = createSwcOptions(false);
-    const tsxOptions = createSwcOptions(true);
-    function createSwcOptions(isTsx) {
-        var _a;
-        let swcTarget = (_a = exports.targetMapping.get(target)) !== null && _a !== void 0 ? _a : 'es3';
-        // Downgrade to lower target if swc does not support the selected target.
-        // Perhaps project has an older version of swc.
-        // TODO cache the results of this; slightly faster
-        let swcTargetIndex = swcTargets.indexOf(swcTarget);
-        for (; swcTargetIndex >= 0; swcTargetIndex--) {
-            try {
-                swcInstance.transformSync('', {
-                    jsc: { target: swcTargets[swcTargetIndex] },
-                });
-                break;
-            }
-            catch (e) { }
-        }
-        swcTarget = swcTargets[swcTargetIndex];
-        const keepClassNames = target >= /* ts.ScriptTarget.ES2016 */ 3;
-        // swc only supports these 4x module options [MUST_UPDATE_FOR_NEW_MODULEKIND]
-        const moduleType = module === ModuleKind.CommonJS
-            ? 'commonjs'
-            : module === ModuleKind.AMD
-                ? 'amd'
-                : module === ModuleKind.UMD
-                    ? 'umd'
-                    : 'es6';
-        // In swc:
-        //   strictMode means `"use strict"` is *always* emitted for non-ES module, *never* for ES module where it is assumed it can be omitted.
-        //   (this assumption is invalid, but that's the way swc behaves)
-        // tsc is a bit more complex:
-        //   alwaysStrict will force emitting it always unless `import`/`export` syntax is emitted which implies it per the JS spec.
-        //   if not alwaysStrict, will emit implicitly whenever module target is non-ES *and* transformed module syntax is emitted.
-        // For node, best option is to assume that all scripts are modules (commonjs or esm) and thus should get tsc's implicit strict behavior.
-        // Always set strictMode, *unless* alwaysStrict is disabled and noImplicitUseStrict is enabled
-        const strictMode = 
-        // if `alwaysStrict` is disabled, remembering that `strict` defaults `alwaysStrict` to true
-        (alwaysStrict === false || (alwaysStrict !== true && strict !== true)) &&
-            // if noImplicitUseStrict is enabled
-            noImplicitUseStrict === true
-            ? false
-            : true;
-        return {
-            sourceMaps: sourceMap,
-            // isModule: true,
-            module: moduleType
-                ? {
-                    noInterop: !esModuleInterop,
-                    type: moduleType,
-                    strictMode,
-                }
-                : undefined,
-            swcrc: false,
-            jsc: {
-                externalHelpers: importHelpers,
-                parser: {
-                    syntax: 'typescript',
-                    tsx: isTsx,
-                    decorators: experimentalDecorators,
-                    dynamicImport: true,
-                },
-                target: swcTarget,
-                transform: {
-                    decoratorMetadata: emitDecoratorMetadata,
-                    legacyDecorator: true,
-                    react: {
-                        throwIfNamespace: false,
-                        development: false,
-                        useBuiltins: false,
-                        pragma: jsxFactory,
-                        pragmaFrag: jsxFragmentFactory,
-                    },
-                },
-                keepClassNames,
-            },
-        };
-    }
+    const { nonTsxOptions, tsxOptions } = createSwcOptions(config.options, nodeModuleEmitKind, swcInstance, swcDepName);
     const transpile = (input, transpileOptions) => {
@@ -166,3 +92,124 @@ const { fileName } = transpileOptions;
     ESNext: 99,
+    Node16: 100,
+    NodeNext: 199,
 };
+const JsxEmit = {
+    ReactJSX: /* ts.JsxEmit.ReactJSX */ 4,
+    ReactJSXDev: /* ts.JsxEmit.ReactJSXDev */ 5,
+};
+/**
+ * Prepare SWC options derived from typescript compiler options.
+ * @internal exported for testing
+ */
+function createSwcOptions(compilerOptions, nodeModuleEmitKind, swcInstance, swcDepName) {
+    var _a;
+    const { esModuleInterop, sourceMap, importHelpers, experimentalDecorators, emitDecoratorMetadata, target, module, jsx, jsxFactory, jsxFragmentFactory, strict, alwaysStrict, noImplicitUseStrict, } = compilerOptions;
+    let swcTarget = (_a = exports.targetMapping.get(target)) !== null && _a !== void 0 ? _a : 'es3';
+    // Downgrade to lower target if swc does not support the selected target.
+    // Perhaps project has an older version of swc.
+    // TODO cache the results of this; slightly faster
+    let swcTargetIndex = swcTargets.indexOf(swcTarget);
+    for (; swcTargetIndex >= 0; swcTargetIndex--) {
+        try {
+            swcInstance.transformSync('', {
+                jsc: { target: swcTargets[swcTargetIndex] },
+            });
+            break;
+        }
+        catch (e) { }
+    }
+    swcTarget = swcTargets[swcTargetIndex];
+    const keepClassNames = target >= /* ts.ScriptTarget.ES2016 */ 3;
+    const isNodeModuleKind = module === ModuleKind.Node16 || module === ModuleKind.NodeNext;
+    // swc only supports these 4x module options [MUST_UPDATE_FOR_NEW_MODULEKIND]
+    const moduleType = module === ModuleKind.CommonJS
+        ? 'commonjs'
+        : module === ModuleKind.AMD
+            ? 'amd'
+            : module === ModuleKind.UMD
+                ? 'umd'
+                : isNodeModuleKind && nodeModuleEmitKind === 'nodecjs'
+                    ? 'commonjs'
+                    : isNodeModuleKind && nodeModuleEmitKind === 'nodeesm'
+                        ? 'es6'
+                        : 'es6';
+    // In swc:
+    //   strictMode means `"use strict"` is *always* emitted for non-ES module, *never* for ES module where it is assumed it can be omitted.
+    //   (this assumption is invalid, but that's the way swc behaves)
+    // tsc is a bit more complex:
+    //   alwaysStrict will force emitting it always unless `import`/`export` syntax is emitted which implies it per the JS spec.
+    //   if not alwaysStrict, will emit implicitly whenever module target is non-ES *and* transformed module syntax is emitted.
+    // For node, best option is to assume that all scripts are modules (commonjs or esm) and thus should get tsc's implicit strict behavior.
+    // Always set strictMode, *unless* alwaysStrict is disabled and noImplicitUseStrict is enabled
+    const strictMode = 
+    // if `alwaysStrict` is disabled, remembering that `strict` defaults `alwaysStrict` to true
+    (alwaysStrict === false || (alwaysStrict !== true && strict !== true)) &&
+        // if noImplicitUseStrict is enabled
+        noImplicitUseStrict === true
+        ? false
+        : true;
+    const jsxRuntime = jsx === JsxEmit.ReactJSX || jsx === JsxEmit.ReactJSXDev
+        ? 'automatic'
+        : undefined;
+    const jsxDevelopment = jsx === JsxEmit.ReactJSXDev ? true : undefined;
+    const nonTsxOptions = createVariant(false);
+    const tsxOptions = createVariant(true);
+    return { nonTsxOptions, tsxOptions };
+    function createVariant(isTsx) {
+        const swcOptions = {
+            sourceMaps: sourceMap,
+            // isModule: true,
+            module: moduleType
+                ? {
+                    noInterop: !esModuleInterop,
+                    type: moduleType,
+                    strictMode,
+                    // For NodeNext and Node12, emit as CJS but do not transform dynamic imports
+                    ignoreDynamic: nodeModuleEmitKind === 'nodecjs',
+                }
+                : undefined,
+            swcrc: false,
+            jsc: {
+                externalHelpers: importHelpers,
+                parser: {
+                    syntax: 'typescript',
+                    tsx: isTsx,
+                    decorators: experimentalDecorators,
+                    dynamicImport: true,
+                    importAssertions: true,
+                },
+                target: swcTarget,
+                transform: {
+                    decoratorMetadata: emitDecoratorMetadata,
+                    legacyDecorator: true,
+                    react: {
+                        throwIfNamespace: false,
+                        development: jsxDevelopment,
+                        useBuiltins: false,
+                        pragma: jsxFactory,
+                        pragmaFrag: jsxFragmentFactory,
+                        runtime: jsxRuntime,
+                    },
+                },
+                keepClassNames,
+                experimental: {
+                    keepImportAssertions: true,
+                },
+            },
+        };
+        // Throw a helpful error if swc version is old, for example, if it rejects `ignoreDynamic`
+        try {
+            swcInstance.transformSync('', swcOptions);
+        }
+        catch (e) {
+            throw new Error(`${swcDepName} threw an error when attempting to validate swc compiler options.\n` +
+                'You may be using an old version of swc which does not support the options used by ts-node.\n' +
+                'Try upgrading to the latest version of swc.\n' +
+                'Error message from swc:\n' +
+                (e === null || e === void 0 ? void 0 : e.message));
+        }
+        return swcOptions;
+    }
+}
+exports.createSwcOptions = createSwcOptions;
 //# sourceMappingURL=swc.js.map

dist/transpilers/types.d.ts

@@ -6,2 +6,4 @@ import type * as ts from 'typescript';
  * named export "create"
+ *
+ * @category Transpiler
  */
@@ -13,13 +15,19 @@ export interface TranspilerModule {
  * Called by ts-node to create a custom transpiler.
+ *
+ * @category Transpiler
  */
 export declare type TranspilerFactory = (options: CreateTranspilerOptions) => Transpiler;
+/** @category Transpiler */
 export interface CreateTranspilerOptions {
     service: Pick<Service, Extract<'config' | 'options' | 'projectLocalResolveHelper', keyof Service>>;
 }
+/** @category Transpiler */
 export interface Transpiler {
     transpile(input: string, options: TranspileOptions): TranspileOutput;
 }
+/** @category Transpiler */
 export interface TranspileOptions {
     fileName: string;
 }
+/** @category Transpiler */
 export interface TranspileOutput {
@@ -26,0 +34,0 @@ outputText: string;

dist/ts-compiler-types.d.ts

@@ -21,3 +21,3 @@ import type * as _ts from 'typescript';
     transpileModule: typeof _ts.transpileModule;
-    ModuleKind: typeof _ts.ModuleKind;
+    ModuleKind: TSCommon.ModuleKindEnum;
     ScriptTarget: typeof _ts.ScriptTarget;
@@ -34,3 +34,3 @@ findConfigFile: typeof _ts.findConfigFile;
     resolveModuleNameFromCache: typeof _ts.resolveModuleNameFromCache;
-    resolveTypeReferenceDirective(typeReferenceDirectiveName: string, containingFile: string | undefined, options: _ts.CompilerOptions, host: _ts.ModuleResolutionHost, redirectedReference?: _ts.ResolvedProjectReference, cache?: _ts.TypeReferenceDirectiveResolutionCache, resolutionMode?: _ts.SourceFile['impliedNodeFormat']): _ts.ResolvedTypeReferenceDirectiveWithFailedLookupLocations;
+    resolveTypeReferenceDirective: typeof _ts.resolveTypeReferenceDirective;
     createIncrementalCompilerHost: typeof _ts.createIncrementalCompilerHost;
@@ -46,3 +46,2 @@ createSourceFile: typeof _ts.createSourceFile;
     interface LanguageServiceHost extends _ts.LanguageServiceHost {
-        resolveTypeReferenceDirectives?(typeDirectiveNames: string[] | _ts.FileReference[], containingFile: string, redirectedReference: _ts.ResolvedProjectReference | undefined, options: _ts.CompilerOptions, containingFileMode?: _ts.SourceFile['impliedNodeFormat'] | undefined): (_ts.ResolvedTypeReferenceDirective | undefined)[];
     }
@@ -58,2 +57,11 @@ type ModuleResolutionHost = _ts.ModuleResolutionHost;
     type SourceFile = _ts.SourceFile;
+    type ModuleKindEnum = typeof _ts.ModuleKind & {
+        Node16: typeof _ts.ModuleKind extends {
+            Node16: any;
+        } ? typeof _ts.ModuleKind['Node16'] : 100;
+    };
+    namespace ModuleKind {
+        type CommonJS = _ts.ModuleKind.CommonJS;
+        type ESNext = _ts.ModuleKind.ESNext;
+    }
 }

dist/ts-internals.js

@@ -168,6 +168,6 @@ "use strict";
     // POSIX or UNC
-    if (ch0 === 47 /* slash */ || ch0 === 92 /* backslash */) {
+    if (ch0 === 47 /* CharacterCodes.slash */ || ch0 === 92 /* CharacterCodes.backslash */) {
         if (path.charCodeAt(1) !== ch0)
             return 1; // POSIX: "/" (or non-normalized "\")
-        const p1 = path.indexOf(ch0 === 47 /* slash */ ? directorySeparator : altDirectorySeparator, 2);
+        const p1 = path.indexOf(ch0 === 47 /* CharacterCodes.slash */ ? directorySeparator : altDirectorySeparator, 2);
         if (p1 < 0)
@@ -178,5 +178,5 @@ return path.length; // UNC: "//server" or "\\server"
     // DOS
-    if (isVolumeCharacter(ch0) && path.charCodeAt(1) === 58 /* colon */) {
+    if (isVolumeCharacter(ch0) && path.charCodeAt(1) === 58 /* CharacterCodes.colon */) {
         const ch2 = path.charCodeAt(2);
-        if (ch2 === 47 /* slash */ || ch2 === 92 /* backslash */)
+        if (ch2 === 47 /* CharacterCodes.slash */ || ch2 === 92 /* CharacterCodes.backslash */)
             return 3; // DOS: "c:/" or "c:\"
@@ -203,3 +203,3 @@ if (path.length === 2)
                 if (volumeSeparatorEnd !== -1) {
-                    if (path.charCodeAt(volumeSeparatorEnd) === 47 /* slash */) {
+                    if (path.charCodeAt(volumeSeparatorEnd) === 47 /* CharacterCodes.slash */) {
                         // URL: "file:///c:/", "file://localhost/c:/", "file:///c%3a/", "file://localhost/c%3a/"
@@ -232,3 +232,3 @@ return ~(volumeSeparatorEnd + 1);
 function isAnyDirectorySeparator(charCode) {
-    return (charCode === 47 /* slash */ || charCode === 92 /* backslash */);
+    return (charCode === 47 /* CharacterCodes.slash */ || charCode === 92 /* CharacterCodes.backslash */);
 }
@@ -245,13 +245,13 @@ function removeTrailingDirectorySeparator(path) {
 function isVolumeCharacter(charCode) {
-    return ((charCode >= 97 /* a */ && charCode <= 122 /* z */) ||
-        (charCode >= 65 /* A */ && charCode <= 90 /* Z */));
+    return ((charCode >= 97 /* CharacterCodes.a */ && charCode <= 122 /* CharacterCodes.z */) ||
+        (charCode >= 65 /* CharacterCodes.A */ && charCode <= 90 /* CharacterCodes.Z */));
 }
 function getFileUrlVolumeSeparatorEnd(url, start) {
     const ch0 = url.charCodeAt(start);
-    if (ch0 === 58 /* colon */)
+    if (ch0 === 58 /* CharacterCodes.colon */)
         return start + 1;
-    if (ch0 === 37 /* percent */ &&
-        url.charCodeAt(start + 1) === 51 /* _3 */) {
+    if (ch0 === 37 /* CharacterCodes.percent */ &&
+        url.charCodeAt(start + 1) === 51 /* CharacterCodes._3 */) {
         const ch2 = url.charCodeAt(start + 2);
-        if (ch2 === 97 /* a */ || ch2 === 65 /* A */)
+        if (ch2 === 97 /* CharacterCodes.a */ || ch2 === 65 /* CharacterCodes.A */)
             return start + 3;
@@ -258,0 +258,0 @@ }

dist/util.js

 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBasePathForProjectLocalDependencyResolution = exports.createProjectLocalResolveHelper = exports.attemptRequireWithV8CompileCache = exports.cachedLookup = exports.hasOwnProperty = exports.normalizeSlashes = exports.parse = exports.split = exports.assign = exports.yn = exports.createRequire = void 0;
+exports.versionGteLt = exports.once = exports.getBasePathForProjectLocalDependencyResolution = exports.createProjectLocalResolveHelper = exports.attemptRequireWithV8CompileCache = exports.cachedLookup = exports.hasOwnProperty = exports.normalizeSlashes = exports.parse = exports.split = exports.assign = exports.yn = exports.createRequire = void 0;
 const module_1 = require("module");
@@ -140,2 +140,37 @@ const ynModule = require("yn");
 exports.getBasePathForProjectLocalDependencyResolution = getBasePathForProjectLocalDependencyResolution;
+/** @internal */
+function once(fn) {
+    let value;
+    let ran = false;
+    function onceFn(...args) {
+        if (ran)
+            return value;
+        value = fn(...args);
+        ran = true;
+        return value;
+    }
+    return onceFn;
+}
+exports.once = once;
+/** @internal */
+function versionGteLt(version, gteRequirement, ltRequirement) {
+    const [major, minor, patch, extra] = parse(version);
+    const [gteMajor, gteMinor, gtePatch] = parse(gteRequirement);
+    const isGte = major > gteMajor ||
+        (major === gteMajor &&
+            (minor > gteMinor || (minor === gteMinor && patch >= gtePatch)));
+    let isLt = true;
+    if (ltRequirement) {
+        const [ltMajor, ltMinor, ltPatch] = parse(ltRequirement);
+        isLt =
+            major < ltMajor ||
+                (major === ltMajor &&
+                    (minor < ltMinor || (minor === ltMinor && patch < ltPatch)));
+    }
+    return isGte && isLt;
+    function parse(requirement) {
+        return requirement.split(/[\.-]/).map((s) => parseInt(s, 10));
+    }
+}
+exports.versionGteLt = versionGteLt;
 //# sourceMappingURL=util.js.map

package.json

 {
   "name": "ts-node",
-  "version": "10.7.0",
+  "version": "10.9.1",
   "description": "TypeScript execution environment and REPL for node.js, with source map support",
@@ -49,2 +49,3 @@ "main": "dist/index.js",
     "!/dist/test",
+    "/dist-raw/NODE-LICENSE.md",
     "/dist-raw/**.js",
@@ -64,9 +65,9 @@ "/register/",
   "scripts": {
-    "lint": "prettier --check .",
-    "lint-fix": "prettier --write .",
-    "clean": "rimraf dist tsconfig.schema.json tsconfig.schemastore-schema.json tsconfig.tsbuildinfo tests/ts-node-packed.tgz",
+    "lint": "dprint check",
+    "lint-fix": "dprint fmt",
+    "clean": "rimraf temp dist tsconfig.schema.json tsconfig.schemastore-schema.json tsconfig.tsbuildinfo tests/ts-node-packed.tgz tests/node_modules tests/tmp",
     "rebuild": "npm run clean && npm run build",
     "build": "npm run build-nopack && npm run build-pack",
     "build-nopack": "npm run build-tsc && npm run build-configSchema",
-    "build-tsc": "tsc",
+    "build-tsc": "tsc -b ./tsconfig.build-dist.json",
     "build-configSchema": "typescript-json-schema --topRef --refs --validationKeywords allOf --out tsconfig.schema.json tsconfig.build-schema.json TsConfigSchema && node --require ./register ./scripts/create-merged-schema",
@@ -116,5 +117,4 @@ "build-pack": "node ./scripts/build-pack.js",
     "@microsoft/api-extractor": "^7.19.4",
-    "@swc/core": ">=1.2.50",
-    "@swc/wasm": ">=1.2.50",
-    "@types/chai": "^4.0.4",
+    "@swc/core": ">=1.2.205",
+    "@swc/wasm": ">=1.2.205",
     "@types/diff": "^4.0.2",
@@ -125,3 +125,3 @@ "@types/lodash": "^4.14.151",
     "@types/proxyquire": "^1.3.28",
-    "@types/react": "^16.0.2",
+    "@types/react": "^16.14.19",
     "@types/rimraf": "^3.0.0",
@@ -132,3 +132,3 @@ "@types/semver": "^7.1.0",
     "axios": "^0.21.1",
-    "chai": "^4.0.1",
+    "dprint": "^0.25.0",
     "expect": "^27.0.2",
@@ -139,3 +139,3 @@ "get-stream": "^6.0.0",
     "nyc": "^15.0.1",
-    "prettier": "^2.5.1",
+    "outdent": "^0.8.0",
     "proper-lockfile": "^4.1.2",
@@ -148,3 +148,3 @@ "proxyquire": "^2.0.0",
     "typedoc": "^0.22.10",
-    "typescript": "4.5.5",
+    "typescript": "4.7.4",
     "typescript-json-schema": "^0.53.0",
@@ -168,3 +168,3 @@ "util.promisify": "^1.0.1"
   "dependencies": {
-    "@cspotcode/source-map-support": "0.7.0",
+    "@cspotcode/source-map-support": "^0.8.0",
     "@tsconfig/node10": "^1.0.7",
@@ -180,3 +180,3 @@ "@tsconfig/node12": "^1.0.7",
     "make-error": "^1.1.1",
-    "v8-compile-cache-lib": "^3.0.0",
+    "v8-compile-cache-lib": "^3.0.1",
     "yn": "3.1.1"
@@ -188,5 +188,5 @@ },
   "volta": {
-    "node": "17.5.0",
+    "node": "18.1.0",
     "npm": "6.14.15"
   }
 }

README.md

@@ -30,6 +30,6 @@ <!--
 *   [Usage](#usage)
-    *   [Shell](#shell)
+    *   [Command Line](#command-line)
     *   [Shebang](#shebang)
+    *   [node flags and other tools](#node-flags-and-other-tools)
     *   [Programmatic](#programmatic)
-        *   [Developers](#developers)
 *   [Configuration](#configuration)
@@ -42,9 +42,45 @@ *   [CLI flags](#cli-flags)
 *   [Options](#options)
-    *   [Shell](#shell-1)
-    *   [TSConfig](#tsconfig)
+    *   [CLI Options](#cli-options)
+        *   [help](#help)
+        *   [version](#version)
+        *   [eval](#eval)
+        *   [print](#print)
+        *   [interactive](#interactive)
+        *   [esm](#esm)
+    *   [TSConfig Options](#tsconfig-options)
+        *   [project](#project)
+        *   [skipProject](#skipproject)
+        *   [cwdMode](#cwdmode)
+        *   [compilerOptions](#compileroptions)
+        *   [showConfig](#showconfig)
     *   [Typechecking](#typechecking)
-    *   [Transpilation](#transpilation)
-    *   [Diagnostics](#diagnostics)
-    *   [Advanced](#advanced)
-    *   [API](#api)
+        *   [transpileOnly](#transpileonly)
+        *   [typeCheck](#typecheck)
+        *   [compilerHost](#compilerhost)
+        *   [files](#files)
+        *   [ignoreDiagnostics](#ignorediagnostics)
+    *   [Transpilation Options](#transpilation-options)
+        *   [ignore](#ignore)
+        *   [skipIgnore](#skipignore)
+        *   [compiler](#compiler)
+        *   [swc](#swc)
+        *   [transpiler](#transpiler)
+        *   [preferTsExts](#prefertsexts)
+    *   [Diagnostic Options](#diagnostic-options)
+        *   [logError](#logerror)
+        *   [pretty](#pretty)
+        *   [TS_NODE_DEBUG](#ts_node_debug)
+    *   [Advanced Options](#advanced-options)
+        *   [require](#require)
+        *   [cwd](#cwd)
+        *   [emit](#emit)
+        *   [scope](#scope)
+        *   [scopeDir](#scopedir)
+        *   [moduleTypes](#moduletypes)
+        *   [TS_NODE_HISTORY](#ts_node_history)
+        *   [noExperimentalReplAwait](#noexperimentalreplawait)
+        *   [experimentalResolver](#experimentalresolver)
+        *   [experimentalSpecifierResolution](#experimentalspecifierresolution)
+    *   [API Options](#api-options)
+*   [SWC](#swc-1)
 *   [CommonJS vs native ECMAScript modules](#commonjs-vs-native-ecmascript-modules)
@@ -54,27 +90,34 @@ *   [CommonJS](#commonjs)
 *   [Troubleshooting](#troubleshooting)
-    *   [Understanding configuration](#understanding-configuration)
-    *   [Understanding Errors](#understanding-errors)
+    *   [Configuration](#configuration-1)
+    *   [Common errors](#common-errors)
         *   [`TSError`](#tserror)
         *   [`SyntaxError`](#syntaxerror)
             *   [Unsupported JavaScript syntax](#unsupported-javascript-syntax)
-*   [Make it fast](#make-it-fast)
+        *   [`ERR_REQUIRE_ESM`](#err_require_esm)
+        *   [`ERR_UNKNOWN_FILE_EXTENSION`](#err_unknown_file_extension)
+    *   [Missing Types](#missing-types)
+    *   [npx, yarn dlx, and node_modules](#npx-yarn-dlx-and-node_modules)
+*   [Performance](#performance)
     *   [Skip typechecking](#skip-typechecking)
     *   [With typechecking](#with-typechecking)
-*   [Advanced](#advanced-1)
-    *   [How It Works](#how-it-works)
+*   [Advanced](#advanced)
+    *   [How it works](#how-it-works)
+    *   [Ignored files](#ignored-files)
+        *   [File extensions](#file-extensions)
         *   [Skipping `node_modules`](#skipping-node_modules)
         *   [Skipping pre-compiled TypeScript](#skipping-pre-compiled-typescript)
+        *   [Scope by directory](#scope-by-directory)
+        *   [Ignore by regexp](#ignore-by-regexp)
     *   [paths and baseUrl
         ](#paths-and-baseurl)
         *   [Why is this not built-in to ts-node?](#why-is-this-not-built-in-to-ts-node)
-    *   [Help! My Types Are Missing!](#help-my-types-are-missing)
     *   [Third-party compilers](#third-party-compilers)
     *   [Transpilers](#transpilers)
-        *   [swc](#swc)
-        *   [Third-party transpilers](#third-party-transpilers)
-        *   [Writing your own integration](#writing-your-own-integration)
+        *   [Third-party plugins](#third-party-plugins)
+        *   [Write your own plugin](#write-your-own-plugin)
     *   [Module type overrides](#module-type-overrides)
         *   [Caveats](#caveats)
+    *   [API](#api)
 *   [Recipes](#recipes)
-    *   [Watching and Restarting](#watching-and-restarting)
+    *   [Watching and restarting](#watching-and-restarting)
     *   [AVA](#ava)
@@ -136,3 +179,3 @@ *   [CommonJS](#commonjs-1)
 
-## Shell
+## Command Line
 
@@ -167,9 +210,13 @@ ```shell
 
+To write scripts with maximum portability, [specify options in your `tsconfig.json`](#via-tsconfigjson-recommended) and omit them from the shebang.
+
 ```typescript twoslash
 #!/usr/bin/env ts-node
 
+// ts-node options are read from tsconfig.json
+
 console.log("Hello, world!")
 ```
 
-Passing options via shebang requires the [`env -S` flag](https://manpages.debian.org/bullseye/coreutils/env.1.en.html#S), which is available on recent versions of `env`. ([compatibility](https://github.com/TypeStrong/ts-node/pull/1448#issuecomment-913895766))
+Including options within the shebang requires the [`env -S` flag](https://manpages.debian.org/bullseye/coreutils/env.1.en.html#S), which is available on recent versions of `env`. ([compatibility](https://github.com/TypeStrong/ts-node/pull/1448#issuecomment-913895766))
 
@@ -182,26 +229,39 @@ ```typescript twoslash
 
-To write scripts with maximum portability, [specify all options in your `tsconfig.json`](#via-tsconfigjson-recommended) and omit them from the shebang.
+To test your version of `env` for compatibility with `-S`:
 
-```typescript twoslash
-#!/usr/bin/env ts-node
-// This shebang works everywhere
+```shell
+# Note that these unusual quotes are necessary
+/usr/bin/env --debug '-S echo foo bar'
 ```
 
-To test your version of `env` for compatibility:
+## node flags and other tools
 
+You can register ts-node without using our CLI: `node -r ts-node/register` and `node --loader ts-node/esm`
+
+In many cases, setting [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node_options_options) will enable `ts-node` within other node tools, child processes, and worker threads.  This can be combined with other node flags.
+
 ```shell
-# Note that these unusual quotes are necessary
-/usr/bin/env --debug '-S echo foo bar'
+NODE_OPTIONS="-r ts-node/register --no-warnings" node ./index.ts
 ```
 
-## Programmatic
+Or, if you require native ESM support:
 
-You can require ts-node and register the loader for future requires by using `require('ts-node').register({ /* options */ })`. You can also use file shortcuts - `node -r ts-node/register` or `node -r ts-node/register/transpile-only` - depending on your preferences.
+```shell
+NODE_OPTIONS="--loader ts-node/esm"
+```
 
-**Note:** If you need to use advanced node.js CLI arguments (e.g. `--inspect`), use them with `node -r ts-node/register` instead of ts-node's CLI.
+This tells any node processes which receive this environment variable to install `ts-node`'s hooks before executing other code.
 
-### Developers
+If you are invoking node directly, you can avoid the environment variable and pass those flags to node.
 
-ts-node exports a `create()` function that can be used to initialize a TypeScript compiler that isn't registered to `require.extensions`, and it uses the same code as `register`.
+```shell
+node --loader ts-node/esm --inspect ./index.ts
+```
 
+## Programmatic
+
+You can require ts-node and register the loader for future requires by using `require('ts-node').register({ /* options */ })`.
+
+Check out our [API](#api) for more features.
+
 # Configuration
@@ -234,4 +294,4 @@
 {
-  // This is an alias to @tsconfig/node12: https://github.com/tsconfig/bases
-  "extends": "ts-node/node12/tsconfig.json",
+  // This is an alias to @tsconfig/node16: https://github.com/tsconfig/bases
+  "extends": "ts-node/node16/tsconfig.json",
 
@@ -302,64 +362,428 @@ // Most ts-node options can be specified here using their programmatic names.
 
-`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI options](https://nodejs.org/api/cli.html).
-
 All command-line flags support both `--camelCase` and `--hyphen-case`.
 
+Most options can be declared in your tsconfig.json: [Configuration via tsconfig.json](#via-tsconfigjson-recommended)
+
+`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI](https://nodejs.org/api/cli.html).
+
+`ts-node` supports `--project` and `--showConfig` similar to the [tsc CLI](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options).
+
 *Environment variables, where available, are in `ALL_CAPS`*
 
-## Shell
+## CLI Options
 
-*   `-h, --help`   Prints the help text
-*   `-v, --version`   Prints the version. `-vv` prints node and typescript compiler versions, too
-*   `-e, --eval`   Evaluate code
-*   `-p, --print`   Print result of `--eval`
-*   `-i, --interactive`   Opens the REPL even if stdin does not appear to be a terminal
-*   `--esm`   Bootstrap with the ESM loader, enabling full ESM support
+### help
 
-## TSConfig
+```shell
+ts-node --help
+```
 
-*   `-P, --project [path]`   Path to TypeScript JSON project file <br/>*Environment:* `TS_NODE_PROJECT`
-*   `--skipProject`   Skip project config resolution and loading <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_SKIP_PROJECT`
-*   `-c, --cwdMode`   Resolve config relative to the current directory instead of the directory of the entrypoint script
-*   `-O, --compilerOptions [opts]`   JSON object to merge with compiler options <br/>*Environment:* `TS_NODE_COMPILER_OPTIONS`
-*   `--showConfig`   Print resolved `tsconfig.json`, including `ts-node` options, and exit
+Prints the help text
 
+### version
+
+```shell
+ts-node -v
+ts-node -vvv
+```
+
+Prints the version. `-vv` includes node and typescript compiler versions.  `-vvv` includes absolute paths to ts-node and
+typescript installations.
+
+### eval
+
+```shell
+ts-node -e <typescript code>
+# Example
+ts-node -e 'console.log("Hello world!")'
+```
+
+Evaluate code
+
+### print
+
+```shell
+ts-node -p -e <typescript code>
+# Example
+ts-node -p -e '"Hello world!"'
+```
+
+Print result of `--eval`
+
+### interactive
+
+```shell
+ts-node -i
+```
+
+Opens the REPL even if stdin does not appear to be a terminal
+
+### esm
+
+```shell
+ts-node --esm
+ts-node-esm
+```
+
+Bootstrap with the ESM loader, enabling full ESM support
+
+## TSConfig Options
+
+### project
+
+```shell
+ts-node -P <path/to/tsconfig>
+ts-node --project <path/to/tsconfig>
+```
+
+Path to tsconfig file.
+
+*Note the uppercase `-P`. This is different from `tsc`'s `-p/--project` option.*
+
+*Environment:* `TS_NODE_PROJECT`
+
+### skipProject
+
+```shell
+ts-node --skipProject
+```
+
+Skip project config resolution and loading
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_SKIP_PROJECT`
+
+### cwdMode
+
+```shell
+ts-node -c
+ts-node --cwdMode
+ts-node-cwd
+```
+
+Resolve config relative to the current directory instead of the directory of the entrypoint script
+
+### compilerOptions
+
+```shell
+ts-node -O <json compilerOptions>
+ts-node --compilerOptions <json compilerOptions>
+```
+
+JSON object to merge with compiler options
+
+*Environment:* `TS_NODE_COMPILER_OPTIONS`
+
+### showConfig
+
+```shell
+ts-node --showConfig
+```
+
+Print resolved `tsconfig.json`, including `ts-node` options, and exit
+
 ## Typechecking
 
-*   `-T, --transpileOnly`   Use TypeScript's faster `transpileModule` <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_TRANSPILE_ONLY`
-*   `--typeCheck`   Opposite of `--transpileOnly` <br/>*Default:* `true`<br/>*Environment:* `TS_NODE_TYPE_CHECK`
-*   `-H, --compilerHost`   Use TypeScript's compiler host API <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_COMPILER_HOST`
-*   `--files`   Load `files`, `include` and `exclude` from `tsconfig.json` on startup <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_FILES`
-*   `-D, --ignoreDiagnostics [code]`   Ignore TypeScript warnings by diagnostic code <br/>*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS`
+### transpileOnly
 
-## Transpilation
+```shell
+ts-node -T
+ts-node --transpileOnly
+```
 
-*   `-I, --ignore [pattern]`   Override the path patterns to skip compilation <br/>*Default:* `/node_modules/` <br/>*Environment:* `TS_NODE_IGNORE`
-*   `--skipIgnore`   Skip ignore checks <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_SKIP_IGNORE`
-*   `-C, --compiler [name]`   Specify a custom TypeScript compiler <br/>*Default:* `typescript` <br/>*Environment:* `TS_NODE_COMPILER`
-*   `--swc`   Transpile with [swc](#swc).  Implies `--transpileOnly` <br/>*Default:* `false`
-*   `--transpiler [name]`   Specify a third-party, non-typechecking transpiler
-*   `--preferTsExts`   Re-order file extensions so that TypeScript imports are preferred <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_PREFER_TS_EXTS`
+Use TypeScript's faster `transpileModule`
 
-## Diagnostics
+*Default:* `false`<br/>
+*Environment:* `TS_NODE_TRANSPILE_ONLY`
 
-*   `--logError`   Logs TypeScript errors to stderr instead of throwing exceptions <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_LOG_ERROR`
-*   `--pretty`   Use pretty diagnostic formatter <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_PRETTY`
-*   `TS_NODE_DEBUG` Enable debug logging<br/>
+### typeCheck
 
-## Advanced
+```shell
+ts-node --typeCheck
+```
 
-*   `-r, --require [path]`   Require a node module before execution
-*   `--cwd`   Behave as if invoked in this working directory <br/>*Default:* `process.cwd()`<br/>*Environment:* `TS_NODE_CWD`
-*   `--emit`   Emit output files into `.ts-node` directory <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_EMIT`
-*   `--scope`  Scope compiler to files within `scopeDir`.  Anything outside this directory is ignored. <br/>\*Default: `false` <br/>*Environment:* `TS_NODE_SCOPE`
-*   `--scopeDir` Directory within which compiler is limited when `scope` is enabled. <br/>*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.<br/>*Environment:* `TS_NODE_SCOPE_DIR`
-*   `moduleTypes`  Override the module type of certain files, ignoring the `package.json` `"type"` field.  See [Module type overrides](#module-type-overrides) for details.<br/>*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"` <br/>*Can only be specified via `tsconfig.json` or API.*
-*   `TS_NODE_HISTORY` Path to history file for REPL <br/>*Default:* `~/.ts_node_repl_history`<br/>
-*   `--noExperimentalReplAwait` Disable top-level await in REPL.  Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)<br/>*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.<br/>*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable
-*   `experimentalResolverFeatures` Enable experimental features that re-map imports and require calls to support: `baseUrl`, `paths`, `rootDirs`, `.js` to `.ts` file extension mappings, `outDir` to `rootDir` mappings for composite projects and monorepos.  For details, see [#1514](https://github.com/TypeStrong/ts-node/issues/1514)<br/>*Default:* `false`<br/>*Can only be specified via `tsconfig.json` or API.*
+Opposite of `--transpileOnly`
 
-## API
+*Default:* `true`<br/>
+*Environment:* `TS_NODE_TYPE_CHECK`
 
+### compilerHost
+
+```shell
+ts-node -H
+ts-node --compilerHost
+```
+
+Use TypeScript's compiler host API
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_COMPILER_HOST`
+
+### files
+
+```shell
+ts-node --files
+```
+
+Load `files`, `include` and `exclude` from `tsconfig.json` on startup.  This may
+avoid certain typechecking failures.  See [Missing types](#missing-types) for details.
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_FILES`
+
+### ignoreDiagnostics
+
+```shell
+ts-node -D <code,code>
+ts-node --ignoreDiagnostics <code,code>
+```
+
+Ignore TypeScript warnings by diagnostic code
+
+*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS`
+
+## Transpilation Options
+
+### ignore
+
+```shell
+ts-node -I <regexp matching ignored files>
+ts-node --ignore <regexp matching ignored files>
+```
+
+Override the path patterns to skip compilation
+
+*Default:* `/node_modules/` <br/>
+*Environment:* `TS_NODE_IGNORE`
+
+### skipIgnore
+
+```shell
+ts-node --skipIgnore
+```
+
+Skip ignore checks
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_SKIP_IGNORE`
+
+### compiler
+
+```shell
+ts-node -C <name>
+ts-node --compiler <name>
+```
+
+Specify a custom TypeScript compiler
+
+*Default:* `typescript` <br/>
+*Environment:* `TS_NODE_COMPILER`
+
+### swc
+
+```shell
+ts-node --swc
+```
+
+Transpile with [swc](#swc).  Implies `--transpileOnly`
+
+*Default:* `false`
+
+### transpiler
+
+```shell
+ts-node --transpiler <name>
+# Example
+ts-node --transpiler ts-node/transpilers/swc
+```
+
+Use a third-party, non-typechecking transpiler
+
+### preferTsExts
+
+```shell
+ts-node --preferTsExts
+```
+
+Re-order file extensions so that TypeScript imports are preferred
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_PREFER_TS_EXTS`
+
+## Diagnostic Options
+
+### logError
+
+```shell
+ts-node --logError
+```
+
+Logs TypeScript errors to stderr instead of throwing exceptions
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_LOG_ERROR`
+
+### pretty
+
+```shell
+ts-node --pretty
+```
+
+Use pretty diagnostic formatter
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_PRETTY`
+
+### TS_NODE_DEBUG
+
+```shell
+TS_NODE_DEBUG=true ts-node
+```
+
+Enable debug logging
+
+## Advanced Options
+
+### require
+
+```shell
+ts-node -r <module name or path>
+ts-node --require <module name or path>
+```
+
+Require a node module before execution
+
+### cwd
+
+```shell
+ts-node --cwd <path/to/directory>
+```
+
+Behave as if invoked in this working directory
+
+*Default:* `process.cwd()`<br/>
+*Environment:* `TS_NODE_CWD`
+
+### emit
+
+```shell
+ts-node --emit
+```
+
+Emit output files into `.ts-node` directory. Requires `--compilerHost`
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_EMIT`
+
+### scope
+
+```shell
+ts-node --scope
+```
+
+Scope compiler to files within `scopeDir`.  Anything outside this directory is ignored.
+
+*Default:* `false` <br/>
+*Environment:* `TS_NODE_SCOPE`
+
+### scopeDir
+
+```shell
+ts-node --scopeDir <path/to/directory>
+```
+
+Directory within which compiler is limited when `scope` is enabled.
+
+*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.<br/>
+*Environment:* `TS_NODE_SCOPE_DIR`
+
+### moduleTypes
+
+Override the module type of certain files, ignoring the `package.json` `"type"` field.  See [Module type overrides](#module-type-overrides) for details.
+
+*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"` <br/>
+*Can only be specified via `tsconfig.json` or API.*
+
+### TS_NODE_HISTORY
+
+```shell
+TS_NODE_HISTORY=<path/to/history/file> ts-node
+```
+
+Path to history file for REPL
+
+*Default:* `~/.ts_node_repl_history`
+
+### noExperimentalReplAwait
+
+```shell
+ts-node --noExperimentalReplAwait
+```
+
+Disable top-level await in REPL.  Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)
+
+*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.<br/>
+*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable
+
+### experimentalResolver
+
+Enable experimental hooks that re-map imports and require calls to support:
+
+*   remapping extensions, e.g. so that `import "./foo.js"` will execute `foo.ts`. Currently the following extensions will be mapped:
+    *   `.js` to `.ts`, `.tsx`, or `.jsx`
+    *   `.cjs` to `.cts`
+    *   `.mjs` to `.mts`
+    *   `.jsx` to `.tsx`
+*   including file extensions in CommonJS, for consistency with ESM where this is often mandatory
+
+In the future, this hook will also support:
+
+*   `baseUrl`, `paths`
+*   `rootDirs`
+*   `outDir` to `rootDir` mappings for composite projects and monorepos
+
+For details, see [#1514](https://github.com/TypeStrong/ts-node/issues/1514).
+
+*Default:* `false`, but will likely be enabled by default in a future version<br/>
+*Can only be specified via `tsconfig.json` or API.*
+
+### experimentalSpecifierResolution
+
+```shell
+ts-node --experimentalSpecifierResolution node
+```
+
+Like node's [`--experimental-specifier-resolution`](https://nodejs.org/dist/latest-v18.x/docs/api/esm.html#customizing-esm-specifier-resolution-algorithm), but can also be set in your `tsconfig.json` for convenience.
+Requires [`esm`](#esm) to be enabled.
+
+*Default:* `explicit`<br/>
+
+## API Options
+
 The API includes [additional options](https://typestrong.org/ts-node/api/interfaces/RegisterOptions.html) not shown here.
 
+# SWC
+
+SWC support is built-in via the `--swc` flag or `"swc": true` tsconfig option.
+
+[SWC](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust.  This makes it an order of magnitude faster than vanilla `transpileOnly`.
+
+To use it, first install `@swc/core` or `@swc/wasm`.  If using `importHelpers`, also install `@swc/helpers`.  If `target` is less than "es2015" and using `async`/`await` or generator functions, also install `regenerator-runtime`.
+
+```shell
+npm i -D @swc/core @swc/helpers regenerator-runtime
+```
+
+Then add the following to your `tsconfig.json`.
+
+```jsonc title="tsconfig.json"
+{
+  "ts-node": {
+    "swc": true
+  }
+}
+```
+
+> SWC uses `@swc/helpers` instead of `tslib`.  If you have enabled `importHelpers`, you must also install `@swc/helpers`.
+
 # CommonJS vs native ECMAScript modules
@@ -462,3 +886,3 @@
 
-## Understanding configuration
+## Configuration
 
@@ -513,3 +937,3 @@ ts-node uses sensible default configurations to reduce boilerplate while still respecting `tsconfig.json` if you
 
-## Understanding Errors
+## Common errors
 
@@ -545,4 +969,99 @@ It is important to differentiate between errors from ts-node, errors from the TypeScript compiler, and errors from `node`.  It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration.
 
-# Make it fast
+### `ERR_REQUIRE_ESM`
 
+This error is thrown by node when a module is `require()`d, but node believes it should execute as native ESM.  This can happen for a few reasons:
+
+*   You have installed an ESM dependency but your own code compiles to CommonJS.
+    *   Solution: configure your project to compile and execute as native ESM. [Docs](#native-ecmascript-modules)
+    *   Solution: downgrade the dependency to an older, CommonJS version.
+*   You have moved your project to ESM but still have a config file, such as `webpack.config.ts`, which must be executed as CommonJS <!-- SYNC_WITH_MTO_DOCS -->
+    *   Solution: if supported by the relevant tool, rename your config file to `.cts`
+    *   Solution: Configure a module type override. [Docs](#module-type-overrides)
+*   You have a mix of CommonJS and native ESM in your project
+    *   Solution: double-check all package.json "type" and tsconfig.json "module" configuration [Docs](#commonjs-vs-native-ecmascript-modules)
+    *   Solution: consider simplifying by making your project entirely CommonJS or entirely native ESM
+
+### `ERR_UNKNOWN_FILE_EXTENSION`
+
+This error is thrown by node when a module has an unrecognized file extension, or no extension at all, and is being executed as native ESM.  This can happen for a few reasons:
+
+*   You are using a tool which has an extensionless binary, such as `mocha`.
+    *   CommonJS supports extensionless files but native ESM does not.
+    *   Solution: upgrade to ts-node >=[v10.6.0](https://github.com/TypeStrong/ts-node/releases/tag/v10.6.0), which implements a workaround.
+*   Our ESM loader is not installed.
+    *   Solution: Use `ts-node-esm`, `ts-node --esm`, or add `"ts-node": {"esm": true}` to your tsconfig.json.  [Docs](#native-ecmascript-modules)
+*   You have moved your project to ESM but still have a config file, such as `webpack.config.ts`, which must be executed as CommonJS <!-- SYNC_WITH_MTO_DOCS -->
+    *   Solution: if supported by the relevant tool, rename your config file to `.cts`
+    *   Solution: Configure a module type override. [Docs](#module-type-overrides)
+
+## Missing Types
+
+ts-node does *not* eagerly load `files`, `include` or `exclude` by default. This is because a large majority of projects do not use all of the files in a project directory (e.g. `Gulpfile.ts`, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. `ts-node index.ts`) and TypeScript resolves dependencies based on imports and references.
+
+Occasionally, this optimization leads to missing types. Fortunately, there are other ways to include them in typechecking.
+
+For global definitions, you can use the `typeRoots` compiler option.  This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types).
+
+Example `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "typeRoots" : ["./node_modules/@types", "./typings"]
+  }
+}
+```
+
+Example project structure:
+
+```text
+<project_root>/
+-- tsconfig.json
+-- typings/
+  -- <module_name>/
+    -- index.d.ts
+```
+
+Example module declaration file:
+
+```typescript twoslash
+declare module '<module_name>' {
+    // module definitions go here
+}
+```
+
+For module definitions, you can use [`paths`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping):
+
+```jsonc title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "custom-module-type": ["types/custom-module-type"]
+    }
+  }
+}
+```
+
+Another option is [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). This may be helpful if you prefer not to change your `compilerOptions` or structure your type definitions for `typeRoots`. Below is an example of a triple-slash directive as a relative path within your project:
+
+```typescript twoslash
+/// <reference path="./types/lib_greeter" />
+import {Greeter} from "lib_greeter"
+const g = new Greeter();
+g.sayHello();
+```
+
+If none of the above work, and you *must* use `files`, `include`, or `exclude`, enable our [`files`](#files) option.
+
+## npx, yarn dlx, and node_modules
+
+When executing TypeScript with `npx` or `yarn dlx`, the code resides within a temporary `node_modules` directory.
+
+The contents of `node_modules` are ignored by default.  If execution fails, enable [`skipIgnore`](#skipignore).
+
+<!--See also: [npx and yarn dlx](./recipes/npx-and-yarn-dlx.md)-->
+
+# Performance
+
 These tricks will make ts-node faster.
@@ -552,10 +1071,14 @@
 
-It is often better to use `tsc --noEmit` to typecheck once before your tests run or as a lint step. In these cases, ts-node can skip typechecking.
+It is often better to typecheck as part of your tests or linting.  You can run `tsc --noEmit` to do this.  In these cases, ts-node can skip typechecking, making it much faster.
 
-*   Enable [`transpileOnly`](#options) to skip typechecking
-*   Use our [`swc` integration](#swc)
+To skip typechecking in ts-node, do one of the following:
+
+*   Enable [swc](#swc)
     *   This is by far the fastest option
+*   Enable [`transpileOnly`](#transpileonly) to skip typechecking without swc
 
 ## With typechecking
 
+If you absolutely must typecheck in ts-node:
+
 *   Avoid dynamic `require()` which may trigger repeated typechecking; prefer `import`
@@ -569,3 +1092,3 @@ *   Try with and without `--files`; one may be faster depending on your project
 
-## How It Works
+## How it works
 
@@ -576,2 +1099,17 @@ ts-node works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions.
 
+We also register a few other hooks to apply sourcemaps to stack traces and remap from `.js` imports to `.ts`.
+
+## Ignored files
+
+ts-node transforms certain files and ignores others.  We refer to this mechanism as "scoping."  There are various
+options to configure scoping, so that ts-node transforms only the files in your project.
+
+> **Warning:**
+>
+> An ignored file can still be executed by node.js.  Ignoring a file means we do not transform it from TypeScript into JavaScript, but it does not prevent execution.
+>
+> If a file requires transformation but is ignored, node may either fail to resolve it or attempt to execute it as vanilla JavaScript.  This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.
+
+### File extensions
+
 `.js` and `.jsx` are only transformed when [`allowJs`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) is enabled.
@@ -581,6 +1119,6 @@
 
-> **Warning:** if a file is ignored or its file extension is not registered, node will either fail to resolve the file or will attempt to execute it as JavaScript without any transformation.  This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.
+> **Warning:**
+>
+> When ts-node is used with `allowJs`, *all* non-ignored JavaScript files are transformed by ts-node.
 
-> **Warning:** When ts-node is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler.
-
 ### Skipping `node_modules`
@@ -594,3 +1132,3 @@
 
-If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](#transpilation) or [`TS_NODE_SKIP_IGNORE`](#transpilation) to bypass this restriction.
+If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](#skipignore) or [`TS_NODE_SKIP_IGNORE`](#skipignore) to bypass this restriction.
 
@@ -601,4 +1139,13 @@ ### Skipping pre-compiled TypeScript
 
-To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](#transpilation).
+To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](#prefertsexts).
 
+### Scope by directory
+
+Our [`scope`](#scope) and [`scopeDir`](#scopedir) options will limit transformation to files
+within a directory.
+
+### Ignore by regexp
+
+Our [`ignore`](#ignore) option will ignore files matching one or more regular expressions.
+
 ## paths and baseUrl&#xA;
@@ -628,60 +1175,2 @@
 
-## Help! My Types Are Missing!
-
-ts-node does *not* use `files`, `include` or `exclude`, by default. This is because a large majority projects do not use all of the files in a project directory (e.g. `Gulpfile.ts`, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. `ts-node index.ts`) and TypeScript resolves dependencies based on imports and references.
-
-For global definitions, you can use the `typeRoots` compiler option.  This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types).
-
-Example `tsconfig.json`:
-
-```jsonc
-{
-  "compilerOptions": {
-    "typeRoots" : ["./node_modules/@types", "./typings"]
-  }
-}
-```
-
-Example project structure:
-
-```text
-<project_root>/
--- tsconfig.json
--- typings/
-  -- <module_name>/
-    -- index.d.ts
-```
-
-Example module declaration file:
-
-```typescript twoslash
-declare module '<module_name>' {
-    // module definitions go here
-}
-```
-
-For module definitions, you can use [`paths`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping):
-
-```jsonc title="tsconfig.json"
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "custom-module-type": ["types/custom-module-type"]
-    }
-  }
-}
-```
-
-An alternative approach for definitions of third-party libraries are [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). This may be helpful if you prefer not to change your TypeScript `compilerOptions` or structure your custom type definitions when using `typeRoots`. Below is an example of the triple-slash directive as a relative path within your project:
-
-```typescript twoslash
-/// <reference path="./types/untyped_js_lib" />
-import {Greeter} from "untyped_js_lib"
-const g = new Greeter();
-g.sayHello();
-```
-
-**Tip:** If you *must* use `files`, `include`, or `exclude`, enable `--files` flags or set `TS_NODE_FILES=true`.
-
 ## Third-party compilers
@@ -712,7 +1201,6 @@
 
-In transpile-only mode, we skip typechecking to speed up execution time.  You can go a step further and use a
-third-party transpiler to transform TypeScript into JavaScript even faster.  You will still benefit from
-ts-node's automatic `tsconfig.json` discovery, sourcemap support, and global ts-node CLI.  Integrations
-can automatically derive an appropriate configuration from your existing `tsconfig.json` which simplifies project
-boilerplate.
+ts-node supports third-party transpilers as plugins.  Transpilers such as swc can transform TypeScript into JavaScript
+much faster than the TypeScript compiler.  You will still benefit from ts-node's automatic `tsconfig.json` discovery,
+sourcemap support, and global ts-node CLI. Plugins automatically derive an appropriate configuration from your existing
+`tsconfig.json` which simplifies project boilerplate.
 
@@ -724,33 +1212,9 @@ > **What is the difference between a compiler and a transpiler?**
 
-### swc
+### Third-party plugins
 
-swc support is built-in via the `--swc` flag or `"swc": true` tsconfig option.
+The `transpiler` option allows using third-party transpiler plugins with ts-node.  `transpiler` must be given the
+name of a module which can be `require()`d.  The built-in `swc` plugin is exposed as `ts-node/transpilers/swc`.
 
-[`swc`](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust.  This makes it an order of magnitude faster than vanilla `transpileOnly`.
+For example, to use a hypothetical "@cspotcode/fast-ts-compiler", first install it into your project: `npm install @cspotcode/fast-ts-compiler`
 
-To use it, first install `@swc/core` or `@swc/wasm`.  If using `importHelpers`, also install `@swc/helpers`.  If `target` is less than "es2015" and using either `async`/`await` or generator functions, also install `regenerator-runtime`.
-
-```shell
-npm i -D @swc/core @swc/helpers regenerator-runtime
-```
-
-Then add the following to your `tsconfig.json`.
-
-```jsonc title="tsconfig.json"
-{
-  "ts-node": {
-    "swc": true
-  }
-}
-```
-
-> `swc` uses `@swc/helpers` instead of `tslib`.  If you have enabled `importHelpers`, you must also install `@swc/helpers`.
-
-### Third-party transpilers
-
-The `transpiler` option allows using third-party transpiler integrations with ts-node.  `transpiler` must be given the
-name of a module which can be `require()`d.  The built-in `swc` integration is exposed as `ts-node/transpilers/swc`.
-
-For example, to use a hypothetical "speedy-ts-compiler", first install it into your project: `npm install speedy-ts-compiler`
-
 Then add the following to your tsconfig:
@@ -762,3 +1226,3 @@
     "transpileOnly": true,
-    "transpiler": "speedy-ts-compiler"
+    "transpiler": "@cspotcode/fast-ts-compiler"
   }
@@ -768,25 +1232,33 @@ }
 
-### Writing your own integration
+### Write your own plugin
 
-To write your own transpiler integration, check our [API docs](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html).
+To write your own transpiler plugin, check our [API docs](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html).
 
-Integrations are `require()`d by ts-node, so they can be published to npm for convenience.  The module must export a `create` function described by our
-[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface.  `create` is invoked by ts-node
-at startup to create the transpiler.  The transpiler is used repeatedly to transform TypeScript into JavaScript.
+Plugins are `require()`d by ts-node, so they can be a local script or a node module published to npm.  The module must
+export a `create` function described by our
+[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface.  `create` is
+invoked by ts-node at startup to create one or more transpiler instances.  The instances are used to transform
+TypeScript into JavaScript.
 
+For a working example, check out out our bundled swc plugin: https://github.com/TypeStrong/ts-node/blob/main/src/transpilers/swc.ts
+
 ## Module type overrides
 
-When deciding between CommonJS and native ECMAScript modules, ts-node defaults to matching vanilla `node` and `tsc`
-behavior.  This means TypeScript files are transformed according to your `tsconfig.json` `"module"` option and executed
-according to node's rules for the `package.json` `"type"` field.
+> Wherever possible, it is recommended to use TypeScript's [`NodeNext` or `Node16` mode](https://www.typescriptlang.org/docs/handbook/esm-node.html) instead of the options described
+> in this section.  Setting `"module": "NodeNext"` and using the `.cts` file extension should work well for most projects.
 
-In some projects you may need to override this behavior for some files.  For example, in a webpack
-project, you may have `package.json` configured with `"type": "module"` and `tsconfig.json` with
-`"module": "esnext"`.  However, webpack uses our CommonJS hook to execute your `webpack.config.ts`,
-so you need to force your webpack config and any supporting scripts to execute as CommonJS.
+When deciding how a file should be compiled and executed -- as either CommonJS or native ECMAScript module -- ts-node matches
+`node` and `tsc` behavior.  This means TypeScript files are transformed according to your `tsconfig.json` `"module"`
+option and executed according to node's rules for the `package.json` `"type"` field.  Set `"module": "NodeNext"` and everything should work.
 
-In these situations, our `moduleTypes` option lets you override certain files, forcing execution as
-CommonJS or ESM.  Node supports similar overriding via `.cjs` and `.mjs` file extensions, but `.ts` files cannot use them.
-`moduleTypes` achieves the same effect, and *also* overrides your `tsconfig.json` `"module"` config appropriately.
+In rare cases, you may need to override this behavior for some files.  For example, some tools read a `name-of-tool.config.ts`
+and require that file to execute as CommonJS.  If you have `package.json` configured with `"type": "module"` and `tsconfig.json` with
+`"module": "esnext"`, the config is native ECMAScript by default and will raise an error.  You will need to force the config and
+any supporting scripts to execute as CommonJS.
 
+In these situations, our `moduleTypes` option can override certain files to be
+CommonJS or ESM.  Similar overriding is possible by using `.mts`, `.cts`, `.cjs` and `.mjs` file extensions.
+`moduleTypes` achieves the same effect for `.ts` and `.js` files, and *also* overrides your `tsconfig.json` `"module"`
+config appropriately.
+
 The following example tells ts-node to execute a webpack config as CommonJS:
@@ -824,10 +1296,25 @@
 
+## API
+
+ts-node's complete API is documented here: [API Docs](https://typestrong.org/ts-node/api/)
+
+Here are a few highlights of what you can accomplish:
+
+*   [`create()`](https://typestrong.org/ts-node/api/index.html#create) creates ts-node's compiler service without
+    registering any hooks.
+*   [`createRepl()`](https://typestrong.org/ts-node/api/index.html#createRepl) creates an instance of our REPL service, so
+    you can create your own TypeScript-powered REPLs.
+*   [`createEsmHooks()`](https://typestrong.org/ts-node/api/index.html#createEsmHooks) creates our ESM loader hooks,
+    suitable for composing with other loaders or augmenting with additional features.
+
 # Recipes
 
-## Watching and Restarting
+## Watching and restarting
 
-**TypeScript Node** compiles source code via `require()`, watching files and code reloads are out of scope for the project. If you want to restart the `ts-node` process on file change, existing node.js tools such as [nodemon](https://github.com/remy/nodemon), [onchange](https://github.com/Qard/onchange) and [node-dev](https://github.com/fgnass/node-dev) work.
+ts-node focuses on adding first-class TypeScript support to node.  Watching files and code reloads are out of scope for the project.
 
-There's also [`ts-node-dev`](https://github.com/whitecolor/ts-node-dev), a modified version of [`node-dev`](https://github.com/fgnass/node-dev) using `ts-node` for compilation that will restart the process on file change.
+If you want to restart the `ts-node` process on file change, existing node.js tools such as [nodemon](https://github.com/remy/nodemon), [onchange](https://github.com/Qard/onchange) and [node-dev](https://github.com/fgnass/node-dev) work.
 
+There's also [`ts-node-dev`](https://github.com/whitecolor/ts-node-dev), a modified version of [`node-dev`](https://github.com/fgnass/node-dev) using `ts-node` for compilation that will restart the process on file change. Note that `ts-node-dev` is incompatible with our native ESM loader.
+
 ## AVA
@@ -834,0 +1321,0 @@

tsconfig.schema.json

@@ -38,3 +38,3 @@ {
                 "esm": {
-                    "description": "TODO DOCS YAY",
+                    "description": "Enable native ESM support.\n\nFor details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules",
                     "type": "boolean"
@@ -46,6 +46,18 @@ },
                 },
-                "experimentalResolverFeatures": {
+                "experimentalResolver": {
                     "description": "Enable experimental features that re-map imports and require calls to support:\n`baseUrl`, `paths`, `rootDirs`, `.js` to `.ts` file extension mappings,\n`outDir` to `rootDir` mappings for composite projects and monorepos.\n\nFor details, see https://github.com/TypeStrong/ts-node/issues/1514",
                     "type": "boolean"
                 },
+                "experimentalSpecifierResolution": {
+                    "description": "Like node's `--experimental-specifier-resolution`, , but can also be set in your `tsconfig.json` for convenience.\n\nFor details, see https://nodejs.org/dist/latest-v18.x/docs/api/esm.html#customizing-esm-specifier-resolution-algorithm",
+                    "enum": [
+                        "explicit",
+                        "node"
+                    ],
+                    "type": "string"
+                },
+                "experimentalTsImportSpecifiers": {
+                    "description": "Allow using voluntary `.ts` file extension in import specifiers.\n\nTypically, in ESM projects, import specifiers must have an emit extension, `.js`, `.cjs`, or `.mjs`,\nand we automatically map to the corresponding `.ts`, `.cts`, or `.mts` source file.  This is the\nrecommended approach.\n\nHowever, if you really want to use `.ts` in import specifiers, and are aware that this may\nbreak tooling, you can enable this flag.",
+                    "type": "boolean"
+                },
                 "files": {
@@ -83,3 +95,3 @@ "default": false,
                     "$ref": "#/definitions/ModuleTypes",
-                    "description": "Override certain paths to be compiled and executed as CommonJS or ECMAScript modules.\nWhen overridden, the tsconfig \"module\" and package.json \"type\" fields are overridden.\nThis is useful because TypeScript files cannot use the .cjs nor .mjs file extensions;\nit achieves the same effect.\n\nEach key is a glob pattern following the same rules as tsconfig's \"include\" array.\nWhen multiple patterns match the same file, the last pattern takes precedence.\n\n`cjs` overrides matches files to compile and execute as CommonJS.\n`esm` overrides matches files to compile and execute as native ECMAScript modules.\n`package` overrides either of the above to default behavior, which obeys package.json \"type\" and\ntsconfig.json \"module\" options."
+                    "description": "Override certain paths to be compiled and executed as CommonJS or ECMAScript modules.\nWhen overridden, the tsconfig \"module\" and package.json \"type\" fields are overridden, and\nthe file extension is ignored.\nThis is useful if you cannot use .mts, .cts, .mjs, or .cjs file extensions;\nit achieves the same effect.\n\nEach key is a glob pattern following the same rules as tsconfig's \"include\" array.\nWhen multiple patterns match the same file, the last pattern takes precedence.\n\n`cjs` overrides matches files to compile and execute as CommonJS.\n`esm` overrides matches files to compile and execute as native ECMAScript modules.\n`package` overrides either of the above to default behavior, which obeys package.json \"type\" and\ntsconfig.json \"module\" options."
                 },
@@ -86,0 +98,0 @@ "preferTsExts": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

746842

increased by19.11%

Dev dependency count

31

decreased by-3.12%

Number of package files

117

increased by15.84%

Lines of code

8255

increased by18.2%

Number of lines in readme file

1443

increased by50.94%

Worsened metrics

Number of low supply chain risk alerts

32

increased by14.29%