FluidCache Class

A cache that can be used by the Fluid ODSP driver to cache data for faster performance.

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

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

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

Signature

export declare class FluidCache implements IPersistedCache

Implements: IPersistedCache

Constructors

Constructor	Alerts	Description
(constructor)(config)	Beta	Constructs a new instance of the FluidCache class

Methods

Method	Alerts	Return Type	Description
get(cacheEntry)	Beta	Promise<any>
put(entry, value)	Beta	Promise<void>
removeEntries(file)	Beta	Promise<void>
removeEntry(entry)	Beta	Promise<void>
update(entry, updater)	Beta	Promise<boolean>	Atomically reads the existing cached entry, hands it to updater, and writes a new value iff updater calls the supplied set callback. The read and the conditional write happen inside a single IndexedDB readwrite transaction, so the decision sees a consistent view across consumers sharing the same underlying IndexedDB instance (for example, multiple browser tabs racing to persist pending state).

Constructor Details

(constructor)

Constructs a new instance of the FluidCache class

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

constructor(config: FluidCacheConfig);

Parameters

Parameter	Type	Description
config	FluidCacheConfig

Method Details

get

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(cacheEntry: ICacheEntry): Promise<any>;

Parameters

Parameter	Type	Description
cacheEntry	ICacheEntry

Returns

Return type: Promise<any>

put

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: any): Promise<void>;

Parameters

Parameter	Type	Description
entry	ICacheEntry
value	any

Returns

Return type: Promise<void>

removeEntries

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

Returns

Return type: Promise<void>

removeEntry

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

Returns

Return type: Promise<void>

update

Atomically reads the existing cached entry, hands it to updater, and writes a new value iff updater calls the supplied set callback. The read and the conditional write happen inside a single IndexedDB readwrite transaction, so the decision sees a consistent view across consumers sharing the same underlying IndexedDB instance (for example, multiple browser tabs racing to persist pending state).

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

Remarks

The implementation uses transaction.store.get + transaction.store.put rather than an IDB cursor. Both run inside the same readwrite transaction, so the atomicity guarantee is identical, and the get/put pair is materially simpler to reason about for a single-key update. A cursor would be the right tool if we needed to iterate or range-scan; for a known key we don't.

Parameters

Parameter	Type	Description
entry	ICacheEntry	cache entry; identifies the file and the key within that file.
updater	(existing: unknown, set: (value: unknown) => void) => void	synchronous callback invoked with (existing, set). existing is the currently-cached value, or undefined when the cached row is invisible under the same rules get applies: no entry exists for the key, the existing entry belongs to a different partition, or the existing entry is older than maxCacheItemAge. The updater can derive the new value from existing (read-modify-write) or ignore it entirely. To commit a write, call set(value); to leave the cache untouched, return without calling set. Stored via IndexedDB structured clone, with the same value requirements as put(entry, value) — not restricted to JSON-serializable values. Calling set(undefined) removes the row at the key (equivalent to removeEntry(entry) inside the same atomic transaction). get already collapses "no entry" and "entry stored as undefined" into the same observable result, so the delete-on-undefined semantics gives callers an atomic conditional-delete without ambiguity for any meaningful use case. The updater itself must be synchronous and set must be called from within it. IndexedDB transactions auto-close on any non-IDB await, which would silently break the atomicity that makes the update correct. Two guards make misuse loud rather than silent: calling set after updater has returned throws a UsageError at the call site; returning a thenable (e.g. an async updater) is detected after updater returns, aborts the transaction, and is logged under FluidCacheUpdateCallbackError. If updater calls set more than once, the last value wins. When set is called, the write (or delete) atomically replaces whatever row exists at the key, including cross-partition or stale rows that the updater saw as undefined. This matches the unconditional overwrite behavior of put. Callers that must preserve cross-partition rows should not use update. Exceptions thrown by updater are logged under the dedicated FluidCacheUpdateCallbackError telemetry event (distinct from IDB write errors) and surfaced to the caller as a false return value, after aborting the transaction so the existing row is preserved — even if set was called before the throw. Compare-and-set callers: a false return collapses three distinct outcomes — the updater returned without calling set, the updater threw (including the async-updater misuse case above), and the IDB write itself failed. Callers that need to distinguish these must consult telemetry: updater-side failures are logged under FluidCacheUpdateCallbackError; IDB-write failures are logged under FluidCachePutError. A lost compare-and-set race (the updater returned without calling set) is not logged.

Returns

true if updater called set and the write committed; false if updater returned without calling set, threw, or an IDB error occurred. IDB errors are logged and not thrown, matching the behavior of put.

Return type: Promise<boolean>