Documentation / @ember-data/json-api / index / default

Class: default

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:35

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

A Cache implementation tuned for {json:api}

Implements

• Cache

Constructors

Constructor

new default(capabilities): JSONAPICache;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:42

Parameters

capabilities

CacheCapabilitiesManager

Returns

JSONAPICache

Cache Management

APIs for primary cache management functionality

mutate()

mutate(mutation): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:99

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

Parameters

mutation

LocalRelationshipOperation

Returns

void

Implementation of

Cache.mutate

---

patch()

patch(op): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:92

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

peek(identifier): 
  | null
  | ResourceObject;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:139

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

peek(identifier): 
  | null
  | ResourceDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:140

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

peekRemoteState(identifier): 
  | null
  | ResourceObject;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:147

Peek the remote resource data from the Cache.

Parameters

identifier

ResourceKey

Returns

| null | ResourceObject

Implementation of

Cache.peekRemoteState

Call Signature

peekRemoteState(identifier): 
  | null
  | ResourceDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:148

Peek the remote resource data from the Cache.

Parameters

identifier

RequestKey

Returns

| null | ResourceDocument

Implementation of

Cache.peekRemoteState

---

peekRequest()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:160

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

put<T>(doc): SingleResourceDataDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:80

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

put<T>(doc): CollectionResourceDataDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:81

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

Cache.put

Call Signature

put<T>(doc): ResourceErrorDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:82

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

Cache.put

Call Signature

put<T>(doc): ResourceMetaDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:83

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

Cache.put

---

upsert()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:168

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

Other

version

version: "2";

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:41

The Cache Version that this implementation implements.

Implementation of

Cache.version

Resource Data

APIs that support granular field level management of resource data

changedAttrs()

changedAttrs(identifier): ChangedAttributesHash;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:327

Query the cache for the changed attributes of a resource.

Parameters

identifier

ResourceKey

Returns

ChangedAttributesHash

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

Implementation of

Cache.changedAttrs

---

changedRelationships()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:370

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: 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()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:303

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()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:397

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()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:310

Retrieve the remote data for an attribute from the cache

Parameters

identifier

ResourceKey

attr

string | string[]

Returns

| undefined | Value

Implementation of

Cache.getRemoteAttr

---

getRemoteRelationship()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:405

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()

hasChangedAttrs(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:334

Query the cache for whether any mutated attributes exist

Parameters

identifier

ResourceKey

Returns

boolean

Implementation of

Cache.hasChangedAttrs

---

hasChangedRelationships()

hasChangedRelationships(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:377

Query the cache for whether any mutated relationships exist

Parameters

identifier

ResourceKey

Returns

boolean

Implementation of

Cache.hasChangedRelationships

---

rollbackAttrs()

rollbackAttrs(identifier): string[];

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:344

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()

rollbackRelationships(identifier): string[];

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:389

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()

setAttr(
   identifier, 
   attr, 
   value): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:319

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 Lifecycle

APIs that support management of resource data

clientDidCreate()

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

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:259

[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()

commitWasRejected(identifier, errors?): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:285

[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

didCommit(committedIdentifier, result): SingleResourceDataDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:275

[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

didCommit(committedIdentifier, result): SingleResourceDataDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:276

[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

didCommit(committedIdentifier, result): CollectionResourceDataDocument;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:277

[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()

unloadRecord(identifier): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:295

[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()

willCommit(identifier, _context): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:267

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

APIs that support managing Resource states

getErrors()

getErrors(identifier): ApiError[];

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:422

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

Parameters

identifier

ResourceKey

Returns

ApiError[]

Implementation of

Cache.getErrors

---

isDeleted()

isDeleted(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:445

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()

isDeletionCommitted(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:453

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()

isEmpty(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:429

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

Parameters

identifier

ResourceKey

Returns

boolean

Implementation of

Cache.isEmpty

---

isNew()

isNew(identifier): boolean;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:437

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()

setIsDeleted(identifier, isDeleted): void;

Defined in: warp-drive-packages/json-api/declarations/-private/cache.d.ts:415

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