@dgpholdings/greatoak-shared 1.2.86 → 1.2.87

package/dist/utils/scoring/calculateCalories.js

@@ -1,345 +0,0 @@
-"use strict";
-// calculateCalories.ts
-/**
- * ============================================================================
- * 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.)
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateCalories = calculateCalories;
-const constants_1 = require("./constants");
-const helpers_1 = require("./helpers");
-// ---------------------------------------------------------------------------
-// Main Calorie Calculation
-// ---------------------------------------------------------------------------
-/**
- * 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)
- */
-function calculateCalories(sets, metabolicData, user, difficultyLevel, scoringSpecialHandling) {
-    if (sets.length === 0)
-        return 0;
-    // Stretch/mobility: no meaningful work calories — only passive rest MET applies
-    if (scoringSpecialHandling === "stretch-mobility") {
-        const totalRestSecs = sets.reduce((sum, s) => { var _a; return sum + ((_a = s.restDurationSecs) !== null && _a !== void 0 ? _a : 0); }, 0);
-        return Math.round(constants_1.REST_MET * user.weightKg * (totalRestSecs / 3600) * 10) / 10;
-    }
-    // Normalize metRange so [0] = min, [1] = max (sample data has them reversed)
-    const [metMin, metMax] = normalizeMetRange(metabolicData.metRange, metabolicData.baseMET);
-    let totalWorkCalories = 0;
-    let totalRestCalories = 0;
-    for (const set of sets) {
-        // 1. Calculate effective MET for this set
-        const effectiveMET = calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel, scoringSpecialHandling);
-        // 2. Work calories: MET × weight × time
-        const workHours = set.activeDurationSecs / 3600;
-        totalWorkCalories += effectiveMET * user.weightKg * workHours;
-        // 3. Rest calories: elevated resting MET during recovery
-        if (set.restDurationSecs !== null && set.restDurationSecs > 0) {
-            const restHours = set.restDurationSecs / 3600;
-            totalRestCalories += constants_1.REST_MET * user.weightKg * restHours;
-        }
-    }
-    // 4. EPOC (Excess Post-exercise Oxygen Consumption) — afterburn effect
-    const epocCalories = totalWorkCalories * metabolicData.epocFactor;
-    // 5. Total = work + rest + afterburn
-    const total = totalWorkCalories + totalRestCalories + epocCalories;
-    return Math.round(total * 10) / 10; // Round to 1 decimal place
-}
-// ---------------------------------------------------------------------------
-// Effective MET Calculation (per set)
-// ---------------------------------------------------------------------------
-/**
- * Calculate the effective MET for a single set based on its type and intensity.
- *
- * The general approach:
- *   1. Interpolate base MET within [metMin, metMax] using effort fraction
- *   2. Apply type-specific intensity multiplier
- *   3. Apply compound multiplier
- *
- * The effort fraction (from RPE/RIR) determines WHERE in the MET range
- * this set falls. Low effort → closer to metMin, high effort → closer to metMax.
- */
-function calculateEffectiveMET(set, metabolicData, metMin, metMax, user, difficultyLevel, scoringSpecialHandling) {
-    var _a, _b, _c, _d, _e;
-    // Start with effort-scaled MET
-    // effortFraction is 0.5–1.3 (from helpers), we normalize to 0–1 for interpolation
-    const effortNormalized = (0, helpers_1.clamp)((set.effortFraction - 0.5) / 0.8, 0, 1);
-    let met = metMin + (metMax - metMin) * effortNormalized;
-    // Continuous-duration (battle ropes, high knees, jump rope): these behave like
-    // cardio metabolically — bypass the static-hold duration formula entirely
-    if (scoringSpecialHandling === "continuous-duration") {
-        met = metMin + (metMax - metMin) * effortNormalized;
-        met *= metabolicData.compoundMultiplier;
-        return (0, helpers_1.clamp)(met, 1, 25);
-    }
-    // Apply type-specific intensity scaling
-    switch (set.type) {
-        case "weight-reps":
-            met *= getWeightMultiplier((_a = set.kg) !== null && _a !== void 0 ? _a : 0, user.weightKg, metabolicData);
-            break;
-        case "reps-only":
-            met *= getRepsOnlyMultiplier((_b = set.auxWeightKg) !== null && _b !== void 0 ? _b : 0, user.weightKg, difficultyLevel);
-            break;
-        case "duration":
-            met *= getDurationMultiplier((_c = set.durationSecs) !== null && _c !== void 0 ? _c : 0, (_d = set.auxWeightKg) !== null && _d !== void 0 ? _d : 0, user.weightKg, metabolicData);
-            break;
-        case "cardio-machine":
-            met = getCardioMachineMET(set, metabolicData, metMin, metMax, effortNormalized);
-            break;
-        case "cardio-free":
-            met = getCardioFreeMET(set, metabolicData, metMin, metMax, effortNormalized);
-            // Loaded carry: scale MET up by the weight being carried relative to bodyweight
-            if (scoringSpecialHandling === "loaded-carry") {
-                const auxWeightKg = (_e = set.auxWeightKg) !== null && _e !== void 0 ? _e : 0;
-                if (auxWeightKg > 0) {
-                    met *= 1 + (auxWeightKg / user.weightKg) * constants_1.LOADED_CARRY_WEIGHT_MET_SCALE;
-                }
-            }
-            break;
-    }
-    // Apply compound multiplier (multi-joint exercises have higher energy cost)
-    met *= metabolicData.compoundMultiplier;
-    // Safety clamp: MET should never go below 1 or above 25
-    return (0, helpers_1.clamp)(met, 1, 25);
-}
-// ---------------------------------------------------------------------------
-// Type-Specific Multipliers
-// ---------------------------------------------------------------------------
-/**
- * Weight multiplier for weight-reps exercises.
- *
- * Classifies the weight as light/moderate/heavy relative to bodyweight
- * and returns the corresponding multiplier.
- *
- * Example: 10kg at 75kg bodyweight → ratio 0.13 → "light" → 0.8 multiplier
- */
-function getWeightMultiplier(kg, userWeightKg, metabolicData) {
-    const ratio = kg / userWeightKg;
-    // Resolve weight factors (handle both nested and flat shapes)
-    const factors = resolveWeightFactors(metabolicData);
-    if (ratio < constants_1.WEIGHT_CATEGORY_THRESHOLDS.lightMax) {
-        return factors.light;
-    }
-    else if (ratio < constants_1.WEIGHT_CATEGORY_THRESHOLDS.moderateMax) {
-        return factors.moderate;
-    }
-    else {
-        return factors.heavy;
-    }
-}
-/**
- * Multiplier for reps-only (bodyweight) exercises.
- *
- * The "load" is the user's bodyweight (scaled by difficulty) + any aux weight.
- * We return a gentle multiplier that boosts MET slightly for added weight.
- *
- * Example: Push-up (difficulty 1) with 2.5kg vest at 75kg bodyweight
- *   bodyweightLoad = (1/4) × 0.65 × 75 = 12.19 kg equivalent
- *   totalLoad = 12.19 + 2.5 = 14.69
- *   ratio = 14.69 / 75 = 0.196
- *   multiplier = 1.0 + 0.196 × 0.5 = 1.098
- */
-function getRepsOnlyMultiplier(auxWeightKg, userWeightKg, difficultyLevel) {
-    const bodyweightLoad = (difficultyLevel / 4) * constants_1.BW_FRACTION_SCALE * userWeightKg;
-    const totalLoad = bodyweightLoad + auxWeightKg;
-    const ratio = totalLoad / userWeightKg;
-    // Gentle scaling: aux weight adds intensity but not dramatically
-    return 1.0 + ratio * 0.5;
-}
-/**
- * Multiplier for duration (isometric/hold) exercises.
- *
- * Two factors:
- * 1. Duration category (short/medium/long) — longer holds are metabolically harder
- * 2. Aux weight boost — holding weight during a plank increases energy cost
- */
-function getDurationMultiplier(durationSecs, auxWeightKg, userWeightKg, metabolicData) {
-    // Resolve duration factors (handle both nested and flat shapes)
-    const factors = resolveDurationFactors(metabolicData);
-    let durationMultiplier;
-    if (durationSecs < constants_1.DURATION_CATEGORY_THRESHOLDS.shortMax) {
-        durationMultiplier = factors.short;
-    }
-    else if (durationSecs <= constants_1.DURATION_CATEGORY_THRESHOLDS.mediumMax) {
-        durationMultiplier = factors.medium;
-    }
-    else {
-        durationMultiplier = factors.long;
-    }
-    // Aux weight boosts MET (holding a plate during plank, weighted vest, etc.)
-    const auxBoost = 1.0 + (auxWeightKg / userWeightKg) * 0.3;
-    return durationMultiplier * auxBoost;
-}
-/**
- * MET calculation for cardio-machine exercises (treadmill, stationary bike, etc.)
- *
- * Uses average speed to interpolate within the MET range.
- * If paceFactors are available, we interpolate from the pace table instead.
- */
-function getCardioMachineMET(set, metabolicData, metMin, metMax, effortNormalized) {
-    var _a;
-    // Average speed from the set data
-    const avgSpeed = (_a = set.speed) !== null && _a !== void 0 ? _a : 0;
-    if (avgSpeed > 0) {
-        // If we have pace factors, use them for more accurate MET lookup
-        if (metabolicData.paceFactors) {
-            return interpolatePaceFactors(avgSpeed, metabolicData.paceFactors);
-        }
-        // Otherwise, interpolate linearly within metRange based on speed
-        const speedFraction = (0, helpers_1.clamp)((avgSpeed - constants_1.CARDIO_SPEED_RANGE.min) /
-            (constants_1.CARDIO_SPEED_RANGE.max - constants_1.CARDIO_SPEED_RANGE.min), 0, 1);
-        return metMin + (metMax - metMin) * speedFraction;
-    }
-    // No speed data: fall back to effort-based interpolation
-    return metMin + (metMax - metMin) * effortNormalized;
-}
-/**
- * MET calculation for cardio-free exercises (outdoor running, cycling, etc.)
- *
- * Derives speed from distance ÷ time, then interpolates MET.
- */
-function getCardioFreeMET(set, metabolicData, metMin, metMax, effortNormalized) {
-    var _a, _b;
-    const distance = (_a = set.distance) !== null && _a !== void 0 ? _a : 0;
-    const durationSecs = (_b = set.cardioDurationSecs) !== null && _b !== void 0 ? _b : 0;
-    if (distance > 0 && durationSecs > 0) {
-        // Speed in km/h
-        const speed = distance / (durationSecs / 3600);
-        if (metabolicData.paceFactors) {
-            return interpolatePaceFactors(speed, metabolicData.paceFactors);
-        }
-        const speedFraction = (0, helpers_1.clamp)((speed - constants_1.CARDIO_SPEED_RANGE.min) /
-            (constants_1.CARDIO_SPEED_RANGE.max - constants_1.CARDIO_SPEED_RANGE.min), 0, 1);
-        return metMin + (metMax - metMin) * speedFraction;
-    }
-    // No distance/time data: fall back to effort-based
-    return metMin + (metMax - metMin) * effortNormalized;
-}
-// ---------------------------------------------------------------------------
-// Resolution Helpers (handle flat vs nested metabolicData shapes)
-// ---------------------------------------------------------------------------
-/**
- * Resolve weight factors from metabolicData.
- * Sample data sometimes has them nested under `weightFactors`, sometimes flat.
- */
-function resolveWeightFactors(metabolicData) {
-    var _a, _b;
-    if (metabolicData.weightFactors) {
-        return {
-            light: metabolicData.weightFactors.lightWeight,
-            moderate: metabolicData.weightFactors.moderateWeight,
-            heavy: metabolicData.weightFactors.heavyWeight,
-        };
-    }
-    // Check flat shape
-    if (metabolicData.lightWeight !== undefined) {
-        return {
-            light: metabolicData.lightWeight,
-            moderate: (_a = metabolicData.moderateWeight) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_WEIGHT_FACTORS.moderate,
-            heavy: (_b = metabolicData.heavyWeight) !== null && _b !== void 0 ? _b : constants_1.DEFAULT_WEIGHT_FACTORS.heavy,
-        };
-    }
-    return constants_1.DEFAULT_WEIGHT_FACTORS;
-}
-/**
- * Resolve duration factors from metabolicData.
- * Same flat-vs-nested handling as weight factors.
- */
-function resolveDurationFactors(metabolicData) {
-    var _a, _b;
-    if (metabolicData.durationFactors) {
-        return {
-            short: metabolicData.durationFactors.shortDuration,
-            medium: metabolicData.durationFactors.mediumDuration,
-            long: metabolicData.durationFactors.longDuration,
-        };
-    }
-    // Check flat shape
-    if (metabolicData.shortDuration !== undefined) {
-        return {
-            short: metabolicData.shortDuration,
-            medium: (_a = metabolicData.mediumDuration) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_DURATION_FACTORS.medium,
-            long: (_b = metabolicData.longDuration) !== null && _b !== void 0 ? _b : constants_1.DEFAULT_DURATION_FACTORS.long,
-        };
-    }
-    return constants_1.DEFAULT_DURATION_FACTORS;
-}
-/**
- * Interpolate MET from a pace factors table.
- *
- * paceFactors is a map of speed (km/h) → MET value.
- * We find the two closest speeds and linearly interpolate between them.
- *
- * Example:
- *   paceFactors = { "5.0": 4.3, "8.0": 8.3, "12.0": 11.0, "16.0": 15.0 }
- *   speed = 10 km/h → interpolate between 8.0 (8.3 MET) and 12.0 (11.0 MET)
- *   result ≈ 9.65 MET
- */
-function interpolatePaceFactors(speed, paceFactors) {
-    const entries = Object.keys(paceFactors)
-        .map((k) => [parseFloat(k), paceFactors[k]])
-        .filter(([k]) => !isNaN(k))
-        .sort((a, b) => a[0] - b[0]);
-    if (entries.length === 0)
-        return 3; // fallback moderate MET
-    // Below minimum pace
-    if (speed <= entries[0][0])
-        return entries[0][1];
-    // Above maximum pace
-    if (speed >= entries[entries.length - 1][0])
-        return entries[entries.length - 1][1];
-    // Find surrounding entries and interpolate
-    for (let i = 0; i < entries.length - 1; i++) {
-        const [speedLow, metLow] = entries[i];
-        const [speedHigh, metHigh] = entries[i + 1];
-        if (speed >= speedLow && speed <= speedHigh) {
-            const fraction = (speed - speedLow) / (speedHigh - speedLow);
-            return metLow + (metHigh - metLow) * fraction;
-        }
-    }
-    return entries[entries.length - 1][1]; // shouldn't reach here
-}
-/**
- * Normalize metRange so [0] is always min and [1] is always max.
- * Sample data has metRange as [5, 2] (max first) for some exercises.
- */
-function normalizeMetRange(metRange, baseMET) {
-    const min = Math.min(metRange[0], metRange[1]);
-    const max = Math.max(metRange[0], metRange[1]);
-    // If range seems invalid, create one around baseMET
-    if (min === max || max === 0) {
-        return [baseMET * 0.7, baseMET * 1.5];
-    }
-    return [min, max];
-}

