@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

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

Usage

Basic Examples

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

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

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

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