npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

running-tools

v0.8.1

Published

Tools for running. Convert speed into pace, convert miles to kilometers, etc.

Downloads

83

Readme

Running Tools

Installation

npm install running-tools

Features

Running Tools provides several typed functions that can be useful for running.

Distance

Running Tools provides several distance converters:

import {
  calculateDistance,
  convertDistance,
  distanceToMeters,
  metersToKilometers,
  metersToMiles,
  kilometersToMiles,
  kilometersToMeters,
  milesToKilometers,
  milesToMeters,
} from "running-tools";
/**
 * Convert meters to kilometers.
 * @param meters - The meter distance to convert (number).
 * @returns The corresponding distance in kilometers (number).
 */
metersToKilometers(2500); // Result: 2.5
/**
 * Convert meters to miles.
 * @param meters - The meter distance to convert (number).
 * @returns The corresponding distance in miles (number).
 */
metersToMiles(1609.344); // Result: 1

/**
 * Convert kilometers to miles.
 * @param kilometers - The kilometer distance to convert (number).
 * @returns The corresponding distance in miles (number).
 */
kilometersToMiles(1.609344); // Result: 1
/**
 * Convert kilometers to meters.
 * @param kilometers - The kilometer distance to convert (number).
 * @returns The corresponding distance in meters (number).
 */
kilometersToMeters(2); // Result: 2000

/**
 * Convert miles to kilometers.
 * @param miles - The mile distance to convert (number).
 * @returns The corresponding distance in kilometers (number).
 */
milesToKilometers(1); // Result: 1.609344
/**
 * Convert miles to meters.
 * @param miles - The mile distance to convert (number).
 * @returns The corresponding distance in meters (number).
 */
milesToMeters(1); // Result: 1609.344

/**
 * Convert a distance to meters based on the specified unit.
 * @param distance - The distance to convert (number).
 * @param unit - The unit of the distance (DistanceUnit).
 * @returns The corresponding distance in meters (number).
 * @throws Error if the unit is unknown.
 */
distanceToMeters(1, "km"); // Result: 1000

/**
 * Convert a distance to a different unit.
 * @param distance - The distance to convert (number).
 * @param unit - The unit of the distance (DistanceUnit).
 * @param toUnit - The unit to convert to (DistanceUnit).
 * @returns The corresponding distance in the new unit (number).
 * @throws Error if the unit or toUnit is unknown.
 */
convertDistance(1, "km", "m"); // Result: 1000

/**
 * Calculate the distance traveled based on time and speed.
 * @param speed - The speed of travel (number).
 * @param speedUnit - The unit of the speed (SpeedUnit).
 * @param time - The time taken to travel (Time).
 * @param toUnit - The unit to calculate the distance in (DistanceUnit). Defaults to DistanceUnit.Meters.
 * @returns The calculated distance in the specified unit (number) or null if the speed or time is invalid.
 */
calculateDistance(10, "kph", {
  hours: 1,
  minutes: 0,
  seconds: 0,
}); // Result: 10000

Elevation

Running Tools provides a function to calculate a slope and a function to calculate an elevation:

import { calculateElevation, calculateSlope } from "running-tools";
/**
 * Calculates the elevation given the distance and slope.
 * @param distance - The distance traveled.
 * @param slope - The slope as a percentage.
 * @returns The change in elevation, or null if the distance is less than or equal to 0.
 */
calculateElevation(100, -10); // Result: -10

/**
 * Calculates the slope given the distance and elevation.
 * Distance and elevation must be in the same units.
 * @param distance - The distance traveled.
 * @param elevation - The change in elevation.
 * @returns The slope as a percentage, or null if the distance is less than or equal to 0.
 */
calculateSlope(100, 50); // Result: 50

Heart rate

Maximum heart rate

Running Tools provides three different functions to calculate maximum heart rate:

