IPersistedCache Interface

Persistent cache. This interface can be implemented by the host to provide durable caching across sessions. If not provided at driver factory construction, factory will use in-memory cache implementation that does not survive across sessions. Snapshot entires stored in the IPersistedCache will be considered stale and removed after 2 days. Read the README for more information.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/driver-definitions/legacy.

For more information about our API support guarantees, see here.

Signature

export interface IPersistedCache

Methods

Method	Alerts	Modifiers	Return Type	Description
get(entry)	Beta		Promise<unknown>	Get the cache value of the key
put(entry, value)	Beta		Promise<void>	Put the value into cache. Important - only serializable content is allowed since this cache may be persisted between sessions
removeEntries(file)	Beta		Promise<void>	Removes the entries from the cache for given parameters.
removeEntry(entry)	Beta	optional	Promise<void>	Removes a specific entry from the cache.
update(entry, updater)	Beta	optional	Promise<boolean>	Atomically read the currently-cached value, hand it to updater, and write a new value iff updater calls the supplied set callback inside the same atomic transaction. Enables compare-and-set / read-modify-write across consumers that share the underlying storage (for example, multiple browser tabs). Implementations must invoke updater synchronously between reading the existing value and committing the write, so the get/decide/put runs atomically. The updater is passed (existing, set); calling set(value) schedules a write, calling set(undefined) schedules a delete of the row at the key, and returning without calling set leaves the cache untouched. If the updater throws, the existing row is preserved.

Method Details

get

Get the cache value of the key

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get(entry: ICacheEntry): Promise<unknown>;

Parameters

Parameter	Type	Description
entry	ICacheEntry	cache entry, identifies file and particular key for this file.

Returns

Cached value. undefined if nothing is cached.

Return type: Promise<unknown>

put

Put the value into cache. Important - only serializable content is allowed since this cache may be persisted between sessions

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

put(entry: ICacheEntry, value: unknown): Promise<void>;

Parameters

Parameter	Type	Description
entry	ICacheEntry	cache entry.
value	unknown	JSON-serializable content.

Returns

Return type: Promise<void>

removeEntries

Removes the entries from the cache for given parameters.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

removeEntries(file: IFileEntry): Promise<void>;

Parameters

Parameter	Type	Description
file	IFileEntry	file entry to be deleted.

Returns

Return type: Promise<void>

removeEntry

Removes a specific entry from the cache.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

removeEntry?(entry: ICacheEntry): Promise<void>;

Parameters

Parameter	Type	Description
entry	ICacheEntry	cache entry to be deleted.

Returns

Return type: Promise<void>

update

Atomically read the currently-cached value, hand it to updater, and write a new value iff updater calls the supplied set callback inside the same atomic transaction. Enables compare-and-set / read-modify-write across consumers that share the underlying storage (for example, multiple browser tabs).

Implementations must invoke updater synchronously between reading the existing value and committing the write, so the get/decide/put runs atomically. The updater is passed (existing, set); calling set(value) schedules a write, calling set(undefined) schedules a delete of the row at the key, and returning without calling set leaves the cache untouched. If the updater throws, the existing row is preserved.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

update?(entry: ICacheEntry, updater: (existing: unknown, set: (value: unknown) => void) => void): Promise<boolean>;

Parameters

Parameter	Type	Description
entry	ICacheEntry	cache entry, identifies file and particular key for this file.
updater	(existing: unknown, set: (value: unknown) => void) => void	synchronous callback invoked with (existing, set). existing matches what get would return (typically undefined when the row is missing or invisible under implementation-specific staleness rules).

Returns

true if set was called and the write (or delete) committed; false if the updater returned without calling set, threw, or the implementation observed an error.

Return type: Promise<boolean>