Caching Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Caching Configuration in @cellarnode/beverage-utils is designed to optimize the retrieval and availability of beverage classification data across different frontend frameworks. Since beverage classifications (categories and subtypes) change infrequently, the system utilizes a long-term caching strategy to minimize redundant network requests and improve application performance.
The project leverages TanStack Query (formerly React Query) as the primary caching engine, providing standardized query options for React, Vue, and Angular adapters. This ensures that once classification data is fetched from the CellarNode API, it remains available in memory throughout the application lifecycle.
Sources: README.md:1-12, README.md:65-68
TanStack Query Integration
The core of the caching logic is encapsulated within beverageLabelMapOptions, which is implemented consistently across all framework-specific modules. This function configures how data is fetched, identified, and stored in the cache.
Query Key and Stale Time
To uniquely identify the classification data within the global cache, the system uses a specific queryKey. The staleTime is set to Infinity, reflecting the static nature of beverage classification data.
| Configuration Property | Value | Description |
|---|---|---|
queryKey | ["beverage-classifications"] | The unique identifier used to look up data in the cache. |
staleTime | Infinity | Ensures the data never expires automatically once fetched successfully. |
Sources: src/react/use-beverage-label-map.ts:7-10, src/vue/use-beverage-label-map.ts:7-10, src/angular/beverage-label-map.service.ts:7-10
Data Flow and Transformation
When a cache miss occurs, the system initiates a fetch request to the CellarNode API. The raw JSON response is immediately transformed into a LabelMap using the buildLabelMap utility before being stored in the cache.
The following diagram illustrates the data flow from the API to the framework-specific cache:
The buildLabelMap function processes the classification data into a flat lookup map containing category IDs, subtype IDs, and composite keys (e.g., category:subtype) to ensure unambiguous lookups.
Sources: src/label-map.ts:5-15, src/react/use-beverage-label-map.ts:11-19
Framework Implementation Patterns
Each framework utilizes the same underlying caching configuration but provides different entry points for developers.
Standardized Query Options
Each adapter exports a beverageLabelMapOptions(apiBaseUrl: string) function. This allows for manual cache management, such as prefetching data before a component renders.
// Example: Prefetching configuration
await queryClient.prefetchQuery(beverageLabelMapOptions("https://api.cellarnode.com"));
Sources: README.md:83-87, src/react/use-beverage-label-map.ts:7-22
Framework Adapters
The adapters provide idiomatic ways to access the cached data:
- React: Uses the
useBeverageLabelMaphook. - Vue: Uses the
useBeverageLabelMapcomposable. - Angular: Uses the
injectBeverageLabelMapfunction via@tanstack/angular-query-experimental.
| Framework | Implementation Function | Source File |
|---|---|---|
| React | useBeverageLabelMap(apiBaseUrl) | src/react/use-beverage-label-map.ts:24-26 |
| Vue | useBeverageLabelMap(apiBaseUrl) | src/vue/use-beverage-label-map.ts:24-26 |
| Angular | injectBeverageLabelMap(apiBaseUrl) | src/angular/beverage-label-map.service.ts:24-26 |
Error Handling in Cache Initialization
The fetch function defined within the query options includes basic error handling. If the network request fails (e.g., a non-200 response), it throws an error which TanStack Query then manages (typically by setting the query status to error).
if (!res.ok) throw new Error("Failed to fetch beverage classifications");
Sources: src/react/use-beverage-label-map.ts:16, src/vue/use-beverage-label-map.ts:16, src/angular/beverage-label-map.service.ts:16
Summary
The caching configuration of @cellarnode/beverage-utils centralizes beverage classification data into a persistent, immutable-in-practice cache. By leveraging TanStack Query with staleTime: Infinity, the library ensures high performance and consistency across React, Vue, and Angular applications while providing flexible prefetching options through a standardized beverageLabelMapOptions interface.