import {
  maxHeartRateGellishAl,
  maxHeartRateGellishColl,
  maxHeartRateHaskellFox,
} from "running-tools";
/**
 * Calculates the maximum heart rate using the Gellish and Al formula.
 * @param age - The age of the person in years.
 * @returns The maximum heart rate in beats per minute, or null if age is not a positive number.
 */
maxHeartRateGellishAl(20); // Result: 193

/**
 * Calculates the maximum heart rate using the Haskell and Fox formula.
 * @param age - The age of the person in years.
 * @returns The maximum heart rate in beats per minute, or null if age is not a positive number.
 */
maxHeartRateHaskellFox(20); // Result: 200

/**
 * Calculates the maximum heart rate using the Gellish and Coll formula.
 * @param age - The age of the person in years.
 * @returns The maximum heart rate in beats per minute, or null if age is not a positive number.
 */
maxHeartRateGellishColl(20); // Result: 189.2

Heart rate zones

Running tools provides two functions to calculate heart rate zones: one using the Karvonen method and the other using maximum heart rate only. Zone ranges are the following for the two functions: [50%-60%], [60%-70%], [70%-80%], [80%-90%], [90%-100%].

import {
  calculateHeartRateZonesUsingKarvonen,
  calculateHeartRateZonesUsingMax,
} from "running-tools";
/**
 * Calculates the heart rate zones based on the maximum heart rate and resting heart rate.
 * @param maxHeartRate - The maximum heart rate.
 * @param restingHeartRate - The resting heart rate.
 * @returns - The heart rate zones or null if maxHeartRate is not greater than restingHeartRate or if either value is not positive.
 */
calculateHeartRateZonesUsingKarvonen(180, 60);
[
  {
    index: 1,
    minPercentage: 0.5,
    maxPercentage: 0.6,
    minHeartRate: 120,
    maxHeartRate: 132,
  },
  {
    index: 2,
    minPercentage: 0.6,
    maxPercentage: 0.7,
    minHeartRate: 132,
    maxHeartRate: 144,
  },
  {
    index: 3,
    minPercentage: 0.7,
    maxPercentage: 0.8,
    minHeartRate: 144,
    maxHeartRate: 156,
  },
  {
    index: 4,
    minPercentage: 0.8,
    maxPercentage: 0.9,
    minHeartRate: 156,
    maxHeartRate: 168,
  },
  {
    index: 5,
    minPercentage: 0.9,
    maxPercentage: 1,
    minHeartRate: 168,
    maxHeartRate: 180,
  },
];

/**
 * Calculates the heart rate zones based on the maximum heart rate.
 * @param maxHeartRate - The maximum heart rate.
 * @returns - The heart rate zones or null if maxHeartRate is not positive.
 */
calculateHeartRateZonesUsingMax(180);
[
  {
    index: 1,
    minPercentage: 0.5,
    maxPercentage: 0.6,
    minHeartRate: 90,
    maxHeartRate: 108,
  },
  {
    index: 2,
    minPercentage: 0.6,
    maxPercentage: 0.7,
    minHeartRate: 108,
    maxHeartRate: 126,
  },
  {
    index: 3,
    minPercentage: 0.7,
    maxPercentage: 0.8,
    minHeartRate: 126,
    maxHeartRate: 144,
  },
  {
    index: 4,
    minPercentage: 0.8,
    maxPercentage: 0.9,
    minHeartRate: 144,
    maxHeartRate: 162,
  },
  {
    index: 5,
    minPercentage: 0.9,
    maxPercentage: 1,
    minHeartRate: 162,
    maxHeartRate: 180,
  },
];

Pace

Running Tools provides a pace to speed converter.

import {
  minutesPerKilometerToMinutesPerMile,
  minutesPerMileToMinutesPerKilometer,
  paceToSpeed,
} from "../pace";
/**
 * Convert a pace to speed. See the pace param for unit description.
 * @param pace - The pace to convert (Pace).
 * If the unit of the provided pace is minutes, seconds per mile, the result will be in miles per hour.
 * If the unit of the provided pace is minutes, seconds per kilometer, the result will be in kilometers per hour.
 * @param fractionDigits - Number of digits after the decimal point. Must be in the range 0 - 20, inclusive.
 * @returns The corresponding speed (number) or null if the pace is invalid (if minutes or seconds is less than or equal to 0).
 */
