nutri-calc/README.md

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

# Health Star Rating Calculator

A TypeScript library for calculating Health Star Ratings according to the Australian and New Zealand food labelling system. This calculator helps determine the nutritional rating of food products on a scale from 0.5 to 5 stars.

## Installation

```bash
npm install nutri-calc
```

## Usage

```typescript
import { 
  Category, 
  Attributes, 
  calculateHealthStarRating 
} from 'nutri-calc';

// Calculate rating for a dairy beverage
const rating = calculateHealthStarRating(
  Category.DairyBeverages,
  {
    energykJ: 300,
    saturatedFatGrams: 1.5,
    totalSugarsGrams: 4,
    sodiumMilligrams: 80,
    percentageFruitVegetableNutLegume: 0,
    fibreGrams: 0,
    proteinGrams: 3.2,
    attributes: [Attributes.ContainsFruitOrVegetable]
  }
);

console.log(`Health Star Rating: ${rating}`); // e.g., 4.5
```

## Features

- Supports all major food categories defined in the Health Star Rating system
- Handles special cases like plain water and unsweetened flavoured water
- Calculates baseline points considering energy, saturated fat, total sugars, and sodium
- Accounts for protein, fiber, and fruit/vegetable/nut/legume content
- Written in TypeScript with full type safety
- Thoroughly tested with Jest

## API

### Categories

Foods are classified into one of the following categories:

```typescript
enum Category {
  DairyBeverages = 0,
  DairyFoods = 1,
  FatsOilsAndSpreads = 2,
  Cheese = 3,
  PlainWater = 4,
  UnsweetenedFlavouredWater = 5,
  UnprocessedFruitAndVegetables = 6,
  NonDairyBeverages = 7,
  Jellies = 8,
  WaterBasedIcedConfection = 9,
  OtherFoods = 100
}
```

### Attributes

Products can have the following attributes:

```typescript
enum Attributes {
  ContainsFruitOrVegetable = 0,
  ContainsNutsOrLegumes = 1
}
```

### Main Function

```typescript
function calculateHealthStarRating(
  category: Category,
  nutritionalInfo: Partial<NutritionalInformation>
): HealthStarRating
```

The `NutritionalInformation` interface accepts:
- energykJ: number
- saturatedFatGrams: number
- totalSugarsGrams: number
- sodiumMilligrams: number
- percentageFruitVegetableNutLegume: number
- fibreGrams: number
- proteinGrams: number
- attributes: Attributes[]

Returns a `HealthStarRating` type which is one of: 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | null

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Build
npm run build
```

## License

Apache-2.0

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.