Working with the Data Store

What is it?

The data store is an instance of DS. The data store is an in-memory cache for storing and managing your data. You register resources with the data store which tell the data store how to manage your data. The data store holds instances of your resources.

Adding and removing data

There is only one way to add instances to the data store, and that is via DS#inject. This method takes an object or an array of objects, and expects each object to contain a primary key for indexing. DS#inject is used by various other DS methods. For example, DS#find first calls the find method of an adapter, then calls DS#inject to inject the result into the data store. Instances can only leave the data store via DS#eject and DS#ejectAll.

References, not copies

Once an instance has been added to the data store it is indexed by its primary key. A method called identity mapping is used to keep a single unique object in memory for each instance in the data store. When you retrieve an instance or instances from the data store, you are given references to the actual objects. If you were to inject instances that have the same primary keys as instances already in the data store, then the properties of the new instances are mixed in to the existing instances, and any references to the originally injected instances remain valid. For example:

var store = new JSData.DS();
var User = store.defineResource('user');
var user = User.inject({ id: 1, name: 'John' });
var user2 = User.inject({ id: 1, age: 30 });

user; // User { id: 1, name: 'John', age: 30 }
user2; // User { id: 1, name: 'John', age: 30 }
User.get(1); // User { id: 1, name: 'John', age: 30 }
user === user2; // true
user === User.get(1); // true
user2 === User.get(1); // true

Async vs Sync

The data store has an arsenal of asynchronous and synchronous methods for managing your data. The async methods first work through adapters, then effect any necessary changes in the data store. The sync methods only affect the data store.

Some of the async and sync methods are counterparts. For example:

If you have no need for any of the adapters, you could use only data store just for its organized caching capabilities.

📘

Need Help?

Want more examples or have a question? Post on the [Slack channel(http://slack.js-data.io) or mailing list then we'll get your question answered and probably update this wiki.