paceToSpeed({ minutes: 4, seconds: 25 }); // Result: 13.58
paceToSpeed({ minutes: 4, seconds: 25 }, 1); // Result: 13.6

/**
 * Converts a pace from minutes per kilometer to minutes per mile.
 * @param pace - The pace to convert (Pace).
 * @returns The converted pace in minutes per mile (Pace) or null if the pace is invalid.
 */
minutesPerKilometerToMinutesPerMile({ minutes: 4, seconds: 15 }); //Result: { minutes: 6, seconds: 50 }

/**
 * Converts a pace from minutes per mile to minutes per kilometer.
 * @param pace - The pace to convert (Pace).
 * @returns The converted pace in minutes per kilometer (Pace) or null if the pace is invalid.
 */
minutesPerMileToMinutesPerKilometer({ minutes: 5, seconds: 18 }); // Result: { minutes: 3, seconds: 17 })

Speed

Running Tools provides a speed to pace converter and speed converters:

import {
  calculateSpeed,
  convertSpeed,
  metersPerSecondToKilometersPerHour,
  metersPerSecondToMilesPerHour,
  kilometersPerHourToMilesPerHour,
  kilometersPerHourToMetersPerSecond,
  milesPerHourToKilometersPerHour,
  milesPerHourToMetersPerSecond,
  speedToMetersPerSecond,
  speedToPace,
} from "running-tools";
/**
 * Convert a speed to pace. See the speed param for unit description.
 * @param speed - The speed to convert (number).
 * If the unit of the provided speed is miles per hour, the result will be in minutes, seconds per mile.
 * If the unit of the provided speed is kilometers per hour, the result will be in minutes, seconds per kilometer.
 * @returns The corresponding pace (Pace) or null if the speed is less than or equal to 0.
 */
speedToPace(11); // Result: {minutes: 5, seconds: 27}

/**
 * Convert speed from meters per second to kilometers per hour.
 * @param speed - The speed in meters per second.
 * @returns The speed in kilometers per hour.
 */
metersPerSecondToKilometersPerHour(11); // Result: 39.6

/**
 * Convert speed from meters per second to miles per hour.
 * @param speed - The speed in meters per second.
 * @returns The speed in miles per hour.
 */
metersPerSecondToMilesPerHour(11); // Result: ~24.6063

/**
 * Convert speed from kilometers per hour to miles per hour.
 * @param speed - The speed in kilometers per hour.
 * @returns The speed in miles per hour.
 */
kilometersPerHourToMilesPerHour(11); // Result: ~6.8351

/**
 * Convert speed from kilometers per hour to meters per second.
 * @param speed - The speed in kilometers per hour.
 * @returns The speed in meters per second.
 */
kilometersPerHourToMetersPerSecond(11); // Result: ~3.0556

/**
 * Convert speed from miles per hour to kilometers per hour.
 * @param speed - The speed in miles per hour.
 * @returns The speed in kilometers per hour.
 */
milesPerHourToKilometersPerHour(11); // Result: ~17.7028

/**
 * Convert speed from miles per hour to meters per second.
 * @param speed - The speed in miles per hour.
 * @returns The speed in meters per second.
 */
milesPerHourToMetersPerSecond(11); // Result: ~4.9174

/**
 * Converts the given speed to meters per second.
 * @param speed - The speed value to convert.
 * @param unit - The unit of the speed value.
 * @returns The converted speed in meters per second.
 * @throws Error if the speed unit is unknown.
 */
speedToMetersPerSecond(11); // Result: ~4.9174

/**
 * Converts the given speed to the specified unit.
 * @param speed - The speed value to convert.
 * @param unit - The unit of the speed value.
 * @param toUnit - The unit to convert the speed to.
 * @returns The converted speed in the specified unit.
 * @throws Error if the speed unit or the target unit is unknown.
 */
