calcpace 1.17.0 → 1.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b4581502040b195baf42c3dbf64bdb8cc6902d2fd1f4011d7982c18961bbf5f
-  data.tar.gz: 0dff0cbdd1604680521987db6a08b96ec136546074d76fe7f45b7d4028f9f8bf
+  metadata.gz: 70f0253d8a81513d2f48082bc39c96a1c9c324fc29ffb7f64ffde0590e5134c7
+  data.tar.gz: 2add58bc0d0f904e1e4cf6e08379e495bdeef2ee74bdcb068b973e4e4f0c995a
 SHA512:
-  metadata.gz: 0d4106b957c4da8334d470d67aa5a350f243bac65d0ca5767a356f93e62063a197f7fe338fa2474dcf4079bc5e366f3cfb3a98125820020f3b4bacdb7c4fd856
-  data.tar.gz: d8f85dd081aa9e1941bcea8931d70d994bb195f9dd5e46fbc47cb2a3ace57df99c545c8283ba76f0a3b4e53b35ff880e8f663d6a464cc85276a3a03e3e7ab1b1
+  metadata.gz: 9abfbeae4e5cccd4c9634f0abcfa7bc51a29d317f47db86aceffd4afe04b17a629f0075440cc3729fd0893d614b007d16d3f5318ee3e4c671226832fb2373327
+  data.tar.gz: 8d6f1e3e2cd0e10a0436bbdd9ea7ebfc1f0a6973d2e69a83c0419c17ce0ae12c554790d1f80b5fedf2ad047ec6c5092c03bb58710da2bdc76434b71ac9ccc071

data/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-09-06
+
+### Fixed
+- `age_grade_label(Float::NAN)` raised an opaque `NoMethodError` (`undefined
+  method '[]' for nil`) instead of a clear error; it now raises
+  `ArgumentError`. `Float::INFINITY` is unchanged and still maps to the top
+  band, "Approximate World Record Level".
+
+### Changed
+- `AGE_GRADE_LABELS` is now sorted by `min` descending at load time and
+  validated to be strictly descending with a `min` of exactly `0.0` on the
+  last entry, raising `Calcpace::InvalidDataError` at require time otherwise.
+  `age_grade_label` walks the list in order and returns the first match, so
+  an out-of-order entry in the data file would have silently misclassified
+  percentages, and a missing zero floor raised an opaque `NoMethodError`
+  instead of failing loudly.
+- Corrected the provenance note for the age-grade categories in the README
+  and in `wma_2023_open_standards.yml`. The WMA / Alan Jones (Howard Grubb)
+  tables are numeric age factors and open standards only — they define no
+  categories at all. The bands from Local Class (60%) upward follow the
+  USATF Masters / National Masters News convention; the three bands below
+  60% remain calcpace's own extension for recreational runners. No band
+  boundaries or labels changed, only the attribution text.
+- Documented in the README that the bands apply to the percentage as
+  reported by `age_grade` (rounded to one decimal), so calling
+  `age_grade_label` directly on an unrounded value can land one band lower
+  at an edge.
+
+## [1.18.0] - 2026-09-06
+
+### Breaking
+- **`age_grade[:category]` and `age_grade_label` return different strings for
+  anything below 60%.** The old single `"Developing"` band below 60% is now
+  three bands: `"Intermediate"` (50–59.9%), `"Recreational"` (40–49.9%) and
+  `"Active Beginner"` (below 40%). Most recreational runners grade under 60%,
+  so the old catch-all told nearly every one of them the same thing. A caller
+  matching on the string `"Developing"` must update — that string is no
+  longer returned by either method.
+
+  ```ruby
+  calc.age_grade_label(55.0) # => "Intermediate"      (was "Developing")
+  calc.age_grade_label(45.0) # => "Recreational"      (was "Developing")
+  calc.age_grade_label(30.0) # => "Active Beginner"   (was "Developing")
+  ```
+
+  The bands at 60% and above are untouched, and the numeric fields —
+  `age_grade_percent`, `age_graded_time_seconds` and the rest — are
+  unaffected; only the two label-returning methods changed.
+
 ## [1.17.0] - 2026-09-05
 
 ### Added
@@ -600,7 +649,9 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.17.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.18.1...HEAD
+[1.18.1]: https://github.com/0jonjo/calcpace/compare/v1.18.0...v1.18.1
+[1.18.0]: https://github.com/0jonjo/calcpace/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/0jonjo/calcpace/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/0jonjo/calcpace/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/0jonjo/calcpace/compare/v1.14.0...v1.15.0

data/README.md

@@ -2,10 +2,12 @@
 
 A Ruby gem for runners: pace, time, and distance calculations, unit conversions, race predictions, GPS track analysis, age grading, VO2max estimation, and training zones.
 
