Appearance

Documentation / @warp-drive/json-api / JSONAPICache

Class: JSONAPICache ​

Defined in: -private/cache.ts:140

ts
import { JSONAPICache } from '@warp-drive/json-api';

A Cache implementation tuned for {json:api}

Implements ​

Constructors ​

Constructor ​

ts
new JSONAPICache(capabilities): JSONAPICache;

Defined in: -private/cache.ts:159

Parameters ​

capabilities ​

CacheCapabilitiesManager

Returns ​

JSONAPICache

Cache Management ​

APIs for primary cache management functionality

mutate() ​

ts
mutate(mutation): void;

Defined in: -private/cache.ts:435

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

Parameters ​

mutation ​

LocalRelationshipOperation

Returns ​

void

Implementation of ​

Cache.mutate

patch() ​

ts
patch(op): void;

Defined in: -private/cache.ts:407

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

Parameters ​

op ​

the operation or list of operations to perform

Operation | Operation[]

Returns ​

void

Implementation of ​

Cache.patch

peek() ​

Call Signature ​

ts
peek(identifier): 
  | null
  | ResourceObject;

Defined in: -private/cache.ts:494

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.

WARNING

It is not recommended to use the return value as a serialized representation of the resource both due to it containing local mutations and because it may contain additional fields not recognized by the {json:api} API implementation such as lid and the various internal WarpDrive bookkeeping fields.

Parameters ​
identifier ​

ResourceKey

Returns ​

| null | ResourceObject

Implementation of ​

Cache.peek

Call Signature ​

ts
peek(identifier): 
  | null
  | ResourceDocument;

Defined in: -private/cache.ts:495

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.

WARNING

It is not recommended to use the return value as a serialized representation of the resource both due to it containing local mutations and because it may contain additional fields not recognized by the {json:api} API implementation such as lid and the various internal WarpDrive bookkeeping fields.

Parameters ​
identifier ​

RequestKey

Returns ​

| null | ResourceDocument

Implementation of ​

Cache.peek

peekRemoteState() ​

Call Signature ​

ts
peekRemoteState(identifier): 
  | null
  | ResourceObject;

Defined in: -private/cache.ts:559

Peek the remote resource data from the Cache.

Parameters ​
identifier ​

ResourceKey

Returns ​

| null | ResourceObject

Implementation of ​

Cache.peekRemoteState

Call Signature ​

ts
peekRemoteState(identifier): 
  | null
  | ResourceDocument;

Defined in: -private/cache.ts:560

Peek the remote resource data from the Cache.

Parameters ​
identifier ​

RequestKey

Returns ​

| null | ResourceDocument

Implementation of ​

Cache.peekRemoteState

peekRequest() ​

ts
peekRequest(identifier): 
  | null
| StructuredDocument<ResourceDocument>;

Defined in: -private/cache.ts:627

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 ​

identifier ​

RequestKey

Returns ​

| null | StructuredDocument<ResourceDocument>

Implementation of ​

Cache.peekRequest

put() ​

Call Signature ​

ts
put<T>(doc): SingleResourceDataDocument;

Defined in: -private/cache.ts:209

Cache the response to a request

Implements Cache.put.

Expects a StructuredDocument whose content member is a JsonApiDocument.

js
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.

Type Parameters ​
T ​

T extends SingleResourceDocument

Parameters ​
doc ​

StructuredDataDocument<T>

Returns ​

SingleResourceDataDocument

Implementation of ​

Cache.put

Call Signature ​

ts
put<T>(doc): CollectionResourceDataDocument;

Defined in: -private/cache.ts:210

Cache the response to a request

Implements Cache.put.

Expects a StructuredDocument whose content member is a JsonApiDocument.

js
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.

Type Parameters ​
T ​

T extends CollectionResourceDocument

Parameters ​
doc ​

StructuredDataDocument<T>

Returns ​

CollectionResourceDataDocument

Implementation of ​
ts
Cache.put

Call Signature ​

ts
put<T>(doc): ResourceErrorDocument;

Defined in: -private/cache.ts:211

Cache the response to a request

Implements Cache.put.

Expects a StructuredDocument whose content member is a JsonApiDocument.

js
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.

Type Parameters ​
T ​

T extends ResourceErrorDocument

Parameters ​
doc ​

StructuredErrorDocument<T>

Returns ​

ResourceErrorDocument

Implementation of ​
ts
Cache.put

Call Signature ​

