Update module docs for 5.4 changes (#3063)

Author: andrewbranch

package.json

@@ -23,7 +23,7 @@
     "@types/react": "16.9.17",
     "@types/estree": "0.0.46",
     "node-gyp": "5.1.0",
-    "typescript": "5.0.2",
+    "typescript": "5.4.5",
     "tslib": "2.6.0",
     "prettier": "^2.0.2",
     "shelljs": "0.8.4",

packages/documentation/copy/en/modules-reference/Reference.md

@@ -272,6 +272,41 @@ const dynamic = import("mod"); // not transformed
 - ESM emit transforms `import x = require("...")` to a `require` call constructed from a `createRequire` import.
 - CommonJS emit leaves dynamic `import()` calls untransformed, so CommonJS modules can asynchronously import ES modules.
 
+### `preserve`
+
+In `--module preserve` ([added](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-4.html#support-for-require-calls-in---moduleresolution-bundler-and---module-preserve) in TypeScript 5.4), ECMAScript imports and exports written in input files are preserved in the output, and CommonJS-style `import x = require("...")` and `export = ...` statements are emitted as CommonJS `require` and `module.exports`. In other words, the format of each individual import or export statement is preserved, rather than being coerced into a single format for the whole compilation (or even a whole file).
+
+While it’s rare to need to mix imports and require calls in the same file, this `module` mode best reflects the capabilities of most modern bundlers, as well as the Bun runtime.
+
+> Why care about TypeScript’s `module` emit with a bundler or with Bun, where you’re likely also setting `noEmit`? TypeScript’s type checking and module resolution behavior are affected by the module format that it _would_ emit. Setting `module` gives TypeScript information about how your bundler or runtime will process imports and exports, which ensures that the types you see on imported values accurately reflect what will happen at runtime or after bundling. See [`--moduleResolution bundler`](#bundler) for more discussion.
+
+#### Examples
+
+```ts
+import x, { y, z } from "mod";
+import mod = require("mod");
+const dynamic = import("mod");
+
+export const e1 = 0;
+export default "default export";
+```
+
+```js
+import x, { y, z } from "mod";
+const mod = require("mod");
+const dynamic = import("mod");
+
+export const e1 = 0;
+export default "default export";
+```
+
+#### Implied and enforced options
+
+- `--module preserve` implies `--moduleResolution bundler`.
+- `--module preserve` implies `--esModuleInterop`.
+
+> The option `--esModuleInterop` is enabled by default in `--module preserve` only for its [type checking](https://www.typescriptlang.org/docs/handbook/modules/appendices/esm-cjs-interop.html#allowsyntheticdefaultimports-and-esmoduleinterop) behavior. Since imports never transform into require calls in `--module preserve`, `--esModuleInterop` does not affect the emitted JavaScript.
+
 ### `es2015`, `es2020`, `es2022`, `esnext`
 
 #### Summary
@@ -1083,42 +1118,38 @@ Features are listed in order of precedence.
 
 `--moduleResolution bundler` attempts to model the module resolution behavior common to most JavaScript bundlers. In short, this means supporting all the behaviors traditionally associated with Node.js’s CommonJS `require` resolution algorithm like [`node_modules` lookups](#node_modules-package-lookups), [directory modules](#directory-modules-index-file-resolution), and [extensionless paths](#extensionless-relative-paths), while also supporting newer Node.js resolution features like [package.json `"exports"`](#packagejson-exports) and [package.json `"imports"`](#packagejson-imports-and-self-name-imports).
 
-This is very similar to the behavior of [`node16` and `nodenext`](#node16-nodenext-1) resolving in CommonJS mode, but in `bundler`, the conditions used to resolve package.json `"exports"` and `"imports"` are always `"types"` and `"import"`. To understand why, let’s compare against what happens to an import in a `.ts` file in `nodenext`:
+It’s instructive to think about the similarities and differences between `--moduleResolution bundler` and `--moduleResolution nodenext`, particularly in how they decide what conditions to use when resolving package.json `"exports"` or `"imports"`. Consider an import statement in a `.ts` file:
 
 ```ts
 // index.ts
 import { foo } from "pkg";
 ```
 
-In `--module nodenext --moduleResolution nodenext`, the `--module` setting first [determines](#module-format-detection) whether the import will be emitted to the `.js` file as an `import` or `require` call and passes that information to TypeScript’s module resolver, which decides whether to match `"import"` or `"require"` conditions accordingly. This ensures TypeScript’s module resolution process, although working from input `.ts` files, reflects what will happen in Node.js’s module resolution process when it runs the output `.js` files.
+Recall that in `--module nodenext --moduleResolution nodenext`, the `--module` setting first [determines](#module-format-detection) whether the import will be emitted to the `.js` file as an `import` or `require` call, then passes that information to TypeScript’s module resolver, which decides whether to match `"import"` or `"require"` conditions in `"pkg"`’s package.json `"exports"` accordingly. Let’s assume that there’s no package.json in scope of this file. The file extension is `.ts`, so the output file extension will be `.js`, which Node.js will interpret as CommonJS, so TypeScript will emit this `import` as a `require` call. So, the module resolver will use the `require` condition as it resolves `"exports"` from `"pkg"`.
 
-When using a bundler, on the other hand, the bundler typically processes the raw `.ts` files directly and runs its module resolution process on the untransformed `import` statement. In this scenario, it doesn’t make a lot of sense to think about how TypeScript will emit the `import`, because TypeScript isn’t being used to emit anything at all. As far as the bundler is concerned, `import`s are `import`s and `require`s are `require`s, so the conditions used to resolve package.json `"exports"` and `"imports"` are determined by the syntax seen in the input `.ts` file. Likewise, the conditions TypeScript’s module resolution process uses in `--moduleResolution bundler` are _also_ determined by the input syntax in input TypeScript files—it’s just that `require` calls are not currently resolved at all:
+The same process happens in `--moduleResolution bundler`, but the rules for deciding whether to emit an `import` or `require` call for this import statement will be different, since `--moduleResolution bundler` necessitates using [`--module esnext`](#es2015-es2020-es2022-esnext) or [`--module preserve`](#preserve). In both of those modes, ESM `import` declarations always emit as ESM `import` declarations, so TypeScript’s module resolver will receive that information and use the `"import"` condition as it resolves `"exports"` from `"pkg"`.
 
-```ts
-// Some library file:
-declare function require(module: string): any;
+This explanation may be somewhat unintuitive, since `--moduleResolution bundler` is usually used in combination with `--noEmit`—bundlers typically process raw `.ts` files and perform module resolution on untransformed `import`s or `require`s. However, for consistency, TypeScript still uses the hypothetical emit decided by `module` to inform module resolution and type checking. This makes [`--module preserve`](#preserve) the best choice whenever a runtime or bundler is operating on raw `.ts` files, since it implies no transformation. Under `--module preserve --moduleResolution bundler`, you can write imports and requires in the same file that will resolve with the `import` and `require` conditions, respectively:
 
+```ts
 // index.ts
-import { foo } from "pkg";    // Resolved with "import" condition
-import pkg2 = require("pkg"); // Not allowed
-const pkg = require("pkg");   // Not an error, but not resolved to anything
-   // ^? any
+import pkg1 from "pkg";       // Resolved with "import" condition
+import pkg2 = require("pkg"); // Resolved with "require" condition
 ```
 
-Since TypeScript doesn’t currently support resolving `require` calls in `--moduleResolution bundler`, everything it _does_ resolve uses the `"import"` condition.
 
 #### Implied and enforced options
 
-- `--moduleResolution bundler` must be paired with the `--module esnext` option.
+- `--moduleResolution bundler` must be paired with `--module esnext` or `--module preserve`.
 - `--moduleResolution bundler` implies `--allowSyntheticDefaultImports`.
 
 #### Supported features
 
 - [`paths`](#paths) ✅
 - [`baseUrl`](#baseurl) ✅
 - [`node_modules` package lookups](#node_modules-package-lookups) ✅
-- [package.json `"exports"`](#packagejson-exports) ✅ matches `types`, `import`
-- [package.json `"imports"` and self-name imports](#packagejson-imports-and-self-name-imports) ✅ matches `types`, `import`
+- [package.json `"exports"`](#packagejson-exports) ✅ matches `types`, `import`/`require` depending on syntax
+- [package.json `"imports"` and self-name imports](#packagejson-imports-and-self-name-imports) ✅ matches `types`, `import`/`require` depending on syntax
 - [package.json `"typesVersions"`](#packagejson-typesversions) ✅
 - [Package-relative paths](#package-relative-file-paths) ✅ when `exports` not present
 - [Full relative paths](#relative-file-path-resolution) ✅

packages/documentation/copy/en/project-config/Compiler Options.md

@@ -809,7 +809,7 @@ tsc app.ts util.ts --target esnext --outfile index.js
 
 <tr class='even' name='module'>
   <td><code><a href='/tsconfig/#module'>--module</a></code></td>
-  <td><p><code>none</code>, <code>commonjs</code>, <code>amd</code>, <code>umd</code>, <code>system</code>, <code>es6</code>/<code>es2015</code>, <code>es2020</code>, <code>es2022</code>, <code>esnext</code>, <code>node16</code>, or <code>nodenext</code></p>
+  <td><p><code>none</code>, <code>commonjs</code>, <code>amd</code>, <code>umd</code>, <code>system</code>, <code>es6</code>/<code>es2015</code>, <code>es2020</code>, <code>es2022</code>, <code>esnext</code>, <code>node16</code>, <code>nodenext</code>, or <code>preserve</code></p>
 </td>
   <td><p><code>CommonJS</code> if <a href="#target"><code>target</code></a> is <code>ES3</code> or <code>ES5</code>; <code>ES6</code>/<code>ES2015</code> otherwise.</p>
 </td>

packages/documentation/scripts/types/AllFilenames.d.ts

@@ -57,6 +57,7 @@ export type AllDocsPages =
   | "modules-reference/diagrams/esm-cjs-interop.md"
   | "modules-reference/diagrams/esm-cjs-interop.md-1.svg"
   | "modules-reference/diagrams/esm-cjs-interop.md-2.svg"
+  | "modules-reference/diagrams/mermaid.config.json"
   | "modules-reference/diagrams/theory.md"
   | "modules-reference/diagrams/theory.md-1.svg"
   | "modules-reference/diagrams/theory.md-2.svg"
@@ -124,6 +125,8 @@ export type AllDocsPages =
   | "release-notes/TypeScript 5.0.md"
   | "release-notes/TypeScript 5.1.md"
   | "release-notes/TypeScript 5.2.md"
+  | "release-notes/TypeScript 5.3.md"
+  | "release-notes/TypeScript 5.4.md"
   | "tutorials/ASP.NET Core.md"
   | "tutorials/Angular.md"
   | "tutorials/Babel with TypeScript.md"

packages/playground/tsconfig.json

@@ -12,6 +12,7 @@
     "rootDir": "./src",
     "strict": true,
     "moduleResolution": "node",
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "skipLibCheck": true,
   }
 }

packages/sandbox/tsconfig.json

@@ -13,6 +13,7 @@
     "strict": true,
     "allowJs": true,
     "moduleResolution": "node",
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "skipLibCheck": true
   }
 }

packages/ts-twoslasher/test/results/compiler_errors.json

@@ -33,7 +33,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 28,
       "length": 3,
       "line": 2,

packages/ts-twoslasher/test/results/compiler_flags.json

@@ -33,7 +33,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 80,
       "length": 3,
       "line": 3,

packages/ts-twoslasher/test/results/completions.json

@@ -146,7 +146,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 8,
       "length": 3,
       "line": 0,

packages/ts-twoslasher/test/results/highlighting.json

@@ -60,7 +60,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 55,
       "length": 3,
       "line": 1,

packages/ts-twoslasher/test/results/import_files.json

@@ -33,7 +33,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 156,
       "length": 3,
       "line": 5,

packages/ts-twoslasher/test/results/importsModules.json

@@ -78,7 +78,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 214,
       "length": 3,
       "line": 13,

packages/ts-twoslasher/test/results/tests/queryHandlesNoToken.json

@@ -106,7 +106,7 @@
     },
     {
       "text": "(method) Console.log(...data: any[]): void",
-      "docs": "",
+      "docs": "[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)",
       "start": 130,
       "length": 3,
       "line": 5,

packages/tsconfig-reference/copy/en/options/module.md

@@ -3,7 +3,7 @@ display: "Module"
 oneline: "Specify what module code is generated."
 ---
 
-Sets the module system for the program. See the [theory behind TypeScript’s `module` option](/docs/handbook/modules/theory.html#the-module-output-format) and [its reference page](/docs/handbook/modules/reference.html#the-module-compiler-option) for more information. You very likely want `"nodenext"` for modern Node.js projects.
+Sets the module system for the program. See the [theory behind TypeScript’s `module` option](/docs/handbook/modules/theory.html#the-module-output-format) and [its reference page](/docs/handbook/modules/reference.html#the-module-compiler-option) for more information. You very likely want `"nodenext"` for modern Node.js projects and `preserve` or `esnext` for code that will be bundled.
 
 Changing `module` affects [`moduleResolution`](#moduleResolution) which [also has a reference page](/docs/handbook/modules/reference.html#the-moduleresolution-compiler-option).
 
@@ -91,6 +91,24 @@ In addition to the base functionality of `ES2015`/`ES6`, `ES2020` adds support f
 
 Available from 4.7+, the `node16` and `nodenext` modes integrate with Node's [native ECMAScript Module support](https://nodejs.org/api/esm.html). The emitted JavaScript uses either `CommonJS` or `ES2020` output depending on the file extension and the value of the `type` setting in the nearest `package.json`. Module resolution also works differently. You can learn more in the [handbook](/docs/handbook/esm-node.html) and [Modules Reference](/docs/handbook/modules/reference.html#node16-nodenext).
 
+#### `preserve`
+
+In `--module preserve` ([added](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-4.html#support-for-require-calls-in---moduleresolution-bundler-and---module-preserve) in TypeScript 5.4), ECMAScript imports and exports written in input files are preserved in the output, and CommonJS-style `import x = require("...")` and `export = ...` statements are emitted as CommonJS `require` and `module.exports`. In other words, the format of each individual import or export statement is preserved, rather than being coerced into a single format for the whole compilation (or even a whole file).
+
+```ts twoslash
+// @showEmit
+// @module: preserve
+// @noErrors
+import { valueOfPi } from "./constants";
+import constants = require("./constants");
+
+export const piSquared = valueOfPi * constants.valueOfPi;
+```
+
+While it’s rare to need to mix imports and require calls in the same file, this `module` mode best reflects the capabilities of most modern bundlers, as well as the Bun runtime.
+
+> Why care about TypeScript’s `module` emit with a bundler or with Bun, where you’re likely also setting `noEmit`? TypeScript’s type checking and module resolution behavior are affected by the module format that it _would_ emit. Setting `module` gives TypeScript information about how your bundler or runtime will process imports and exports, which ensures that the types you see on imported values accurately reflect what will happen at runtime or after bundling.
+
 #### `None`
 
 ```ts twoslash

packages/tsconfig-reference/copy/en/options/moduleResolution.md

@@ -8,9 +8,6 @@ Specify the module resolution strategy:
 - `'node16'` or `'nodenext'` for modern versions of Node.js. Node.js v12 and later supports both ECMAScript imports and CommonJS `require`, which resolve using different algorithms. These `moduleResolution` values, when combined with the corresponding [`module`](#module) values, picks the right algorithm for each resolution based on whether Node.js will see an `import` or `require` in the output JavaScript code.
 - `'node10'` (previously called `'node'`) for Node.js versions older than v10, which only support CommonJS `require`. You probably won't need to use `node10` in modern code.
 - `'bundler'` for use with bundlers. Like `node16` and `nodenext`, this mode supports package.json `"imports"` and `"exports"`, but unlike the Node.js resolution modes, `bundler` never requires file extensions on relative paths in imports.
-
-  `bundler` does not support resolution of `require` calls. In TypeScript files, this means the `import mod = require("foo")` syntax is forbidden; in JavaScript files, `require` calls are not errors but only ever return the type `any` (or whatever an ambient declaration of a global require function is declared to `return`).
-
 - `'classic'` was used in TypeScript before the release of 1.6. `classic` should not be used.
 
 There are reference pages explaining the [theory behind TypeScript’s module resolution](https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution) and the [details of each option](/docs/handbook/modules/reference.html#the-moduleresolution-compiler-option).