nutri-calc/build/index.d.ts

A TypeScript library for calculating Health Star Ratings according to the Australian and New Zealand food labelling system

/**
 * Health Star Rating Calculator
 *
 * This module implements the Health Star Rating (HSR) system, which is a front-of-pack labeling system
 * that rates the nutritional profile of packaged foods from 0.5 to 5 stars. The system helps consumers
 * make healthier food choices by comparing similar packaged foods.
 */
/**
 * Represents the different food categories in the Health Star Rating system.
 * Each category has specific calculation rules and thresholds.
 */
export declare enum Category {
    DairyBeverages = 0,// Category 1D: Dairy beverages
    DairyFoods = 1,// Category 2D: Dairy food products
    FatsOilsAndSpreads = 2,// Category 3: Fats, oils, and spreads
    Cheese = 3,// Category 3D: Cheese and processed cheese
    PlainWater = 4,// Automatically receives 5 stars
    UnsweetenedFlavouredWater = 5,// Automatically receives 4.5 stars
    UnprocessedFruitAndVegetables = 6,// Automatically receives 5 stars
    NonDairyBeverages = 7,// Category 1: Non-dairy beverages
    Jellies = 8,// Category 1: Jellies and similar products
    WaterBasedIcedConfection = 9,// Category 1: Water-based ice confections
    OtherFoods = 100
}
/**
 * Represents additional attributes that can affect the HSR calculation.
 */
export declare enum Attributes {
    ContainsFruitOrVegetable = 0,
    ContainsNutsOrLegumes = 1
}
/**
 * Interface defining the nutritional information required for HSR calculation.
 */
export interface NutritionalInformation {
    energykJ: number;
    saturatedFatGrams: number;
    totalSugarsGrams: number;
    sodiumMilligrams: number;
    percentageFruitVegetableNutLegume: number;
    fibreGrams: number;
    proteinGrams: number;
    attributes: Attributes[];
}
/**
 * Valid Health Star Rating values.
 * Ratings range from 0.5 to 5 stars in 0.5 star increments, or null if invalid.
 */
type HealthStarRating = 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | null;
/**
 * Checks if a food belongs to Category 1 (Non-dairy beverages).
 */
export declare function isCategory1(category: Category): boolean;
/**
 * Checks if a food belongs to Category 1D (Dairy beverages).
 */
export declare function isCategory1D(category: Category): boolean;
/**
 * Checks if a food belongs to Category 2 (Other foods).
 */
export declare function isCategory2(category: Category): boolean;
/**
 * Checks if a food belongs to Category 2D (Dairy foods).
 */
export declare function isCategory2D(category: Category): boolean;
/**
 * Checks if a food belongs to Category 3 (Fats, oils, and spreads).
 */
export declare function isCategory3(category: Category): boolean;
/**
 * Checks if a food belongs to Category 3D (Cheese).
 */
export declare function isCategory3D(category: Category): boolean;
/**
 * Calculates points based on fruit, vegetable, nut, and legume (FVNL) content.
 *
 * @param category - The food category
 * @param attributes - Array of additional food attributes
 * @param percentageFruitVegetableNutLegume - Percentage of FVNL content
 * @returns Number of points (0-8 for most categories, 0-10 for Category 1)
 */
export declare function calculateFruitVegetableNutLegumePoints(category: Category, attributes: Attributes[], percentageFruitVegetableNutLegume: number): number;
/**
 * Calculates protein points based on protein content and other factors.
 *
 * @param category - The food category
 * @param baselinePoints - Previously calculated baseline points
 * @param fruitVegetableNutLegumePoints - Previously calculated FVNL points
 * @param proteinGrams - Protein content in grams
 * @returns Number of protein points (0-15)
 */
export declare function calculateProteinPoints(category: Category, baselinePoints: number, fruitVegetableNutLegumePoints: number, proteinGrams: number): number;
/**
 * Calculates fibre points based on fibre content.
 *
 * @param category - The food category
 * @param fibreGrams - Fibre content in grams
 * @returns Number of fibre points (0-15)
 */
export declare function calculateFibrePoints(category: Category, fibreGrams: number): number;
/**
 * Interface for the basic nutritional information needed for baseline points calculation.
 */
interface BaselineNutritionalInformation {
    energykJ: number;
    saturatedFatGrams: number;
    totalSugarsGrams: number;
    sodiumMilligrams: number;
}
/**
 * Calculates baseline points based on energy, saturated fat, sugar, and sodium content.
 *
 * @param category - The food category
 * @param nutritionalInformation - Basic nutritional information
 * @returns Total baseline points
 */
export declare function calculateBaselinePoints(category: Category, nutritionalInformation: BaselineNutritionalInformation): number;
/**
 * Converts total points to a Health Star Rating based on category-specific thresholds.
 *
 * @param category - The food category
 * @param totalPoints - Previously calculated total points
 * @returns Health Star Rating (0.5-5 stars, or null if invalid)
 */
export declare function ratingFromTotalPoints(category: Category, totalPoints: number): HealthStarRating;
/**
 * Main function to calculate the Health Star Rating for a food product.
 *
 * @param category - The food category
 * @param nutritionalInfo - Complete nutritional information for the product
 * @returns Health Star Rating (0.5-5 stars, or null if invalid)
 *
 * @example
 * ```typescript
 * const rating = calculateHealthStarRating(Category.DairyBeverages, {
 *   energykJ: 500,
 *   saturatedFatGrams: 2.5,
 *   totalSugarsGrams: 12,
 *   sodiumMilligrams: 120,
 *   percentageFruitVegetableNutLegume: 0,
 *   fibreGrams: 0,
 *   proteinGrams: 3.2,
 *   attributes: []
 * });
 * ```
 */
export declare function calculateHealthStarRating(category: Category, { energykJ, saturatedFatGrams, totalSugarsGrams, sodiumMilligrams, percentageFruitVegetableNutLegume, fibreGrams, proteinGrams, attributes, }?: Partial<NutritionalInformation>): HealthStarRating;
export {};