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

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
});

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);

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.

1
2
3
4
5
6
7

import Ember from 'ember';

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

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

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.

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 });
  }
});

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;
});
    ```

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

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

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));
});

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');

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

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:

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.

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.

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.

1
2
3

import DS from 'ember-data';

export default DS.ActiveModelSerializer;

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

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.

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.

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
});

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');

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);
});