Appearance

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

Class: JSONAPICache ​

Defined in: cache.ts:215

JSONAPICache ​

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

A Cache implementation tuned for {json:api}

This format excels at simiplifying common complex problems around cache consistency and information density. Because most API responses can be quickly transformed into {json:api} format without losing any information, WarpDrive recommends that most apps use this Cache implementation.

If a cache built to understand another format would do better for your app then it just needs to follow the same interface.

Do you really need a cache? Are sunsets beautiful? Caching is what powers features like immutability, mutation management, and allows WarpDrive to understand your relational data.

Some caches are simple request/response maps. WarpDrive's is not. The Cache deeply understands the structure of your data, ensuring your data remains consistent both within and across requests.

Installation ​

sh
pnpm add -E @warp-drive/core@latest @warp-drive/json-api@latest
sh
npm add -E @warp-drive/core@latest @warp-drive/json-api@latest
sh
yarn add -E @warp-drive/core@latest @warp-drive/json-api@latest
sh
bun add --exact @warp-drive/core@latest @warp-drive/json-api@latest

Setup ​

services/store.ts
ts
import { Fetch, RequestManager, Store } from '@warp-drive/core';
import {
  registerDerivations,
  SchemaService,
} from '@warp-drive/core/reactive';
import { CacheHandler } from '@warp-drive/core/store';
import type { CacheCapabilitiesManager } from '@warp-drive/core/types'; 
import { JSONAPICache } from '@warp-drive/json-api';

export default class AppStore extends Store {

  requestManager = new RequestManager()
    .use([Fetch])
    .useCache(CacheHandler);

  createSchemaService() {
    const schema = new SchemaService();
    registerDerivations(schema);
    return schema;
  }

  createCache(capabilities: CacheCapabilitiesManager) { 
    return new JSONAPICache(capabilities);
  }
}

Implements ​

Constructors ​

Constructor ​

ts
new JSONAPICache(capabilities): JSONAPICache;

Defined in: cache.ts:234

Parameters ​

capabilities ​

CacheCapabilitiesManager

Returns ​

JSONAPICache

Cache Management ​

APIs for primary cache management functionality

mutate() ​

ts
mutate(mutation): void;

Defined in: cache.ts:506

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: cache.ts:478

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: cache.ts:556

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

Returns ​

| null | ResourceObject

Implementation of ​

Cache.peek

Call Signature ​

ts
peek(identifier): 
  | null
  | ResourceDocument;

Defined in: cache.ts:557

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 ​

StableDocumentIdentifier

Returns ​

| null | ResourceDocument

Implementation of ​

Cache.peek

peekRemoteState() ​

Call Signature ​

ts
peekRemoteState(identifier): 
  | null
  | ResourceObject;

Defined in: cache.ts:622

Peek the remote resource data from the Cache.

Parameters ​
identifier ​

StableRecordIdentifier

Returns ​

| null | ResourceObject

Implementation of ​

Cache.peekRemoteState

Call Signature ​

ts
peekRemoteState(identifier): 
  | null
  | ResourceDocument;

Defined in: cache.ts:623

Peek the remote resource data from the Cache.

Parameters ​
identifier ​

StableDocumentIdentifier

Returns ​

| null | ResourceDocument

Implementation of ​

Cache.peekRemoteState

peekRequest() ​

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

Defined in: cache.ts:692

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 ​

StableDocumentIdentifier

Returns ​

| null | StructuredDocument<ResourceDocument>

Implementation of ​

Cache.peekRequest

put() ​

Call Signature ​

ts
put<T>(doc): SingleResourceDataDocument;

Defined in: cache.ts:284

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: cache.ts:285

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: cache.ts:286

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: cache.ts:287

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: cache.ts:703

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

Parameters ​

identifier ​

StableRecordIdentifier

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: cache.ts:838

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

StableRecordIdentifier

options? ​

Record<string, Value>

Returns ​

Record<string, unknown>

Implementation of ​

Cache.clientDidCreate

commitWasRejected() ​

ts
commitWasRejected(identifier, errors?): void;

Defined in: cache.ts:1121

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

Parameters ​

identifier ​

StableRecordIdentifier

errors? ​

ApiError[]

Returns ​

void

Implementation of ​

Cache.commitWasRejected

didCommit() ​

ts
didCommit(committedIdentifier, result): SingleResourceDataDocument;

Defined in: cache.ts:978

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

Parameters ​

committedIdentifier ​

StableRecordIdentifier

