home
  • Blog
  • Home
  • Projects
    • Ember
    • EmberData
    • Ember CLI
4.12
  • Packages
    • @ember-data/adapter
    • @ember-data/adapter/error
    • @ember-data/adapter/json-api
    • @ember-data/adapter/rest
    • @ember-data/canary-features
    • @ember-data/debug
    • @ember-data/deprecations
    • @ember-data/experimental-preview-types
    • @ember-data/graph
    • @ember-data/json-api
    • @ember-data/legacy-compat
    • @ember-data/model
    • @ember-data/request
    • @ember-data/request/fetch
    • @ember-data/serializer
    • @ember-data/serializer/json
    • @ember-data/serializer/json-api
    • @ember-data/serializer/rest
    • @ember-data/store
    • @ember-data/tracking
  • Classes
    • <Interface> Adapter
    • <Interface> Cache
    • <Interface> Handler
    • <Interface> Serializer
    • AbortError
    • Adapter
    • AdapterError
    • BelongsToReference
    • BooleanTransform
    • BuildURLMixin
    • Cache
    • CacheManager
    • CacheStoreWrapper
    • CanaryFeatureFlags
    • ConflictError
    • CurrentDeprecations
    • DateTransform
    • DebugLogging
    • EmbeddedRecordsMixin
    • Errors
    • Fetch
    • ForbiddenError
    • Future
    • HasManyReference
    • IdentifierCache
    • InvalidError
    • JSONAPIAdapter
    • JSONAPISerializer
    • JSONSerializer
    • ManyArray
    • Model
    • NotFoundError
    • NotificationManager
    • NumberTransform
    • PromiseArray
    • PromiseManyArray
    • PromiseObject
    • RESTAdapter
    • RESTSerializer
    • RecordArray
    • RecordReference
    • RequestManager
    • RequestStateService
    • SchemaService
    • Serializer
    • ServerError
    • Snapshot
    • SnapshotRecordArray
    • StableRecordIdentifier
    • Store
    • StringTransform
    • TimeoutError
    • Transform
    • UnauthorizedError

Class CacheManager public


Defined in: ../store/src/-private/managers/cache-manager.ts:71
Module: @ember-data/store

The CacheManager wraps a Cache enforcing that only the public API surface area is exposed.

Hence, it is the value of Store.cache, wrapping the cache instance returned by Store.createCache.

This class is the the return value of both the recordDataFor function supplied to the store hook instantiateRecord, and the recordDataFor method on the CacheStoreWrapper. It is not directly instantiatable.

It handles translating between cache versions when necessary, for instance when a Store is configured to use both a v1 and a v2 cache depending on some heuristic.

Starting with the v2 spec, the cache is designed such that it must be implemented as a singleton. However, because the v1 spec was not designed for this whenever we encounter any v1 cache we must wrap all caches, even singletons, in non-singleton managers to preserve v1 compatibility.

To avoid this performance penalty being paid by all applications, singleton behavior may be opted-in via the configuration supplied to your Ember application at build time. This effectively removes support for v1 caches.

let app = new EmberApp(defaults, {
  emberData: {
    useSingletonManager: true
  },
});


Methods

clientDidCreate (identifier, options) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:505

identifier
options

[LIFECYLCE] Signal to the cache that a new record has been instantiated on the client

It returns properties from options that should be set on the record during the create process. This return value behavior is deprecated.

commitWasRejected (identifier, errors) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:606

identifier
errors

[LIFECYCLE] Signals to the cache that a resource was update via a save transaction failed.

didCommit (identifier, data) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:577

identifier
data

[LIFECYCLE] Signals to the cache that a resource was successfully updated as part of a save transaction.

diff public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:384

Generate the list of changes applied to all record in the store.

Each individual resource or document that has been mutated should be described as an individual Change entry in the returned array.

A Change is described by an object containing up to three properties: (1) the identifier of the entity that changed; (2) the op code of that change being one of upsert or remove, and if the op is upsert a patch containing the data to merge into the cache for the given entity.

This patch is opaque to the Store but should be understood by the Cache and may expect to be utilized by an Adapter when generating data during a save operation.

It is generally recommended that the patch contain only the updated state, ignoring fields that are unchanged

interface Change {
 identifier: StableRecordIdentifier | StableDocumentIdentifier;
 op: 'upsert' | 'remove';
 patch?: unknown;
}

dump : Promise<ReadableStream> public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:428

returns
Promise<ReadableStream>

Serialize the entire contents of the Cache into a Stream which may be fed back into a new instance of the same Cache via cache.hydrate.

fork : public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:345

returns

Promise

Create a fork of the cache from the current state.

Applications should typically not call this method themselves, preferring instead to fork at the Store level, which will utilize this method to fork the cache.

getAttr (identifier, propertyName) : Unknown public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:639

identifier
propertyName
returns
Unknown

Retrieve the data for an attribute from the cache

getErrors (identifier) : public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:986

identifier
returns

Query the cache for any validation errors applicable to the given resource.

getRelationship (identifier, propertyName) : public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:796

identifier
propertyName
returns

resource relationship object

Query the cache for the current state of a relationship property

