chore: misc updates to TS guide (#9645)

* update TS guidance * fix links * fix line * more guidance
emberjs · Jan 29, 2025 · d3d64f8 · d3d64f8
1 parent 3a720ae
commit d3d64f8
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 39 deletions.
diff --git a/guides/typescript/0-installation.md b/guides/typescript/0-installation.md
@@ -19,7 +19,9 @@ simply running the command again.
 For additional documentation or to manuall install and configure, continue reading the
 below guide.
 
-=========================================================
+
+---
+
 
 > [!CAUTION]
 > EmberData does not maintain the DefinitelyTyped types for 
@@ -29,43 +31,53 @@ below guide.
 > [!IMPORTANT]
 > EmberData's Native Types require the use of Ember's
 > Native Types.
-
-> [!IMPORTANT]  
+>
 > Type definitions need to be installed top-level, this means
 > you have to install every EmberData package `ember-data`
 > depends on.
 
 > [!TIP]
-> When installing packages, use the `@canary` dist tag to get the latest
-> version. E.g. `pnpm install ember-data@canary`
+> When installing packages, use an NPM dist tag to get the latest
+> version for a given channel. E.g. `pnpm install ember-data@latest`
+> valid channels with types are `latest`, `canary`, `v4-latest` and `v4-canary`
 
 There are currently two ways to gain access to EmberData's native types.
 
-1) [Use Canary](#using-canary)
+1) [Use A Version That Has Types](#using-native-types)
 
 2) [Use Official Types Packages](#using-types-packages)
 with releases `>= 4.12.*`
 
 ---
 
-### Using Canary
+### Using Versions That Supply Types
+
+The following versions supply their own type definitions. These type definitions will still need to be configured for use in tsconfig.
+
+- Versions of 4.x >= 4.13.0-alpha.0
+- Versions of 5.x >= 5.3.8
+
+In order to use the types for these versions, the dependencies of `ember-data` (and their peer-dependencies) must also be added to `package.json`.
+
+Generally that means:
+
 
 Required Packages for Canary Types
 
-| Name | Version |
-| ---- | ------- |
-| [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/ember-data/canary?label=&color=90EE90) |
-| [@ember-data/adapter](https://github.com/emberjs/data/blob/main/packages/adapter/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/adapter/canary?label=&color=90EE90) |
-| [@ember-data/graph](https://github.com/emberjs/data/blob/main/packages/graph/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/graph/canary?label=&color=90EE90) |
-| [@ember-data/json-api](https://github.com/emberjs/data/blob/main/packages/json-api/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/json-api/canary?label=&color=90EE90) |
-| [@ember-data/legacy-compat](https://github.com/emberjs/data/blob/main/packages/legacy-compat/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/legacy-compat/canary?label=&color=90EE90) |
-| [@ember-data/model](https://github.com/emberjs/data/blob/main/packages/model/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/model/canary?label=&color=90EE90) |
-| [@ember-data/request](https://github.com/emberjs/data/blob/main/packages/request/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/request/canary?label=&color=90EE90) |
-| [@ember-data/request-utils](https://github.com/emberjs/data/blob/main/packages/request-utils/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/request-utils/canary?label=&color=90EE90) |
-| [@ember-data/serializer](https://github.com/emberjs/data/blob/main/packages/serializer/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/serializer/canary?label=&color=90EE90) |
-| [@ember-data/store](https://github.com/emberjs/data/blob/main/packages/store/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/store/canary?label=&color=90EE90) |
-| [@ember-data/tracking](https://github.com/emberjs/data/blob/main/packages/tracking/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/tracking/canary?label=&color=90EE90) |
-| [@warp-drive/core-types](https://github.com/emberjs/data/blob/main/packages/core-types/README.md) | ![NPM Canary Version](https://img.shields.io/npm/v/%40warp-drive/core-types/canary?label=&color=90EE90) |
+| Name | Latest | Canary | V4 |
+| ---- | -------| ------ | -- |
+| [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/ember-data/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/ember-data/v4-canary?label=&color=90EE90) |
+| [@ember-data/adapter](https://github.com/emberjs/data/blob/main/packages/adapter/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/adapter/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/adapter/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/adapter/v4-canary?label=&color=90EE90) |
+| [@ember-data/graph](https://github.com/emberjs/data/blob/main/packages/graph/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/graph/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/graph/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/graph/v4-canary?label=&color=90EE90) |
+| [@ember-data/json-api](https://github.com/emberjs/data/blob/main/packages/json-api/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/json-api/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/json-api/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/json-api/v4-canary?label=&color=90EE90) |
+| [@ember-data/legacy-compat](https://github.com/emberjs/data/blob/main/packages/legacy-compat/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/legacy-compat/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/legacy-compat/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/legacy-compat/v4-canary?label=&color=90EE90) |
+| [@ember-data/model](https://github.com/emberjs/data/blob/main/packages/model/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/model/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/model/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/model/v4-canary?label=&color=90EE90) |
+| [@ember-data/request](https://github.com/emberjs/data/blob/main/packages/request/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/request/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/request/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/request/v4-canary?label=&color=90EE90) |
+| [@ember-data/request-utils](https://github.com/emberjs/data/blob/main/packages/request-utils/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/request-utils/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/request-utils/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/request-utils/v4-canary?label=&color=90EE90) |
+| [@ember-data/serializer](https://github.com/emberjs/data/blob/main/packages/serializer/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/serializer/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/serializer/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/serializer/v4-canary?label=&color=90EE90) |
+| [@ember-data/store](https://github.com/emberjs/data/blob/main/packages/store/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/store/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/store/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/store/v4-canary?label=&color=90EE90) |
+| [@ember-data/tracking](https://github.com/emberjs/data/blob/main/packages/tracking/README.md) | ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/tracking/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/tracking/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40ember-data/tracking/v4-canary?label=&color=90EE90) |
+| [@warp-drive/core-types](https://github.com/emberjs/data/blob/main/packages/core-types/README.md) | ![NPM Latest Version](https://img.shields.io/npm/v/%40warp-drive/core-types/latest?label=&color=90EE90) | ![NPM Canary Version](https://img.shields.io/npm/v/%40warp-drive/core-types/canary?label=&color=90EE90) | ![NPM V4 Version](https://img.shields.io/npm/v/%40warp-drive/core-types/v4-canary?label=&color=90EE90) |
 
 Here's a single install command for pnpm. Swap pnpm for yarn or npm as needed.
 
@@ -74,7 +86,7 @@ PACKAGES=("@types/ember" "@types/ember-data" "@types/ember-data__adapter" "@type
 
 for pkg in "${PACKAGES[@]}"; do pnpm remove "$pkg"; done
 
-pnpm install ember-data@canary @ember-data/adapter@canary @ember-data/graph@canary @ember-data/json-api@canary @ember-data/legacy-compat@canary @ember-data/model@canary @ember-data/request@canary @ember-data/request-utils@canary @ember-data/serializer@canary @ember-data/store@canary @ember-data/tracking@canary @warp-drive/core-types@canary
+pnpm install ember-data@latest @ember-data/adapter@latest @ember-data/graph@latest @ember-data/json-api@latest @ember-data/legacy-compat@latest @ember-data/model@latest @ember-data/request@latest @ember-data/request-utils@latest @ember-data/serializer@latest @ember-data/store@latest @ember-data/tracking@latest @warp-drive/core-types@latest
 ```
 
 Here's an example change to package.json which drops all use of types from `@types/` for both Ember and EmberData and adds the appropriate canary packages.

diff --git a/guides/typescript/1-configuration.md b/guides/typescript/1-configuration.md
@@ -4,7 +4,7 @@ There are currently two ways to gain access to EmberData's native types.
 Follow the configuration guide below for the [installation](./0-installation.md)
 option you chose.
 
-1) [Use Canary](#using-canary)
+1) [Use A Version That Has Types](#using-native-types)
 
 2) [Use Official Types Packages](#using-types-packages)
 with releases `>= 4.12.*`
@@ -14,7 +14,7 @@ with releases `>= 4.12.*`
 > Native Types, the configuration below will also setup
 > Your application to consume Ember's Native Types.
 
-### Using Canary
+### Using Native Types
 
 To consume `alpha` stage types, you must import the types in your project's `tsconfig.json`.
 
@@ -26,18 +26,18 @@ potential volatility.
    "compilerOptions": {
 +   "types": [
 +      "ember-source/types",
-+      "./node_modules/ember-data/unstable-preview-types",
-+      "./node_modules/@ember-data/store/unstable-preview-types",
-+      "./node_modules/@ember-data/adapter/unstable-preview-types",
-+      "./node_modules/@ember-data/graph/unstable-preview-types",
-+      "./node_modules/@ember-data/json-api/unstable-preview-types",
-+      "./node_modules/@ember-data/legacy-compat/unstable-preview-types",
-+      "./node_modules/@ember-data/request/unstable-preview-types",
-+      "./node_modules/@ember-data/request-utils/unstable-preview-types",
-+      "./node_modules/@ember-data/model/unstable-preview-types",
-+      "./node_modules/@ember-data/serializer/unstable-preview-types",
-+      "./node_modules/@ember-data/tracking/unstable-preview-types",
-+      "./node_modules/@warp-drive/core-types/unstable-preview-types"
++      "ember-data/unstable-preview-types",
++      "@ember-data/store/unstable-preview-types",
++      "@ember-data/adapter/unstable-preview-types",
++      "@ember-data/graph/unstable-preview-types",
++      "@ember-data/json-api/unstable-preview-types",
++      "@ember-data/legacy-compat/unstable-preview-types",
++      "@ember-data/request/unstable-preview-types",
++      "@ember-data/request-utils/unstable-preview-types",
++      "@ember-data/model/unstable-preview-types",
++      "@ember-data/serializer/unstable-preview-types",
++      "@ember-data/tracking/unstable-preview-types",
++      "@warp-drive/core-types/unstable-preview-types"
 +    ]
    }
  }

diff --git a/guides/typescript/index.md b/guides/typescript/index.md
@@ -10,10 +10,10 @@ the following two sections
 ---
 
 - Installation
-  - [Using Canary](./0-installation.md#using-canary)
+  - [Using Versions That Supply Types](./0-installation.md#using-versions-that-supply-types)
   - [Using Types Packages](./0-installation.md#using-types-packages)
 - Configuration
-  - [Using Canary](./1-configuration.md#using-canary)
+  - [Using Native Types](./1-configuration.md#using-native-types)
   - [Using Types Packages](./1-configuration.md#using-types-packages)
 - Usage
   - [Why Brands](./2-why-brands.md)
@@ -43,7 +43,7 @@ Each package in the project can choose its own stage for types.
 
 ## Contributing Type Fixes
 
-Even though EmberData is typed, what makes for good types for a project doesn't necessarily make for good types for that project's consumers (your application).
+Even though EmberData/WarpDrive is typed, what makes for good types for a project doesn't necessarily make for good types for that project's consumers (your application).
 
 Currently, TypeScript support is `alpha` largely because we expect to need to improve **a lot** of type signatures to make them more useful and correct for your app.