@@ -6006,19 +6006,67 @@ declare namespace ts {
6006
6006
isSourceFileFromExternalLibrary(file: SourceFile): boolean;
6007
6007
isSourceFileDefaultLibrary(file: SourceFile): boolean;
6008
6008
/**
6009
- * Calculates the final resolution mode for a given module reference node. This is the resolution mode explicitly provided via import
6010
- * attributes, if present, or the syntax the usage would have if emitted to JavaScript. In `--module node16` or `nodenext`, this may
6011
- * depend on the file's `impliedNodeFormat`. In `--module preserve`, it depends only on the input syntax of the reference. In other
6012
- * `module` modes, when overriding import attributes are not provided, this function returns `undefined`, as the result would have no
6013
- * impact on module resolution, emit, or type checking.
6009
+ * Calculates the final resolution mode for a given module reference node. This function only returns a result when module resolution
6010
+ * settings allow differing resolution between ESM imports and CJS requires, or when a mode is explicitly provided via import attributes,
6011
+ * which cause an `import` or `require` condition to be used during resolution regardless of module resolution settings. In absence of
6012
+ * overriding attributes, and in modes that support differing resolution, the result indicates the syntax the usage would emit to JavaScript.
6013
+ * Some examples:
6014
+ *
6015
+ * ```ts
6016
+ * // tsc foo.mts --module nodenext
6017
+ * import {} from "mod";
6018
+ * // Result: ESNext - the import emits as ESM due to `impliedNodeFormat` set by .mts file extension
6019
+ *
6020
+ * // tsc foo.cts --module nodenext
6021
+ * import {} from "mod";
6022
+ * // Result: CommonJS - the import emits as CJS due to `impliedNodeFormat` set by .cts file extension
6023
+ *
6024
+ * // tsc foo.ts --module preserve --moduleResolution bundler
6025
+ * import {} from "mod";
6026
+ * // Result: ESNext - the import emits as ESM due to `--module preserve` and `--moduleResolution bundler`
6027
+ * // supports conditional imports/exports
6028
+ *
6029
+ * // tsc foo.ts --module preserve --moduleResolution node10
6030
+ * import {} from "mod";
6031
+ * // Result: undefined - the import emits as ESM due to `--module preserve`, but `--moduleResolution node10`
6032
+ * // does not support conditional imports/exports
6033
+ *
6034
+ * // tsc foo.ts --module commonjs --moduleResolution node10
6035
+ * import type {} from "mod" with { "resolution-mode": "import" };
6036
+ * // Result: ESNext - conditional imports/exports always supported with "resolution-mode" attribute
6037
+ * ```
6014
6038
*/
6015
6039
getModeForUsageLocation(file: SourceFile, usage: StringLiteralLike): ResolutionMode;
6016
6040
/**
6017
- * Calculates the final resolution mode for an import at some index within a file's `imports` list. This is the resolution mode
6018
- * explicitly provided via import attributes, if present, or the syntax the usage would have if emitted to JavaScript. In
6019
- * `--module node16` or `nodenext`, this may depend on the file's `impliedNodeFormat`. In `--module preserve`, it depends only on the
6020
- * input syntax of the reference. In other `module` modes, when overriding import attributes are not provided, this function returns
6021
- * `undefined`, as the result would have no impact on module resolution, emit, or type checking.
6041
+ * Calculates the final resolution mode for an import at some index within a file's `imports` list. This function only returns a result
6042
+ * when module resolution settings allow differing resolution between ESM imports and CJS requires, or when a mode is explicitly provided
6043
+ * via import attributes, which cause an `import` or `require` condition to be used during resolution regardless of module resolution
6044
+ * settings. In absence of overriding attributes, and in modes that support differing resolution, the result indicates the syntax the
6045
+ * usage would emit to JavaScript. Some examples:
6046
+ *
6047
+ * ```ts
6048
+ * // tsc foo.mts --module nodenext
6049
+ * import {} from "mod";
6050
+ * // Result: ESNext - the import emits as ESM due to `impliedNodeFormat` set by .mts file extension
6051
+ *
6052
+ * // tsc foo.cts --module nodenext
6053
+ * import {} from "mod";
6054
+ * // Result: CommonJS - the import emits as CJS due to `impliedNodeFormat` set by .cts file extension
6055
+ *
6056
+ * // tsc foo.ts --module preserve --moduleResolution bundler
6057
+ * import {} from "mod";
6058
+ * // Result: ESNext - the import emits as ESM due to `--module preserve` and `--moduleResolution bundler`
6059
+ * // supports conditional imports/exports
6060
+ *
6061
+ * // tsc foo.ts --module preserve --moduleResolution node10
6062
+ * import {} from "mod";
6063
+ * // Result: undefined - the import emits as ESM due to `--module preserve`, but `--moduleResolution node10`
6064
+ * // does not support conditional imports/exports
6065
+ *
6066
+ * // tsc foo.ts --module commonjs --moduleResolution node10
6067
+ * import type {} from "mod" with { "resolution-mode": "import" };
6068
+ * // Result: ESNext - conditional imports/exports always supported with "resolution-mode" attribute
6069
+ * ```
6022
6070
*/
6023
6071
getModeForResolutionAtIndex(file: SourceFile, index: number): ResolutionMode;
6024
6072
getProjectReferences(): readonly ProjectReference[] | undefined;
@@ -9366,24 +9414,43 @@ declare namespace ts {
9366
9414
function getModeForResolutionAtIndex(file: SourceFile, index: number, compilerOptions: CompilerOptions): ResolutionMode;
9367
9415
/**
9368
9416
* Use `program.getModeForUsageLocation`, which retrieves the correct `compilerOptions`, instead of this function whenever possible.
9369
- * Calculates the final resolution mode for a given module reference node. This is the resolution mode explicitly provided via import
9370
- * attributes, if present, or the syntax the usage would have if emitted to JavaScript. In `--module node16` or `nodenext`, this may
9371
- * depend on the file's `impliedNodeFormat`. In `--module preserve`, it depends only on the input syntax of the reference. In other
9372
- * `module` modes, when overriding import attributes are not provided, this function returns `undefined`, as the result would have no
9373
- * impact on module resolution, emit, or type checking.
9417
+ * Calculates the final resolution mode for a given module reference node. This function only returns a result when module resolution
9418
+ * settings allow differing resolution between ESM imports and CJS requires, or when a mode is explicitly provided via import attributes,
9419
+ * which cause an `import` or `require` condition to be used during resolution regardless of module resolution settings. In absence of
9420
+ * overriding attributes, and in modes that support differing resolution, the result indicates the syntax the usage would emit to JavaScript.
9421
+ * Some examples:
9422
+ *
9423
+ * ```ts
9424
+ * // tsc foo.mts --module nodenext
9425
+ * import {} from "mod";
9426
+ * // Result: ESNext - the import emits as ESM due to `impliedNodeFormat` set by .mts file extension
9427
+ *
9428
+ * // tsc foo.cts --module nodenext
9429
+ * import {} from "mod";
9430
+ * // Result: CommonJS - the import emits as CJS due to `impliedNodeFormat` set by .cts file extension
9431
+ *
9432
+ * // tsc foo.ts --module preserve --moduleResolution bundler
9433
+ * import {} from "mod";
9434
+ * // Result: ESNext - the import emits as ESM due to `--module preserve` and `--moduleResolution bundler`
9435
+ * // supports conditional imports/exports
9436
+ *
9437
+ * // tsc foo.ts --module preserve --moduleResolution node10
9438
+ * import {} from "mod";
9439
+ * // Result: undefined - the import emits as ESM due to `--module preserve`, but `--moduleResolution node10`
9440
+ * // does not support conditional imports/exports
9441
+ *
9442
+ * // tsc foo.ts --module commonjs --moduleResolution node10
9443
+ * import type {} from "mod" with { "resolution-mode": "import" };
9444
+ * // Result: ESNext - conditional imports/exports always supported with "resolution-mode" attribute
9445
+ * ```
9446
+ *
9374
9447
* @param file The file the import or import-like reference is contained within
9375
9448
* @param usage The module reference string
9376
9449
* @param compilerOptions The compiler options for the program that owns the file. If the file belongs to a referenced project, the compiler options
9377
9450
* should be the options of the referenced project, not the referencing project.
9378
9451
* @returns The final resolution mode of the import
9379
9452
*/
9380
- function getModeForUsageLocation(
9381
- file: {
9382
- impliedNodeFormat?: ResolutionMode;
9383
- },
9384
- usage: StringLiteralLike,
9385
- compilerOptions: CompilerOptions,
9386
- ): ModuleKind.CommonJS | ModuleKind.ESNext | undefined;
9453
+ function getModeForUsageLocation(file: SourceFile, usage: StringLiteralLike, compilerOptions: CompilerOptions): ResolutionMode;
9387
9454
function getConfigFileParsingDiagnostics(configFileParseResult: ParsedCommandLine): readonly Diagnostic[];
9388
9455
/**
9389
9456
* A function for determining if a given file is esm or cjs format, assuming modern node module resolution rules, as configured by the
0 commit comments