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)!
+

docs/cookbook/working-with-route-models.md

@@ -0,0 +1,124 @@
+# Models
+
+Ember Data models are normal TypeScript classes, but with properties decorated to define how the model represents an API resource and relationships to other resources. The decorators the library supplies "just work" with TypeScript at runtime, but require type annotations to be useful with TypeScript.
+
+For an overview of using Ember's decorators with TypeScript, see our overview.
+
+## `@attr`
+
+The type returned by the `@attr` decorator is whatever [Transform](https://api.emberjs.com/ember-data/release/classes/Transform) is applied via the invocation.
+
+* If you supply no argument to `@attr`, the value is passed through without transformation.
+* If you supply one of the built-in transforms, you will get back a corresponding type:
+  * `@attr('string')` → `string`
+  * `@attr(number)` → `number`, 
+  * `@attr('boolean')` → `boolean`
+  * `@attr'date')` → `Date`
+* If you supply a custom transform, you will get back the type returned by your transform.
+
+So, for example, you might write a class like this:
+
+```typescript
+import Model, { attr } from '@ember-data/object';
+import CustomType from '../transforms/custom-transform';
+
+export default class User extends Model {
+  @attr()
+  name?:  string;
+
+  @attr('number')
+  declare age: number;
+
+  @attr('boolean')
+  declare isAdmin: boolean;
+
+  @attr('custom-transform')
+  declare myCustomThing: CustomType;
+}
+```
+
+**Very important:** Even more than with decorators in general, you should be careful when deciding whether to mark a property as optional `?` or definitely present \(no annotation\): Ember Data will default to leaving a property empty if it is not supplied by the API or by a developer when creating it. That is: the _default_ for Ember corresponds to an optional field on the model.
+
+The _safest_ type you can write for an Ember Data model, therefore, leaves every property optional: this is how models _actually_ behave. If you choose to mark properties as definitely present by leaving off the `?`, you should take care to guarantee that this is a guarantee your API upholds, and that ever time you create a record from within the app, _you_ uphold those guarantees.
+
+One way to make this safer is to supply a default value using the `defaultValue` on the options hash for the attribute:
+
+```typescript
+import Model, { attr } from '@ember-data/object';
+
+export default class User extends Model {
+  @attr()
+  declare name?:  string;
+
+  @attr('number', { defaultValue: 13 })
+  declare age: number;
+
+  @attr('boolean', { defaultValue: false })
+  declare isAdmin: boolean;
+}
+```
+
+## `@belongsTo`
+
+The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` \(which it is by default\).
+
+* If the value is `true`, the type you should use is `DS.PromiseObject<Model>`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `false`, the type is `Model`, where `Model` is the type of the model you are creating a relationship to.
+
+So, for example, you might define a class like this:
+
+```typescript
+import Model, { belongsTo } from '@ember-data/model';
+import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
+import User from './user';
+import Site from './site';
+
+export default class Post extends Model {
+  @belongsTo('user')
+  declare user: DS.PromiseObject<User>;
+
+  @belongsTo('site', { async: false })
+  declare site: Site;
+}
+```
+
+These are _type_-safe to define as always present, that is to leave off the `?` optional marker:
+
+* accessing an async relationship will always return a `PromiseObject`, which itself may or may not ultimately resolve to a value—depending on the API response—but will always be present itself.
+* accessing a non-async relationship which is known to be associated but has not been loaded will trigger an error, so all access to the property will be safe _if_ it resolves at all.
+
+Note, however, that this type-safety is not a guarantee of there being no runtime error: you still need to uphold the contract for non-async relationships \(that is: loading the data first, or side-loading it with the request\) to avoid throwing an error!
+
+## `@hasMany`
+
+The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` \(which it is by default\).
+
+* If the value is `true`, the type you should use is `DS.PromiseManyArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `false`, the type is `EmberArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
+
+So, for example, you might define a class like this:
+
+```typescript
+import Model, { hasMany } from '@ember-data/model';
+import EmberArray from '@ember/array';
+import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
+import Comment from './comment';
+import User from './user';
+
+export default class Thread extends Model {
+  @hasMany('comment')
+  declare comment: DS.PromiseManyArray<Comment>;
+
+  @hasMany('user', { async: false })
+  declare participants: EmberArray<User>;
+}
+```
+
+The same basic rules about the safety of these lookups as with `@belongsTo` apply to these types. The difference is just that in `@hasMany` the resulting types are _arrays_ rather than single objects.
+
+## Importing `PromiseObject` and `PromiseManyArray`
+
+There is no public import path in the [Ember Data Packages](https://emberjs.github.io/rfcs/0395-ember-data-packages.html) API for the `PromiseObject` and `PromiseManyArray` types. These types are slowly being disentangled from Ember Data and will eventually be removed. However, until they are, we need a way to refer to them. For _now_, the best option is to refer to them via the legacy `DS` import.
+
+In the future, they will become unnecesary, as the types will simply be `Promise<Model>` and `Promise<Array<Model>>`.
+

docs/ember-data/README.md

@@ -0,0 +1,15 @@
+# Working With Ember
+
+In this section, we cover how to use TypeScript effectively with specific Ember APIs \(anything you'd find under the `@ember` package namespace\).
+
+We do _not_ cover general usage of Ember; instead, we assume that as background knowledge. Please see the Ember [Guides](https://guides.emberjs.com/release/) and [API docs](https://api.emberjs.com/ember/release)!
+
+## Outline
+
+* [Controllers](ember/controllers.md)
+* [Services](ember/services.md)
+* [Overview: Ember](ember/overview.md)
+* [Testing](ember/testing.md)
+* [Components](ember/components.md)
+* [Helpers](ember/helpers.md)
+* [Routes](ember/routes.md)