TypeScript Interfaces

Relevant source files

The following files were used as context for generating this wiki page:

• src/types.ts
• src/label-map.ts
• src/format.ts
• src/index.ts
• src/react/use-beverage-label-map.ts
• README.md

The @cellarnode/beverage-utils library relies on a structured set of TypeScript interfaces to define the industry-standard beverage classification system used by the CellarNode platform. These interfaces ensure type safety when handling beverage categories, subtypes, and the resulting lookup maps used for UI formatting.

These interfaces facilitate the conversion of raw API data into a LabelMap, which is a flattened structure designed for efficient O(1) lookups of human-readable labels based on slugs or composite keys.
Sources: README.md:1-10, src/types.ts:1-15

Core Data Models

The core models define the hierarchy of beverage classifications. A classification consists of multiple categories (e.g., Still Wine), and each category contains specific subtypes (e.g., Red Wine).

Beverage Classification Hierarchy

The diagram above illustrates the nested relationship between the primary classification entry point and its child components.
Sources: src/types.ts:1-15

Data Model Definitions

Interface	Field	Type	Description
BeverageSubtype	id	string	Unique identifier for the subtype (e.g., "red").
	name	string	Human-readable name (e.g., "Red Wine").
	oivType	string (Optional)	International Organisation of Vine and Wine classification code.
BeverageCategory	id	string	Unique identifier for the category (e.g., "wine").
	name	string	Human-readable name (e.g., "Still Wine").
	hsHeading	string (Optional)	Harmonized System (HS) code heading.
	subtypes	BeverageSubtype[]	Array of associated subtypes.
BeverageClassification	categories	BeverageCategory[]	The top-level container for all beverage data.

Sources: src/types.ts:1-15, README.md:162-178

Label Mapping and Utility Types

The library transforms hierarchical classification data into a flat LabelMap to handle disambiguation. This is particularly important because subtype IDs (like red) may be reused across different categories.

LabelMap Structure

The LabelMap is a standard record type used throughout the library's formatting functions.

export type LabelMap = Record<string, string>;

Sources: src/label-map.ts:3

Transformation Logic

The buildLabelMap function processes BeverageClassification data to populate the LabelMap with three types of keys:

1. Category ID: Maps to the category name.
2. Subtype ID: Maps to the subtype name (last-write-wins for duplicates).
3. Composite Key: Format category:subtype, ensuring unambiguous lookups.

The flow diagram represents how hierarchical data is flattened into a key-value pair structure for fast retrieval.
Sources: src/label-map.ts:5-14, README.md:31-45

Usage in Framework Adapters

The interfaces are utilized by framework-specific hooks (React, Vue, Angular) to type the results of asynchronous API fetches via TanStack Query.

Function	Return Type	Purpose
beverageLabelMapOptions	QueryOptions<LabelMap>	Defines the fetch logic and caching for classification data.
useBeverageLabelMap	QueryResult<LabelMap>	React/Vue hook to access the label map in components.
formatBeverageType	string	Uses LabelMap to format a category and subtype into a display string.

Sources: src/react/use-beverage-label-map.ts:7-22, src/format.ts:13-23

Conclusion

TypeScript interfaces in @cellarnode/beverage-utils provide the structural foundation for consistent beverage data handling. By defining clear boundaries for categories and subtypes, the library enables robust formatting utilities that resolve naming collisions through composite keys.
Sources: README.md:180-188, src/index.ts:1-5