ts
put<T>(doc): ResourceMetaDocument;

Defined in: -private/cache.ts:212

Cache the response to a request

Implements Cache.put.

Expects a StructuredDocument whose content member is a JsonApiDocument.

js
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.

Type Parameters ​
T ​

T extends ResourceMetaDocument

Parameters ​
doc ​

StructuredDataDocument<T>

Returns ​

ResourceMetaDocument

Implementation of ​
ts
Cache.put

upsert() ​

ts
upsert(
   identifier, 
   data, 
   calculateChanges?): void | string[];

Defined in: -private/cache.ts:638

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

Parameters ​

identifier ​

ResourceKey

data ​

ExistingResourceObject

calculateChanges? ​

boolean

Returns ​

void | string[]

if calculateChanges is true then calculated key changes should be returned

Implementation of ​

Cache.upsert

Resource Lifecycle ​

APIs that support management of resource data

clientDidCreate() ​

ts
clientDidCreate(identifier, options?): Record<string, unknown>;

Defined in: -private/cache.ts:770

[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 ​

ResourceKey

options? ​

Record<string, Value>

Returns ​

Record<string, unknown>

Implementation of ​

Cache.clientDidCreate

commitWasRejected() ​

ts
commitWasRejected(identifier, errors?): void;

Defined in: -private/cache.ts:949

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

Parameters ​

identifier ​

ResourceKey | ResourceKey[]

errors? ​

ApiError[]

Returns ​

void

Implementation of ​

Cache.commitWasRejected

didCommit() ​

Call Signature ​

ts
didCommit(committedIdentifier, result): SingleResourceDataDocument;

Defined in: -private/cache.ts:865

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

Parameters ​
committedIdentifier ​

ResourceKey

result ​

null | StructuredDataDocument<SingleResourceDataDocument<PersistedResourceKey<string>, PersistedResourceKey<string>>>

Returns ​

SingleResourceDataDocument

Implementation of ​

Cache.didCommit

Call Signature ​

ts
didCommit(committedIdentifier, result): SingleResourceDataDocument;

Defined in: -private/cache.ts:869

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

Parameters ​
committedIdentifier ​

ResourceKey[]

result ​

null | StructuredDataDocument<SingleResourceDataDocument<PersistedResourceKey<string>, PersistedResourceKey<string>>>

Returns ​

SingleResourceDataDocument

Implementation of ​

Cache.didCommit

Call Signature ​

ts
didCommit(committedIdentifier, result): CollectionResourceDataDocument;

Defined in: -private/cache.ts:873

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

Parameters ​
committedIdentifier ​

ResourceKey[]

result ​

null | StructuredDataDocument<CollectionResourceDataDocument<PersistedResourceKey<string>>>

Returns ​

CollectionResourceDataDocument

Implementation of ​

Cache.didCommit

unloadRecord() ​

ts
unloadRecord(identifier): void;

Defined in: -private/cache.ts:969

[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 ​

ResourceKey

Returns ​

void

Implementation of ​

Cache.unloadRecord

willCommit() ​

ts
willCommit(identifier, _context): void;

Defined in: -private/cache.ts:848

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

Parameters ​

identifier ​

ResourceKey | ResourceKey[]

_context ​

null | RequestContext

Returns ​

void

Implementation of ​

Cache.willCommit

Resource Data ​

APIs that support granular field level management of resource data

changedAttrs() ​

ts
changedAttrs(identifier): ChangedAttributesHash;

Defined in: -private/cache.ts:1306

Query the cache for the changed attributes of a resource.

Parameters ​

identifier ​

ResourceKey

Returns ​

ChangedAttributesHash

{ '<field>': ['<old>', '<new>'] }

Implementation of ​

Cache.changedAttrs

changedRelationships() ​

ts
changedRelationships(identifier): Map<string, RelationshipDiff>;

Defined in: -private/cache.ts:1417

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: ResourceKey[];
     additions: Set<ResourceKey>;
     removals: Set<ResourceKey>;
     localState: ResourceKey[];
     reordered: boolean;
    }
  | {
     kind: 'resource';
     remoteState: ResourceKey | null;
     localState: ResourceKey | null;
   };

Parameters ​

identifier ​

ResourceKey

Returns ​

Map<string, RelationshipDiff>

Implementation of ​

Cache.changedRelationships

getAttr() ​

ts
getAttr(identifier, attr): undefined | Value;

Defined in: -private/cache.ts:1051

Retrieve the data for an attribute from the cache with local mutations applied.

Parameters ​

identifier ​

ResourceKey

attr ​

string | string[]

Returns ​

undefined | Value

Implementation of ​

Cache.getAttr

getRelationship() ​

ts
getRelationship(identifier, field): 
  | ResourceRelationship<ResourceKey>
| CollectionRelationship<ResourceKey>;

Defined in: -private/cache.ts:1459

Query the cache for the current state of a relationship property

Parameters ​

identifier ​

ResourceKey

field ​

string

Returns ​

| ResourceRelationship<ResourceKey> | CollectionRelationship<ResourceKey>

resource relationship object

Implementation of ​

Cache.getRelationship

getRemoteAttr() ​

ts
getRemoteAttr(identifier, attr): undefined | Value;

Defined in: -private/cache.ts:1122

Retrieve the remote data for an attribute from the cache

Parameters ​

identifier ​

ResourceKey

attr ​

string | string[]

Returns ​

undefined | Value

Implementation of ​

Cache.getRemoteAttr

getRemoteRelationship() ​

ts
getRemoteRelationship(identifier, field): 
  | ResourceRelationship<ResourceKey>
| CollectionRelationship<ResourceKey>;

Defined in: -private/cache.ts:1470

Query the cache for the remote state of a relationship property

Parameters ​

identifier ​

ResourceKey

field ​

string

Returns ​

| ResourceRelationship<ResourceKey> | CollectionRelationship<ResourceKey>

resource relationship object

Implementation of ​

Cache.getRemoteRelationship

hasChangedAttrs() ​

ts
hasChangedAttrs(identifier): boolean;

Defined in: -private/cache.ts:1329

Query the cache for whether any mutated attributes exist

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.hasChangedAttrs

hasChangedRelationships() ​

ts
hasChangedRelationships(identifier): boolean;

Defined in: -private/cache.ts:1427

Query the cache for whether any mutated relationships exist

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.hasChangedRelationships

rollbackAttrs() ​

ts
rollbackAttrs(identifier): string[];

Defined in: -private/cache.ts:1357

Tell the cache to discard any uncommitted mutations to attributes

This method is a candidate to become a mutation

Parameters ​

identifier ​

ResourceKey

Returns ​

string[]

the names of fields that were restored

Implementation of ​

Cache.rollbackAttrs

rollbackRelationships() ​

ts
rollbackRelationships(identifier): string[];

Defined in: -private/cache.ts:1442

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 ​

ResourceKey

Returns ​

string[]

the names of relationships that were restored

Implementation of ​

Cache.rollbackRelationships

setAttr() ​

ts
setAttr(
   identifier, 
   attr, 
   value): void;

Defined in: -private/cache.ts:1189

Mutate the data for an attribute in the cache

This method is a candidate to become a mutation

Parameters ​

identifier ​

ResourceKey

attr ​

string | string[]

value ​

Value

Returns ​

void

Implementation of ​

Cache.setAttr

Resource State ​

APIs that support managing Resource states

getErrors() ​

ts
getErrors(identifier): ApiError[];

Defined in: -private/cache.ts:1500

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

Parameters ​

identifier ​

ResourceKey

Returns ​

ApiError[]

Implementation of ​

Cache.getErrors

isDeleted() ​

ts
isDeleted(identifier): boolean;

Defined in: -private/cache.ts:1534

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

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.isDeleted

isDeletionCommitted() ​

ts
isDeletionCommitted(identifier): boolean;

Defined in: -private/cache.ts:1546

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

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.isDeletionCommitted

isEmpty() ​

ts
isEmpty(identifier): boolean;

Defined in: -private/cache.ts:1510

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

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.isEmpty

isNew() ​

ts
isNew(identifier): boolean;

Defined in: -private/cache.ts:1522

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

Parameters ​

identifier ​

ResourceKey

Returns ​

boolean

Implementation of ​

Cache.isNew

setIsDeleted() ​

ts
setIsDeleted(identifier, isDeleted): void;

Defined in: -private/cache.ts:1487

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 ​

ResourceKey

isDeleted ​

boolean

Returns ​

void

Implementation of ​

Cache.setIsDeleted

Other ​

version ​

ts
version: "2";

Defined in: -private/cache.ts:146

The Cache Version that this implementation implements.

Implementation of ​

Cache.version

Released under the MIT License.

Copyright © 2025 Ember.js and Contributors