Merge pull request #1319 from bartocc/ember-data-4-x-deprecation-guides

📝 Add all 4.x ember-data deprecation pages

Author: jaredgalanis

app/templates/index.hbs

@@ -70,7 +70,10 @@
         <li class="list-unstyled" data-test-ember-data-3-link>
           <LinkTo @route="show" @models={{array "ember-data" "v3.x" }}>v3.x</LinkTo>
         </li>
+        <li class="list-unstyled" data-test-ember-data-4-link>
+          <LinkTo @route="show" @models={{array "ember-data" "v4.x" }}>v4.x</LinkTo>
+        </li>
       </ul>
     </li>
   </ul>
-</div>
+</div>

content/ember-data/v4/ember-data-deprecate-array-like.md

@@ -0,0 +1,26 @@
+---
+title: Deprecate Array Like
+until: '5.0'
+since: '4.7'
+displayId: ember-data:deprecate-array-like
+---
+
+Deprecates Ember "Array-like" methods on `RecordArray` and `ManyArray`.
+
+These are the arrays returned respectively by `store.peekAll()`, `store.findAll()` and hasMany relationships on instance of Model or `record.hasMany('relationshipName').value()`.
+
+The appropriate refactor is to treat these arrays as native arrays and to use native array methods.
+
+For instance, instead of:
+
+```js
+users.firstObject;
+```
+
+Use:
+
+```js
+users[0];
+// or
+users.at(0);
+```

content/ember-data/v4/ember-data-deprecate-early-static.md

@@ -0,0 +1,33 @@
+---
+displayId: ember-data:deprecate-early-static
+title: Deprecate Early Static
+until: '5.0'
+since: '4.7'
+---
+
+This deprecation triggers if static computed properties or methods are triggered without looking up the record via the store service's `modelFor` hook. Accessing this static information without looking up the model via the store most commonly occurs when:
+
+- using ember-cli-mirage (to fix, refactor to not use its auto-discovery of ember-data models)
+- importing a model class and accessing its static information via the import
+
+Instead of:
+
+```js
+import User from 'my-app/models/user';
+
+const relationships = User.relationshipsByName;
+```
+
+Do _at least_ this:
+
+```js
+const relationships = store.modelFor('user').relationshipsByName;
+```
+
+However, the much more future proof refactor is to not use `modelFor` at all, but instead to utilize the schema service for this static information:
+
+```js
+const relationships = store
+  .getSchemaDefinitionService()
+  .relationshipsDefinitionFor({ type: 'user' });
+```

content/ember-data/v4/ember-data-deprecate-errors-array-to-hash-helper.md

