A Node.js library for speed and pace calculations for sports like running, swimming, and cycling. Age-graded times and heart-rate training-zones are also supported.
Add m26-js to your project or package.json file:
npm install m26-js
This library is now implemented with TypeScript, and these examples are also in TypeScript.
Import the m26-js classes into your TypeScript code:
import {
Age,
AgeCalculator,
Constants,
Distance,
ElapsedTime,
RunWalkCalculation,
RunWalkCalculator,
Speed,
TrainingZone
} from "m26-js";
Class Constants defines the following:
public static LIB_NAME : string = 'm26-js';
public static LIB_VERSION : string = '1.0.0';
public static LIB_AUTHOR : string = 'Chris Joakim';
public static LIB_LICENSE : string = 'MIT';
public static UOM_MILES : string = 'm';
public static UOM_KILOMETERS : string = 'k';
public static UOM_YARDS : string = 'y';
public static UNITS_OF_MEASURE : string[] = [
Constants.UOM_MILES, Constants.UOM_KILOMETERS, Constants.UOM_YARDS];
public static KILOMETERS_PER_MILE : number = 1.609344;
public static MILES_PER_KILOMETER : number = 0.621371192237334;
public static YARDS_PER_KILOMETER : number = 1093.6132983377076;
public static FEET_PER_KILOMETER : number = 3280.839895013123;
public static FEET_PER_METER : number = 3.280839895013123;
public static YARDS_PER_MILE : number = 1760.0;
public static SECONDS_PER_MINUTE : number = 60.0;
public static SECONDS_PER_HOUR : number = 3600.0;
The remaining code examples are in the form of working unit tests.
test("Age: maxPulse", () => {
let a19 = new Age(19.1);
let a66 = new Age(66);
expect(a19.value).toBe(19.1);
expect(a66.value).toBe(66);
expect(a19.maxPulse()).toBe(200);
expect(a66.maxPulse()).toBe(220 - 66);
});
test("Age: add", () => {
let a1 = new Age(19.1);
let a2 = new Age(66);
a1.add(a2);
expect(a1.value).toBe(85.1);
expect(a2.value).toBe(66);
});
test("Age: subtract", () => {
let a1 = new Age(19.1);
let a2 = new Age(66);
a2.subtract(a1);
expect(a1.value).toBe(19.1);
expect(a2.value).toBe(66 - 19.1);
});
test("Age: maxPulse and trainingZones", () => {
let a1 = new Age(19.1);
let a2 = new Age(66);
expect(a1.maxPulse()).toBe(200);
expect(a2.maxPulse()).toBe(154);
expect(a2.maxPulse()).toBe(220 - 66);
// first case; age 19.1
let zones = a1.trainingZones();
//console.log(zones);
expect(zones.length).toBe(5);
expect(zones[0].zone).toBe(1);
expect(zones[0].pct).toBe(0.75);
expect(zones[0].age).toBe(19.1);
expect(zones[0].maxHeartRate).toBe(a1.maxPulse());
expect(zones[0].zoneHeartRate).toBe(150);
expect(zones[4].zone).toBe(5);
expect(zones[4].pct).toBe(0.95);
expect(zones[4].age).toBe(19.1);
expect(zones[4].maxHeartRate).toBe(a1.maxPulse());
expect(zones[4].zoneHeartRate).toBe(190);
// second case; age 66
zones = a2.trainingZones();
//console.log(zones);
expect(zones.length).toBe(5);
expect(zones[0].zone).toBe(1);
expect(zones[0].pct).toBe(0.75);
expect(zones[0].age).toBe(66);
expect(zones[0].maxHeartRate).toBe(a2.maxPulse());
expect(zones[0].zoneHeartRate).toBe(116);
expect(zones[4].zone).toBe(5);
expect(zones[4].pct).toBe(0.95);
expect(zones[4].age).toBe(66);
expect(zones[4].maxHeartRate).toBe(a2.maxPulse());
expect(zones[4].zoneHeartRate).toBe(146);
});
test("AgeCalculator: calculate", () => {
let ac : AgeCalculator = new AgeCalculator();
let age1 : Age = ac.calculate('1960-10-01', '2014-10-01');
let age2 : Age = ac.calculate('2001-09-11', '2023-09-17');
expect(age1.value).toBeCloseTo(53.998631074606436, 0.00001);
expect(age2.value).toBeCloseTo(22.015058179329227, 0.00001);
});
test("Distance: constructor default uom", () => {
let d = new Distance(26.2);
expect(d.value).toBe(26.2);
expect(d.uom).toBe(Constants.UOM_MILES);
expect(d.asMiles()).toBe(26.2);
expect(d.asKilometers()).toBe(42.1648128);
expect(d.asYards()).toBe(46112.0);
});
test("Distance: constructor miles uom", () => {
let d = new Distance(26.2, Constants.UOM_MILES);
expect(d.value).toBe(26.2);
expect(d.uom).toBe(Constants.UOM_MILES);
expect(d.asMiles()).toBe(26.2);
expect(d.asKilometers()).toBe(42.1648128);
expect(d.asYards()).toBe(46112.0);
});
test("Distance: constructor kilometers uom", () => {
let d = new Distance(10.0, Constants.UOM_KILOMETERS);
expect(d.value).toBe(10.0);
expect(d.uom).toBe(Constants.UOM_KILOMETERS);
expect(d.asMiles()).toBe(6.2137119223733395);
expect(d.asKilometers()).toBe(10.0);
expect(d.asYards()).toBe(10936.132983377078);
});
test("Distance: constructor yards uom", () => {
let d = new Distance(1800, Constants.UOM_YARDS);
expect(d.value).toBe(1800);
expect(d.uom).toBe(Constants.UOM_YARDS);
expect(d.asMiles()).toBe(1.0227272727272727);
expect(d.asKilometers()).toBe(1.64592);
expect(d.asYards()).toBe(1800);
});
test("Distance: add", () => {
let d1 = new Distance(26.2);
let d2 = new Distance(4.8);
let d3 = d1.add(d2);
expect(d3.uom).toBe(Constants.UOM_MILES);
expect(d3.asMiles()).toBe(31.0);
});
test("Distance: subtract", () => {
let d1 = new Distance(26.2);
let d2 = new Distance(10.0, 'k');
let d3 = d1.subtract(d2);
expect(d3.uom).toBe(Constants.UOM_MILES);
expect(d3.asMiles()).toBe(19.98628807762666);
});
test("ElapsedTime: constructor with a number of seconds", () => {
let et = new ElapsedTime(' 3675 ');
expect(et.arg).toBe('3675');
expect(et.asHHMMSS()).toBe('01:01:15');
expect(et.hh).toBe(1);
expect(et.mm).toBe(1);
expect(et.ss).toBe(15);
expect(et.secs).toBe(3675);
});
test("ElapsedTime: constructor with a hh:mm:ss string", () => {
let et = new ElapsedTime('1:1:15');
expect(et.arg).toBe('1:1:15');
expect(et.asHHMMSS()).toBe('01:01:15');
expect(et.hh).toBe(1);
expect(et.mm).toBe(1);
expect(et.ss).toBe(15);
expect(et.secs).toBe(3675);
});
test("ElapsedTime: constructor with a mm:ss string", () => {
let et = new ElapsedTime('42:01');
expect(et.arg).toBe('42:01');
expect(et.asHHMMSS()).toBe('00:42:01');
expect(et.hh).toBe(0);
expect(et.mm).toBe(42);
expect(et.ss).toBe(1);
expect(et.secs).toBe((42 * 60) + 1);
});
test("ElapsedTime: constructor with a ss string", () => {
let et = new ElapsedTime('59');
expect(et.arg).toBe('59');
expect(et.asHHMMSS()).toBe('00:00:59');
expect(et.hh).toBe(0);
expect(et.mm).toBe(0);
expect(et.ss).toBe(59);
expect(et.secs).toBe(59);
});
test("ElapsedTime: constructor with an empty string", () => {
let et = new ElapsedTime('');
expect(et.arg).toBe('');
expect(et.asHHMMSS()).toBe('00:00:00');
expect(et.hh).toBe(0);
expect(et.mm).toBe(0);
expect(et.ss).toBe(0);
expect(et.secs).toBe(0);
});
test("ElapsedTime: constructor with a malformed string", () => {
// garbage-in, garbage-out
let et = new ElapsedTime('?what!');
expect(et.arg).toBe('?what!');
expect(et.asHHMMSS()).toBe('NaN:NaN:NaN');
});
test("Speed: property formats ss second values as nn.nn strings", () => {
let d1 = new Distance(1.0);
let et1 = new ElapsedTime('8:00');
let s1 = new Speed(d1, et1);
expect(s1.formattedSeconds(0)).toBe('00.00');
expect(s1.formattedSeconds(1)).toBe('01.00');
expect(s1.formattedSeconds(17.76)).toBe('17.76');
expect(s1.formattedSeconds(59.90)).toBe('59.90');
expect(s1.formattedSeconds(59.99)).toBe('59.99');
});
test("Speed: calculates a 2-mile walk, with round numbers", () => {
let d1 = new Distance(2.0);
let et1 = new ElapsedTime('30:00');
let s1 = new Speed(d1, et1);
expect(s1.secondsPerMile()).toBe(900);
expect(s1.pacePerMile()).toBe('15:00.00');
});
test("Speed: calculates a marathon with fractional seconds pace", () => {
let d1 = new Distance(26.2);
let et1 = new ElapsedTime('3:47:30');
let s1 = new Speed(d1, et1);
expect(s1.secondsPerMile()).toBe(520.9923664122138);
expect(s1.pacePerMile()).toBe('8:40.99');
});
test("Speed: project a time using simple linear formula", () => {
let d1 = new Distance(10.0);
let d2 = new Distance(20.0);
let et1 = new ElapsedTime('1:30:00');
let s1 = new Speed(d1, et1);
expect(s1.secondsPerMile()).toBe(540.0);
expect(s1.pacePerMile()).toBe('9:00.00');
let hhmmss = s1.projectedTime(d2);
expect(hhmmss).toBe('03:00:00');
});
test("Speed: project a time using the exponential riegel formula", () => {
let d1 = new Distance(10.0);
let d2 = new Distance(20.0);
let et1 = new ElapsedTime('1:30:00');
let s1 = new Speed(d1, et1);
expect(s1.secondsPerMile()).toBe(540.0);
expect(s1.pacePerMile()).toBe('9:00.00');
let hhmmss = s1.projectedTime(d2, 'riegel');
expect(hhmmss).toBe('03:07:38');
});
test("Speed: calculated age-graded speeds", () => {
let d = new Distance(26.2);
let et = new ElapsedTime('3:47:30');
let s1 = new Speed(d, et);
let a1 = new Age(42.5);
let a2 = new Age(43.5);
let a3 = new Age(57.1);
expect(s1.mph()).toBe(6.90989010989011);
let s2 = s1.ageGraded(a1, a2);
let s3 = s1.ageGraded(a1, a3);
expect(s2.mph()).toBe(6.871129889997814);
expect(s3.mph()).toBe(6.341693000739595);
});
test("RunWalkCalculator: calculate with all walking, no running", () => {
let calculator = new RunWalkCalculator()
let run_hhmmss = '00:00';
let run_ppm = '9:00';
let walk_hhmmss = '10:00';
let walk_ppm = '18:00';
let miles = 3.333;
let result : RunWalkCalculation =
calculator.calculate(run_hhmmss, run_ppm, walk_hhmmss, walk_ppm, miles);
// inputs
expect(result.runHhmmss).toBe(run_hhmmss);
expect(result.runPpm).toBe(run_ppm);
expect(result.walkHhmmss).toBe(walk_hhmmss);
expect(result.walkPpm).toBe(walk_ppm);
expect(result.miles).toBe(miles);
// calculated
expect(result.avgMph).toBeCloseTo(3.333333, 0.0001);
expect(result.avgPpm).toBe('18:00.00');
expect(result.projectedTime).toBe('00:59:59');
expect(result.projectedMiles).toBeCloseTo(3.333, 0.001);
});
test("RunWalkCalculator: calculate with all running, no walking", () => {
let calculator = new RunWalkCalculator()
let run_hhmmss = '10:00';
let run_ppm = '9:00';
let walk_hhmmss = '0:00';
let walk_ppm = '18:00';
let miles = 3.333;
let result : RunWalkCalculation =
calculator.calculate(run_hhmmss, run_ppm, walk_hhmmss, walk_ppm, miles);
// inputs
expect(result.runHhmmss).toBe(run_hhmmss);
expect(result.runPpm).toBe(run_ppm);
expect(result.walkHhmmss).toBe(walk_hhmmss);
expect(result.walkPpm).toBe(walk_ppm);
expect(result.miles).toBe(miles);
// calculated
expect(result.avgMph).toBeCloseTo(6.666666666666667, 0.00001);
expect(result.avgPpm).toBe('9:00.00');
expect(result.projectedTime).toBe('00:29:59');
expect(result.projectedMiles).toBeCloseTo(3.333, 0.001);
});
test("RunWalkCalculator: calculate a marathon with a 9:1 ratio of running to walking", () => {
let calculator = new RunWalkCalculator()
let run_hhmmss = '9:00';
let run_ppm = '9:00';
let walk_hhmmss = '1:00';
let walk_ppm = '18:00';
let miles = 26.2;
let result : RunWalkCalculation =
calculator.calculate(run_hhmmss, run_ppm, walk_hhmmss, walk_ppm, miles);
// inputs
expect(result.runHhmmss).toBe(run_hhmmss);
expect(result.runPpm).toBe(run_ppm);
expect(result.walkHhmmss).toBe(walk_hhmmss);
expect(result.walkPpm).toBe(walk_ppm);
expect(result.miles).toBe(miles);
// calculated
expect(result.avgMph).toBeCloseTo(6.060606, 0.000001);
expect(result.avgPpm).toBe('9:54.00');
expect(result.projectedTime).toBe('04:19:22');
expect(result.projectedMiles).toBeCloseTo(26.2, 0.001);
});
- 2023-09-19 - 1.0.0 - Re-implemented with TypeScript.
- 2015-08-04 - 0.4.0 - Added class RunWalkCalculator, and ported the project back to CoffeeScript.
- 2015-05-13 - 0.3.2 - Repackaged again, from a single merged m26-js.ts file. Tests enhanced.
- 2015-05-12 - 0.3.1 - Renamed lib from m26.js to m26-js.js, etc, and repackaged.
- 2015-05-12 - 0.3.0 - Project ported from CoffeeScript to Typescript, with m26.d.ts typings file.
- 2014-11-09 - 0.2.0 - Corrected the English-to-Metric and Metric-to-English conversions.
- 2014-11-06 - 0.1.5 - Fix require statement in examples documentation.
- 2014-11-05 - 0.1.4 - Removed a spec_helper function.
- 2014-11-02 - 0.1.3 - Added Age.training_zones()
- 2014-11-01 - 0.1.2 - Added Speed.age_graded()
- 2014-11-01 - 0.1.1 - Added Speed.projected_time(), Age, AgeCalculator.
- 2014-11-01 - 0.1.0 - Initial working version.
- 2014-11-01 - 0.0.3 - alpha 3
- 2014-11-01 - 0.0.2 - alpha 2
- 2014-11-01 - 0.0.1 - alpha 1