hasChangedAttrs (identifier) : Boolean public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:746

identifier
returns
Boolean

Query the cache for whether any mutated attributes exist

hydrate (stream) : Promise<void> public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:445

stream
ReadableStream
returns
Promise<void>

hydrate a Cache from a Stream with content previously serialized from another instance of the same Cache, resolving when hydration is complete.

This method should expect to be called both in the context of restoring the Cache during application rehydration after SSR AND at unknown times during the lifetime of an already booted application when it is desired to bulk-load additional information into the cache. This latter behavior supports optimizing pre/fetching of data for route transitions via data-only SSR modes.

isDeleted (identifier) : Boolean public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:1026

identifier
returns
Boolean

Query the cache for whether a given resource is marked as deleted (but not necessarily persisted yet).

isDeletionCommitted (identifier) : Boolean public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:1039

identifier
returns
Boolean

Query the cache for whether a given resource has been deleted and that deletion has also been persisted.

isEmpty (identifier) : Boolean public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:998

identifier
returns
Boolean

Query the cache for whether a given resource has any available data

isNew (identifier) : Boolean public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:1013

identifier
returns
Boolean

Query the cache for whether a given resource was created locally and not yet persisted.

merge (cache) : public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:364

cache
Cache
returns

Promise

Merge a fork back into a parent Cache.

Applications should typically not call this method themselves, preferring instead to merge at the Store level, which will utilize this method to merge the caches.

mutate (mutation) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:205

mutation

Update resource data with a local mutation. Currently supports operations on relationships only.

patch (op) : Void public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:186

op

the operation to perform

returns
Void

Perform an operation on the cache to update the remote state.

Note: currently the only valid operation is a MergeOperation which occurs when a collision of identifiers is detected.

peek (identifier) : ResourceDocument | ResourceBlob | null public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:259

identifier
StableRecordIdentifier | StableDocumentIdentifier
returns
ResourceDocument | ResourceBlob | null

the known resource data

Peek resource data from the Cache.

In development, if the return value is JSON the return value will be deep-cloned and deep-frozen to prevent mutation thereby enforcing cache Immutability.

This form of peek is useful for implementations that want to feed raw-data from cache to the UI or which want to interact with a blob of data directly from the presentation cache.

An implementation might want to do this because de-referencing records which read from their own blob is generally safer because the record does not require retainining connections to the Store and Cache to present data on a per-field basis.

This generally takes the place of getAttr as an API and may even take the place of getRelationship depending on implementation specifics, though this latter usage is less recommended due to the advantages of the Graph handling necessary entanglements and notifications for relational data.

peekRequest (UNKNOWN) : StableDocumentIdentifier | null public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:301

UNKNOWN
StableDocumentIdentifier
returns
StableDocumentIdentifier | null

Peek the Cache for the existing request data associated with a cacheable request

put (doc) : ResourceDocument public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:151

doc
StructuredDocument
returns
ResourceDocument

Cache the response to a request

Unlike store.push which has UPSERT semantics, put has replace semantics similar to the http method PUT

the individually cacheabl e resource data it may contain should upsert, but the document data surrounding it should fully replace any existing information

Note that in order to support inserting arbitrary data to the cache that did not originate from a request put should expect to sometimes encounter a document with only a content member and therefor must not assume the existence of request and response on the document.

rollbackAttrs (identifier) : public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:774

identifier
returns

the names of attributes that were restored

Tell the cache to discard any uncommitted mutations to attributes

setAttr (identifier, propertyName, value) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:658

identifier
propertyName
value

Mutate the data for an attribute in the cache

setIsDeleted (identifier, isDeleted) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:968

identifier
isDeleted

Update the cache state for the given resource to be marked as locally deleted, or remove such a mark.

unloadRecord (identifier) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:619

identifier

[LIFECYCLE] Signals to the cache that all data for a resource should be cleared.

upsert (identifier, data, hasRecord) : Void | string[] public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:318

identifier
data
hasRecord
returns
Void | string[]

if hasRecord is true then calculated key changes should be returned

Push resource data from a remote source into the cache for this identifier

willCommit (identifier) public

Module: @ember-data/store

Defined in ../packages/store/src/-private/managers/cache-manager.ts:553

identifier

[LIFECYCLE] Signals to the cache that a resource will be part of a save transaction.

On this page


Methods

  • clientDidCreate
  • commitWasRejected
  • didCommit
  • diff
  • dump
  • fork
  • getAttr
  • getErrors
  • getRelationship
  • hasChangedAttrs
  • hydrate
  • isDeleted
  • isDeletionCommitted
  • isEmpty
  • isNew
  • merge
  • mutate
  • patch
  • peek
  • peekRequest
  • put
  • rollbackAttrs
  • setAttr
  • setIsDeleted
  • unloadRecord
  • upsert
  • willCommit
Team Sponsors Security Legal Branding Community Guidelines
Twitter GitHub Discord Mastodon

If you want help you can contact us by email, open an issue, or get realtime help by joining the Ember Discord.

© Copyright 2025 - Tilde Inc.
Ember.js is free, open source and always will be.


Ember is generously supported by
blue Created with Sketch.