Sync with TypeScript-Website @ 80d3fc1 (#60)

Author: awxiaoxian2020

.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
-  "changelog": "@changesets/cli/changelog",
+  "changelog": ["@changesets/changelog-github", { "repo": "microsoft/TypeScript-Website" }],
   "commit": false,
   "fixed": [],
   "linked": [],

package.json

@@ -6,6 +6,7 @@
     "pnpm": ">=9"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.0",
     "@changesets/cli": "^2.27.5",
     "@oss-docs/sync": "^1.1.4",
     "@types/express": "^4.17.6",

packages/ata/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @typescript/ata
 
+## 0.9.6
+
+### Patch Changes
+
+- [#2977](https://github.com/microsoft/TypeScript-Website/pull/2977) [`7691811`](https://github.com/microsoft/TypeScript-Website/commit/7691811c180e3b352cf4e888387d1edfc10f5252) Thanks [@curran](https://github.com/curran)! - Widen typescript peer dependency range
+
+- [#3000](https://github.com/microsoft/TypeScript-Website/pull/3000) [`71776ae`](https://github.com/microsoft/TypeScript-Website/commit/71776aecc1b56289ab56d240a9272ce83686ef1a) Thanks [@antfu](https://github.com/antfu)! - Handle `.d.cts` and `.d.mts` files
+
+- [#3002](https://github.com/microsoft/TypeScript-Website/pull/3002) [`fd776c0`](https://github.com/microsoft/TypeScript-Website/commit/fd776c05bb8fa9c897d18fa237af39ae8da03a7c) Thanks [@antfu](https://github.com/antfu)! - Fix return type of `setupTypeAcquisition`
+
 ## 0.9.5
 
 ### Patch Changes

packages/ata/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript/ata",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "license": "MIT",
   "homepage": "https://github.com/microsoft/TypeScript-Website",
   "repository": {
@@ -27,6 +27,6 @@
     "jest": "^29.5.0"
   },
   "peerDependencies": {
-    "typescript": "^4.4.4"
+    "typescript": ">=4.4.4"
   }
 }

packages/ata/src/index.ts

@@ -71,7 +71,7 @@ export const setupTypeAcquisition = (config: ATABootstrapConfig) => {
     const treesOnly = trees.filter(t => !("error" in t)) as NPMTreeMeta[]
 
     // These are the modules which we can grab directly
-    const hasDTS = treesOnly.filter(t => t.files.find(f => f.name.endsWith(".d.ts")))
+    const hasDTS = treesOnly.filter(t => t.files.find(f => isDtsFile(f.name)))
     const dtsFilesFromNPM = hasDTS.map(t => treeToDTSFiles(t, `/node_modules/${t.moduleName}`))
 
     // These are ones we need to look on DT for (which may not be there, who knows)
@@ -142,7 +142,7 @@ function treeToDTSFiles(tree: NPMTreeMeta, vfsPrefix: string) {
   const dtsRefs: ATADownload[] = []
 
   for (const file of tree.files) {
-    if (file.name.endsWith(".d.ts")) {
+    if (isDtsFile(file.name)) {
       dtsRefs.push({
         moduleName: tree.moduleName,
         moduleVersion: tree.version,
@@ -170,7 +170,7 @@ export const getReferencesForModule = (ts: typeof import("typescript"), code: st
   const references = meta.referencedFiles
     .concat(meta.importedFiles)
     .concat(meta.libReferenceDirectives)
-    .filter(f => !f.fileName.endsWith(".d.ts"))
+    .filter(f => !isDtsFile(f.fileName))
     .filter(d => !libMap.has(d.fileName))
 
   return references.map(r => {
@@ -268,3 +268,7 @@ function getDTName(s: string) {
   }
   return s
 }
+
+function isDtsFile(file: string) {
+  return /\.d\.([^\.]+\.)?[cm]?ts$/i.test(file)
+}

packages/ata/src/userFacingTypes.d.ts

@@ -33,7 +33,7 @@ type ModuleMeta = { state: "loading" }
  * basically exported for tests and should be considered
  * implementation details by consumers.
  */
-export const setupTypeAcquisition: (config: ATABootstrapConfig) => (initialSourceFile: string) => void
+export const setupTypeAcquisition: (config: ATABootstrapConfig) => (initialSourceFile: string) => Promise<void>
 
 interface Logger {
   log: (...args: any[]) => void

packages/documentation/copy/en/get-started/TS for Functional Programmers.md

@@ -76,8 +76,8 @@ TypeScript has corresponding primitive types for the built-in types:
 | -------------- | ------------------------------------------------------------------------------- |
 | `unknown`      | the top type.                                                                   |
 | `never`        | the bottom type.                                                                |
-| object literal | eg `{ property: Type }`                                                         |
-| `void`         | for functions with no documented return value |
+| object literal | e.g. `{ property: Type }`                                                       |
+| `void`         | for functions with no documented return value                                   |
 | `T[]`          | mutable arrays, also written `Array<T>`                                         |
 | `[T, T]`       | tuples, which are fixed-length but mutable                                      |
 | `(t: T) => U`  | functions                                                                       |

packages/documentation/copy/en/handbook-v2/Classes.md

@@ -150,11 +150,14 @@ class Point {
 
 ```ts twoslash
 class Point {
-  // Overloads
-  constructor(x: number, y: string);
-  constructor(s: string);
-  constructor(xs: any, y?: any) {
-    // TBD
+  x: number = 0;
+  y: number = 0;
+
+  // Constructor overloads
+  constructor(x: number, y: number);
+  constructor(xy: string);
+  constructor(x: string | number, y: number = 0) {
+    // Code logic here
   }
 }
 ```
@@ -250,7 +253,6 @@ TypeScript has some special inference rules for accessors:
 
 - If `get` exists but no `set`, the property is automatically `readonly`
 - If the type of the setter parameter is not specified, it is inferred from the return type of the getter
-- Getters and setters must have the same [Member Visibility](#member-visibility)
 
 Since [TypeScript 4.3](https://devblogs.microsoft.com/typescript/announcing-typescript-4-3/), it is possible to have accessors with different types for getting and setting.
 

packages/documentation/copy/en/handbook-v2/Everyday Types.md

@@ -469,6 +469,7 @@ You'll learn more about these concepts in later chapters, so don't worry if you
 - Type aliases may not participate [in declaration merging, but interfaces can](/play?#code/PTAEEEDtQS0gXApgJwGYEMDGjSfdAIx2UQFoB7AB0UkQBMAoEUfO0Wgd1ADd0AbAK6IAzizp16ALgYM4SNFhwBZdAFtV-UAG8GoPaADmNAcMmhh8ZHAMMAvjLkoM2UCvWad+0ARL0A-GYWVpA29gyY5JAWLJAwGnxmbvGgALzauvpGkCZmAEQAjABMAMwALLkANBl6zABi6DB8okR4Jjg+iPSgABboovDk3jjo5pbW1d6+dGb5djLwAJ7UoABKiJTwjThpnpnGpqPBoTLMAJrkArj4kOTwYmycPOhW6AR8IrDQ8N04wmo4HHQCwYi2Waw2W1S6S8HX8gTGITsQA).
 - Interfaces may only be used to [declare the shapes of objects, not rename primitives](/play?#code/PTAEAkFMCdIcgM6gC4HcD2pIA8CGBbABwBtIl0AzUAKBFAFcEBLAOwHMUBPQs0XFgCahWyGBVwBjMrTDJMAshOhMARpD4tQ6FQCtIE5DWoixk9QEEWAeV37kARlABvaqDegAbrmL1IALlAEZGV2agBfampkbgtrWwMAJlAAXmdXdy8ff0Dg1jZwyLoAVWZ2Lh5QVHUJflAlSFxROsY5fFAWAmk6CnRoLGwmILzQQmV8JmQmDzI-SOiKgGV+CaYAL0gBBdyy1KCQ-Pn1AFFplgA5enw1PtSWS+vCsAAVAAtB4QQWOEMKBuYVUiVCYvYQsUTQcRSBDGMGmKSgAAa-VEgiQe2GLgKQA).
 - Interface names will [_always_ appear in their original form](/play?#code/PTAEGEHsFsAcEsA2BTATqNrLusgzngIYDm+oA7koqIYuYQJ56gCueyoAUCKAC4AWHAHaFcoSADMaQ0PCG80EwgGNkALk6c5C1EtWgAsqOi1QAb06groEbjWg8vVHOKcAvpokshy3vEgyyMr8kEbQJogAFND2YREAlOaW1soBeJAoAHSIkMTRmbbI8e6aPMiZxJmgACqCGKhY6ABGyDnkFFQ0dIzMbBwCwqIccabcYLyQoKjIEmh8kwN8DLAc5PzwwbLMyAAeK77IACYaQSEjUWY2Q-YAjABMAMwALA+gbsVjNXW8yxySoAADaAA0CCaZbPh1XYqXgOIY0ZgmcK0AA0nyaLFhhGY8F4AHJmEJILCWsgZId4NNfIgGFdcIcUTVfgBlZTOWC8T7kAJ42G4eT+GS42QyRaYbCgXAEEguTzeXyCjDBSAAQSE8Ai0Xsl0K9kcziExDeiQs1lAqSE6SyOTy0AKQ2KHk4p1V6s1OuuoHuzwArMagA) in error messages, but _only_ when they are used by name.
+- Using interfaces with `extends` [can often be more performant for the compiler](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections) than type aliases with intersections
 
 For the most part, you can choose based on personal preference, and TypeScript will tell you if it needs something to be the other kind of declaration. If you would like a heuristic, use `interface` until you need to use features from `type`.
 

packages/documentation/copy/en/handbook-v2/Object Types.md

@@ -274,8 +274,8 @@ This index signature states that when a `StringArray` is indexed with a `number`
 Only some types are allowed for index signature properties: `string`, `number`, `symbol`, template string patterns, and union types consisting only of these.
 
 <details>
-    <summary>It is possible to support both types of indexers...</summary>
-    <p>It is possible to support both types of indexers, but the type returned from a numeric indexer must be a subtype of the type returned from the string indexer. This is because when indexing with a <code>number</code>, JavaScript will actually convert that to a <code>string</code> before indexing into an object. That means that indexing with <code>100</code> (a <code>number</code>) is the same thing as indexing with <code>"100"</code> (a <code>string</code>), so the two need to be consistent.</p>
+    <summary>It is possible to support multiple types of indexers...</summary>
+    <p>It is possible to support multiple types of indexers. Note that when using both `number` and `string` indexers, the type returned from a numeric indexer must be a subtype of the type returned from the string indexer. This is because when indexing with a <code>number</code>, JavaScript will actually convert that to a <code>string</code> before indexing into an object. That means that indexing with <code>100</code> (a <code>number</code>) is the same thing as indexing with <code>"100"</code> (a <code>string</code>), so the two need to be consistent.</p>
 
 ```ts twoslash
 // @errors: 2413

packages/documentation/copy/en/handbook-v2/Type Manipulation/Generics.md

@@ -152,7 +152,7 @@ let myIdentity: <Type>(arg: Type) => Type = identity;
 We could also have used a different name for the generic type parameter in the type, so long as the number of type variables and how the type variables are used line up.
 
 ```ts twoslash
-function identity<Input>(arg: Input): Input {
+function identity<Type>(arg: Type): Type {
   return arg;
 }
 

packages/documentation/copy/en/javascript/JSDoc Reference.md

@@ -827,6 +827,7 @@ The following tags have open issues to support them:
 
 - `@memberof` ([issue #7237](https://github.com/Microsoft/TypeScript/issues/7237))
 - `@yields` ([issue #23857](https://github.com/Microsoft/TypeScript/issues/23857))
+- `@member` ([issue #56674](https://github.com/microsoft/TypeScript/issues/56674))
 
 ### Legacy type synonyms
 
@@ -852,4 +853,4 @@ So the compiler treats these types as synonyms based on usage in old JSDoc:
 The last four aliases are turned off when `noImplicitAny: true`:
 
 - `object` and `Object` are built-in types, although `Object` is rarely used.
-- `array` and `promise` are not built-in, but might be declared somewhere in your program.
+- `array` and `promise` are not built-in, but might be declared somewhere in your program.

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

@@ -231,10 +231,12 @@ The detected module format of input `.ts`/`.tsx`/`.mts`/`.cts` files determines
 The emit format of each file is determined by the [detected module format](#module-format-detection) of each file. ESM emit is similar to [`--module esnext`](#es2015-es2020-es2022-esnext), but has a special transformation for `import x = require("...")`, which is not allowed in `--module esnext`:
 
 ```ts
+// @Filename: main.ts
 import x = require("mod");
 ```
 
 ```js
+// @Filename: main.js
 import { createRequire as _createRequire } from "module";
 const __require = _createRequire(import.meta.url);
 const x = __require("mod");
@@ -243,11 +245,13 @@ const x = __require("mod");
 CommonJS emit is similar to [`--module commonjs`](#commonjs), but dynamic `import()` calls are not transformed. Emit here is shown with `esModuleInterop` enabled:
 
 ```ts
+// @Filename: main.ts
 import fs from "fs"; // transformed
 const dynamic = import("mod"); // not transformed
 ```
 
 ```js
+// @Filename: main.js
 "use strict";
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -322,6 +326,7 @@ export default "default export";
 #### Examples
 
 ```ts
+// @Filename: main.ts
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -332,6 +337,7 @@ export default "default export";
 ```
 
 ```js
+// @Filename: main.js
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -355,6 +361,7 @@ export default "default export";
 > Output is shown with `esModuleInterop: false`.
 
 ```ts
+// @Filename: main.ts
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -365,6 +372,7 @@ export default "default export";
 ```
 
 ```js
+// @Filename: main.js
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.e1 = void 0;
@@ -378,6 +386,7 @@ exports.default = "default export";
 ```
 
 ```ts
+// @Filename: main.ts
 import mod = require("mod");
 console.log(mod);
 
@@ -388,6 +397,7 @@ export = {
 ```
 
 ```js
+// @Filename: main.js
 "use strict";
 const mod = require("mod");
 console.log(mod);
@@ -407,6 +417,7 @@ module.exports = {
 #### Examples
 
 ```ts
+// @Filename: main.ts
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -417,6 +428,7 @@ export default "default export";
 ```
 
 ```js
+// @Filename: main.js
 System.register(["mod"], function (exports_1, context_1) {
     "use strict";
     var mod_1, mod, dynamic, e1;
@@ -450,6 +462,7 @@ System.register(["mod"], function (exports_1, context_1) {
 #### Examples
 
 ```ts
+// @Filename: main.ts
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -460,6 +473,7 @@ export default "default export";
 ```
 
 ```js
+// @Filename: main.js
 define(["require", "exports", "mod", "mod"], function (require, exports, mod_1, mod) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -484,6 +498,7 @@ define(["require", "exports", "mod", "mod"], function (require, exports, mod_1,
 #### Examples
 
 ```ts
+// @Filename: main.ts
 import x, { y, z } from "mod";
 import * as mod from "mod";
 const dynamic = import("mod");
@@ -494,6 +509,7 @@ export default "default export";
 ```
 
 ```js
+// @Filename: main.js
 (function (factory) {
     if (typeof module === "object" && typeof module.exports === "object") {
         var v = factory(require, exports);
@@ -985,7 +1001,7 @@ import foo = require("pkg/dist/foo"); // ✅ require, no extension needed
 
 #### package.json `"imports"` and self-name imports
 
-When `moduleResolution` is set to `node16`, `nodenext`, or `bundler`, and `resolvePackageJsonImports` is not disabled, TypeScript will attempt to resolve import paths beginning with `#` through the the `"imports"` field of the nearest ancestor package.json of the importing file. Similarly, when [package.json `"exports"` lookups](#packagejson-exports) are enabled, TypeScript will attempt to resolve import paths beginning with the current package name—that is, the value in the `"name"` field of the nearest ancestor package.json of the importing file—through the `"exports"` field of that package.json. Both of these features allow files in a package to import other files in the same package, replacing a relative import path.
+When `moduleResolution` is set to `node16`, `nodenext`, or `bundler`, and `resolvePackageJsonImports` is not disabled, TypeScript will attempt to resolve import paths beginning with `#` through the `"imports"` field of the nearest ancestor package.json of the importing file. Similarly, when [package.json `"exports"` lookups](#packagejson-exports) are enabled, TypeScript will attempt to resolve import paths beginning with the current package name—that is, the value in the `"name"` field of the nearest ancestor package.json of the importing file—through the `"exports"` field of that package.json. Both of these features allow files in a package to import other files in the same package, replacing a relative import path.
 
 TypeScript follows Node.js’s resolution algorithm for [`"imports"`](https://nodejs.org/api/packages.html#subpath-imports) and [self references](https://nodejs.org/api/packages.html#self-referencing-a-package-using-its-name) exactly up until a file path is resolved. At that point, TypeScript’s resolution algorithm forks based on whether the package.json containing the `"imports"` or `"exports"` being resolved belongs to a `node_modules` dependency or the local project being compiled (i.e., its directory contains the tsconfig.json file for the project that contains the importing file):
 

packages/documentation/copy/en/reference/Utility Types.md

@@ -140,13 +140,13 @@ Constructs an object type whose property keys are `Keys` and whose property valu
 ##### Example
 
 ```ts twoslash
+type CatName = "miffy" | "boris" | "mordred";
+
 interface CatInfo {
   age: number;
   breed: string;
 }
 
-type CatName = "miffy" | "boris" | "mordred";
-
 const cats: Record<CatName, CatInfo> = {
   miffy: { age: 10, breed: "Persian" },
   boris: { age: 5, breed: "Maine Coon" },

packages/documentation/copy/en/release-notes/TypeScript 2.8.md

@@ -328,7 +328,7 @@ type T7 = T4<A, B>; // "a" | "b"
 ## Better handling for namespace patterns in `.js` files
 
 TypeScript 2.8 adds support for understanding more namespace patterns in `.js` files.
-Empty object literals declarations on top level, just like functions and classes, are now recognized as as namespace declarations in JavaScript.
+Empty object literals declarations on top level, just like functions and classes, are now recognized as namespace declarations in JavaScript.
 
 ```js
 var ns = {}; // recognized as a declaration for a namespace `ns`

packages/documentation/copy/en/release-notes/TypeScript 4.0.md

@@ -417,7 +417,7 @@ if (!obj.prop) {
 }
 ```
 
-[Try running the following example](https://www.typescriptlang.org/play?ts=Nightly#code/MYewdgzgLgBCBGArGBeGBvAsAKBnmA5gKawAOATiKQBQCUGO+TMokIANkQHTsgHUAiYlChFyMABYBDCDHIBXMANoBuHI2Z4A9FpgAlIqXZTgRGAFsiAQg2byJeeTAwAslKgSu5KWAAmIczoYAB4YAAYuAFY1XHwAXwAaWxgIEhgKKmoAfQA3KXYALhh4EA4iH3osWM1WCDKePkFUkTFJGTlFZRimOJw4mJwAM0VgKABLcBhB0qCqplr63n4BcjGCCVgIMd8zIjz2eXciXy7k+yhHZygFIhje7BwFzgblgBUJMdlwM3yAdykAJ6yBSQGAeMzNUTkU7YBCILgZUioOBIBGUJEAHwxUxmqnU2Ce3CWgnenzgYDMACo6pZxpYIJSOqDwSkSFCYXC0VQYFi0NMQHQVEA) to see how that differs from _always_ performing the assignment.
+[Try running the following example](https://www.typescriptlang.org/play?ts=next#code/MYewdgzgLgBCBGArGBeGBvAsAKBnmA5gKawAOATiKQBQCUGO+TMokIANkQHTsgHUAiYlChFyMABYBDCDHIBXMANoBuHI2Z4A9FpgAlIqXZTgRGAFsiAQg2byJeeTAwAslKgSu5KWAAmIczoYAB4YAAYuAFY1XHwAXwAaWxgIEhgKKmoAfQA3KXYALhh4EA4iH3osWM1WCDKePkFUkTFJGTlFZRimOJw4mJwAM0VgKABLcBhB0qCqplr63n4BcjGCCVgIMd8zIjz2eXciXy7k+yhHZygFIhje7BwFzgblgBUJMdlwM3yAdykAJ6yBSQGAeMzNUTkU7YBCILgZUioOBIBGUJEAHwxUxmqnU2Ce3CWgnenzgYDMACo6pZxpYIJSOqDwSkSFCYXC0VQYFi0NMQHQVEA) to see how that differs from _always_ performing the assignment.
 
 ```ts twoslash
 const obj = {

packages/documentation/copy/en/release-notes/TypeScript 4.9.md

@@ -20,10 +20,7 @@ const palette = {
 //  ^^^^ sacrebleu - we've made a typo!
 };
 
-// We want to be able to use array methods on 'red'...
-const redComponent = palette.red.at(0);
-
-// or string methods on 'green'...
+// We want to be able to use string methods on 'green'...
 const greenNormalized = palette.green.toUpperCase();
 ```
 
@@ -42,8 +39,9 @@ const palette: Record<Colors, string | RGB> = {
 //  ~~~~ The typo is now correctly detected
 };
 
-// But we now have an undesirable error here - 'palette.red' "could" be a string.
-const redComponent = palette.red.at(0);
+// But we now have an undesirable error here - 'palette.green' "could" be of type RGB and
+// property 'toUpperCase' does not exist on type 'string | RGB'.
+const greenNormalized = palette.green.toUpperCase();
 ```
 
 The new `satisfies` operator lets us validate that the type of an expression matches some type, without changing the resulting type of that expression.
@@ -61,8 +59,7 @@ const palette = {
 //  ~~~~ The typo is now caught!
 } satisfies Record<Colors, string | RGB>;
 
-// Both of these methods are still accessible!
-const redComponent = palette.red.at(0);
+// toUpperCase() method is still accessible!
 const greenNormalized = palette.green.toUpperCase();
 ```