cocktailfyi

Pure TypeScript cocktail computation engine for developers. Parse bartending measures into milliliters, estimate ABV with dilution factor, calculate calories from ingredients, compute 4-dimension flavor profiles, and score recipe difficulty -- all with zero dependencies. Extracted from the CocktailFYI database of 636 cocktail recipes across 15 families and 11 categories.

Try the interactive tools at cocktailfyi.com -- ABV Calculator, Calorie Calculator, Cocktail Explorer, Ingredient Guide

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Parse Bartending Measures
  • Estimate ABV (Alcohol by Volume)
  • Estimate Calories
  • Compute Flavor Profiles
  • Score Recipe Difficulty
  • ABV & Dilution Science
  • Cocktail Families
• API Reference
• TypeScript Types
• Features
• Also Available for Python
• Beverage FYI Family
• License

Install

npm install cocktailfyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { parseMeasureMl, estimateAbv, estimateCalories } from "cocktailfyi";

// Parse bartending measures into milliliters
const ml = parseMeasureMl("1 1/2 oz");   // 45.0
const cl = parseMeasureMl("2 cl");       // 20.0
const splash = parseMeasureMl("splash"); // 5.0

// Estimate ABV for a Margarita (with 22% dilution from ice)
const abv = estimateAbv([
  { measure: "2 oz", abv: 40.0 },    // Tequila
  { measure: "1 oz", abv: 40.0 },    // Triple Sec
  { measure: "1 oz", abv: 0 },       // Lime juice
]);
console.log(abv);  // 23.4

// Estimate calories
const kcal = estimateCalories([
  { measure: "2 oz", abv: 40.0, caloriesPer100ml: null },
  { measure: "1 oz", abv: 0, caloriesPer100ml: 40 },
]);
console.log(kcal);  // 145

What You Can Do

Parse Bartending Measures

Convert any bartending measure string into milliliters. Handles 20 units including imperial, metric, and descriptive measures, with full fraction support (1 1/2, 3/4).

| Unit | ml | Unit | ml | Unit | ml | |------|---:|------|---:|------|---:| | oz | 30.0 | cl | 10.0 | ml | 1.0 | | tsp | 5.0 | tbsp | 15.0 | shot | 45.0 | | cup | 240.0 | jigger | 45.0 | pint | 473.0 | | dash | 1.0 | drop | 0.5 | splash | 5.0 | | part | 30.0 | glass | 240.0 | can | 355.0 | | bottle | 750.0 | fifth | 750.0 | | |

Descriptive measures like garnish, twist, wedge, sprig, float, and pinch are recognized and mapped to 5.0 ml (negligible volume).

import { parseMeasureMl } from "cocktailfyi";

parseMeasureMl("1 1/2 oz");  // 45.0  -- standard jigger
parseMeasureMl("3/4 cl");    // 7.5   -- metric fraction
parseMeasureMl("2 tbsp");    // 30.0  -- tablespoon
parseMeasureMl("1 jigger");  // 45.0  -- barware unit
parseMeasureMl("garnish");   // 5.0   -- descriptive measure
parseMeasureMl("2 dashes");  // 2.0   -- bitters

Learn more: Ingredient Guide | Glossary

Estimate ABV (Alcohol by Volume)

Calculate the estimated ABV of a cocktail from its ingredient list. The engine applies a 22% dilution factor to account for ice melt during shaking or stirring -- the standard assumption in professional bartending.

The dilution model: when a cocktail is shaken or stirred with ice, approximately 22% of the final volume is water from melted ice. This dilutes the alcohol concentration by a factor of 0.78 (i.e., rawAbv * 0.78 = dilutedAbv).

import { estimateAbv } from "cocktailfyi";

// Classic Margarita
const abv = estimateAbv([
  { measure: "2 oz", abv: 40.0 },   // Tequila
  { measure: "1 oz", abv: 40.0 },   // Triple Sec
  { measure: "1 oz", abv: 0 },      // Lime juice
]);
console.log(abv);  // 23.4

// Highball (lighter drink)
const highball = estimateAbv([
  { measure: "2 oz", abv: 40.0 },   // Spirit
  { measure: "4 oz", abv: 0 },      // Mixer
]);
console.log(highball);  // 10.4

