pace-calculator

A small, UI-agnostic TypeScript library for running pace, time, distance, and split calculations.

Core tenets

• One conversion path. Every distance conversion goes through a single meter↔yard ratio, so any rounding stays consistent and never compounds.
• UI-agnostic. The library knows nothing about any app — the same package can power a web app, an iOS app, or anything else.

Install

npm install pace-calculator

Usage

import {calculatePace, DistanceUnit} from 'pace-calculator';

const pace = calculatePace({
  time: {minutes: 20},
  distance: {distanceValue: 5, distanceUnit: DistanceUnit.Kilometers},
});
// → {
//     perKilometer: {hours: 0, minutes: 4, seconds: 0, milliseconds: 0},
//     perMile: {hours: 0, minutes: 6, seconds: 26, milliseconds: 244},
//     speedKph: 15,
//     speedMph: 9.32,
//   }

API

• calculatePace({ time, distance }) — pace and speed across units
• calculateTime({ pace, distance }) — finish time
• calculateDistance({ pace, time }) — distance covered
• calculateSplits({ time, distance, splitInterval? }) — per-interval splits
• getDistanceInAllUnits(distance) — a distance expressed in km, miles and meters
• getTimesForPace({ pace, distances? }) — finish times across multiple distances

getTimesForPace

The most useful function: give it a pace and get the finish time for a whole set of distances at once.

Called with just a pace, it uses a default set of standard races — 5km, 10km, half and full marathon:

import {getTimesForPace, DistanceUnit} from 'pace-calculator';

getTimesForPace({pace: {minutes: 4, unit: DistanceUnit.Kilometers}});
// → {
//     '5km': {hours: 0, minutes: 20, seconds: 0, milliseconds: 0},
//     '10km': {hours: 0, minutes: 40, seconds: 0, milliseconds: 0},
//     '13.1mi': {hours: 1, minutes: 24, seconds: 19, milliseconds: 793},
//     '26.2mi': {hours: 2, minutes: 48, seconds: 39, milliseconds: 586},
//   }

Pass your own distances to use a different set — the keys are your labels, and the result is keyed to match:

getTimesForPace({
  pace: {minutes: 4, unit: DistanceUnit.Kilometers},
  distances: {
    Parkrun: {distanceValue: 5, distanceUnit: DistanceUnit.Kilometers},
    'Track lap': {distanceValue: 400, distanceUnit: DistanceUnit.Meters},
  },
});
// → {
//     Parkrun: {hours: 0, minutes: 20, seconds: 0, milliseconds: 0},
//     'Track lap': {hours: 0, minutes: 1, seconds: 36, milliseconds: 0},
//   }

License

MIT