Skip to content

Release v6.5.0 #2121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion guides/v6.3.0/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ At the top of the page (for the package, method, or class), you will find the wo

You can open the link to find a comment block. Make a pull request to update the comment block. The API Guides may take a few weeks to update while the future release is finalized.

Here is an example of updating a method. At the top of the section for [`store.createRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/createRecord?anchor=createRecord), you can find the words "Defined in."
Here is an example of updating a method. At the top of the section for [`store.createRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/createRecord?anchor=createRecord), you can find the words "Defined in."

Next to the words is, once again, the link to the source code [`ds-model-store.ts`](https://github.com/emberjs/data/blob/master/packages/store/addon/-private/system/ds-model-store.ts).

Expand Down
2 changes: 1 addition & 1 deletion guides/v6.3.0/in-depth-topics/native-classes-in-depth.md
Original file line number Diff line number Diff line change
Expand Up @@ -720,7 +720,7 @@ after overriding. This allows the super class method to continue operating as it
normally would.

One common example is when overriding the
[`normalizeResponse()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/normalizeResponse?anchor=normalizeResponse)
[`normalizeResponse()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/normalizeResponse?anchor=normalizeResponse)
hook in one of EmberData's serializers.

A handy shortcut for this is to use a "spread operator", like `...arguments`:
Expand Down
16 changes: 8 additions & 8 deletions guides/v6.3.0/models/creating-updating-and-deleting-records.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
## Creating Records

You can create records by calling the
[`createRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/createRecord?anchor=createRecord)
[`createRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/createRecord?anchor=createRecord)
method on the store.

```javascript
Expand All @@ -28,7 +28,7 @@ this.store.findRecord('post', 1).then(function(post) {
## Persisting Records

Records in EmberData are persisted on a per-instance basis.
Call [`save()`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/save?anchor=save)
Call [`save()`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/save?anchor=save)
on any instance of `Model` and it will make a network request.

EmberData takes care of tracking the state of each record for
Expand Down Expand Up @@ -60,10 +60,10 @@ store.findRecord('post', 1).then(function(post) {

You can tell if a record has outstanding changes that have not yet been
saved by checking its
[`hasDirtyAttributes`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/properties/hasDirtyAttributes?anchor=hasDirtyAttributes)
[`hasDirtyAttributes`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/properties/hasDirtyAttributes?anchor=hasDirtyAttributes)
property. You can also see which parts of
the record were changed and what the original value was using the
[`changedAttributes()`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/changedAttributes?anchor=changedAttributes)
[`changedAttributes()`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/changedAttributes?anchor=changedAttributes)
method. `changedAttributes` returns an object, whose keys are the changed
properties and values are an array of values `[oldValue, newValue]`.

Expand All @@ -75,7 +75,7 @@ person.hasDirtyAttributes; // => true
person.changedAttributes(); // => { isAdmin: [false, true] }
```

At this point, you can either persist your changes via `save()` or you can roll back your changes using [`rollbackAttributes()`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/rollbackAttributes?anchor=rollbackAttributes).
At this point, you can either persist your changes via `save()` or you can roll back your changes using [`rollbackAttributes()`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/rollbackAttributes?anchor=rollbackAttributes).

```javascript
person.hasDirtyAttributes; // => true
Expand Down Expand Up @@ -105,7 +105,7 @@ the errors from saving a blog post in your template:

## Promises

[`save()`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/save?anchor=save) returns
[`save()`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/save?anchor=save) returns
a promise, which makes it easy to asynchronously handle success and failure
scenarios. Here's a common pattern:

Expand All @@ -126,10 +126,10 @@ try {

## Deleting Records

Deleting records is as straightforward as creating records. Call [`deleteRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/deleteRecord?anchor=deleteRecord)
Deleting records is as straightforward as creating records. Call [`deleteRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/deleteRecord?anchor=deleteRecord)
on any instance of `Model`. This flags the record as `isDeleted`. The
deletion can then be persisted using `save()`. Alternatively, you can use
the [`destroyRecord`](https://api.emberjs.com/ember-data/5.4.0/classes/Model/methods/destroyRecord?anchor=destroyRecord) method to delete and persist at the same time.
the [`destroyRecord`](https://api.emberjs.com/ember-data/5.3.12/classes/Model/methods/destroyRecord?anchor=destroyRecord) method to delete and persist at the same time.

```javascript
let post = store.peekRecord('post', 1);
Expand Down
8 changes: 4 additions & 4 deletions guides/v6.3.0/models/customizing-adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,25 +51,25 @@ export default class PostAdapter extends JSONAPIAdapter {
EmberData comes with several built-in adapters.
Feel free to use these adapters as a starting point for creating your own custom adapter.

- [`Adapter`](https://api.emberjs.com/ember-data/5.4.0/classes/Adapter) is the basic adapter
- [`Adapter`](https://api.emberjs.com/ember-data/5.3.12/classes/Adapter) is the basic adapter
with no functionality. It is generally a good starting point if you
want to create an adapter that is radically different from the other
Ember adapters.

- [`JSONAPIAdapter`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPIAdapter)
- [`JSONAPIAdapter`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPIAdapter)
The `JSONAPIAdapter` is the default adapter and follows JSON:API
conventions to communicate with an HTTP server by transmitting JSON
via XHR.

- [`RESTAdapter`](https://api.emberjs.com/ember-data/5.4.0/classes/RESTAdapter)
- [`RESTAdapter`](https://api.emberjs.com/ember-data/5.3.12/classes/RESTAdapter)
The `RESTAdapter` allows your store to communicate with an HTTP server
by transmitting JSON via XHR. Before EmberData 2.0 this adapter was the default.


## Customizing the JSONAPIAdapter

The
[JSONAPIAdapter](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPIAdapter)
[JSONAPIAdapter](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPIAdapter)
has a handful of hooks that are commonly used to extend it to work
with non-standard backends.

Expand Down
26 changes: 13 additions & 13 deletions guides/v6.3.0/models/customizing-serializers.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ format, EmberData allows you to customize the serializer or use a
different serializer entirely.

EmberData ships with 3 serializers. The
[`JSONAPISerializer`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer)
[`JSONAPISerializer`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer)
is the default serializer and works with JSON:API backends. The
[`JSONSerializer`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONSerializer)
[`JSONSerializer`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONSerializer)
is a simple serializer for working with single JSON object or arrays of records. The
[`RESTSerializer`](https://api.emberjs.com/ember-data/5.4.0/classes/RESTSerializer)
[`RESTSerializer`](https://api.emberjs.com/ember-data/5.3.12/classes/RESTSerializer)
is a more complex serializer that supports sideloading and was the default
serializer before 2.0.

Expand Down Expand Up @@ -141,7 +141,7 @@ export default class PostSerializer extends JSONAPISerializer {
```

To change the format of the data that is sent to the backend store, you can use
the [`serialize()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/serialize?anchor=serialize)
the [`serialize()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/serialize?anchor=serialize)
hook. Let's say that we have this JSON:API response from EmberData:

```json
Expand Down Expand Up @@ -200,7 +200,7 @@ export default class ApplicationSerializer extends JSONAPISerializer {

Similarly, if your backend store provides data in a format other than JSON:API,
you can use the
[`normalizeResponse()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/normalizeResponse?anchor=normalizeResponse)
[`normalizeResponse()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/normalizeResponse?anchor=normalizeResponse)
hook. Using the same example as above, if the server provides data that looks
like:

Expand Down Expand Up @@ -254,11 +254,11 @@ export default class ApplicationSerializer extends JSONAPISerializer {
```

To normalize only a single model, you can use the
[`normalize()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/normalize?anchor=normalize)
[`normalize()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/normalize?anchor=normalize)
hook similarly.

For more hooks to customize the serializer with, see the [EmberData serializer
API documentation](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer).
API documentation](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer).

### IDs

Expand Down Expand Up @@ -311,7 +311,7 @@ in the document payload returned by your server:

If the attributes returned by your server use a different convention
you can use the serializer's
[`keyForAttribute()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/keyForAttribute?anchor=keyForAttribute)
[`keyForAttribute()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/keyForAttribute?anchor=keyForAttribute)
method to convert an attribute name in your model to a key in your JSON
payload. For example, if your backend returned attributes that are
`under_scored` instead of `dash-cased` you could override the `keyForAttribute`
Expand Down Expand Up @@ -422,7 +422,7 @@ The JSON should encode the relationship as an ID to another record:
```
If needed these naming conventions can be overwritten by implementing
the
[`keyForRelationship()`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPISerializer/methods/keyForRelationship?anchor=keyForRelationship)
[`keyForRelationship()`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPISerializer/methods/keyForRelationship?anchor=keyForRelationship)
method.

```javascript {data-filename=app/serializers/application.js}
Expand Down Expand Up @@ -545,7 +545,7 @@ looks similar to this:
The `JSONAPISerializer` is built on top of the `JSONSerializer` so they share
many of the same hooks for customizing the behavior of the
serialization process. Be sure to check out the
[API docs](https://api.emberjs.com/ember-data/5.4.0/classes/JSONSerializer)
[API docs](https://api.emberjs.com/ember-data/5.3.12/classes/JSONSerializer)
for a full list of methods and properties.


Expand Down Expand Up @@ -751,7 +751,7 @@ Note that the type is `"post"` to match the post model and the
### Normalizing adapter responses

When creating a custom serializer you will need to define a
[normalizeResponse](https://api.emberjs.com/ember-data/5.4.0/classes/Serializer/methods/normalizeResponse?anchor=normalizeResponse)
[normalizeResponse](https://api.emberjs.com/ember-data/5.3.12/classes/Serializer/methods/normalizeResponse?anchor=normalizeResponse)
method to transform the response from the adapter into the normalized
JSON object described above.

Expand All @@ -763,7 +763,7 @@ the possible values of: `'findRecord'`, `'queryRecord'`, `'findAll'`,
`'createRecord'`, `'deleteRecord'`, and `'updateRecord'`) as arguments.

A custom serializer will also need to define a
[normalize](https://api.emberjs.com/ember-data/5.4.0/classes/Serializer/methods/normalize?anchor=normalize)
[normalize](https://api.emberjs.com/ember-data/5.3.12/classes/Serializer/methods/normalize?anchor=normalize)
method.
This method is called by `store.normalize(type, payload)` and is often
used for normalizing requests made outside of EmberData because they
Expand All @@ -772,7 +772,7 @@ do not fall into the normal CRUD flow that the adapter provides.
### Serializing records

Finally a serializer will need to implement a
[serialize](https://api.emberjs.com/ember-data/5.4.0/classes/Serializer/methods/serialize?anchor=serialize)
[serialize](https://api.emberjs.com/ember-data/5.3.12/classes/Serializer/methods/serialize?anchor=serialize)
method.
EmberData will provide a record snapshot and an options hash and this
method should return an object that the adapter will send to the
Expand Down
2 changes: 1 addition & 1 deletion guides/v6.3.0/models/defining-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ and [working with records](../creating-updating-and-deleting-records/) of that t
## Defining Attributes

The `person` model we generated earlier didn't have any attributes. Let's
add first and last name, as well as the birthday, using [`attr`](https://api.emberjs.com/ember-data/5.4.0/functions/@ember-data%2Fmodel/attr):
add first and last name, as well as the birthday, using [`attr`](https://api.emberjs.com/ember-data/5.3.12/functions/@ember-data%2Fmodel/attr):

```javascript {data-filename=app/models/person.js}
import Model, { attr } from '@ember-data/model';
Expand Down
16 changes: 8 additions & 8 deletions guides/v6.3.0/models/finding-records.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ The EmberData store provides an interface for retrieving records of a single typ

### Retrieving a Single Record

Use [`store.findRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/findRecord?anchor=findRecord) to retrieve a record by its type and ID.
Use [`store.findRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/findRecord?anchor=findRecord) to retrieve a record by its type and ID.
This will return a promise that fulfills with the requested record:

```javascript
Expand All @@ -13,7 +13,7 @@ this.store.findRecord('blog-post', 1) // => GET /blog-posts/1
});
```

Use [`store.peekRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/peekRecord?anchor=peekRecord) to retrieve a record by its type and ID, without making a network request.
Use [`store.peekRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/peekRecord?anchor=peekRecord) to retrieve a record by its type and ID, without making a network request.
This will return the record only if it is already present in the store:

```javascript
Expand All @@ -22,7 +22,7 @@ let blogPost = this.store.peekRecord('blog-post', 1); // => no network request

### Retrieving Multiple Records

Use [`store.findAll()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/findAll?anchor=findAll) to retrieve all of the records for a given type:
Use [`store.findAll()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/findAll?anchor=findAll) to retrieve all of the records for a given type:

```javascript
// GET /blog-posts
Expand All @@ -32,7 +32,7 @@ this.store.findAll('blog-post') // => GET /blog-posts
});
```

Use [`store.peekAll()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/peekAll?anchor=peekAll) to retrieve all of the records for a given type that are already loaded into the store, without making a network request:
Use [`store.peekAll()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/peekAll?anchor=peekAll) to retrieve all of the records for a given type that are already loaded into the store, without making a network request:

```javascript
let blogPosts = this.store.peekAll('blog-post'); // => no network request
Expand All @@ -47,7 +47,7 @@ the `[]` notation will not work--you'll have to use `objectAt(index)` instead.
### Querying for Multiple Records

EmberData provides the ability to query for records that meet certain criteria.
Calling [`store.query()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/query?anchor=query) will make a `GET` request with the passed object serialized as query params.
Calling [`store.query()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/query?anchor=query) will make a `GET` request with the passed object serialized as query params.
This method returns a `PromiseArray` in the same way as `findAll`.

For example, we could search for all `person` models who have the name of
Expand All @@ -67,7 +67,7 @@ this.store.query('person', {
### Querying for A Single Record

If you are using an adapter that supports server requests capable of returning a single model object,
EmberData provides a convenience method [`store.queryRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/queryRecord?anchor=queryRecord) that will return a promise that resolves with that single record.
EmberData provides a convenience method [`store.queryRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/queryRecord?anchor=queryRecord) that will return a promise that resolves with that single record.
The request is made via a method `queryRecord()` defined by the adapter.

For example, if your server API provides an endpoint for the currently logged in user:
Expand Down Expand Up @@ -95,7 +95,7 @@ export default class UserAdapter extends Adapter {
}
```

Then, calling [`store.queryRecord()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/queryRecord?anchor=queryRecord) will retrieve that object from the server:
Then, calling [`store.queryRecord()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/queryRecord?anchor=queryRecord) will retrieve that object from the server:

```javascript
store.queryRecord('user', {}).then(function(user) {
Expand All @@ -108,7 +108,7 @@ As in the case of `store.query()`, a query object can also be passed to `store.q
However the adapter must return a single model object, not an array containing one element,
otherwise EmberData will throw an exception.

Note that Ember's default [JSON:API adapter](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPIAdapter) does not provide the functionality needed to support `queryRecord()` directly as it relies on REST request definitions that return result data in the form of an array.
Note that Ember's default [JSON:API adapter](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPIAdapter) does not provide the functionality needed to support `queryRecord()` directly as it relies on REST request definitions that return result data in the form of an array.

If your server API or your adapter only provides array responses but you wish to retrieve just a single record, you can alternatively use the `query()` method as follows:

Expand Down
4 changes: 2 additions & 2 deletions guides/v6.3.0/models/pushing-records-into-the-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ you want to update the UI immediately.

### Pushing Records

To push a record into the store, call the store's [`push()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/push?anchor=push) method.
To push a record into the store, call the store's [`push()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/push?anchor=push) method.

For example, imagine we want to preload some data into the store when
the application boots for the first time.
Expand Down Expand Up @@ -81,7 +81,7 @@ the casing of the properties defined on the Model class.

If you would like the data to be normalized by the model's default
serializer before pushing it into the store, you can use the
[`store.pushPayload()`](https://api.emberjs.com/ember-data/5.4.0/classes/Store/methods/pushPayload?anchor=pushPayload) method.
[`store.pushPayload()`](https://api.emberjs.com/ember-data/5.3.12/classes/Store/methods/pushPayload?anchor=pushPayload) method.

```javascript {data-filename=app/serializers/album.js}
import RESTSerializer from '@ember-data/serializer/rest';
Expand Down
2 changes: 1 addition & 1 deletion guides/v6.3.0/models/relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ include those related records in the response returned to the client.
The value of the parameter should be a comma-separated list of names of the
relationships required.

If you are using an adapter that supports JSON:API, such as Ember's default [`JSONAPIAdapter`](https://api.emberjs.com/ember-data/5.4.0/classes/JSONAPIAdapter),
If you are using an adapter that supports JSON:API, such as Ember's default [`JSONAPIAdapter`](https://api.emberjs.com/ember-data/5.3.12/classes/JSONAPIAdapter),
you can easily add the `include` parameter to the server requests created by
the `findRecord()`, `findAll()`,
`query()` and `queryRecord()` methods.
Expand Down
Loading