Merge pull request #935 from typed-ember/octane-docs

docs: Octane and much polish and clarification

Author: chriskrycho

.eslintrc.js

@@ -7,7 +7,7 @@ module.exports = {
     sourceType: 'module',
   },
   plugins: ['ember', '@typescript-eslint', 'prettier'],
-  extends: ['eslint:recommended', 'plugin:ember/recommended'],
+  extends: ['eslint:recommended', 'plugin:ember/recommended', 'prettier/@typescript-eslint'],
   env: {
     browser: true,
   },

.gitbook.yaml

@@ -0,0 +1,4 @@
+root: ./docs
+
+structure:
+  readme: ./index.md

README.md

@@ -89,7 +89,7 @@ ember install ember-decorators@^3.1.0 @ember-decorators/babel-transforms@^3.1.0
 
 #### Update ember-decorators
 
-Follow the same process of deduplication, reinstallation, and re-deduplication as described for ember-cli-babel above. This will get you the latest version of ember-decorators and, importantly, its @ember-decorators/babel-transforms dependency.
+If you're on a version of Ember before 3.10, follow the same process of deduplication, reinstallation, and re-deduplication as described for ember-cli-babel above for ember-decorators. This will get you the latest version of ember-decorators and, importantly, its @ember-decorators/babel-transforms dependency.
 
 #### Update ember-cli-typescript
 

config/addon-docs.js

@@ -0,0 +1,31 @@
+# Table of contents
+
+* [ember-cli-typescript](index.md)
+* [Installation](installation.md)
+* [Configuration](configuration.md)
+* [TypeScript and Ember](ts/README.md)
+  * [Using TypeScript With Ember Effectively](ts/using-ts-effectively.md)
+  * [Decorators](ts/decorators.md)
+  * [Current limitations](ts/current-limitations.md)
+  * [Building Addons in TypeScript](ts/with-addons.md)
+  * [Understanding the `@types` Package Names](ts/package-names.md)
+* [Working With Ember](ember/README.md)
+  * [Components](ember/components.md)
+  * [Services](ember/services.md)
+  * [Routes](ember/routes.md)
+  * [Controllers](ember/controllers.md)
+  * [Helpers](ember/helpers.md)
+  * [Testing](ember/testing.md)
+* [Working With Ember Data](ember-data/README.md)
+  * [Models](ember-data/models.md)
+* [Cookbook](cookbook/README.md)
+  * [Working with route models](cookbook/working-with-route-models.md)
+* [Working With Ember Classic](legacy/README.md)
+  * [EmberComponent](legacy/ember-component.md)
+  * [Mixins](legacy/mixins.md)
+  * [Computed Properties](legacy/computed-properties.md)
+  * [EmberObject](legacy/ember-object.md)
+* [Upgrading from 1.x](upgrade-notes.md)
+* [Troubleshooting](troubleshooting/README.md)
+  * [Conflicting Type Dependencies](troubleshooting/conflicting-types.md)
+

config/deploy.js

@@ -1,50 +1,42 @@
-# Configuring ember-cli-typescript
+# Configuration
 
 ## Blueprints
 
