@airia-in/run-app-data-format/README.md

Shared data formatting library for Airia fitness platform

# @airia/data-format

A comprehensive data formatting library for the Airia fitness platform. This library provides consistent formatting functions for time, distance, pace, heart rate, and other fitness metrics that can be used across all services.

## Features

- **Time Formatting**: Convert seconds to various time formats (hh:mm:ss, mm:ss, human readable)
- **Distance Formatting**: Convert meters to appropriate units (km/m) with proper formatting
- **Pace Conversion**: Convert between different pace units (min/km, min/mi, s/m)
- **Heart Rate**: Format heart rate values and calculate heart rate zones
- **Speed Formatting**: Convert m/s to km/h or other units
- **Elevation/Altitude**: Format elevation in meters or feet
- **Power**: Format power output for cycling activities
- **Cadence**: Format cadence for running (spm) and cycling (rpm)
- **Temperature**: Convert between Celsius and Fahrenheit
- **Date Formatting**: Multiple date format options including relative dates
- **Calories**: Format calorie values with proper rounding

## Installation

```bash
npm install @airia-in/lib-run-app-conversion
```

## Usage

### Basic Examples

```typescript
import { 
  msToMinPerKm, 
  mToKm, 
  formatDuration, 
  formatHeartRate,
  formatSpeed 
} from '@airia/data-format';

// Convert speed to pace
const pace = msToMinPerKm(5); // "3:20"

// Format distance
const distance = mToKm(1500); // "1.5 km"
const shortDistance = mToKm(800); // "800 m"

// Format duration
const duration = formatDuration(3661); // "1:01:01"
const shortDuration = formatDuration(125, 'mm:ss'); // "2:05"
const humanDuration = formatDuration(3661, 'humanReadable'); // "1h 1m 1s"

// Format heart rate
const hr = formatHeartRate(150); // "150 bpm"
const hrNoUnit = formatHeartRate(150, false); // "150"

// Format speed
const speed = formatSpeed(5); // "18.0 km/h"
const speedMs = formatSpeed(5, 'ms'); // "5.0 m/s"
```

### Heart Rate Zones

```typescript
import { getHeartRateZone } from '@airia/data-format';

const zone = getHeartRateZone(150, 200); // Using max HR
// {
//   zone: 3,
//   zoneName: 'Cardio',
//   percentage: 75,
//   description: 'Hard activity'
// }

const zoneFromAge = getHeartRateZone(150, undefined, 30); // Calculate max HR from age
```

### Advanced Formatting

```typescript
import { 
  formatElevation, 
  formatPower, 
  formatCadence, 
  formatTemperature,
  formatDate,
  formatCalories,
  convertPace
} from '@airia/data-format';

// Elevation
const elevation = formatElevation(1500); // "1500 m"
const elevationFt = formatElevation(1500, 'ft'); // "4921 ft"

// Power (cycling)
const power = formatPower(250); // "250 W"

// Cadence
const runCadence = formatCadence(180); // "180 spm"
const bikeCadence = formatCadence(90, 'cycling'); // "90 rpm"

// Temperature
const temp = formatTemperature(25); // "25°C"
const tempF = formatTemperature(25, 'F'); // "77°F"

// Date formatting
const date = formatDate(new Date(), 'short'); // "09/07/25"
const longDate = formatDate(new Date(), 'long'); // "Tuesday, July 9, 2025"
const relativeDate = formatDate(new Date(), 'relative'); // "Today"

// Calories
const calories = formatCalories(500); // "500 cal"

// Pace conversion
const paceConverted = convertPace(5, 'min/km', 'min/mi'); // "8:03"
```

## API Reference

### Time Functions

- `formatDuration(seconds, format?)`: Format duration in various formats
- `msToMinPerKm(ms)`: Convert m/s to min/km pace format

### Distance Functions

- `mToKm(meters)`: Convert meters to km with appropriate unit
- `formatElevation(meters, unit?)`: Format elevation in m or ft

### Speed & Pace Functions

- `formatSpeed(metersPerSecond, unit?)`: Format speed in km/h or m/s
- `convertPace(value, fromUnit, toUnit)`: Convert between pace units

### Heart Rate Functions

- `formatHeartRate(hr, includeUnit?)`: Format heart rate value
- `getHeartRateZone(currentHR, maxHR?, age?)`: Calculate HR zone information

### Other Fitness Metrics

- `formatPower(watts, includeUnit?)`: Format power output
- `formatCadence(cadence, type?)`: Format cadence for running/cycling
- `formatCalories(calories, includeUnit?)`: Format calorie values

### General Utilities

- `formatTemperature(celsius, unit?)`: Convert temperature units
- `formatDate(date, format?)`: Format dates in various styles

## Testing

```bash
npm test
```

## Contributing

This library is part of the Airia fitness platform. When adding new formatting functions:

1. Follow the existing patterns for type safety and error handling
2. Include comprehensive tests
3. Add proper JSDoc documentation
4. Handle edge cases (null, undefined, invalid inputs)
5. Use consistent return values ("-" for invalid inputs)

## License

MIT