Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

feat(stats): forecast fatigue recovery from the display value

Сергей Горбатенко3a39e163c159
diff --git a/frontend/src/lib/recovery-view.js b/frontend/src/lib/recovery-view.js
index 1abc6ffa4..54bfd6db3 100644
--- a/frontend/src/lib/recovery-view.js
+++ b/frontend/src/lib/recovery-view.js
@@ -1,4 +1,5 @@
-import { FATIGUE_STATES } from './recovery.js'
+import { FATIGUE_STATES, fatigueHalfLifeOf } from './recovery.js'
+import { dateLocale } from './i18n-core.js'
/**
* Select the consumer-facing fatigue state for one numeric recovery value.
@@ -15,3 +16,46 @@ export function fatigueStateOf(value) {
? FATIGUE_STATES.RECOVERING
: FATIGUE_STATES.FATIGUED
}
+
+// Boundaries fatigueStateOf draws: below READY_BELOW the muscle reads ready,
+// at or below RECOVERING_BELOW (but above ready) it reads recovering.
+export const FATIGUE_READY_BELOW = 0.25
+export const FATIGUE_RECOVERING_BELOW = 0.5
+
+/**
+ * Milliseconds until a fatigued muscle drops back through the display bands,
+ * assuming no new training. Exact, not simulated: after the last stimulus the
+ * accumulated volume decays as one exponential with the muscle's own half-life,
+ * so the crossing time solves in closed form from the saturation curve.
+ *
+ * @param {number} value Current fatigue value from fatigueOf(), in [0, 1).
+ * @param {string} slug Drawable muscle slug (owns the half-life).
+ * @returns {{toRecoveringMs: number|null, toReadyMs: number|null}} Null where already below the band.
+ */
+export function fatigueRecoveryMs(value, slug) {
+ const v = Number(value)
+ if (!Number.isFinite(v) || v <= FATIGUE_READY_BELOW) return { toRecoveringMs: null, toReadyMs: null }
+ const halfLife = fatigueHalfLifeOf(slug)
+ if (!(halfLife > 0)) return { toRecoveringMs: null, toReadyMs: null }
+ const v0 = -Math.log(1 - Math.min(v, 1 - 1e-9))
+ const msFor = target => {
+ if (v <= target) return null
+ return Math.max(0, halfLife * Math.log2(v0 / -Math.log(1 - target)))
+ }
+ return { toRecoveringMs: msFor(FATIGUE_RECOVERING_BELOW), toReadyMs: msFor(FATIGUE_READY_BELOW) }
+}
+
+/**
+ * Localised "in N hours/days" for a recovery duration, via the platform's own
+ * plural rules (Intl.RelativeTimeFormat) so no locale pack carries the words.
+ *
+ * @param {number|null} ms Duration in milliseconds, or null when already recovered.
+ * @returns {string|null} Localised duration, or null for null input.
+ */
+export function fmtRecoveryIn(ms) {
+ if (ms == null || !(ms >= 0)) return null
+ const minutes = Math.round(ms / 60000)
+ const [n, unit] = minutes < 60 ? [Math.max(1, minutes), 'minute'] : minutes < 2880 ? [Math.max(1, Math.round(minutes / 60)), 'hour'] : [Math.max(1, Math.round(minutes / 1440)), 'day']
+ try { return new Intl.RelativeTimeFormat(dateLocale(), { numeric: 'always' }).format(n, unit) }
+ catch { return `${n} ${unit}` }
+}
diff --git a/frontend/src/lib/recovery-view.test.js b/frontend/src/lib/recovery-view.test.js
index 6ccc7e61d..030f47217 100644
--- a/frontend/src/lib/recovery-view.test.js
+++ b/frontend/src/lib/recovery-view.test.js
@@ -1,6 +1,6 @@
import { describe, expect, it } from 'vitest'
-import { FATIGUE_STATES, fatigueOf, strengthOf } from './recovery.js'
-import { fatigueStateOf } from './recovery-view.js'
+import { FATIGUE_STATES, fatigueHalfLifeOf, fatigueOf, strengthOf } from './recovery.js'
+import { fatigueStateOf, fatigueRecoveryMs, fmtRecoveryIn } from './recovery-view.js'
import { MUSCLES, levelsOf } from './muscles.js'
const FATIGUE_BANDS = [
@@ -56,3 +56,38 @@ describe('production recovery view selectors', () => {
expect(strengthOf([workout], now + 7 * 86400000).chest).toBe(0.5)
})
})
+
+describe('fatigue recovery forecast', () => {
+ it('returns nulls for a ready muscle and only toReady for a recovering one', () => {
+ expect(fatigueRecoveryMs(0, 'chest')).toEqual({ toRecoveringMs: null, toReadyMs: null })
+ expect(fatigueRecoveryMs(0.24, 'chest')).toEqual({ toRecoveringMs: null, toReadyMs: null })
+ const mid = fatigueRecoveryMs(0.4, 'chest')
+ expect(mid.toRecoveringMs).toBe(null)
+ expect(mid.toReadyMs).toBeGreaterThan(0)
+ })
+
+ it('returns both crossings for a fatigued muscle, recovering first', () => {
+ const { toRecoveringMs, toReadyMs } = fatigueRecoveryMs(0.6, 'chest')
+ expect(toRecoveringMs).toBeGreaterThan(0)
+ expect(toReadyMs).toBeGreaterThan(toRecoveringMs)
+ })
+
+ it('matches the closed-form crossing: HL * log2(v0 / targetV)', () => {
+ const v = 0.6
+ const hl = fatigueHalfLifeOf('chest')
+ const v0 = -Math.log(1 - v)
+ const expected = hl * Math.log2(v0 / -Math.log(1 - 0.5))
+ expect(fatigueRecoveryMs(v, 'chest').toRecoveringMs).toBeCloseTo(expected, 6)
+ })
+
+ it('gives longer recoveries to 48h legs than to 24h arms at the same value', () => {
+ expect(fatigueRecoveryMs(0.6, 'quadriceps').toReadyMs)
+ .toBeGreaterThan(fatigueRecoveryMs(0.6, 'biceps').toReadyMs)
+ })
+
+ it('formats durations without locale-pack words', () => {
+ expect(fmtRecoveryIn(null)).toBe(null)
+ expect(fmtRecoveryIn(30 * 60000)).toMatch(/30/)
+ expect(fmtRecoveryIn(30 * 3600000)).toMatch(/6|hour/)
+ })
+})