Angular Adapter

Relevant source files

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

• src/angular/index.ts
• src/angular/beverage-label-map.service.ts
• src/label-map.ts
• src/types.ts
• README.md
• package.json

The Angular Adapter provides a framework-specific interface for the @cellarnode/beverage-utils library. It facilitates the retrieval and caching of beverage classification data within Angular applications using TanStack Query. By wrapping core utility functions like buildLabelMap, it allows developers to easily integrate CellarNode's industry-standard beverage classification system into Angular components and services.

Sources: src/angular/index.ts, README.md:1-12, README.md:95-122

Core Implementation

The adapter is built around the TanStack Angular Query Experimental library. It provides high-level functions to fetch classification data and transform it into a LabelMap for efficient lookups.

Query Options and Injection

The adapter exposes two primary functions for data management:

• beverageLabelMapOptions(apiBaseUrl: string): Defines the configuration for the classification query, including the fetching logic and cache settings.
• injectBeverageLabelMap(apiBaseUrl: string): A convenience wrapper that uses Angular's dependency injection context to initialize the query.

Sources: src/angular/beverage-label-map.service.ts:7-25, src/angular/index.ts:1

Data Flow Architecture

The diagram below illustrates how the Angular Adapter interacts with the CellarNode API and the core utilities to provide data to components.

The flow starts with an Angular component calling the injection function, which triggers a fetch to the CellarNode API. The resulting JSON data is transformed using the core buildLabelMap utility before being returned to the component.
Sources: src/angular/beverage-label-map.service.ts:10-23, src/label-map.ts:5-15

API Reference

Primary Functions

Function	Parameters	Returns	Description
beverageLabelMapOptions	apiBaseUrl: string	QueryOptions	Configures the query key, fetch function, and set staleTime to Infinity.
injectBeverageLabelMap	apiBaseUrl: string	CreateQueryResult	Injects the query into an Angular context (e.g., a Component).

Sources: src/angular/beverage-label-map.service.ts:7-25, README.md:120-125

Data Models

The adapter utilizes several core types to ensure type safety during the fetch and transformation process.

Type	Source File	Description
BeverageClassification	src/types.ts	The raw response structure from the API containing categories and subtypes.
LabelMap	src/label-map.ts	A Record<string, string> where keys are IDs or composite keys and values are display names.

Sources: src/types.ts:11-13, src/label-map.ts:3

Usage Example

The following example demonstrates how to use injectBeverageLabelMap within an Angular component to display a formatted beverage type.

import { Component, computed } from "@angular/core";
import { injectBeverageLabelMap } from "@cellarnode/beverage-utils/angular";
import { formatBeverageType } from "@cellarnode/beverage-utils";

@Component({
  selector: "app-beverage-display",
  template: `<span>{{ display() }}</span>`,
})
export class BeverageDisplayComponent {
  category = "wine";
  subtype = "red";

  // Injects the classification query using the Angular adapter
  private labelMapQuery = injectBeverageLabelMap("https://api.cellarnode.com");

  // Uses a computed signal to format the label once data is loaded
  display = computed(() =>
    formatBeverageType(this.category, this.subtype, this.labelMapQuery.data())
  );
}

Sources: README.md:105-118, src/angular/beverage-label-map.service.ts:23-25

Configuration and Constraints

• API Endpoint: The adapter specifically targets the endpoint /api/v1/classifications/beverage-types relative to the provided apiBaseUrl.
• Caching: The staleTime is set to Infinity by default, as beverage classifications are considered static data that rarely changes.
• Peer Dependencies: This adapter requires @angular/core (versions 17, 18, or 19) and @tanstack/angular-query-experimental.

Sources: src/angular/beverage-label-map.service.ts:13-20, package.json:52-53, README.md:97

The Angular Adapter serves as a bridge between the framework's reactive ecosystem and the core beverage utilities, ensuring that classification data is fetched efficiently and made available through standard Angular patterns like Signals and Dependency Injection.