+> **See it in action:** [calcpace.app](https://calcpace.app) — free running calculators, race predictors and a training log, all powered by this gem.
+
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.12.0'
+gem 'calcpace', '~> 1.18.1'
 ```
 
 ## Usage
@@ -261,6 +263,30 @@ calc.age_grade_percent(5.0, '00:22:30', age: 40, sex: :female) # => 65.2
 calc.age_grade_label(65.2)                                      # => "Local Class"
 ```
 
+`category` (and `age_grade_label`) returns one of:
+
+| Age grade | Category |
+| --- | --- |
+| 100%+ | Approximate World Record Level |
+| 90–99.9% | World Class |
+| 80–89.9% | National Class |
+| 70–79.9% | Regional Class |
+| 60–69.9% | Local Class |
+| 50–59.9% | Intermediate |
+| 40–49.9% | Recreational |
+| below 40% | Active Beginner |
+
+The WMA / Alan Jones (Howard Grubb) tables are numeric age factors and open
+standards only — they define no categories at all. The bands from Local Class
+(60%) upward follow the USATF Masters / National Masters News convention; the
+three bands below 60% are calcpace's own extension — most recreational
+runners land there, and one catch-all label for everybody under 60% tells
+them nothing.
+
+The bands apply to the percentage as reported by `age_grade`, rounded to one
+decimal, so calling `age_grade_label` directly on an unrounded value can land
+one band lower at an edge.
+
 Supported distances: 5K, 10K, half marathon, marathon.
 
 A numeric distance within **2%** of one of those is graded as that standard —
@@ -665,6 +691,8 @@ All errors inherit from `Calcpace::Error`:
 - `Calcpace::InvalidTimeFormatError` — time string not in `HH:MM:SS` or `MM:SS` format
 - `Calcpace::UnsupportedUnitError` — unknown conversion (`convert`) or unknown
   `unit:` / `distance_unit:` keyword
+- `Calcpace::InvalidDataError` — the bundled data table failed its load-time
+  consistency check (raised on `require`, never for user input)
 
 Argument validation that is not about units or numbers raises a plain `ArgumentError`:
 unknown race names, unsupported age-grading distances, and invalid `age` / `sex` values.

data/lib/calcpace/age_grading.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'errors'
 
 # Module for age-grading race performances with a versioned table
 #
@@ -28,9 +29,18 @@ module AgeGrading
                                                                       aliases: false).freeze
   TABLE_VERSION = OPEN_STANDARDS_DATA.fetch('meta').fetch('table_version').freeze
 
-  AGE_GRADE_LABELS = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
+  raw_age_grade_labels = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
     { min: entry.fetch('min').to_f, label: entry.fetch('label') }
-  end.freeze
+  end
+  AGE_GRADE_LABELS = raw_age_grade_labels.sort_by { |entry| -entry[:min] }.freeze
+
+  age_grade_label_mins = AGE_GRADE_LABELS.map { |entry| entry[:min] }
+  unless age_grade_label_mins.all?(&:finite?) &&
+         age_grade_label_mins == age_grade_label_mins.uniq &&
+         age_grade_label_mins.last == 0.0
+    raise Calcpace::InvalidDataError,
+          "age_grade_classifications must have unique finite mins ending at 0.0, got #{age_grade_label_mins.inspect}"
+  end
 
   DISTANCE_TO_METERS = {
     5.0 => '5000',
@@ -115,6 +125,7 @@ module AgeGrading
   #
   # @param percent [Numeric] age-grade percentage
   # @return [String] category label
+  # @raise [ArgumentError] when percent is not numeric, is negative, or is NaN
   def age_grade_label(percent)
     percent_value = begin
       Float(percent)
@@ -123,6 +134,7 @@ module AgeGrading
     end
 
     raise ArgumentError, 'Age-grade percent must be greater than or equal to 0' if percent_value.negative?
+    raise ArgumentError, 'Age-grade percent must be a number' if percent_value.nan?
 
     AGE_GRADE_LABELS.find { |entry| percent_value >= entry[:min] }[:label]
   end

data/lib/calcpace/data/wma_2023_open_standards.yml

@@ -3,6 +3,12 @@ meta:
   url: "https://howardgrubb.co.uk/athletics/wmatnf23.html"
   table_version: "WMA_2023_ONE_YEAR_FACTORS_V1"
 
+# The WMA / Alan Jones (Howard Grubb) tables are numeric age factors and open
+# standards only — they define no categories at all. The bands from Local
+# Class (60%) upward follow the USATF Masters / National Masters News
+# convention; the three bands under 60% are Calcpace's own extension, added
+# to give recreational runners a meaningful label instead of a single
+# catch-all.
 age_grade_classifications:
   - min: 100.0
     label: "Approximate World Record Level"
@@ -14,8 +20,12 @@ age_grade_classifications:
     label: "Regional Class"
   - min: 60.0
     label: "Local Class"
+  - min: 50.0
+    label: "Intermediate"
+  - min: 40.0
+    label: "Recreational"
   - min: 0.0
-    label: "Developing"
+    label: "Active Beginner"
 
 open_standards_seconds:
   M:

data/lib/calcpace/errors.rb

@@ -20,6 +20,9 @@ class Calcpace
     end
   end
 
+  # Raised when versioned/static gem data fails an internal consistency check
+  class InvalidDataError < Error; end
+
   # Raised when an unsupported unit or unit conversion is requested
   #
   # @example conversion pair

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.17.0'
+  VERSION = '1.18.1'
 end

data/lib/calcpace.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'calcpace/errors'
 require_relative 'calcpace/calculator'
 require_relative 'calcpace/cameron_predictor'
 require_relative 'calcpace/age_grading'
@@ -7,7 +8,6 @@ require_relative 'calcpace/environmental_adjuster'
 require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
-require_relative 'calcpace/errors'
 require_relative 'calcpace/fitness_predictor'
 require_relative 'calcpace/lap_analyzer'
 require_relative 'calcpace/pace_calculator'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.1
 platform: ruby
 authors:
 - João Gilberto Saraiva