Documentation / @warp-drive/core-types / cache / Cache

Interface: Cache

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:38

The interface for WarpDrive Caches.

A Cache handles in-memory storage of Document and Resource data.

Methods

changedAttrs()

changedAttrs(cacheKey): ChangedAttributesHash;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:315

Query the cache for the changed attributes of a resource.

Returns a map of field names to tuples of [old, new] values

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

Parameters

cacheKey

ResourceKey

Returns

ChangedAttributesHash

---

changedRelationships()

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

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:355

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

cacheKey

ResourceKey

Returns

Map<string, RelationshipDiff>

---

clientDidCreate()

clientDidCreate(cacheKey, createArgs?): Record<string, unknown>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:249

[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

cacheKey

ResourceKey

createArgs?

Record<string, unknown>

Returns

Record<string, unknown>

---

commitWasRejected()

commitWasRejected(cacheKey, errors?): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:274

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

Parameters

cacheKey

ResourceKey | ResourceKey[]

errors?

ApiError[]

Returns

void

---

didCommit()

Call Signature

didCommit(cacheKey, result): SingleResourceDataDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:265

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

Parameters

cacheKey

ResourceKey

the primary ResourceKey that was operated on

result

a document in the cache format containing any updated data

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

Returns

SingleResourceDataDocument

Call Signature

didCommit(cacheKey, result): SingleResourceDataDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:266

Parameters

cacheKey

ResourceKey[]

result

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

Returns

SingleResourceDataDocument

Call Signature

didCommit(cacheKey, result): CollectionResourceDataDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:267

Parameters

cacheKey

ResourceKey[]

result

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

Returns

CollectionResourceDataDocument

---

diff()

diff(): Promise<Change[]>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:216

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 CacheKey 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 {
 key: ResourceKey | RequestKey;
 op: 'upsert' | 'remove';
 patch?: unknown;
}

Returns

Promise<Change[]>

---

dump()

dump(): Promise<ReadableStream<unknown>>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:225

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.

Returns

Promise<ReadableStream<unknown>>

---

fork()

fork(): Promise<Cache>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:174

Create a fork of the cache from the current state.

Applications should typically not call this method themselves, preferring instead to fork at the Store level, which will utilize this method to fork the cache.

Returns

Promise<Cache>

---

getAttr()

getAttr(cacheKey, field): undefined | Value;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:289

Retrieve the data for an attribute from the cache

Parameters

cacheKey

ResourceKey

field

string | string[]

Returns

undefined | Value

---

getErrors()

getErrors(cacheKey): ApiError[];

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:401

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

Parameters

cacheKey

ResourceKey

Returns

ApiError[]

---

getRelationship()

getRelationship(
   cacheKey, 
   field, 
   isCollection?): 
  | ResourceRelationship<ResourceKey>
| CollectionRelationship<ResourceKey>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:379

Query the cache for the current state of a relationship property

Parameters

cacheKey

ResourceKey

field

string

isCollection?

boolean

Returns

| ResourceRelationship<ResourceKey> | CollectionRelationship<ResourceKey>

resource relationship object

---

getRemoteAttr()

getRemoteAttr(cacheKey, field): undefined | Value;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:295

Retrieve remote state without any local changes for a specific attribute

Parameters

cacheKey

ResourceKey

field

string | string[]

Returns

undefined | Value

---

getRemoteRelationship()

getRemoteRelationship(
   cacheKey, 
   field, 
   isCollection?): 
  | ResourceRelationship<ResourceKey>
| CollectionRelationship<ResourceKey>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:386

Query the cache for the server state of a relationship property without any local changes

Parameters

cacheKey

ResourceKey

field

string

isCollection?

boolean

Returns

| ResourceRelationship<ResourceKey> | CollectionRelationship<ResourceKey>

resource relationship object

---

hasChangedAttrs()

hasChangedAttrs(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:321

Query the cache for whether any mutated attributes exist

Parameters

cacheKey

ResourceKey

Returns

boolean

---

hasChangedRelationships()

hasChangedRelationships(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:361

Query the cache for whether any mutated attributes exist

Parameters

cacheKey

ResourceKey

Returns

boolean

---

hydrate()

hydrate(stream): Promise<void>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:240

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

Returns

Promise<void>

---

isDeleted()

isDeleted(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:421

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

Parameters

cacheKey

ResourceKey

Returns

boolean

---

isDeletionCommitted()

isDeletionCommitted(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:428

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

Parameters

cacheKey

ResourceKey

Returns

boolean

---

isEmpty()

isEmpty(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:407

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

Parameters

cacheKey

ResourceKey

Returns

boolean

---

isNew()

isNew(cacheKey): boolean;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:414

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

Parameters

cacheKey

ResourceKey

Returns

boolean

---

merge()

merge(cache): Promise<void>;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:183

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

---

mutate()

mutate(mutation): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:80

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

Parameters

mutation

Mutation

Returns

void

---

patch()

patch(op): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:74

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

Parameters

op

the operation(s) to perform

Operation | Operation[]

Returns

void

---

peek()

Call Signature

peek<T>(cacheKey): null | T;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:111

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.

Type Parameters

T

T = unknown

Parameters

cacheKey

ResourceKey<TypeFromInstanceOrString<T>>

Returns

null | T

the known resource data, if any

Call Signature

peek(cacheKey): 
  | null
  | ResourceDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:112

Parameters

cacheKey

RequestKey

Returns

| null | ResourceDocument

---

peekRemoteState()

Call Signature

peekRemoteState<T>(cacheKey): null | T;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:145

Peek remote resource data from the Cache.

This will give the data provided from the server without any local changes.

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.

Type Parameters

T

T = unknown

Parameters

cacheKey

ResourceKey<TypeFromInstanceOrString<T>>

Returns

null | T

the known data, if any

Call Signature

peekRemoteState(cacheKey): 
  | null
  | ResourceDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:146

Parameters

cacheKey

RequestKey

Returns

| null | ResourceDocument

---

peekRequest()

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

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:157

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

cacheKey

RequestKey

Returns

| null | StructuredDocument<ResourceDocument>

---

put()

put<T>(doc): ResourceDocument;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:64

Cache the response to a request

Unlike store.push which has UPSERT semantics, put has replace semantics similar to the http method PUT

the individually cacheable resource data it may contain should upsert, but the document data surrounding it should fully replace any existing information

Note that in order to support inserting arbitrary data to the cache that did not originate from a request put should expect to sometimes encounter a document with only a content member and therefor must not assume the existence of request and response on the document.

Type Parameters

T

T

Parameters

doc

StructuredDocument<T> | { content: T; }

Returns

ResourceDocument

---

rollbackAttrs()

rollbackAttrs(cacheKey): string[];

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:330

Tell the cache to discard any uncommitted mutations to attributes

This method is a candidate to become a mutation

Parameters

cacheKey

ResourceKey

Returns

string[]

the names of fields that were restored

---

rollbackRelationships()

rollbackRelationships(cacheKey): string[];

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:372

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

cacheKey

ResourceKey

Returns

string[]

the names of relationships that were restored

---

setAttr()

setAttr(
   cacheKey, 
   field, 
   value): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:303

Mutate the data for an attribute in the cache

This method is a candidate to become a mutation

Parameters

cacheKey

ResourceKey

field

string | string[]

value

Value

Returns

void

---

setIsDeleted()

setIsDeleted(cacheKey, isDeleted): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:395

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

cacheKey

ResourceKey

isDeleted

boolean

Returns

void

---

unloadRecord()

unloadRecord(cacheKey): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:283

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

This method is a candidate to become a mutation

Parameters

cacheKey

ResourceKey

Returns

void

---

upsert()

upsert(
   cacheKey, 
   data, 
   hasRecord): void | string[];

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:164

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

Parameters

cacheKey

ResourceKey

data

unknown

hasRecord

boolean

Returns

void | string[]

if hasRecord is true then calculated key changes should be returned

---

willCommit()

willCommit(cacheKey, context): void;

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:256

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

Parameters

cacheKey

ResourceKey | ResourceKey[]

context

null | RequestContext

Returns

void

Properties

version

version: "2";

Defined in: warp-drive-packages/core/declarations/types/cache.d.ts:44

The Cache Version that this implementation implements.