Normalization Test Coverage
Relevant source files
The following files were used as context for generating this wiki page:
Normalization within the @cellarnode/beverage-utils library ensures that beverage-related data—such as regions, country names, and production volumes—is deterministic and comparable. The test suite, primarily located in __tests__/normalize.test.ts, validates the logic used to canonicalize free-text identifiers, resolve inconsistent country references to ISO alpha-2 codes, and parse various volume formats into a unified liter measurement.
The normalization layer is critical for the CellarNode platform to perform accurate ranking and signal comparisons, as it eliminates variations caused by accents, casing, mixed units, or inconsistent spelling from different data producers.
Sources: src/normalize.ts:5-8, src/normalize.ts:25-28
Token Normalization
The normalizeToken function is tested to ensure that free-text identifiers are converted into a canonical "slug" format. This process involves stripping diacritics (accents), lowercasing, and replacing whitespace or underscores with single hyphens.
Logic Flow for Token Normalization
The following diagram illustrates the sequence of operations applied to a raw string to produce a normalized token.
This flow ensures that inputs like " Côte du Rhône " are consistently transformed into "cote-du-rhone".
Sources: src/normalize.ts:10-21, tests/normalize.test.ts:15-18
Test Cases for normalizeToken
| Input | Expected Output | Purpose |
|---|---|---|
null / undefined | "" | Null safety |
" Spain " | "spain" | Trimming and casing |
"Côte du Rhône" | "cote-du-rhone" | Diacritic removal |
"sparkling wine" | "sparkling-wine" | Whitespace collapsing |
"--foo--bar--" | "foo-bar" | Hyphen cleanup |
Sources: tests/normalize.test.ts:5-35
Country Code Resolution
The resolveCountryCode function leverages the i18n-iso-countries dependency to map various country representations to a canonical ISO alpha-2 code. The test suite verifies that the system handles English names, native names (e.g., "España"), and ISO alpha-3 codes.
Country Resolution Architecture
This multi-stage resolution ensures high hit rates even when producers provide localized or accented country names.
Sources: src/normalize.ts:32-61, package.json:96
Resolution Coverage
- ISO Standards: Validates "ES" (Alpha-2) and "ESP" (Alpha-3) both resolve to "ES".
- Localization: Supports English ("United States" → "US") and Spanish ("España" → "ES") via registered locales.
- Resilience: Tests show that
resolveCountryCodereturnsnullfor unknown inputs like "Atlantis" rather than throwing errors.
Sources: tests/normalize.test.ts:39-66, src/normalize.ts:25-30
Volume Parsing
The parseVolumeToLiters function is tested against a variety of real-world patterns used to describe beverage production or container volumes. It handles numeric inputs, unit suffixes, and complex bottle-count strings.
Supported Volume Formats
| Pattern Category | Examples | Logic |
|---|---|---|
| Standard Units | 5000 L, 750 ml, 20 hl | Multiplies by factor (e.g., hl = 100) |
| Bottle Counts | bottles 750ml × 4000 | Parses size * count * unit_factor |
| Alternative Units | 5 kL, 5000 liters | Recognizes varied spellings and prefixes |
| Bare Numbers | 330 | Assumed to be liters by default |
Sources: src/normalize.ts:70-113, tests/normalize.test.ts:70-98
Parsing Implementation Details
The parser uses complex Regular Expressions to extract components from strings like 4000 × 750ml. If a parse fails or the input is non-finite, the function returns null to avoid penalizing the system with bad data.
Testing Infrastructure
The project uses vitest for executing the normalization test suite. The configuration ensures all files ending in .test.ts within the __tests__ directory are included in the test run.
- Test Runner: Vitest
- Environment: NodeNext (ESM)
- Script:
npm test
Sources: package.json:61, vitest.config.ts:3-7, tsconfig.json:5-6
The normalization test coverage ensures that the core data processing functions are robust against varied user input, providing a reliable foundation for beverage classification and comparison.