@dgpholdings/greatoak-shared 1.2.53 → 1.2.55

package/dist/utils/exerciseRecord/workoutMath.test.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const workoutMath_1 = require("./workoutMath");
+const templateExercises_mock_1 = require("../../__mocks__/templateExercises.mock");
+(0, vitest_1.describe)('workoutMath - Core Utilities', () => {
+    (0, vitest_1.describe)('parseMmSsToSecs', () => {
+        (0, vitest_1.it)('handles empty or invalid strings safely', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)(undefined)).toBe(0);
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('')).toBe(0);
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('invalid')).toBe(0);
+        });
+        (0, vitest_1.it)('parses MM:SS formats correctly', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('00:00')).toBe(0);
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('05:30')).toBe(330);
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('15:00')).toBe(900);
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('99:59')).toBe(5999);
+        });
+        (0, vitest_1.it)('parses HH:MM:SS formats correctly', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('01:05:30')).toBe(3930);
+        });
+        (0, vitest_1.it)('resists NaN propagation from empty segments', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)(':30')).toBe(30); // Uses || 0 fallback
+            (0, vitest_1.expect)((0, workoutMath_1.parseMmSsToSecs)('05:')).toBe(300);
+        });
+    });
+    (0, vitest_1.describe)('estimateWorkDuration', () => {
+        const benchGuardrails = {
+            type: 'weight-reps',
+            stressRestBonus: 3,
+            fatigueMultiplier: 1.0,
+            setupTypicalSecs: 5,
+            restPeriods: { minimum: 30, typical: 90, maximum: 180, optimalRange: [60, 120] },
+            singleRep: { min: 1.5, max: 4.0, typical: 2.5 },
+        };
+        (0, vitest_1.it)('returns 0 if set is not done', () => {
+            const record = { type: 'weight-reps', isDone: false, isStrictMode: false, kg: '100', reps: '10' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, benchGuardrails)).toBe(0);
+        });
+        (0, vitest_1.it)('calculates duration for standard weight-reps set based on guardrails', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10' };
+            // 10 reps * 2.5s typical + 5s setup = 30s
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, benchGuardrails)).toBe(30);
+        });
+        (0, vitest_1.it)('handles reps-only type exactly like weight-reps', () => {
+            const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: '10', auxWeightKg: '' };
+            // 10 reps * 2.5s typical + 5s setup = 30s
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, benchGuardrails)).toBe(30);
+        });
+        (0, vitest_1.it)('handles Zero Reps / Failed Set edge case safely', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '150', reps: '0' };
+            // 0 reps * 2.5s + 5s setup = 5s (still took time to setup and fail)
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, benchGuardrails)).toBe(5);
+        });
+        (0, vitest_1.it)('guards against negative reps input returning negative duration', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '150', reps: '-5' };
+            // Math.max(0, -5) -> 0 reps * 2.5s + 5s setup = 5s
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, benchGuardrails)).toBe(5);
+        });
+        (0, vitest_1.it)('falls back to hardcoded defaults (2.5 rep, 3 setup) if guardrails are completely missing', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10' };
+            // 10 reps * 2.5s fallback + 3s setup fallback = 28s
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record, undefined)).toBe(28);
+        });
+        (0, vitest_1.it)('parses duration explicitly for cardio/duration types', () => {
+            const record = { type: 'duration', isDone: true, isStrictMode: false, durationMmSs: '02:30', auxWeightKg: '0' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record)).toBe(150);
+        });
+        (0, vitest_1.it)('parses duration explicitly for cardio-machine type', () => {
+            const record = { type: 'cardio-machine', isDone: true, isStrictMode: false, durationMmSs: '05:00' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateWorkDuration)(record)).toBe(300);
+        });
+    });
+    (0, vitest_1.describe)('estimateRestDuration', () => {
+        const guardrails = {
+            type: 'weight-reps',
+            stressRestBonus: 0,
+            fatigueMultiplier: 1.0,
+            setupTypicalSecs: 5,
+            restPeriods: { minimum: 30, typical: 60, maximum: 180, optimalRange: [45, 90] },
+            singleRep: { min: 2, max: 3, typical: 2.5 },
+        };
+        (0, vitest_1.it)('returns 0 if set is not done', () => {
+            const record = { type: 'weight-reps', isDone: false, isStrictMode: false, kg: '10', reps: '10' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, guardrails)).toBe(0);
+        });
+        (0, vitest_1.it)('prioritizes explicit rest duration if valid', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '10', reps: '10', restDurationSecs: 45 };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, guardrails)).toBe(45);
+        });
+        (0, vitest_1.it)('clamps distracted logger rest to maximum guardrail', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '10', reps: '10', restDurationSecs: 500 }; // 500s is > 180s
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, guardrails)).toBe(180);
+        });
+        (0, vitest_1.it)('falls back to typical rest if missing', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '10', reps: '10' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, guardrails)).toBe(60);
+        });
+        (0, vitest_1.it)('falls back to typical rest if explicitly 0 (physically impossible edge case)', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '10', reps: '10', restDurationSecs: 0 };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, guardrails)).toBe(60);
+        });
+        (0, vitest_1.it)('falls back to hardcoded default (60) if guardrails are completely missing', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '10', reps: '10' };
+            (0, vitest_1.expect)((0, workoutMath_1.estimateRestDuration)(record, undefined)).toBe(60);
+        });
+    });
+    (0, vitest_1.describe)('calculateTotalExerciseDuration (Unit Tests)', () => {
+        const guardrails = {
+            type: 'weight-reps',
+            stressRestBonus: 0,
+            fatigueMultiplier: 1.0,
+            setupTypicalSecs: 5,
+            restPeriods: { minimum: 30, typical: 90, maximum: 180, optimalRange: [60, 120] },
+            singleRep: { min: 2, max: 3, typical: 2.5 },
+        };
+        (0, vitest_1.it)('returns 0 for empty array', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)([], guardrails)).toBe(0);
+        });
+        (0, vitest_1.it)('calculates total correctly excluding the last rest for multiple sets', () => {
+            const records = [
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 }, // Work: 30s + Rest: 60s
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 }, // Work: 30s + Rest: 60s
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 }, // Work: 30s + Rest: ignored
+            ];
+            // Work = 30 + 30 + 30 = 90
+            // Rest = 60 + 60 = 120
+            // Total = 210
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(records, guardrails)).toBe(210);
+        });
+        (0, vitest_1.it)('calculates just work duration if only a single set is completed', () => {
+            const records = [
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 },
+            ];
+            // Work = 30
+            // Rest = 0 (ignored b/c it is the final set)
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(records, guardrails)).toBe(30);
+        });
+        (0, vitest_1.it)('ignores undone sets and handles non-sequential completion correctly', () => {
+            const records = [
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 }, // Work: 30, Rest: 60
+                { type: 'weight-reps', isDone: false, isStrictMode: false, kg: '100', reps: '10' }, // Ignored completely
+                { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '10', restDurationSecs: 60 }, // Work: 30, Rest: Ignored (final done set)
+            ];
+            // Done records length = 2. Index 0 gets work+rest. Index 1 gets work only.
+            // 30 + 60 + 30 = 120
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(records, guardrails)).toBe(120);
+        });
+    });
+    (0, vitest_1.describe)('calculateSetVolume', () => {
+        (0, vitest_1.it)('calculates weight-reps volume', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '100', reps: '5' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(500);
+        });
+        (0, vitest_1.it)('calculates weight-reps decimal (micro-load) volume safely', () => {
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '42.5', reps: '5' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(212.5);
+        });
+        (0, vitest_1.it)('returns 0 for undone records', () => {
+            const record = { type: 'weight-reps', isDone: false, isStrictMode: false, kg: '100', reps: '5' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(0);
+        });
+        (0, vitest_1.it)('returns 0 for cardio/duration types by design', () => {
+            const record = { type: 'duration', isDone: true, isStrictMode: false, durationMmSs: '15:00', auxWeightKg: '0' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(0);
+        });
+        (0, vitest_1.it)('safely handles Imperial Footgun (treats string verbatim)', () => {
+            // If frontend sends LBS but it is expected to be KG, the pure math doesn't crash,
+            // it just processes it. Data cleansing for LBS must happen before this or at the UI layer.
+            const record = { type: 'weight-reps', isDone: true, isStrictMode: false, kg: '220', reps: '10' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(2200);
+        });
+        (0, vitest_1.it)('calculates reps-only volume with empty auxWeight string (defaults to 1 per rep)', () => {
+            const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: '10', auxWeightKg: '' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(10); // 1 * 10
+        });
+        (0, vitest_1.it)('calculates reps-only volume with explicit zero auxWeight (defaults to 1 per rep)', () => {
+            const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: '10', auxWeightKg: '0' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(10); // 1 * 10
+        });
+        (0, vitest_1.it)('calculates reps-only volume with positive Aux Weight (Dip belt)', () => {
+            const record = { type: 'reps-only', isDone: true, isStrictMode: false, reps: '10', auxWeightKg: '20' };
+            (0, vitest_1.expect)((0, workoutMath_1.calculateSetVolume)(record)).toBe(210); // (1 + 20) * 10
+        });
+    });
+    (0, vitest_1.describe)('Scenario Integration (End-to-End)', () => {
+        const { allUndone: mockTemplateAllUndone, singleSet: mockTemplateSingleSet, nonSequential: mockTemplateNonSequential, lazyLogger: mockTemplateLazyLogger, distractedLogger: mockTemplateDistractedLogger } = templateExercises_mock_1.mockTemplateExercisesDictionary;
+        const guardrails = {
+            type: 'weight-reps',
+            stressRestBonus: 0,
+            fatigueMultiplier: 1.0,
+            setupTypicalSecs: 5,
+            restPeriods: { minimum: 30, typical: 90, maximum: 180, optimalRange: [60, 120] },
+            singleRep: { min: 2, max: 3, typical: 2.5 },
+        };
+        (0, vitest_1.it)('Scenario: "Distracted Logger" -> clamping fires, total is correct', () => {
+            // mockTemplateDistractedLogger has:
+            // Set 1: 10 reps, 600s rest -> Work: 30s, Rest clamped to 180s
+            // Set 2: 10 reps, 90s rest -> Work: 30s, Rest ignored (final set)
+            // Total = 30 + 180 + 30 = 240
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateDistractedLogger.initialRecords, guardrails)).toBe(240);
+        });
+        (0, vitest_1.it)('Scenario: "Lazy Logger" -> fallback to typical, total is correct', () => {
+            // mockTemplateLazyLogger has 3 sets, all rest durations are undefined.
+            // Guardrail typical rest is 90s.
+            // Set 1: 30s work + 90s rest
+            // Set 2: 30s work + 90s rest
+            // Set 3: 30s work + ignored rest
+            // Total = 30*3 + 90*2 = 270
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateLazyLogger.initialRecords, guardrails)).toBe(270);
+        });
+        (0, vitest_1.it)('Scenario: Single set -> rest excluded, work only', () => {
+            // Work: (5 reps * 2.5s) + 5s = 17.5 -> rounded to 18s
+            // Rest: 180s (should be ignored because it's the final set)
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateSingleSet.initialRecords, guardrails)).toBe(18);
+        });
+        (0, vitest_1.it)('Scenario: Non-sequential -> filter ordering, last done set has no rest', () => {
+            // mockTemplateNonSequential has:
+            // Set 1: Done, 10 reps, 90s rest -> Work: 30s, Rest: 90s
+            // Set 2: Undone -> Ignored
+            // Set 3: Done, 10 reps, 90s rest -> Work: 30s, Rest: ignored (because it is the last DONE set)
+            // Total = 30 + 90 + 30 = 150
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateNonSequential.initialRecords, guardrails)).toBe(150);
+        });
+        (0, vitest_1.it)('Scenario: All undone -> returns 0', () => {
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateAllUndone.initialRecords, guardrails)).toBe(0);
+        });
+        (0, vitest_1.it)('Scenario: No guardrails exercise -> hardcoded fallbacks kick in', () => {
+            // Re-use lazy logger (3 sets, no rest tracked).
+            // Fallbacks: 2.5s rep, 3s setup, 60s rest.
+            // Set 1: 28s work + 60s rest
+            // Set 2: 28s work + 60s rest
+            // Set 3: 28s work
+            // Total = 28*3 + 60*2 = 204
+            (0, vitest_1.expect)((0, workoutMath_1.calculateTotalExerciseDuration)(mockTemplateLazyLogger.initialRecords, undefined)).toBe(204);
+        });
+    });
+});

