DS.Store Class addon/-private/system/store.js:98


Extends: Ember.Service

Defined in: addon/-private/system/store.js:98

Module: ember-data

The store contains all of the data for records loaded from the server. It is also responsible for creating instances of DS.Model that wrap the individual data for a record, so that they can be bound to in your Handlebars templates.

Define your application's store like this:

app/services/store.js
1
2
3
4
import DS from 'ember-data';

export default DS.Store.extend({
});

Most Ember.js applications will only have a single DS.Store that is automatically created by their Ember.Application.

You can retrieve models from the store in several ways. To retrieve a record for a specific id, use DS.Store's findRecord() method:

1
2
store.findRecord('person', 123).then(function (person) {
});

By default, the store will talk to your backend using a standard REST mechanism. You can customize how the store talks to your backend by specifying a custom adapter:

app/adapters/application.js
1
2
3
4
import DS from 'ember-data';

export default DS.Adapter.extend({
});

You can learn more about writing a custom adapter by reading the DS.Adapter documentation.

Store createRecord() vs. push() vs. pushPayload()

The store provides multiple ways to create new record objects. They have some subtle differences in their use which are detailed below:

createRecord is used for creating new records on the client side. This will return a new record in the created.uncommitted state. In order to persist this record to the backend you will need to call record.save().

push is used to notify Ember Data's store of new or updated records that exist in the backend. This will return a record in the loaded.saved state. The primary use-case for store#push is to notify Ember Data about record updates (full or partial) that happen outside of the normal adapter methods (for example SSE or Web Sockets).

pushPayload is a convenience wrapper for store#push that will deserialize payloads if the Serializer implements a pushPayload method.

Note: When creating a new record using any of the above methods Ember Data will update DS.RecordArrays such as those returned by store#peekAll(), store#findAll() or store#filter(). This means any data bindings or computed properties that depend on the RecordArray will automatically be synced to include the new or updated record values.

Show:

_dematerializeRecord

(internalModel) private

When a record is destroyed, this un-indexes it and removes it from any record arrays so it can be GCed.

Parameters:

internalModel InternalModel

_fetchAll

(typeClass, array) Promise private

Parameters:

typeClass DS.Model
array DS.RecordArray

Returns:

Promise
promise

_generateId

(modelName, properties) String private

If possible, this method asks the adapter to generate an ID for a newly created record.

Parameters:

modelName String
properties Object
from the new record

Returns:

String
if the adapter can generate one, an ID

_load

(type, data) private

This internal method is used by push.

Parameters:

type (String|DS.Model)
data Object

adapterFor

(modelName) public

Returns an instance of the adapter for a given type. For example, adapterFor('person') will return an instance of App.PersonAdapter.

If no App.PersonAdapter is found, this method will look for an App.ApplicationAdapter (the default adapter for your entire application).

If no App.ApplicationAdapter is found, it will return the value of the defaultAdapter.

Parameters:

modelName String

Returns:

DS.Adapter

buildRecord

(type, id, data) InternalModel private

Build a brand new record for a given type, ID, and initial data.

Parameters:

type DS.Model
id String
data Object

Returns:

InternalModel
internal model

createRecord

(modelName, inputProperties) DS.Model

Create a new record in the current store. The properties passed to this method are set on the newly created record.

To create a new instance of a Post:

1
2
3
store.createRecord('post', {
  title: "Rails is omakase"
});

To create a new instance of a Post that has a relationship with a User record:

1
2
3
4
5
var user = this.store.peekRecord('user', 1);
store.createRecord('post', {
  title: "Rails is omakase",
  user: user
});

Parameters:

modelName String
inputProperties Object
a hash of properties to set on the newly created record.

Returns:

DS.Model
record

dataWasUpdated

(type, internalModel) private

If the adapter updates attributes the record will notify the store to update its membership in any filters. To avoid thrashing, this method is invoked only once per run loop per record.

Parameters:

type Class
internalModel InternalModel

deleteRecord

(record)

For symmetry, a record can be deleted via the store.

Example

1
2
3
4
5
var post = store.createRecord('post', {
  title: "Rails is omakase"
});

