diff --git a/app/templates/index.hbs b/app/templates/index.hbs index fc665f7f..618e4dd7 100644 --- a/app/templates/index.hbs +++ b/app/templates/index.hbs @@ -70,7 +70,10 @@
  • v3.x
  • +
  • + v4.x +
  • - \ No newline at end of file + diff --git a/content/ember-data/v4/ember-data-deprecate-array-like.md b/content/ember-data/v4/ember-data-deprecate-array-like.md new file mode 100644 index 00000000..edc9760f --- /dev/null +++ b/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); +``` diff --git a/content/ember-data/v4/ember-data-deprecate-early-static.md b/content/ember-data/v4/ember-data-deprecate-early-static.md new file mode 100644 index 00000000..e74743fe --- /dev/null +++ b/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' }); +``` diff --git a/content/ember-data/v4/ember-data-deprecate-errors-array-to-hash-helper.md b/content/ember-data/v4/ember-data-deprecate-errors-array-to-hash-helper.md new file mode 100644 index 00000000..8349ba51 --- /dev/null +++ b/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). diff --git a/content/ember-data/v4/ember-data-deprecate-errors-hash-to-array-helper.md b/content/ember-data/v4/ember-data-deprecate-errors-hash-to-array-helper.md new file mode 100644 index 00000000..8349ba51 --- /dev/null +++ b/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). diff --git a/content/ember-data/v4/ember-data-deprecate-has-record-for-id.md b/content/ember-data/v4/ember-data-deprecate-has-record-for-id.md new file mode 100644 index 00000000..b83547b4 --- /dev/null +++ b/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. diff --git a/content/ember-data/v4/ember-data-deprecate-instantiate-record-args.md b/content/ember-data/v4/ember-data-deprecate-instantiate-record-args.md new file mode 100644 index 00000000..b122f4b8 --- /dev/null +++ b/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; + } +} +``` diff --git a/content/ember-data/v4/ember-data-deprecate-model-reopen.md b/content/ember-data/v4/ember-data-deprecate-model-reopen.md new file mode 100644 index 00000000..17c8df79 --- /dev/null +++ b/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. diff --git a/content/ember-data/v4/ember-data-deprecate-model-reopenclass.md b/content/ember-data/v4/ember-data-deprecate-model-reopenclass.md new file mode 100644 index 00000000..408bf35a --- /dev/null +++ b/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 () {}; +``` diff --git a/content/ember-data/v4/ember-data-deprecate-non-strict-relationships.md b/content/ember-data/v4/ember-data-deprecate-non-strict-relationships.md new file mode 100644 index 00000000..ac9ce4c4 --- /dev/null +++ b/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; +} +``` diff --git a/content/ember-data/v4/ember-data-deprecate-normalize-modelname-helper.md b/content/ember-data/v4/ember-data-deprecate-normalize-modelname-helper.md new file mode 100644 index 00000000..ebb39451 --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-normalize-modelname-helper.md @@ -0,0 +1,12 @@ +--- +displayId: ember-data:deprecate-promise-many-array-behaviors +title: Deprecate Promise Many Array Behaviors +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). diff --git a/content/ember-data/v4/ember-data-deprecate-promise-many-array-behaviors.md b/content/ember-data/v4/ember-data-deprecate-promise-many-array-behaviors.md new file mode 100644 index 00000000..9cfcfb52 --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-promise-many-array-behaviors.md @@ -0,0 +1,27 @@ +--- +displayId: ember-data:deprecate-promise-many-array-behaviors +title: Deprecate Promise Many Array Behaviors +until: '5.0' +since: '4.7' +--- + +[RFC Documentation](https://rfcs.emberjs.com/id/0745-ember-data-deprecate-methods-on-promise-many-array) + +This deprecation deprecates accessing values on the asynchronous proxy in favor of first "resolving" or "awaiting" the promise to retrieve a synchronous value. + +Template iteration of the asynchronous value will still work and not trigger the deprecation, but all JS access should be avoided and HBS access for anything but `{{#each}}` should also be refactored. + +Recommended approaches include using the addon `ember-promise-helpers`, using Ember's `resource` pattern (including potentially the addon `ember-data-resources`), resolving the value in routes/provider components, or using the references API. + +An example of using the [hasMany](https://api.emberjs.com/ember-data/4.11/classes/Model/methods/hasMany?anchor=hasMany) [reference API](https://api.emberjs.com/ember-data/release/classes/HasManyReference): + +```js +// get the synchronous "ManyArray" value for the asynchronous "friends" relationship. +// note, this will return `null` if the relationship has not been loaded yet +const value = person.hasMany('friends').value(); + +// to get just the list of related IDs +const ids = person.hasMany('friends').ids(); +``` + +References participate in autotracking and getters/cached getters etc. which consume them will recompute if the value changes. diff --git a/content/ember-data/v4/ember-data-deprecate-promise-proxies.md b/content/ember-data/v4/ember-data-deprecate-promise-proxies.md new file mode 100644 index 00000000..a225c47d --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-promise-proxies.md @@ -0,0 +1,22 @@ +--- +displayId: ember-data:deprecate-promise-proxies +title: Deprecate Promise Proxies +until: '5.0' +since: '4.7' +--- + +Additional Reading: [RFC#846 Deprecate Proxies](https://rfcs.emberjs.com/id/0846-ember-data-deprecate-proxies) + +Deprecates using the proxy object/proxy array capabilities of values returned from: + +- `store.findRecord` +- `store.findAll` +- `store.query` +- `store.queryRecord` +- `record.save` +- `recordArray.save` +- `recordArray.update` + +These methods will now return a native Promise that resolves with the value. + +Note that this does not deprecate the proxy behaviors of `PromiseBelongsTo`. See RFC for reasoning. The opportunity should still be taken if available to stop using these proxy behaviors; however, this class will remain until `import Model from '@ember-data/model';` is deprecated more broadly. diff --git a/content/ember-data/v4/ember-data-deprecate-secret-adapter-fallback.md b/content/ember-data/v4/ember-data-deprecate-secret-adapter-fallback.md new file mode 100644 index 00000000..b898425b --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-secret-adapter-fallback.md @@ -0,0 +1,14 @@ +--- +displayId: ember-data:deprecate-secret-adapter-fallback +title: Deprecate Secret Adapter Fallback +until: '5.0' +since: '4.5' +--- + +Deprecates the secret `-json-api` fallback adapter in favor or an explicit "catch all" application adapter. In addition to this deprecation ensuring the user has explicitly chosen an adapter, this ensures that the user may choose to use no adapter at all. + +Simplest fix: + +```js {data-filename=/app/adapters/application.js} +export { default } from '@ember-data/adapter/json-api'; +``` diff --git a/content/ember-data/v4/ember-data-deprecate-snapshot-model-class-access.md b/content/ember-data/v4/ember-data-deprecate-snapshot-model-class-access.md new file mode 100644 index 00000000..28ae6707 --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-snapshot-model-class-access.md @@ -0,0 +1,16 @@ +--- +displayId: ember-data:deprecate-snapshot-model-class-access +title: Deprecate Snapshot Model Class Access +until: '5.0' +since: '4.5' +--- + +Deprecates accessing the factory class for a given resource type via properties on various classes. + +Guards: + +- SnapshotRecordArray.type +- Snapshot.type +- RecordArray.type + +Use `store.modelFor()` instead. diff --git a/content/ember-data/v4/ember-data-deprecate-store-find.md b/content/ember-data/v4/ember-data-deprecate-store-find.md new file mode 100644 index 00000000..a08a753d --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-store-find.md @@ -0,0 +1,10 @@ +--- +displayId: ember-data:deprecate-promise-many-array-behaviors +title: Deprecate Promise Many Array Behaviors +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. diff --git a/content/ember-data/v4/ember-data-deprecate-string-arg-schemas.md b/content/ember-data/v4/ember-data-deprecate-string-arg-schemas.md new file mode 100644 index 00000000..12d2fa6d --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-string-arg-schemas.md @@ -0,0 +1,15 @@ +--- +displayId: ember-data:deprecate-string-arg-schemas +title: Deprecate String Arg Schemas +until: '5.0' +since: '4.5' +--- + +Deprecates `schema.attributesDefinitionFor(type)` and `schema.relationshipsDefinitionFor(type)` in favor of a consistent object signature (`identifier | { type }`). + +To resolve change: + +```diff +- store.getSchemaDefinitionService().attributesDefinitionFor('user') ++ store.getSchemaDefinitionService().attributesDefinitionFor({ type: 'user' }) +``` diff --git a/content/ember-data/v4/ember-data-deprecate-v1-cache.md b/content/ember-data/v4/ember-data-deprecate-v1-cache.md new file mode 100644 index 00000000..0847d62e --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-v1-cache.md @@ -0,0 +1,12 @@ +--- +displayId: ember-data:deprecate-v1-cache +title: Deprecate V1 Cache +until: '5.0' +since: '4.7' +--- + +Deprecates instantiating a non-singleton cache via `store.createRecordDataFor` in favor of a singleton-cache via `store.createCache`. + +Most applications should not encounter this deprecation, but if you do it means that an addon you are using is likely using an unsupported cache implementation. + +The implementation will need to update to the V2 Cache API and be integrated via the `createCache` hook. diff --git a/content/ember-data/v4/ember-data-deprecate-v1cache-store-apis.md b/content/ember-data/v4/ember-data-deprecate-v1cache-store-apis.md new file mode 100644 index 00000000..0fe420bb --- /dev/null +++ b/content/ember-data/v4/ember-data-deprecate-v1cache-store-apis.md @@ -0,0 +1,12 @@ +--- +displayId: ember-data:deprecate-v1cache-store-apis +title: Deprecate V1 cache Store Apis +until: '5.0' +since: '4.7' +--- + +Deprecates various methods on the store and store-cache-wrapper that were specific to the v1 cache. + +Most applications should not encounter this deprecation, but if you do it means that an addon you are using is likely using these methods as part of having implemented its own cache. + +The implementation will need to update to the V2 Cache API equivalent method as detailed in the deprecation method. Generally this means the implementation needs to be more broadly reworked to use the newer V2.1 Cache API. diff --git a/content/ember-data/v4/ember-data-model-save-promise.md b/content/ember-data/v4/ember-data-model-save-promise.md new file mode 100644 index 00000000..ef2959cf --- /dev/null +++ b/content/ember-data/v4/ember-data-model-save-promise.md @@ -0,0 +1,17 @@ +--- +displayId: ember-data:model-save-promise +title: Model Save Promise +until: '5.0' +since: '4.4' +--- + +Affects: + +- `model.save` / `store.saveRecord` +- `model.reload` + +Deprecates the promise-proxy returned by these methods in favor of a Promise return value. + +To resolve this deprecation, `await` or `.then` the return value before doing work with the result instead of accessing values via the proxy. + +To continue utilizing flags such as `isPending` in your templates consider using [ember-promise-helpers](https://github.com/fivetanley/ember-promise-helpers) diff --git a/content/ember-data/v4/ember-data-no-a-with-array-like.md b/content/ember-data/v4/ember-data-no-a-with-array-like.md new file mode 100644 index 00000000..4861aba5 --- /dev/null +++ b/content/ember-data/v4/ember-data-no-a-with-array-like.md @@ -0,0 +1,24 @@ +--- +displayId: ember-data:no-a-with-array-like +title: No A With Array Like +until: '5.0' +since: '4.7' +--- + +Deprecates calling `A()` when an EmberData ArrayLike class is detected. This deprecation may not always trigger due to complexities in ember-source versions and the use (or disabling) of prototype extensions. + +To fix, use the native JavaScript array methods instead of the `EmberArray` methods and refrain from wrapping the array in `A()`. + +Note that some computed property macros may themselves utilize `A()`, in which scenario the computed properties need to be upgraded to Ember Octane syntax. + +For instance, instead of: + +```js +A([]); +``` + +Use: + +```js +[]; +``` diff --git a/content/ember-data/v4/ember-data-non-explicit-relationships.md b/content/ember-data/v4/ember-data-non-explicit-relationships.md new file mode 100644 index 00000000..d8a6d341 --- /dev/null +++ b/content/ember-data/v4/ember-data-non-explicit-relationships.md @@ -0,0 +1,29 @@ +--- +displayId: ember-data:non-explicit-relationships +title: Non Explicit Relationships +until: '5.0' +since: '4.7' +--- + +Deprecates when polymorphic relationships are detected via inheritance or mixins and no polymorphic relationship configuration has been setup. + +For further reading please review [RFC#793](https://rfcs.emberjs.com/id/0793-polymporphic-relations-without-inheritance) which introduced support for explicit relationship polymorphism without mixins or inheritance. + +You may still use mixins and inheritance to setup your polymorphism; however, the class structure is no longer what drives the design. Instead polymorphism is "traits" based or "structural": so long as each model which can satisfy the polymorphic relationship defines the inverse in the same way they work. + +Notably: `inverse: null` relationships can receive any type as a record with no additional configuration at all. + +Example Polymorphic Relationship Configuration: + +```js +// polymorphic relationship +class Tag extends Model { + @hasMany('taggable', { async: false, polymorphic: true, inverse: 'tags' }) + tagged; +} + +// an inverse concrete relationship (e.g. satisfies "taggable") +class Post extends Model { + @hasMany('tag', { async: false, inverse: 'tagged', as: 'taggable' }) tags; +} +``` diff --git a/content/ember-data/v4/ember-data-rsvp-unresolved-async.md b/content/ember-data/v4/ember-data-rsvp-unresolved-async.md new file mode 100644 index 00000000..d00d98c6 --- /dev/null +++ b/content/ember-data/v4/ember-data-rsvp-unresolved-async.md @@ -0,0 +1,12 @@ +--- +displayId: ember-data:rsvp-unresolved-async +title: Rsvp Unresolved Async +until: '5.0' +since: '4.5' +--- + +Deprecates when a request promise did not resolve prior to the store tearing down. + +Note: in most cases even with the promise guard that is now being deprecated a test crash would still be encountered. + +To resolve: Tests or Fastboot instances which crash need to find triggers requests and properly await them before tearing down. diff --git a/ember-cli-build.js b/ember-cli-build.js index 88ee8b15..ff0e36c8 100644 --- a/ember-cli-build.js +++ b/ember-cli-build.js @@ -4,7 +4,7 @@ const path = require('path'); const EmberApp = require('ember-cli/lib/broccoli/ember-app'); -/* +/* Map over filenames in order to help generate the prembered URLs for the individual deprecation article pages. Their URL is something like `/id/project.bower-dependencies` @@ -30,6 +30,7 @@ module.exports = function (defaults) { '/ember/v1.x', '/ember-data/v2.x', '/ember-data/v3.x', + '/ember-data/v4.x', '/ember-cli/v2.x', '/ember-cli/v4.x', ...getDeprecationFilenames(), diff --git a/lib/content-docs-generator/index.js b/lib/content-docs-generator/index.js index 9a93033f..05c26fbc 100644 --- a/lib/content-docs-generator/index.js +++ b/lib/content-docs-generator/index.js @@ -12,6 +12,7 @@ const contentFolders = [ 'ember/v4', 'ember-data/v2', 'ember-data/v3', + 'ember-data/v4', 'ember-cli/v2', 'ember-cli/v4', ];