-By default, ember-cli-typescript installs the [ember-cli-typescript-blueprints][blueprints] package so that you can use Ember's generators like normal, but with all the special sauce you need for things to work nicely throughout your system with TypeScript.
+By default, ember-cli-typescript installs the [ember-cli-typescript-blueprints](https://github.com/typed-ember/ember-cli-typescript-blueprints) package so that you can use Ember's generators like normal, but with all the special sauce you need for things to work nicely throughout your system with TypeScript.
 
-[blueprints]: https://github.com/typed-ember/ember-cli-typescript-blueprints
-
-If you want to stick with the normal JavaScript blueprints—say, because your team isn't ready to dive into the deep end with making *everything* TypeScript yet—you can simply uninstall the blueprints package.
+If you want to stick with the normal JavaScript blueprints—say, because your team isn't ready to dive into the deep end with making _everything_ TypeScript yet—you can simply uninstall the blueprints package.
 
 With yarn:
 
-```sh
+```bash
 yarn remove ember-cli-typescript-blueprints
 ```
 
 With npm:
 
-```sh
+```bash
 npm uninstall ember-cli-typescript-blueprints
 ```
 
 ## `tsconfig.json`
 
-We generate a good default [`tsconfig.json`][blueprint], which will usually make everything _Just Work™_. In general, you may customize your TypeScript build process as usual using the `tsconfig.json` file.
+We generate a good default [`tsconfig.json`](https://github.com/typed-ember/ember-cli-typescript/blob/master/blueprints/ember-cli-typescript/files/tsconfig.json), which will usually make everything _Just Work™_. In general, you may customize your TypeScript build process as usual using the `tsconfig.json` file.
 
 However, there are a few things worth noting if you're already familiar with TypeScript and looking to make further or more advanced customizations (but _most_ users can just ignore this section!):
 
 1. The generated tsconfig file does not set `"outDir"` and sets `"noEmit"` to `true`. The default configuration we generate allows you to run editors which use the compiler without creating extraneous `.js` files throughout your codebase, leaving the compilation to ember-cli-typescript to manage.
 
-   You _can_ still customize those properties in `tsconfig.json` if your use case requires it, however. For example, to see the output of the compilation in a separate folder you are welcome to set `"outDir"` to some path and set `"noEmit"` to `false`. Then tools which use the TypeScript compiler (e.g. the watcher tooling in JetBrains IDEs) will generate files at that location, while the Ember.js/[Broccoli] pipeline will continue to use its own temp folder.
+   You _can_ still customize those properties in `tsconfig.json` if your use case requires it, however. For example, to see the output of the compilation in a separate folder you are welcome to set `"outDir"` to some path and set `"noEmit"` to `false`. Then tools which use the TypeScript compiler (e.g. the watcher tooling in JetBrains IDEs) will generate files at that location, while the Ember.js/[Broccoli](http://broccolijs.com/) pipeline will continue to use its own temp folder.
 
 2. Closely related to the previous point: any changes you do make to `outDir` won't have any effect on how _Ember_ builds your application—we run the entire build pipeline through Babel's TypeScript support instead of through the TypeScript compiler.
-
-3. Since your application is built by Babel, and only *type-checked* by TypeScript, we set the `target` key in `tsconfig.json` to the current version of the ECMAScript standard so that type-checking uses the latest and greatest from the JavaScript standard library. The Babel configuration in your app's `config/targets.js` and any included polyfills will determine the final build output.
-
-4. If you make changes to the paths included in or excluded from the build via your `tsconfig.json` (using the `"include"`, `"exclude"`, or `"files"` keys), you will need to restart the server to take the changes into account: ember-cli-typescript does not currently watch the `tsconfig.json` file. For more details, see [the TypeScript reference materials for `tsconfig.json`][tsconfig].
-
-[blueprint]: https://github.com/typed-ember/ember-cli-typescript/blob/master/blueprints/ember-cli-typescript/files/tsconfig.json
-[Broccoli]: http://broccolijs.com/
-[tsconfig]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
+3. Since your application is built by Babel, and only _type-checked_ by TypeScript, we set the `target` key in `tsconfig.json` to the current version of the ECMAScript standard so that type-checking uses the latest and greatest from the JavaScript standard library. The Babel configuration in your app's `config/targets.js` and any included polyfills will determine the final build output.
+4. If you make changes to the paths included in or excluded from the build via your `tsconfig.json` (using the `"include"`, `"exclude"`, or `"files"` keys), you will need to restart the server to take the changes into account: ember-cli-typescript does not currently watch the `tsconfig.json` file. For more details, see [the TypeScript reference materials for `tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
 ## Enabling Sourcemaps
 
 To enable TypeScript sourcemaps, you'll need to add the corresponding configuration for Babel to your `ember-cli-build.js` file:
 
-```ts
+```typescript
 const app = new EmberApp(defaults, {
   babel: {
     sourceMaps: 'inline',

docs/SUMMARY.md

@@ -0,0 +1,12 @@
+# Cookbook
+
+This “cookbook” section contains recipes for various scenarios you may encounter while working on your app or addon.
+
+{% hint style="info" %}
+Have an idea for an item that should fit here? [Open an issue for it!](https://github.com/typed-ember/ember-cli-typescript/issues/new/choose) We'd love to help you help us make this experience more awesome for everyone.
+{% endhint %}
+
+## Contents
+
+* [Working with route models](./working-with-route-models.md)
+

tests/dummy/app/templates/docs/configuration.md renamed to docs/configuration.md

@@ -0,0 +1,51 @@
+# Working with route models
+
+We often use routes’ models throughout our application, since they’re a core ingredient of our application’s data. As such, we want to make sure that we have good types for them!
+
+We can start by defining some type utilities to let us get the resolved value returned by a route’s model hook:
+
+```typescript
+import Route from '@ember/routing/route';
+
+/**
+  Get the resolved type of an item.
+
+  - If the item is a promise, the result will be the resolved value type
+  - If the item is not a promise, the result will just be the type of the item
+ */
+export type Resolved<P> = P extends Promise<infer T> ? T : P;
+
+/** Get the resolved model value from a route. */
+export type ModelFrom<R extends Route> = Resolved<ReturnType<R['model']>>;
+```
+
+How that works:
+
+* `Resolved<P>` says "if this is a promise, the type here is whatever the promise resolves to; otherwise, it's just the value"
+* `ReturnType<T>` gets the return value of a given function
+* `R['model']` \(where `R` has to be `Route` itself or a subclass\) uses TS's mapped types to say "the property named `model` on `R`
+
+Putting those all together, `ModelFrom<Route>` ends up giving you the resolved value returned from the `model` hook for a given route:
+
+```typescript
+type MyRouteModel = ModelFrom<MyRoute>;
+```
+
+## `model` on the controller
+
+We can use this functionality to guarantee that the `model` on a `Controller` is always exactly the type returned by `Route::model` by writing something like this:
+
+```typescript
+import Controller from '@ember/controller';
+import MyRoute from '../routes/my-route';
+import { ModelFrom } from '../lib/type-utils';
+
+export default class ControllerWithModel extends Controller {
+  declare model: ModelFrom<MyRoute>;
+}
+```
+
+Now, our controller’s `model` property will _always_ stay in sync with the corresponding route’s model hook.
+
+**Note:** this _only_ works if you do not mutate the `model` in either the `afterModel` or `setupController` hooks on the route! That's generally considered to be a bad practice anyway. If you do change the type there, you'll need to define the type in some other way and make sure your route's model is defined another way.
+

docs/cookbook/README.md

@@ -0,0 +1,6 @@
+# Working With Ember Data
+
+In this section, we cover how to use TypeScript effectively with specific Ember Data APIs \(anything you'd find under the `@ember-data` package namespace\).
+
+We do _not_ cover general usage of Ember Data; instead, we assume that as background knowledge. Please see the Ember Data [Guides](https://guides.emberjs.com/release/models) and [API docs](https://api.emberjs.com/ember-data/release)!
+