Cache Class
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
.
import Cache from '@ember-data/json-api';
import Store from '@ember-data/store';
export default class extends Store {
createCache(wrapper) {
return new Cache(wrapper);
}
}
Item Index
Methods
- changedAttrs
- changedRelationships
- clientDidCreate
- commitWasRejected
- didCommit
- diff
- dump
- getAttr
- getErrors
- getRelationship
- hasChangedAttrs
- hasChangedRelationships
- hydrate
- isDeleted
- isDeletionCommitted
- isEmpty
- isNew
- merge
- mutate
- patch
- peek
- peekRequest
- put
- rollbackAttrs
- rollbackRelationships
- setAttr
- setIsDeleted
- unloadRecord
- upsert
- willCommit
Properties
Methods
changedAttrs
-
identifier
Query the cache for the changed attributes of a resource.
Parameters:
-
identifier
Object
Returns:
{
changedRelationships
-
identifier
Query the cache for the changes to relationships of a resource.
Returns a map of relationship names to RelationshipDiff objects.
type RelationshipDiff =
| {
kind: 'collection';
remoteState: StableRecordIdentifier[];
additions: Set<StableRecordIdentifier>;
removals: Set<StableRecordIdentifier>;
localState: StableRecordIdentifier[];
reordered: boolean;
}
| {
kind: 'resource';
remoteState: StableRecordIdentifier | null;
localState: StableRecordIdentifier | null;
};
`
Parameters:
-
identifier
StableRecordIdentifier
Returns:
clientDidCreate
-
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.
Parameters:
-
identifier
Object -
createArgs
Object
commitWasRejected
-
identifier
-
errors
[LIFECYCLE] Signals to the cache that a resource was update via a save transaction failed.
Parameters:
-
identifier
Object -
errors
Object
didCommit
-
identifier
-
data
[LIFECYCLE] Signals to the cache that a resource was successfully updated as part of a save transaction.
Parameters:
-
identifier
Object -
data
Object
diff
()
public
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
()
PromiseSerialize 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
.
Returns:
getAttr
-
identifier
-
field
Retrieve the data for an attribute from the cache
Parameters:
-
identifier
Object -
field
Object
Returns:
getErrors
-
identifier
Query the cache for any validation errors applicable to the given resource.
Parameters:
-
identifier
Object
Returns:
getRelationship
-
identifier
-
field
Query the cache for the current state of a relationship property
Parameters:
-
identifier
Object -
field
Object
Returns:
resource relationship object
hasChangedAttrs
-
identifier
Query the cache for whether any mutated attributes exist
Parameters:
-
identifier
Object
Returns:
hasChangedRelationships
-
identifier
Query the cache for whether any mutated relationships exist
Parameters:
-
identifier
StableRecordIdentifier
Returns:
hydrate
-
stream
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.
Parameters:
-
stream
ReadableStream
Returns:
isDeleted
-
identifier
Query the cache for whether a given resource is marked as deleted (but not necessarily persisted yet).
Parameters:
-
identifier
Object
Returns:
isDeletionCommitted
-
identifier
Query the cache for whether a given resource has been deleted and that deletion has also been persisted.
Parameters:
-
identifier
Object
Returns:
isEmpty
-
identifier
Query the cache for whether a given resource has any available data
Parameters:
-
identifier
Object
Returns:
isNew
-
identifier
Query the cache for whether a given resource was created locally and not yet persisted.
Parameters:
-
identifier
Object
Returns:
merge
-
cache
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.
Parameters:
-
cache
Cache
Returns:
Promise
mutate
-
mutation
Update the "local" or "current" (unpersisted) state of the Cache
Parameters:
-
mutation
Mutation
Returns:
patch
-
op
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.
Parameters:
-
op
Operationthe operation to perform
Returns:
peek
-
identifier
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.
Parameters:
-
identifier
StableRecordIdentifier | StableDocumentIdentifier
Returns:
the known resource data
peekRequest
-
UNKNOWN
Peek the Cache for the existing request data associated with a cacheable request.
This is effectively the reverse of put
for a request in
that it will return the the request, response, and content
whereas peek
will return just the content
.
Parameters:
-
UNKNOWN
StableDocumentIdentifier
Returns:
put
-
doc
Cache the response to a request
Implements Cache.put
.
Expects a StructuredDocument whose content
member is a JsonApiDocument.
cache.put({
request: { url: 'https://api.example.com/v1/user/1' },
content: {
data: {
type: 'user',
id: '1',
attributes: {
name: 'Chris'
}
}
}
})
Note The nested
content
anddata
members are not a mistake. This is because there are two separate concepts involved here, theStructuredDocument
which contains the context of a given Request that has been issued with the returned contents as itscontent
property, and aJSON:API Document
which is the json contents returned by this endpoint and which uses itsdata
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.
Parameters:
-
doc
StructuredDocument
Returns:
rollbackAttrs
-
identifier
Tell the cache to discard any uncommitted mutations to attributes
This method is a candidate to become a mutation
Parameters:
-
identifier
Object
Returns:
the names of fields that were restored
rollbackRelationships
-
identifier
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
Parameters:
-
identifier
StableRecordIdentifier
Returns:
the names of relationships that were restored
setAttr
-
identifier
-
field
-
value
Mutate the data for an attribute in the cache
This method is a candidate to become a mutation
Parameters:
-
identifier
Object -
field
Object -
value
Object
setIsDeleted
-
identifier
-
isDeleted
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
Parameters:
-
identifier
Object -
isDeleted
Boolean
unloadRecord
-
identifier
[LIFECYCLE] Signals to the cache that all data for a resource should be cleared.
This method is a candidate to become a mutation
Parameters:
-
identifier
Object
upsert
-
identifier
-
data
-
hasRecord
Push resource data from a remote source into the cache for this identifier
Parameters:
-
identifier
Object -
data
Object -
hasRecord
Object
Returns:
if hasRecord
is true then calculated key changes should be returned
willCommit
-
identifier
[LIFECYCLE] Signals to the cache that a resource will be part of a save transaction.
Parameters:
-
identifier
Object
Properties
version
'2'
public
The Cache Version that this implementation implements.