store.deleteRecord(post);

Parameters:

record DS.Model

didSaveRecord

(internalModel, data) private

This method is called once the promise returned by an adapter's createRecord, updateRecord or deleteRecord is resolved.

If the data provides a server-generated ID, it will update the record and the store's indexes.

Parameters:

internalModel InternalModel
the in-flight internal model
data Object
optional data (see above)

didUpdateAll

(typeClass) private

Parameters:

typeClass DS.Model

fetchRecord

(internalModel) Promise private

This method is called by findRecord if it discovers that a particular type/id pair hasn't been loaded yet to kick off a request to the adapter.

Parameters:

internalModel InternalModel
model

Returns:

Promise
promise

filter

(modelName, query, filter) DS.PromiseArray deprecated private

Takes a type and filter function, and returns a live RecordArray that remains up to date as new records are loaded into the store or created locally.

The filter function takes a materialized record, and returns true if the record should be included in the filter and false if it should not.

Example

1
2
3
store.filter('post', function(post) {
  return post.get('unread');
});

The filter function is called once on all records for the type when it is created, and then once on each newly loaded or created record.

If any of a record's properties change, or if it changes state, the filter function will be invoked again to determine whether it should still be in the array.

Optionally you can pass a query, which is the equivalent of calling query with that same query, to fetch additional records from the server. The results returned by the server could then appear in the filter if they match the filter function.

The query itself is not used to filter records, it's only sent to your server for you to be able to do server-side filtering. The filter function will be applied on the returned results regardless.

Example

1
2
3
4
5
6
7
8
store.filter('post', { unread: true }, function(post) {
  return post.get('unread');
}).then(function(unreadPosts) {
  unreadPosts.get('length'); // 5
  var unreadPost = unreadPosts.objectAt(0);
  unreadPost.set('unread', false);
  unreadPosts.get('length'); // 4
});

Parameters:

modelName String
query Object
optional query
filter Function

Returns:

DS.PromiseArray

find

(modelName, id, options) Promise private

Parameters:

modelName String
id String|Integer
options Object

Returns:

Promise
promise

findAll

(modelName, options) Promise

findAll ask the adapter's findAll method to find the records for the given type, and return a promise that will be resolved once the server returns the values. The promise will resolve into all records of this type present in the store, even if the server only returns a subset of them.

app/routes/authors.js
1
2
3
4
5
6
7
import Ember from 'ember';

export default Ember.Route.extend({
  model: function(params) {
    return this.store.findAll('author');
  }
});

Parameters:

modelName String
options Object

Returns:

Promise
promise

findBelongsTo

(owner, link, relationship) Promise private

Parameters:

owner DS.Model
link Any
relationship Relationship

Returns:

Promise
promise

findByIds

(modelName, ids) Promise private

This method makes a series of requests to the adapter's find method and returns a promise that resolves once they are all loaded.

Parameters:

modelName String
ids Array

Returns:

Promise
promise

findHasMany

(owner, link, relationship) Promise private

If a relationship was originally populated by the adapter as a link (as opposed to a list of IDs), this method is called when the relationship is fetched.

The link (which is usually a URL) is passed through unchanged, so the adapter can make whatever request it wants.

The usual use-case is for the server to register a URL as a link, and then use that URL in the future to make a request for the relationship.

Parameters:

owner DS.Model
link Any
relationship (Relationship)

Returns:

Promise
promise

findMany

(internalModels) Promise private

Parameters:

internalModels Array

Returns:

Promise
promise

findRecord

(modelName, id, options) Promise

This method returns a record for a given type and id combination.

The findRecord method will always return a promise that will be resolved with the record. If the record was already in the store, the promise will be resolved immediately. Otherwise, the store will ask the adapter's find method to find the necessary data.

The findRecord method will always resolve its promise with the same object for a given type and id.

Example

app/routes/post.js
1
2
3
4
5
6
7
import Ember from 'ember';

export default Ember.Route.extend({
  model: function(params) {
    return this.store.findRecord('post', params.post_id);
  }
});