convertSpeed(11, "m/s", "kmh"); // Result: 39.6

/**
 * Calculates the speed given the distance, distance unit, time, and target speed unit.
 * @param distance - The distance value (number).
 * @param distanceUnit - The unit of the distance value (DistanceUnit).
 * @param time - The time value (Time).
 * @param toUnit - The target speed unit (SpeedUnit). Defaults to SpeedUnit.MetersPerSecond.
 * @returns The calculated speed in the specified unit or null if the distance or time is invalid.
 */
calculateSpeed(10, "km", { hours: 1, minutes: 0, seconds: 0 }, "mph"); // Result: ~6.2137

Time

Running Tools provides a function to calculate race time:

import {
  calculateRaceTime,
  getSplitTimes,
  secondsToTime,
  timePredictionRiegel,
  timeToSeconds,
} from "running-tools";
/**
 * Calculates the race time based on the given distance and speed.
 * @param distance - The distance of the race.
 * @param distanceUnit - The unit of measurement for the distance.
 * @param speed - The speed at which the race is completed.
 * @param speedUnit - The unit of measurement for the speed.
 * @returns An object representing the race time in hours, minutes, and seconds.
 *          Returns null if either the distance or speed is less than or equal to 0.
 */
calculateRaceTime(5, "mi", "mph"); // Result: {hours: 0, minutes: 30, seconds: 0}

/**
 * Calculates the split times for a given speed and distance.
 * @param speed - The speed at which the distance is covered.
 * @param speedUnit - The unit of measurement for the speed.
 * @param distance - The total distance to be covered.
 * @param distanceUnit - The unit of measurement for the distance.
 * @param splitDistance - The distance at which to calculate the split times.
 * @param splitDistanceUnit - The unit of measurement for the split distance.
 * @returns An array of Time objects representing the split times.
 *          Returns null if either the distance, speed, or split distance is less than or equal to 0,
 *          or if the split distance is greater than or equal to the total distance.
 */
getSplitTimes(15, "kph", 5000, "m", 2500, "m"); // [{hours: 0, minutes: 10, seconds: 0}, {hours: 0, minutes: 20, seconds: 0}]

/**
 * Converts seconds to a Time object.
 * @param seconds - The time in seconds.
 * @returns An object representing the time in hours, minutes, and seconds.
 *          Returns null if the seconds is less than or equal to 0.
 */
secondsToTime(1800); // Result: {hours: 0, minutes: 30, seconds: 0}

/**
 * Predicts the race time for a given distance based on previous achieved time and distance using the Riegel formula.
 * @param achievedTime - The time achieved for the achieved distance (Time).
 * @param achievedDistance - The distance already achieved (number).
 * @param achievedDistanceUnit - The unit of measurement for the achieved distance (DistanceUnit).
 * @param predictedDistance - The distance for which the race time is predicted (number).
 * @param predictedDistanceUnit - The unit of measurement for the predicted distance (DistanceUnit). Optional, defaults to the achieved distance unit.
 * @returns An object representing the predicted race time in hours, minutes, and seconds.
 *          Returns null if either the achieved distance or predicted distance is less than or equal to 0,
 *          or if the achieved time is invalid.
 */
timePredictionRiegel(
  { hours: 1, minutes: 4, seconds: 0 },
  21097.5,
  "m",
  42195,
  "m"
); // Result: {hours: 2, minutes: 13, seconds: 26}

/**
 * Converts a Time object to seconds.
 * @param time - The Time object to convert.
 * @returns The time in seconds.
 *          Returns null if the time is less than or equal to 0.
 */
timeToSeconds({
  hours: 2,
  minutes: 30,
  seconds: 0,
}); // Result: 9000

Contributors

Contributors are more than welcomed. Also feel free to ask for more features on the GitHub repository.

Examples

This package is used as a lib for the following website : https://runningcompanion.eu/

License

MIT License.