result ​

StructuredDataDocument<SingleResourceDocument>

Returns ​

SingleResourceDataDocument

Implementation of ​

Cache.didCommit

unloadRecord() ​

ts
unloadRecord(identifier): void;

Defined in: cache.ts:1151

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

StableRecordIdentifier

Returns ​

void

Implementation of ​

Cache.unloadRecord

willCommit() ​

ts
willCommit(identifier): void;

Defined in: cache.ts:917

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

Parameters ​

identifier ​

StableRecordIdentifier

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: cache.ts:1488

Query the cache for the changed attributes of a resource.

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

ChangedAttributesHash

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

Implementation of ​

Cache.changedAttrs

changedRelationships() ​

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

Defined in: cache.ts:1599

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;
   };

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

Map<string, RelationshipDiff>

Implementation of ​

Cache.changedRelationships

getAttr() ​

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

Defined in: cache.ts:1233

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

Parameters ​

identifier ​

StableRecordIdentifier

attr ​

string | string[]

Returns ​

undefined | Value

Implementation of ​

Cache.getAttr

getRelationship() ​

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

Defined in: cache.ts:1640

Query the cache for the current state of a relationship property

Parameters ​

identifier ​

StableRecordIdentifier

field ​

string

Returns ​

| ResourceRelationship<StableRecordIdentifier> | CollectionRelationship<StableRecordIdentifier>

resource relationship object

Implementation of ​

Cache.getRelationship

getRemoteAttr() ​

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

Defined in: cache.ts:1304

Retrieve the remote data for an attribute from the cache

Parameters ​

identifier ​

StableRecordIdentifier

attr ​

string | string[]

Returns ​

undefined | Value

Implementation of ​

Cache.getRemoteAttr

getRemoteRelationship() ​

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

Defined in: cache.ts:1651

Query the cache for the remote state of a relationship property

Parameters ​

identifier ​

StableRecordIdentifier

field ​

string

Returns ​

| ResourceRelationship<StableRecordIdentifier> | CollectionRelationship<StableRecordIdentifier>

resource relationship object

Implementation of ​

Cache.getRemoteRelationship

hasChangedAttrs() ​

ts
hasChangedAttrs(identifier): boolean;

Defined in: cache.ts:1511

Query the cache for whether any mutated attributes exist

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.hasChangedAttrs

hasChangedRelationships() ​

ts
hasChangedRelationships(identifier): boolean;

Defined in: cache.ts:1609

Query the cache for whether any mutated relationships exist

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.hasChangedRelationships

rollbackAttrs() ​

ts
rollbackAttrs(identifier): string[];

Defined in: cache.ts:1539

Tell the cache to discard any uncommitted mutations to attributes

This method is a candidate to become a mutation

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

string[]

the names of fields that were restored

Implementation of ​

Cache.rollbackAttrs

rollbackRelationships() ​

ts
rollbackRelationships(identifier): string[];

Defined in: cache.ts:1624

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 ​

string[]

the names of relationships that were restored

Implementation of ​

Cache.rollbackRelationships

setAttr() ​

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

Defined in: cache.ts:1371

Mutate the data for an attribute in the cache

This method is a candidate to become a mutation

Parameters ​

identifier ​

StableRecordIdentifier

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: cache.ts:1684

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

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

ApiError[]

Implementation of ​

Cache.getErrors

isDeleted() ​

ts
isDeleted(identifier): boolean;

Defined in: cache.ts:1718

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

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.isDeleted

isDeletionCommitted() ​

ts
isDeletionCommitted(identifier): boolean;

Defined in: cache.ts:1730

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

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.isDeletionCommitted

isEmpty() ​

ts
isEmpty(identifier): boolean;

Defined in: cache.ts:1694

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

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.isEmpty

isNew() ​

ts
isNew(identifier): boolean;

Defined in: cache.ts:1706

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

Parameters ​

identifier ​

StableRecordIdentifier

Returns ​

boolean

Implementation of ​

Cache.isNew

setIsDeleted() ​

ts
setIsDeleted(identifier, isDeleted): void;

Defined in: cache.ts:1671

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 ​

StableRecordIdentifier

isDeleted ​

boolean

Returns ​

void

Implementation of ​

Cache.setIsDeleted

Other ​

version ​

ts
version: "2";

Defined in: cache.ts:221

The Cache Version that this implementation implements.

Implementation of ​

Cache.version

Released under the MIT License.

Copyright © 2025 Ember.js and Contributors