package/dist/utils/scoring/calculateMuscleFatiue.d.ts

@@ -1,67 +0,0 @@
-/**
- * ============================================================================
- * FITFRIX EXERCISE SCORING SYSTEM — Pillar 2: Muscle Fatigue
- * ============================================================================
- *
- * Calculates per-muscle fatigue scores (0–100) for a single exercise.
- *
- * HOW IT WORKS:
- *
- * 1. For each set, compute a "fatigue stimulus" — how much mechanical work
- *    the muscles experienced. This is type-specific:
- *      weight-reps:   kg × reps
- *      reps-only:     (bodyweightLoad + auxWeight) × reps
- *      duration:      durationSecs × (difficultyLevel + 1) × auxBoost
- *      cardio:        durationSecs × speedFactor
- *
- * 2. Multiply by effort (RPE/RIR → 0.5–1.3) and the exercise's
- *    fatigueMultiplier from timingGuardrails.
- *
- * 3. Accumulate across sets with DIMINISHING RETURNS — later sets contribute
- *    less because the muscle is pre-fatigued and can't generate as much force.
- *    Decay: setDecay = 1 / (1 + 0.15 × setIndex)
- *
- * 4. Distribute the accumulated fatigue to muscles:
- *      Primary muscles   → 100% of stimulus
- *      Secondary muscles → 35% of stimulus
- *
- * 5. Normalize to 0–100 using an EXERCISE-AWARE reference maximum.
- *    The reference max is what "5 hard sets of THIS exercise" would produce,
- *    scaled by the exercise's difficultyLevel so bicep curls and squats
- *    get fair scores.
- *
- * IMPORTANT: This function scores ONE exercise. The caller aggregates
- * across exercises for full-workout muscle fatigue maps.
- */
-import type { IParsedSet, IUserContext } from "./types";
-import type { ITimingGuardrails } from "./parseRecords";
-/** Muscle key from EBodyParts (e.g., "pectoralis-major", "quadriceps") */
-type MuscleKey = string;
-/**
- * Minimal exercise metadata needed for fatigue calculation.
- */
-interface IFatigueExerciseData {
-    primaryMuscles: MuscleKey[];
-    secondaryMuscles: MuscleKey[];
-    difficultyLevel: number;
-    metabolicData: {
-        compoundMultiplier: number;
-        muscleGroupFactor: number;
-    };
-    scoringSpecialHandling?: "plyometric" | "stretch-mobility" | "continuous-duration" | "loaded-carry";
-}
-/**
- * Calculate per-muscle fatigue scores for an exercise.
- *
- * @param sets              Parsed & validated sets (from parseRecords)
- * @param exercise          Exercise metadata (muscles, difficulty, metabolic)
- * @param user              Validated user context
- * @param timingGuardrails  For fatigueMultiplier
- * @returns                 Map of muscle key → fatigue score (0–100)
- *
- * @example
- * const fatigue = calculateMuscleFatigue(parsedSets, exercise, userCtx, exercise.timingGuardrails);
- * // → { "pectoralis-major": 24, "pectoralis-minor": 24, "deltoids-anterior": 8, ... }
- */
-export declare function calculateMuscleFatigue(sets: IParsedSet[], exercise: IFatigueExerciseData, user: IUserContext, timingGuardrails?: ITimingGuardrails): Record<string, number>;
-export {};