Package ember-data-overview

Overview

EmberData is a lightweight reactive data library for javascript applications that provides composable primitives for ordering query/mutation/peek flows, managing network and cache, and reducing data for presentation that you can plug-and-play as desired for any api structure and format.

It was designed for robustly managing data in applications built with Ember and is agnostic to the underlying persistence mechanism, so it works just as well with JSON:API or GraphQL over HTTPS as it does with streaming WebSockets or local IndexedDB storage.

It provides many of the facilities you'd find in server-side ORMs like ActiveRecord, but is designed specifically for the unique environment of JavaScript in the browser.

EmberData is organized into primitives that compose together via public APIs.

  • [@ember-data/store](/ember-data/release/modules/@ember-data%2Fstore is the core and handles coordination
  • @ember-data/record-data is a resource cache for JSON:API structured data. It integrates with the store via the hook createRecordDataFor
  • @ember-data/model is a presentation layer, it integrates with the store via the hooks instantiateRecord and teardownRecord.
  • @ember-data/adapter provides various network API integrations for APIS built over specific REST or JSON:API conventions.
  • @ember-data/serializer pairs with @ember-data/adapter to normalize and serialize data to and from an API format into the JSON:API format understood by @ember-data/record-data.
  • @ember-data/debug provides debugging support for the ember-inspector.
  • ember-data is a "meta" package which bundles all of these together for convenience

The packages interop with each other through well defined public API boundaries. The core of the library is the store provided by @ember-data/store, while each of the other libraries plugs into the store when installed. Because these packages interop via fully public APIs, other libraries or applications may provide their own implementations. For instance, ember-m3 is a commonly used presentation and cache implementation suitable for complex resource objects and graphs.

Configuration

Deprecation Stripping

EmberData allows users to opt-in and remove code that exists to support deprecated behaviors.

If your app has resolved all deprecations present in a given version, you may specify that version as your "compatibility" version to remove the code that supported the deprecated behavior from your app.

1
2
3
4
5
let app = new EmberApp(defaults, {
 emberData: {
   compatWith: '4.8',
 },
});

randomUUID polyfill

EmberData uses UUID V4 by default to generate identifiers for new data created on the client. Identifier generation is configurable, but we also for convenience will polyfill the necessary feature if your browser support or deployment environment demands it. To activate this polyfill:

1
2
3
4
5
6
7
8
9
let app = new EmberApp(defaults, {
 '@embroider/macros': {
   setConfig: {
     '@ember-data/store': {
       polyfillUUID: true
     },
   },
 },
});

removing inspector support in production

If you do not with to ship inspector support in your production application, you can specify that all support for it should be stripped from the build.

1
2
3
4
5
let app = new EmberApp(defaults, {
 emberData: {
   includeDataAdapterInProduction: false
 }
});

Debugging

Many portions of the internals are helpfully instrumented with logging that can be activated at build time. This instrumentation is always removed from production builds or any builds that has not explicitly activated it. To activate it set the appropriate flag to true.

1
2
3
4
5
6
7
8
9
10
11
 let app = new EmberApp(defaults, {
   emberData: {
     debug: {
         LOG_NOTIFICATIONS: false,
         LOG_REQUEST_STATUS: false,
         LOG_IDENTIFIERS: false,
         LOG_GRAPH: false,
         LOG_INSTANCE_CACHE: false,
     }
   }
 });