Display Value Cache Service

The DisplayValueCacheService provides a persistent cache for DisplayValueEntry objects, backed by IndexedDB with automatic fallback to in-memory storage when IndexedDB is unavailable.

Overview

When rendering data views, resolved display values (human-readable representations of entity fields) are expensive to recompute. The cache stores these resolved values keyed by collection, entity ID, schema version, and language — so repeated lookups avoid redundant server round-trips or recomputation.

Persistence: Cached entries survive page reloads when IndexedDB is available.

Fallback: When IndexedDB is unavailable (e.g. Safari private browsing, storage quota exceeded, non-browser environments), the service transparently falls back to an in-memory Map. The API is identical in both modes; only persistence is lost.

Installation

The service is exported from the @smallstack/client package:

import { DisplayValueCacheService } from "@smallstack/client";

Initialization

Call init() before performing any cache operations. It is safe to call multiple times — subsequent calls are no-ops.

const cache = new DisplayValueCacheService();
await cache.init();

You can check whether the cache is backed by IndexedDB after initialization:

if (cache.isPersistent) {
  console.log("Cache is persisted via IndexedDB.");
} else {
  console.log("Cache is running in memory-only mode.");
}

Cache Key Structure

Every entry is addressed by a DisplayCacheKey, a composite of four fields:

Field	Type	Description
collectionName	string	The name of the data collection (e.g. "users")
entityId	string	The unique ID of the entity
schemaHash	string	A hash of the schema version used for rendering
language	string	The language/locale of the display value

These four fields are combined into a single composite primary key stored in IndexedDB as ${collectionName}:${entityId}:${schemaHash}:${language}.

import type { DisplayCacheKey } from "@smallstack/client";

const key: DisplayCacheKey = {
  collectionName: "products",
  entityId: "abc123",
  schemaHash: "d4f9a1",
  language: "en"
};

Reading from the Cache

Single Entry

const entry = await cache.getCacheEntry(key);

if (entry) {
  console.log("Cache hit:", entry);
} else {
  console.log("Cache miss — fetch from source.");
}

Batch Read

Retrieve multiple entries in a single operation. Returns a Map keyed by entityId containing only the entries that were found (cache misses are omitted).

const keys: DisplayCacheKey[] = [
  { collectionName: "products", entityId: "abc123", schemaHash: "d4f9a1", language: "en" },
  { collectionName: "products", entityId: "xyz789", schemaHash: "d4f9a1", language: "en" }
];

const found = await cache.getCacheEntriesMany(keys);

for (const [entityId, entry] of found) {
  console.log(entityId, entry);
}

Writing to the Cache

Single Entry

import type { DisplayValueEntry } from "@smallstack/shared";

const entry: DisplayValueEntry = { /* ... */ };
await cache.setCacheEntry(key, entry);

Batch Write

Write multiple entries in a single IndexedDB transaction for better performance:

await cache.setCacheEntriesMany([
  { key: key1, entry: entry1 },
  { key: key2, entry: entry2 }
]);

Fallback Behavior

The service handles IndexedDB unavailability gracefully:

Scenario	Behavior
IndexedDB not available	Falls back to in-memory Map; isPersistent is false
Safari private browsing	Falls back to in-memory Map
Storage quota exceeded	Falls back to in-memory Map
Non-browser environment (SSR)	Falls back to in-memory Map

A warning is logged to the console when the fallback is activated:

DisplayCache: IndexedDB unavailable, falling back to in-memory mode

In-memory mode is fully functional for the lifetime of the page session. All reads and writes behave identically — entries simply will not survive a page reload.

Database Management

The underlying IndexedDB database is named smallstack-display-cache and uses the object store display-entries. These are managed internally and you should not need to interact with them directly under normal usage.

To fully delete the cache database (useful in tests or for a hard cache reset):

import { deleteDisplayCacheDB } from "@smallstack/client";

await deleteDisplayCacheDB();

Type Reference

DisplayCacheKey

interface DisplayCacheKey {
  collectionName: string;
  entityId: string;
  schemaHash: string;
  language: string;
}

CachedDisplayValueEntry

Extends DisplayValueEntry with metadata stored alongside each entry in IndexedDB:

interface CachedDisplayValueEntry extends DisplayValueEntry {
  /** Composite primary key: `${collectionName}:${entityId}:${schemaHash}:${language}` */
  cacheKey: string;
  collectionName: string;
  schemaHash: string;
  language: string;
}

DisplayCacheMetadata

Describes the current state of the cache:

interface DisplayCacheMetadata {
  totalEntries: number;
  entriesByCollection: Record<string, number>;
}