Class Cache

public
Defined in: ../json-api/src/-private/cache.ts:84
Module: @ember-data/json-api

A JSON:API Cache implementation.

What cache the store uses is configurable. Using a different implementation can be achieved by implementing the store's createCache hook.

This is the cache implementation used by ember-data.

1
2
3
4
5
6
7
8

import Cache from '@ember-data/json-api';
import Store from '@ember-data/store';

export default class extends Store {
  createCache(wrapper) {
    return new Cache(wrapper);
  }
}

Show:

changedAttrs (identifier) ChangedAttributesHash public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1067

identifier
returns
ChangedAttributesHash
{ <field>: [<old>, <new>] }

Query the cache for the changed attributes of a resource.

changedRelationships (identifier) Map<string, RelationshipDiff> public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1141

identifier
StableRecordIdentifier
returns
Map<string, RelationshipDiff>

Query the cache for the changes to relationships of a resource.

Returns a map of relationship names to RelationshipDiff objects.

ts type RelationshipDiff = | { kind: 'collection'; remoteState: StableRecordIdentifier[]; additions: Set<StableRecordIdentifier>; removals: Set<StableRecordIdentifier>; localState: StableRecordIdentifier[]; reordered: boolean; } | { kind: 'resource'; remoteState: StableRecordIdentifier | null; localState: StableRecordIdentifier | null; };

clientDidCreate (identifier, createArgs) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:642

identifier
createArgs

[LIFECYCLE] 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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:900

identifier
errors

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

didCommit (identifier, data) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:761

identifier
data

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

diff public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:565

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

1
2
3
4
5

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

dump Promise<ReadableStream> public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:605

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.

getAttr (identifier, field) Unknown public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1012

identifier
field
returns
Unknown

Retrieve the data for an attribute from the cache

getErrors (identifier) JsonApiError[] public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1242

identifier
returns
JsonApiError[]

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

getRelationship (identifier, field) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1205

identifier
field
returns
resource relationship object

Query the cache for the current state of a relationship property

hasChangedAttrs (identifier) Boolean public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1080

identifier
returns
Boolean

Query the cache for whether any mutated attributes exist

hasChangedRelationships (identifier) Boolean public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1172

identifier
StableRecordIdentifier
returns
Boolean

Query the cache for whether any mutated attributes exist

hydrate (stream) Promise<void> public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:618

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1281

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1295

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1254

identifier
returns
Boolean

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

isNew (identifier) Boolean public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1267

identifier
returns
Boolean

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

merge (cache) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:549

cache
Cache
returns
Promise<void>

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) Void public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:352

mutation
Mutation
returns
Void

Update the "local" or "current" (unpersisted) state of the Cache

patch (op) Void public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:319

op
Operation
the operation to perform
returns
Void

Update the "remote" or "canonical" (persisted) state of the Cache by merging new information into the existing state.

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

peek (identifier) ResourceDocument | ResourceBlob | null public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:374

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:448

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:135

doc
StructuredDocument
returns
ResourceDocument

Cache the response to a request

Implements Cache.put.

Expects a StructuredDocument whose content member is a JsonApiDocument.

1
2
3
4
5
6
7
8
9
10
11
12

cache.put({
  request: { url: 'https://api.example.com/v1/user/1' },
  content: {
    data: {
      type: 'user',
      id: '1',
      attributes: {
        name: 'Chris'
      }
    }
  }
})

Note: The nested content and data members are not a mistake. This is because there are two separate concepts involved here, the StructuredDocument which contains the context of a given Request that has been issued with the returned contents as its content property, and a JSON:API Document which is the json contents returned by this endpoint and which uses its data property to signify which resources are the primary resources associated with the request.

StructuredDocument's with urls will be cached as full documents with associated resource membership order and contents preserved but linked into the cache.

rollbackAttrs (identifier) String[] public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1097

identifier
returns
String[]
the names of fields that were restored

Tell the cache to discard any uncommitted mutations to attributes

This method is a candidate to become a mutation

rollbackRelationships (identifier) String[] public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1184

identifier
StableRecordIdentifier
returns
String[]
the names of relationships that were restored

Tell the cache to discard any uncommitted mutations to relationships.

This will also discard the change on any appropriate inverses.

This method is a candidate to become a mutation

setAttr (identifier, field, value) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1035

identifier
field
value

Mutate the data for an attribute in the cache

This method is a candidate to become a mutation

setIsDeleted (identifier, isDeleted) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:1224

identifier
isDeleted
Boolean

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

This method is a candidate to become a mutation

unloadRecord (identifier) public

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:929

identifier

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

This method is a candidate to become a mutation

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

Module: @ember-data/json-api

Defined in ../packages/json-api/src/-private/cache.ts:461

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/json-api

Defined in ../packages/json-api/src/-private/cache.ts:729

identifier

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