React Adapter
Relevant source files
The following files were used as context for generating this wiki page:
The React Adapter for @cellarnode/beverage-utils provides a framework-specific interface for accessing and managing beverage classification data within React applications. It leverages TanStack Query to handle data fetching, caching, and state management, ensuring that beverage labels and categories are available globally with minimal overhead.
The adapter serves as a bridge between the core beverage utilities—specifically the label mapping logic—and React's component-based architecture. It encapsulates the complexities of asynchronous API calls to the CellarNode platform and provides a clean hook-based API for developers.
Sources: README.md:16-24, src/react/use-beverage-label-map.ts:1-23
Architecture and Data Flow
The React Adapter is built around the useBeverageLabelMap hook. This hook utilizes a query configuration that fetches classification data from a specified API endpoint and transforms it into a LabelMap using core library utilities.
Logic Flow
The data flow begins when a component calls the hook. If the data is not in the cache, it is fetched from the CellarNode API. Once received, the raw BeverageClassification JSON is processed by the buildLabelMap function to create a lookup table optimized for React rendering.
The diagram above illustrates the request lifecycle for beverage classifications within a React application.
Sources: src/react/use-beverage-label-map.ts:7-23, src/label-map.ts:5-15
Primary Functions and Hooks
The adapter exports two primary constructs for managing classification data.
useBeverageLabelMap(apiBaseUrl)
A custom React hook that wraps useQuery. It simplifies the retrieval of the label map by managing the loading and error states associated with fetching classification data.
beverageLabelMapOptions(apiBaseUrl)
A function returning a queryOptions object. This allows for prefetching or manual query management outside of the standard hook lifecycle, such as in React Router loaders or Server Components.
| Feature | Description | Reference |
|---|---|---|
| Query Key | ["beverage-classifications"] | src/react/use-beverage-label-map.ts:9 |
| Stale Time | Infinity (Classifications rarely change) | src/react/use-beverage-label-map.ts:19 |
| Data Transformation | Converts API JSON to LabelMap via buildLabelMap | src/react/use-beverage-label-map.ts:17 |
Sources: src/react/use-beverage-label-map.ts:7-23, README.md:95-104
Data Structures and API Interaction
The React Adapter interacts with the CellarNode API and processes data into specific TypeScript interfaces.
API Endpoint
The adapter specifically targets the following endpoint structure:
GET ${apiBaseUrl}/api/v1/classifications/beverage-types
Data Transformation
The adapter transforms the raw BeverageClassification into a LabelMap. This map includes category IDs, subtype IDs, and composite keys (e.g., category:subtype) to prevent naming collisions between different beverage types.
This class diagram shows the relationship between the incoming API data structures and the resulting map used by React components.
Sources: src/types.ts:1-17, src/label-map.ts:3-15, src/react/use-beverage-label-map.ts:12-14
Dependencies and Integration
The React Adapter requires specific peer dependencies to function. These are marked as optional in the core package but are mandatory when using the /react export.
Peer Dependencies
react:^18.0.0or^19.0.0@tanstack/react-query:^5.0.0
Integration Example
import { useBeverageLabelMap } from "@cellarnode/beverage-utils/react";
import { formatBeverageType } from "@cellarnode/beverage-utils";
function BeverageDisplay({ category, subtype }) {
const { data: labelMap, isLoading } = useBeverageLabelMap("https://api.cellarnode.com");
if (isLoading) return <div>Loading...</div>;
return <span>{formatBeverageType(category, subtype, labelMap)}</span>;
}
Sources: package.json:48-56, README.md:86-94
Summary
The React Adapter provides a standardized, cached, and type-safe method for React applications to consume CellarNode beverage classifications. By integrating with TanStack Query and utilizing the core buildLabelMap logic, it ensures efficient data retrieval and disambiguated label formatting across different beverage categories and subtypes.