Learn more: ABV Calculator | Cocktail Families

Estimate Calories

Estimate total calories for a cocktail. When caloriesPer100ml data is available, it uses that directly. For spirit-only ingredients without calorie data, it falls back to the alcohol calorie formula:

calories = volume_ml x (abv / 100) x 0.789 g/ml x 7 kcal/g

This formula uses the density of ethanol (0.789 g/ml) and the caloric value of alcohol (7 kcal per gram) -- the standard method used by nutritional science for estimating alcohol-derived calories.

import { estimateCalories } from "cocktailfyi";

// Spirit with known calorie data for mixer
const kcal = estimateCalories([
  { measure: "2 oz", abv: 40.0, caloriesPer100ml: null },   // Gin (formula)
  { measure: "1 oz", abv: 0, caloriesPer100ml: 40 },        // Tonic (known)
]);
console.log(kcal);  // 145

// Pure spirit (formula only)
const spirit = estimateCalories([
  { measure: "2 oz", abv: 40.0, caloriesPer100ml: null },
]);
console.log(spirit);  // 133

Learn more: Calorie Calculator | Guides

Compute Flavor Profiles

Generate a weighted-average flavor profile across 4 dimensions on a 0--10 scale. Each ingredient contributes proportionally to its volume in the final drink.

| Dimension | What it measures | High scorers | |-----------|-----------------|--------------| | Sweet | Sweetness intensity | Liqueurs, syrups, fruit juices | | Sour | Acidity / tartness | Citrus juice, vinegar shrubs | | Bitter | Bitterness level | Bitters, amari, Campari | | Strong | Alcohol presence | Neat spirits, high-proof cocktails |

import { computeFlavorProfile } from "cocktailfyi";

// Whiskey Sour profile
const profile = computeFlavorProfile([
  { measure: "2 oz", flavorSweet: 0, flavorSour: 0,
    flavorBitter: 0, flavorStrong: 10 },   // Bourbon
  { measure: "1 oz", flavorSweet: 10, flavorSour: 8,
    flavorBitter: 0, flavorStrong: 0 },     // Lemon + syrup
]);
console.log(profile);
// { sweet: 3, sour: 3, bitter: 0, strong: 7 }

Learn more: Cocktail Families | Blog

Score Recipe Difficulty

Evaluate how difficult a cocktail recipe is to prepare based on ingredient count and techniques used.

| Level | Criteria | |-------|----------| | Easy | Fewer than 4 ingredients, 0--1 simple techniques | | Medium | 4--5 ingredients OR 2+ techniques | | Hard | 6+ ingredients OR any advanced technique |

Advanced techniques that automatically trigger "hard" difficulty: muddling, layering, smoking, flaming, sous vide, fat-washing, infusing.

import { computeDifficulty } from "cocktailfyi";

computeDifficulty(3);                              // "easy"
computeDifficulty(4, ["shaking", "stirring"]);     // "medium"
computeDifficulty(5, ["muddling"]);                // "hard"
computeDifficulty(7);                              // "hard"

Learn more: Cocktail Explorer | Technique Glossary

ABV & Dilution Science

Alcohol by Volume (ABV) measures the percentage of pure ethanol in a liquid. For mixed drinks, ABV depends on the volume and strength of each ingredient plus dilution from ice. The standard dilution assumption in professional bartending is 22% -- meaning roughly one-fifth of the final drink volume is water from melted ice.

| Drink Style | Typical ABV | Dilution Source | |-------------|------------|----------------| | Neat spirit (no ice) | 40--46% | None | | Spirit on the rocks | 25--30% | Melting ice over time | | Stirred cocktail | 22--28% | 15--20% dilution (less vigorous) | | Shaken cocktail | 15--22% | 22--25% dilution (ice shatters) | | Highball (spirit + mixer) | 8--12% | Long mixer volume | | Beer/wine cocktail | 4--8% | Low-ABV base |

The calorie calculation uses two methods depending on available data. For spirits without specific calorie data, the alcohol calorie formula derives calories from ethanol content: volume x (ABV/100) x 0.789 g/ml x 7 kcal/g. The 7 kcal/g figure is the caloric density of ethanol (compared to 4 kcal/g for carbohydrates and 9 kcal/g for fat).