@@ -0,0 +1,12 @@
+---
+displayId: ember-data:deprecate-errors-hash-to-array-helper
+title: Deprecate Errors Hash To Array Helper
+until: '5.0'
+since: '4.7'
+---
+
+Deprecates `errorsHashToArray` `errorsArrayToHash` and `normalizeModelName`.
+
+Users making use of these (already private) utilities can trivially copy them into their own codebase to continue using them, though we recommend refactoring to a more direct conversion into the expected errors format for the errors helpers.
+
+For refactoring normalizeModelName we also recommend following the guidance in [RFC#740 Deprecate Non-Strict Types](https://github.com/emberjs/rfcs/pull/740).

content/ember-data/v4/ember-data-deprecate-errors-hash-to-array-helper.md

@@ -0,0 +1,12 @@
+---
+displayId: ember-data:deprecate-errors-hash-to-array-helper
+title: Deprecate Errors Hash To Array Helper
+until: '5.0'
+since: '4.7'
+---
+
+Deprecates `errorsHashToArray` `errorsArrayToHash` and `normalizeModelName`.
+
+Users making use of these (already private) utilities can trivially copy them into their own codebase to continue using them, though we recommend refactoring to a more direct conversion into the expected errors format for the errors helpers.
+
+For refactoring normalizeModelName we also recommend following the guidance in [RFC#740 Deprecate Non-Strict Types](https://github.com/emberjs/rfcs/pull/740).

content/ember-data/v4/ember-data-deprecate-has-record-for-id.md

@@ -0,0 +1,10 @@
+---
+displayId: ember-data:deprecate-has-record-for-id
+title: Deprecate Has Record For Id
+until: '5.0'
+since: '4.5'
+---
+
+Deprecates `store.hasRecordForId(type, id)` in favor of `store.peekRecord({ type, id }) !== null`.
+
+Broadly speaking, while the ability to query for presence is important, a key distinction exists between these methods that make relying on `hasRecordForId` unsafe, as it may report `true` for a record which is not-yet loaded and un-peekable. `peekRecord` offers a safe mechanism by which to check for whether a record is present in a usable manner.

content/ember-data/v4/ember-data-deprecate-instantiate-record-args.md

@@ -0,0 +1,28 @@
+---
+displayId: ember-data:deprecate-instantiate-record-args
+title: Deprecate Instantiate Record Args
+until: '5.0'
+since: '4.12'
+---
+
+Deprecates using the former 3rd and 4th arguments to `Store.instantiateRecord` which are now available as properties on the store.
+
+Before:
+
+```ts
+{
+  instantiateRecord(identifier, createArgs, recordDataFor, notifications) {
+    const cache = recordDataFor(identifier);
+  }
+}
+```
+
+After:
+
+```ts
+{
+  instantiateRecord(identifier, createArgs) {
+     const { cache, notifications } = this;
+  }
+}
+```

content/ember-data/v4/ember-data-deprecate-model-reopen.md

@@ -0,0 +1,27 @@
+---
+displayId: ember-data:deprecate-model-reopen
+title: Deprecate Model Reopen
+until: '5.0'
+since: '4.7'
+---
+
+For properties known ahead of time, instead of:
+
+```ts
+class User extends Model {
+  @attr firstName;
+}
+
+User.reopen({ lastName: attr() });
+```
+
+Extend `User` again or include it in the initial definition:
+
+```ts
+class User extends Model {
+  @attr firstName;
+  @attr lastName;
+}
+```
+
+For properties generated dynamically, consider registering a `SchemaDefinitionService` with the store, as such services are capable of dynamically adjusting their schemas, and utilize the `instantiateRecord` hook to create a Proxy based class that can react to the changes in the schema. Use `Foo extends Model` to extend your class instead.

content/ember-data/v4/ember-data-deprecate-model-reopenclass.md

@@ -0,0 +1,28 @@
+---
+displayId: ember-data:deprecate-model-reopenclass
+title: Deprecate Model Reopenclass
+until: '5.0'
+since: '4.7'
+---
+
+Instead of reopenClass, define `static` properties with native class syntax or add them to the final object.
+
+Instead of:
+
+```js
+User.reopenClass({ aStaticMethod() {} });
+```
+
+Do this:
+
+```js
+class User {
+  static aStaticMethod() {}
+}
+```
+
+Or, do this:
+
+```js
+User.aStaticMethod = function () {};
+```

content/ember-data/v4/ember-data-deprecate-non-strict-relationships.md

@@ -0,0 +1,112 @@
+---
+displayId: ember-data:deprecate-non-strict-relationships
+title: Deprecate Non Strict Relationships
+until: '5.0'
+since: '4.7'
+---
+
+Deprecates when belongsTo and hasMany relationships are defined without specifying whether the relationship is asynchronous.
+
+The current behavior is that relationships which do not define this setting are aschronous (`{ async: true }`).
+
+Instead of:
+
+```js
+class Company extends Model {
+  @hasMany('employee') employees;
+}
+
+class Employee extends Model {
+  @belongsTo('company') company;
+}
+```
+
+Use:
+
+```js
+class Company extends Model {
+  @hasMany('employee', { async: true, inverse: 'company' }) employees;
+}
+
+class Employee extends Model {
+  @belongsTo('company', { async: true, inverse: 'employees' }) company;
+}
+```
+
+Also deprecates when belongsTo and hasMany relationships are defined without specifying the inverse field on the related type.
+
+The current behavior is that relationships which do not define this setting have their inverse determined at runtime, which is potentially non-deterministic when mixins and polymorphism are involved.
+
+If an inverse relationship exists and you wish changes on one side to reflect onto the other side, use the inverse key. If you wish to not have changes reflected or no inverse relationship exists, specify `inverse: null`.
+
+Instead of:
+
+```js
+class Company extends Model {
+  @hasMany('employee') employees;
+}
+class Employee extends Model {
+  @belongsTo('company') company;
+}
+```
+
+Use:
+
+```js
+class Company extends Model {
+  @hasMany('employee', { async: true, inverse: 'company' }) employees;
+}
+
+class Employee extends Model {
+  @belongsTo('company', { async: true, inverse: 'employees' }) company;
+}
+```
+
+Instead of:
+
+```js
+class Company extends Model {
+  @hasMany('employee') employees;
+}
+class Employee extends Model {
+  @attr name;
+}
+```
+
+Use:
+
+```js
+class Company extends Model {
+  @hasMany('employee', { async: true, inverse: null }) employees;
+}
+
+class Employee extends Model {
+  @attr name;
+}
+```
+
+And also deprecates when belongsTo and hasMany relationships are defined without specifying the inverse record's type.
+
+Instead of
+
+```js
+class Company extends Model {
+  @hasMany() employees;
+}
+
+class Employee extends Model {
+  @belongsTo() company;
+}
+```
+
+Use
+
+```js
+class Company extends Model {
+  @hasMany('employee', { async: true, inverse: 'company' }) employees;
+}
+
+class Employee extends Model {
+  @belongsTo('company', { async: true, inverse: 'employees' }) company;
+}
+```