package/dist/utils/index.d.ts

@@ -7,6 +7,8 @@ export { toError } from "./toError.util";
 export { generatePlanCode } from "./planCode.util";
 export { maskEmail, isAnonymousEmail, isEmail } from "./email.utils";
 export { NOOP } from "./noop.utils";
-export { calculateExerciseScoreV2, calculateTotalVolume } from "./scoring";
+export { calculateExerciseScoreV2, calculateTotalVolume } from "./scoringWorkout";
 export { scaleProPlan, calculateBMI, calculateDayPlanDuration, calculateExerciseDurationSecs } from "./adoptionEngine/scaleProPlan.util";
+export * from "./exerciseRecord/workoutMath";
+export * from "./exerciseRecord/recordValidator";
 export * from "./metricConversions";

package/dist/utils/index.js

@@ -38,12 +38,14 @@ Object.defineProperty(exports, "isAnonymousEmail", { enumerable: true, get: func
 Object.defineProperty(exports, "isEmail", { enumerable: true, get: function () { return email_utils_1.isEmail; } });
 var noop_utils_1 = require("./noop.utils");
 Object.defineProperty(exports, "NOOP", { enumerable: true, get: function () { return noop_utils_1.NOOP; } });
-var scoring_1 = require("./scoring");
-Object.defineProperty(exports, "calculateExerciseScoreV2", { enumerable: true, get: function () { return scoring_1.calculateExerciseScoreV2; } });
-Object.defineProperty(exports, "calculateTotalVolume", { enumerable: true, get: function () { return scoring_1.calculateTotalVolume; } });
+var scoringWorkout_1 = require("./scoringWorkout");
+Object.defineProperty(exports, "calculateExerciseScoreV2", { enumerable: true, get: function () { return scoringWorkout_1.calculateExerciseScoreV2; } });
+Object.defineProperty(exports, "calculateTotalVolume", { enumerable: true, get: function () { return scoringWorkout_1.calculateTotalVolume; } });
 var scaleProPlan_util_1 = require("./adoptionEngine/scaleProPlan.util");
 Object.defineProperty(exports, "scaleProPlan", { enumerable: true, get: function () { return scaleProPlan_util_1.scaleProPlan; } });
 Object.defineProperty(exports, "calculateBMI", { enumerable: true, get: function () { return scaleProPlan_util_1.calculateBMI; } });
 Object.defineProperty(exports, "calculateDayPlanDuration", { enumerable: true, get: function () { return scaleProPlan_util_1.calculateDayPlanDuration; } });
 Object.defineProperty(exports, "calculateExerciseDurationSecs", { enumerable: true, get: function () { return scaleProPlan_util_1.calculateExerciseDurationSecs; } });
+__exportStar(require("./exerciseRecord/workoutMath"), exports);
+__exportStar(require("./exerciseRecord/recordValidator"), exports);
 __exportStar(require("./metricConversions"), exports);

package/dist/utils/scoringWorkout/calculateCalories.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Pillar 1: Calorie Burn
+ * ============================================================================
+ *
+ * Estimates energy expenditure (kcal) for an exercise using the MET system.
+ *
+ * Formula (per set):
+ *   calories = effectiveMET × userWeightKg × (activeDurationSecs / 3600)
+ *
+ * Where effectiveMET is the exercise's baseMET adjusted for:
+ *   - Effort level (RPE/RIR → scales within metRange)
+ *   - Weight intensity (for weight-reps: how heavy relative to bodyweight)
+ *   - Duration category (for duration: short/medium/long multiplier)
+ *   - Speed (for cardio: interpolated from pace or speed range)
+ *   - Compound multiplier (multi-joint exercises burn more)
+ *
+ * After summing all sets:
+ *   - Rest calories are added (elevated MET during rest periods)
+ *   - EPOC (afterburn) is added as a percentage of work calories
+ *
+ * References:
+ *   - Ainsworth BE et al. "Compendium of Physical Activities" (2011)
+ *   - Katch, McArdle & Katch, "Exercise Physiology" (8th ed.)
+ */
+import type { IParsedSet, IUserContext } from "./types";
+interface IMetabolicData {
+    baseMET: number;
+    metRange: [number, number];
+    compoundMultiplier: number;
+    muscleGroupFactor: number;
+    intensityScaling: "linear" | "exponential" | "plateau";
+    epocFactor: number;
+    weightFactors?: {
+        lightWeight: number;
+        moderateWeight: number;
+        heavyWeight: number;
+    };
+    durationFactors?: {
+        shortDuration: number;
+        mediumDuration: number;
+        longDuration: number;
+    };
+    paceFactors?: Record<string, number>;
+    lightWeight?: number;
+    moderateWeight?: number;
+    heavyWeight?: number;
+    shortDuration?: number;
+    mediumDuration?: number;
+    longDuration?: number;
+}
+/**
+ * Calculate total calorie burn for an exercise.
+ *
+ * @param sets           Parsed & validated sets (from parseRecords)
+ * @param metabolicData  Exercise's metabolic configuration
+ * @param user           Validated user context
+ * @param difficultyLevel Exercise difficulty (0–4), used for bodyweight estimation
+ * @returns              Total calories burned (kcal), rounded to 1 decimal
+ *
+ * @example
+ * const calories = calculateCalories(parsedSets, exercise.metabolicData, userCtx, exercise.difficultyLevel);
+ * // → 6.4 (for 3 light bench press sets)
+ * // → 142.3 (for a 20-min treadmill run)
+ */
+export declare function calculateCalories(sets: IParsedSet[], metabolicData: IMetabolicData, user: IUserContext, difficultyLevel: number, scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry"): number;
+export {};