Cocktail Families

Cocktails are organized into families based on their structural recipe pattern rather than ingredients. A family defines the ratio template -- for example, a Sour is always a spirit + citrus + sweetener. Understanding families helps bartenders improvise.

| Family | Template | Classic Example | |--------|----------|----------------| | Sour | Spirit + citrus + sweetener | Whiskey Sour, Margarita | | Old Fashioned | Spirit + sugar + bitters | Old Fashioned, Sazerac | | Martini | Spirit + aromatized wine | Dry Martini, Manhattan | | Highball | Spirit + long mixer | Gin & Tonic, Cuba Libre | | Fizz | Spirit + citrus + sweetener + soda | Gin Fizz | | Collins | Spirit + citrus + sweetener + soda (tall) | Tom Collins | | Daisy | Spirit + citrus + liqueur | Margarita, Sidecar | | Tiki | Rum(s) + citrus + syrups + spice | Mai Tai, Zombie |

Learn more: Cocktail Families | Browse All Categories

API Reference

Functions

| Function | Parameters | Returns | Description | |----------|-----------|---------|-------------| | parseMeasureMl(measure) | string | number | Parse bartending measure to milliliters | | estimateAbv(ingredients) | Ingredient[] | number | Estimate ABV with 22% dilution | | estimateCalories(ingredients) | Ingredient[] | number | Estimate total calories | | computeFlavorProfile(ingredients) | FlavorIngredient[] | FlavorProfile | Weighted flavor scores (0--10) | | computeDifficulty(count, techniques?) | number, string[]? | "easy" \| "medium" \| "hard" | Difficulty level |

Constants

| Constant | Type | Description | |----------|------|-------------| | UNIT_TO_ML | Record<string, number> | 20 bartending units to ml conversion | | DESCRIPTIVE_MEASURES | ReadonlySet<string> | 16 descriptive measures (garnish, twist, etc.) | | HARD_TECHNIQUES | ReadonlySet<string> | 7 advanced techniques that trigger hard difficulty | | DILUTION_FACTOR | number | 0.78 (22% dilution from ice) |

TypeScript Types

import type { Ingredient, FlavorIngredient, FlavorProfile } from "cocktailfyi";

interface Ingredient {
  measure: string;
  abv?: number | null;
  caloriesPer100ml?: number | null;
}

interface FlavorIngredient {
  measure: string;
  flavorSweet?: number | null;
  flavorSour?: number | null;
  flavorBitter?: number | null;
  flavorStrong?: number | null;
}

interface FlavorProfile {
  sweet: number;   // 0-10
  sour: number;    // 0-10
  bitter: number;  // 0-10
  strong: number;  // 0-10
}

Features

• Measure parsing: 20 bartending units + 16 descriptive measures + fraction support
• ABV estimation: Dilution-corrected alcohol calculation (0.78 factor)
• Calorie estimation: Dual method -- calorie data or alcohol formula (0.789 g/ml x 7 kcal/g)
• Flavor profiling: Volume-weighted 4-dimension scoring (sweet, sour, bitter, strong)
• Difficulty scoring: Ingredient count + technique complexity analysis
• Zero dependencies: Pure TypeScript, no runtime deps
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Also Available for Python

pip install cocktailfyi

See the Python package on PyPI.

Beverage FYI Family

Part of the FYIPedia open-source developer tools ecosystem -- world beverages from cocktails to sake.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | cocktailfyi | PyPI | npm | 636 cocktails, ABV, calories, flavor profiles -- cocktailfyi.com | | vinofyi | -- | -- | Wines, grapes, regions, food pairings -- vinofyi.com | | beerfyi | -- | -- | 112 beer styles, hops, malts, BJCP -- beerfyi.com | | brewfyi | -- | -- | 72 coffee varieties, roasting, brew methods -- brewfyi.com | | whiskeyfyi | -- | -- | 80 whiskey expressions, distilleries -- whiskeyfyi.com | | teafyi | -- | -- | 60 tea varieties, teaware, brewing -- teafyi.com | | nihonshufyi | -- | -- | 80 sake, rice varieties, breweries -- nihonshufyi.com |

License

MIT