If you would like to force the record to reload, instead of loading it from the cache when present you can set reload: true in the options object for findRecord.

app/routes/post/edit.js
1
2
3
4
5
6
7
import Ember from 'ember';

export default Ember.Route.extend({
  model: function(params) {
    return this.store.findRecord('post', params.post_id, { reload: true });
  }
});

Parameters:

modelName String
id (String|Integer)
options Object

Returns:

Promise
promise

flushPendingSave

private

This method is called at the end of the run loop, and flushes any records passed into scheduleSave

getReference

(type, id) RecordReference

Get the reference for the specified record.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var userRef = store.getReference('user', 1);

// check if the user is loaded
var isLoaded = userRef.value() !== null;

// get the record of the reference (null if not yet available)
var user = userRef.value();

// get the identifier of the reference
if (userRef.remoteType() === "id") {
var id = userRef.id();
}

// load user (via store.find)
userRef.load().then(...)

// or trigger a reload
userRef.reload().then(...)

// provide data for reference
userRef.push({ id: 1, username: "@user" }).then(function(user) {
  userRef.value() === user;
});
    ```

Parameters:

type String
id String|Integer

Returns:

RecordReference

hasRecordForId

(modelName, inputId) Boolean

Returns true if a record for a given type and ID is already loaded.

Parameters:

modelName (String|DS.Model)
inputId (String|Integer)

Returns:

Boolean

init

private

modelFor

(modelName) DS.Model

Returns a model class for a particular key. Used by methods that take a type key (like find, createRecord, etc.)

Parameters:

modelName String

Returns:

DS.Model

normalize

(modelName, payload) Object

normalize converts a json payload into the normalized form that push expects.

Example

1
2
3
4
5
socket.on('message', function(message) {
  var modelName = message.model;
  var data = message.data;
  store.push(modelName, store.normalize(modelName, data));
});

Parameters:

modelName String
The name of the model type for this payload
payload Object

Returns:

Object
The normalized payload

peekAll

(modelName) DS.RecordArray

This method returns a filtered array that contains all of the known records for a given type in the store.

Note that because it's just a filter, the result will contain any locally created records of the type, however, it will not make a request to the backend to retrieve additional records. If you would like to request all the records from the backend please use store.findAll.

Also note that multiple calls to peekAll for a given type will always return the same RecordArray.

Example

1
var localPosts = store.peekAll('post');

Parameters:

modelName String

Returns:

DS.RecordArray

peekRecord

(modelName, id) DS.Model|null

Get a record by a given type and ID without triggering a fetch.

This method will synchronously return the record if it is available in the store, otherwise it will return null. A record is available if it has been fetched earlier, or pushed manually into the store.

Note: This is an synchronous method and does not return a promise.

1
2
3
var post = store.peekRecord('post', 1);

post.get('id'); // 1

Parameters:

modelName String
id String|Integer

Returns:

DS.Model|null
record

push

(data) DS.Model|Array

Push some data for a given type into the store.

This method expects normalized JSON API document. This means you have to follow JSON API specification with few minor adjustments: - record's type should always be in singular, dasherized form - members (properties) should be camelCased

Your primary data should be wrapped inside data property:

1
2
3
4
5
6
7
8
9
10
11
store.push({
  data: {
    // primary data for single record of type `Person`
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Daniel',
      lastName: 'Kmak'
    }
  }
});

Demo.

data property can also hold an array (of records):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
store.push({
  data: [
    // an array of records
    {
      id: '1',
      type: 'person',
      attributes: {
        firstName: 'Daniel',
        lastName: 'Kmak'
      }
    },
    {
      id: '2',
      type: 'person',
      attributes: {
        firstName: 'Tom',
        lastName: 'Dale'
      }
    }
  ]
});

Demo.

There are some typical properties for JSONAPI payload: * id - mandatory, unique record's key * type - mandatory string which matches model's dasherized name in singular form * attributes - object which holds data for record attributes - DS.attr's declared in model * relationships - object which must contain any of the following properties under each relationships' respective key (example path is relationships.achievements.data): - links - data - place for primary data - meta - object which contains meta-information about relationship

For this model:

app/models/person.js
1
2
3
4
5
6
7
8
import DS from 'ember-data';

export default DS.Model.extend({
  firstName: DS.attr('string'),
  lastName: DS.attr('string'),

  children: DS.hasMany('person')
});

To represent the children as IDs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  data: {
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Tom',
      lastName: 'Dale'
    },
    relationships: {
      children: {
        data: [
          {
            id: '2',
            type: 'person'
          },
          {
            id: '3',
            type: 'person'
          },
          {
            id: '4',
            type: 'person'
          }
        ]
      }
    }
  }
}

Demo.

To represent the children relationship as a URL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  data: {
    id: '1',
    type: 'person',
    attributes: {
      firstName: 'Tom',
      lastName: 'Dale'
    },
    relationships: {
      children: {
        links: {
          related: '/people/1/children'
        }
      }
    }
  }
}

If you're streaming data or implementing an adapter, make sure that you have converted the incoming data into this form. The store's normalize method is a convenience helper for converting a json payload into the form Ember Data expects.

1
store.push(store.normalize('person', data));

This method can be used both to push in brand new records, as well as to update existing records.

Parameters:

data Object

Returns:

DS.Model|Array
the record(s) that was created or updated.

pushPayload

(modelName, inputPayload)

Push some raw data into the store.

This method can be used both to push in brand new records, as well as to update existing records. You can push in more than one type of object at once. All objects should be in the format expected by the serializer.

app/serializers/application.js
1
2
3
import DS from 'ember-data';

export default DS.ActiveModelSerializer;
1
2
3
4
5
6
7
8
9
10
var pushData = {
  posts: [
    { id: 1, post_title: "Great post", comment_ids: [2] }
  ],
  comments: [
    { id: 2, comment_body: "Insightful comment" }
  ]
}

store.pushPayload(pushData);

By default, the data will be deserialized using a default serializer (the application serializer if it exists).

Alternatively, pushPayload will accept a model type which will determine which serializer will process the payload.

app/serializers/application.js
1
2
3
import DS from 'ember-data';

export default DS.ActiveModelSerializer;
app/serializers/post.js
1
2
3
import DS from 'ember-data';

export default DS.JSONSerializer;
1
2
store.pushPayload('comment', pushData); // Will use the application serializer
store.pushPayload('post', pushData); // Will use the post serializer

Parameters:

modelName String
Optionally, a model type used to determine which serializer will be used
inputPayload Object

query

(modelName, query) Promise

This method delegates a query to the adapter. This is the one place where adapter-level semantics are exposed to the application.

Exposing queries this way seems preferable to creating an abstract query language for all server-side queries, and then require all adapters to implement them.


If you do something like this:

1
store.query('person', { page: 1 });

The call made to the server, using a Rails backend, will look something like this:

1
2
3
Started GET "/api/v1/person?page=1"
Processing by Api::V1::PersonsController#index as HTML
Parameters: { "page"=>"1" }

If you do something like this:

1
store.query('person', { ids: [1, 2, 3] });

The call to the server, using a Rails backend, will look something like this:

1
2
3
Started GET "/api/v1/person?ids%5B%5D=1&ids%5B%5D=2&ids%5B%5D=3"
Processing by Api::V1::PersonsController#index as HTML
Parameters: { "ids" => ["1", "2", "3"] }

This method returns a promise, which is resolved with a RecordArray once the server returns.

Parameters:

modelName String
query Any
an opaque query to be used by the adapter

Returns:

Promise
promise

queryRecord

(modelName, query) Promise

This method delegates a query to the adapter. This is the one place where adapter-level semantics are exposed to the application.

Exposing queries this way seems preferable to creating an abstract query language for all server-side queries, and then require all adapters to implement them.

This method returns a promise, which is resolved with a RecordObject once the server returns.

Parameters:

modelName String
query Any
an opaque query to be used by the adapter

Returns:

Promise
promise

recordForId

(modelName, id) DS.Model private

Returns id record for a given type and ID. If one isn't already loaded, it builds a new record and leaves it in the empty state.

Parameters:

modelName String
id (String|Integer)

Returns:

DS.Model
record

recordIsLoaded

(modelName, id) Boolean

This method returns if a certain record is already loaded in the store. Use this function to know beforehand if a findRecord() will result in a request or that it will be a cache hit.

Example

1
2
3
4
store.recordIsLoaded('post', 1); // false
store.findRecord('post', 1).then(function() {
  store.recordIsLoaded('post', 1); // true
});

Parameters:

modelName String
id String

Returns:

Boolean

recordWasError

(internalModel, error) private

This method is called once the promise returned by an adapter's createRecord, updateRecord or deleteRecord is rejected (with anything other than a DS.InvalidError).

Parameters:

internalModel InternalModel
error Error

recordWasInvalid

(internalModel, errors) private

This method is called once the promise returned by an adapter's createRecord, updateRecord or deleteRecord is rejected with a DS.InvalidError.

Parameters:

internalModel InternalModel
errors Object

reloadRecord

(internalModel) Promise private

This method is called by the record's reload method.

This method calls the adapter's find method, which returns a promise. When that promise resolves, reloadRecord will resolve the promise returned by the record's reload.

Parameters:

internalModel DS.Model

Returns:

Promise
promise

retrieveManagedInstance

(modelName, name, fallbacks) Ember.Object private

Retrieve a particular instance from the container cache. If not found, creates it and placing it in the cache.

Enabled a store to manage local instances of adapters and serializers.

Parameters:

modelName String
the object modelName
name String
the object name
fallbacks Array
the fallback objects to lookup if the lookup for modelName or 'application' fails

Returns:

Ember.Object

scheduleSave

(internalModel, resolver, options) private

This method is called by record.save, and gets passed a resolver for the promise that record.save returns.

It schedules saving to happen at the end of the run loop.

Parameters:

internalModel InternalModel
resolver Resolver
options Object

serialize

(record, options) private

Returns a JSON representation of the record using a custom type-specific serializer, if one exists.

The available options are:

  • includeId: true if the record's ID should be included in the JSON representation

Parameters:

record DS.Model
the record to serialize
options Object
an options hash

serializerFor

(modelName) DS.Serializer public

Returns an instance of the serializer for a given type. For example, serializerFor('person') will return an instance of App.PersonSerializer.

If no App.PersonSerializer is found, this method will look for an App.ApplicationSerializer (the default serializer for your entire application).

if no App.ApplicationSerializer is found, it will attempt to get the defaultSerializer from the PersonAdapter (adapterFor('person')).

If a serializer cannot be found on the adapter, it will fall back to an instance of DS.JSONSerializer.

Parameters:

modelName String
the record to serialize

Returns:

DS.Serializer

typeMapFor

(typeClass) Object private

Returns a map of IDs to client IDs for a given type.

Parameters:

typeClass DS.Model

Returns:

Object
typeMap

unloadAll

(modelName)

This method unloads all records in the store.

Optionally you can pass a type which unload all records for a given type.

1
2
store.unloadAll();
store.unloadAll('post');

Parameters:

modelName String=

unloadRecord

(record)

For symmetry, a record can be unloaded via the store. Only non-dirty records can be unloaded.

Example

1
2
3
store.findRecord('post', 1).then(function(post) {
  store.unloadRecord(post);
});

Parameters:

record DS.Model

updateId

(internalModel, data) private

When an adapter's createRecord, updateRecord or deleteRecord resolves with data, this method extracts the ID from the supplied data.

Parameters:

internalModel InternalModel
data Object
Show:

adapter

{(DS.Adapter|String)}

The adapter to use to communicate to a backend server or other persistence layer.

This can be specified as an instance, class, or string.

If you want to specify app/adapters/custom.js as a string, do:

1
adapter: 'custom'

Default: DS.JSONAPIAdapter

defaultAdapter

private

This property returns the adapter, after resolving a possible string key.

If the supplied adapter was a class, or a String property path resolved to a class, this property will instantiate the class.

This property is cacheable, so the same instance of a specified adapter class should be used for the lifetime of the store.

Returns:

DS.Adapter