@dgpholdings/greatoak-shared 1.2.16 → 1.2.17

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

@@ -0,0 +1,97 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Record Parser
+ * ============================================================================
+ *
+ * Transforms raw TRecord[] into clean IParsedSet[].
+ *
+ * This is the SINGLE POINT of data cleaning. After this step, all downstream
+ * code (calories, fatigue, quality) works with guaranteed-valid numbers.
+ *
+ * VALIDATION STRATEGY:
+ * The exercise's `timingGuardrails` is the PRIMARY source of truth for
+ * what constitutes valid timing data. Each exercise defines its own:
+ *   - restPeriods.minimum / maximum  → acceptable rest range
+ *   - setDuration.min / max          → acceptable work duration (duration type)
+ *   - singleRep.min / max            → acceptable rep timing (rep-based types)
+ *
+ * Global constants (ABSOLUTE_* and FALLBACK_*) are ONLY used when
+ * timingGuardrails is completely missing from the exercise.
+ *
+ * Responsibilities:
+ * 1. Filter out incomplete sets (isDone === false)
+ * 2. Parse all string fields to numbers
+ * 3. Estimate active work duration when not measured
+ * 4. Validate timing against exercise-specific guardrails
+ * 5. Compute effort fraction per set
+ */
+import type { IParsedSet } from "./types";
+/**
+ * Minimal shape of TRecord that we need. Avoids importing the full
+ * app type, making the scoring module independently testable.
+ */
+interface IRawRecord {
+    type: string;
+    isDone: boolean;
+    isStrictMode: boolean;
+    rpe?: string;
+    rir?: string;
+    workDurationSecs?: number;
+    restDurationSecs?: number;
+    kg?: string;
+    reps?: string;
+    durationMmSs?: string;
+    auxWeightKg?: string;
+    speedMin?: string;
+    speedMax?: string;
+    distance?: string;
+}
+/**
+ * Full timing guardrails shape from TExercise.
+ *
+ * Every field is optional because:
+ * - Different exercise types have different sub-shapes (singleRep vs setDuration)
+ * - Some exercises might have incomplete guardrails
+ * - We need graceful fallback for each missing piece
+ */
+export interface ITimingGuardrails {
+    type?: string;
+    stressRestBonus?: number;
+    fatigueMultiplier?: number;
+    setupTypicalSecs?: number;
+    restPeriods?: {
+        minimum?: number;
+        typical?: number;
+        maximum?: number;
+        optimalRange?: [number, number];
+    };
+    singleRep?: {
+        min?: number;
+        max?: number;
+        typical?: number;
+    };
+    setDuration?: {
+        min?: number;
+        max?: number;
+        typical?: number;
+    };
+    pacing?: {
+        minPacePerUnit?: number;
+        maxPacePerUnit?: number;
+        typicalPacePerUnit?: number;
+    };
+}
+/**
+ * Parse and clean raw records into a validated set array.
+ *
+ * @param records           Raw TRecord[] from the workout
+ * @param timingGuardrails  Exercise's timing guardrails (for validation & fallbacks)
+ * @returns                 Cleaned IParsedSet[] with only completed, valid sets
+ *
+ * @example
+ * const parsed = parseRecords(workout.records, exercise.timingGuardrails);
+ * // parsed[0].activeDurationSecs → guaranteed valid number
+ * // parsed[0].effortFraction     → guaranteed 0.5–1.3
+ */
+export declare function parseRecords(records: IRawRecord[], timingGuardrails?: ITimingGuardrails): IParsedSet[];
+export {};

package/dist/utils/scoring/parseRecords.js

@@ -0,0 +1,280 @@
+"use strict";
+// parseRecords.ts
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Record Parser
+ * ============================================================================
+ *
+ * Transforms raw TRecord[] into clean IParsedSet[].
+ *
+ * This is the SINGLE POINT of data cleaning. After this step, all downstream
+ * code (calories, fatigue, quality) works with guaranteed-valid numbers.
+ *
+ * VALIDATION STRATEGY:
+ * The exercise's `timingGuardrails` is the PRIMARY source of truth for
+ * what constitutes valid timing data. Each exercise defines its own:
+ *   - restPeriods.minimum / maximum  → acceptable rest range
+ *   - setDuration.min / max          → acceptable work duration (duration type)
+ *   - singleRep.min / max            → acceptable rep timing (rep-based types)
+ *
+ * Global constants (ABSOLUTE_* and FALLBACK_*) are ONLY used when
+ * timingGuardrails is completely missing from the exercise.
+ *
+ * Responsibilities:
+ * 1. Filter out incomplete sets (isDone === false)
+ * 2. Parse all string fields to numbers
+ * 3. Estimate active work duration when not measured
+ * 4. Validate timing against exercise-specific guardrails
+ * 5. Compute effort fraction per set
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRecords = parseRecords;
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+// ---------------------------------------------------------------------------
+// Main Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse and clean raw records into a validated set array.
+ *
+ * @param records           Raw TRecord[] from the workout
+ * @param timingGuardrails  Exercise's timing guardrails (for validation & fallbacks)
+ * @returns                 Cleaned IParsedSet[] with only completed, valid sets
+ *
+ * @example
+ * const parsed = parseRecords(workout.records, exercise.timingGuardrails);
+ * // parsed[0].activeDurationSecs → guaranteed valid number
+ * // parsed[0].effortFraction     → guaranteed 0.5–1.3
+ */
+function parseRecords(records, timingGuardrails) {
+    return records
+        .filter((r) => r.isDone) // Only completed sets count
+        .map((record, index) => parseOneRecord(record, index, records.length, timingGuardrails))
+        .filter((set) => set !== null);
+}
+// ---------------------------------------------------------------------------
+// Single Record Parser
+// ---------------------------------------------------------------------------
+function parseOneRecord(record, index, totalSets, guardrails) {
+    const type = record.type;
+    const effortFraction = (0, helpers_1.getEffortFraction)(record);
+    // Parse rest duration using exercise-specific guardrails for validation
+    const restDurationSecs = resolveRestDuration(record.restDurationSecs, index, totalSets, guardrails);
+    switch (type) {
+        case "weight-reps":
+            return parseWeightReps(record, effortFraction, restDurationSecs, guardrails);
+        case "reps-only":
+            return parseRepsOnly(record, effortFraction, restDurationSecs, guardrails);
+        case "duration":
+            return parseDuration(record, effortFraction, restDurationSecs, guardrails);
+        case "cardio-machine":
+            return parseCardioMachine(record, effortFraction, restDurationSecs);
+        case "cardio-free":
+            return parseCardioFree(record, effortFraction, restDurationSecs);
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type-Specific Parsers
+// ---------------------------------------------------------------------------
+function parseWeightReps(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b;
+    const kg = (0, helpers_1.safeParseFloat)(record.kg);
+    const reps = (0, helpers_1.safeParseFloat)(record.reps);
+    // Skip sets with zero reps (likely user error / empty row)
+    if (reps === 0)
+        return null;
+    // Estimate active duration: reps × seconds-per-rep
+    // PRIMARY: exercise's own singleRep.typical
+    // FALLBACK: global default
+    const secsPerRep = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SECS_PER_REP;
+    const estimatedDuration = reps * secsPerRep;
+    const activeDurationSecs = resolveWorkDuration(record.workDurationSecs, estimatedDuration, guardrails);
+    return {
+        type: "weight-reps",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        kg,
+        reps,
+    };
+}
+function parseRepsOnly(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b;
+    const reps = (0, helpers_1.safeParseFloat)(record.reps);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
+    if (reps === 0)
+        return null;
+    const secsPerRep = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SECS_PER_REP;
+    const estimatedDuration = reps * secsPerRep;
+    const activeDurationSecs = resolveWorkDuration(record.workDurationSecs, estimatedDuration, guardrails);
+    return {
+        type: "reps-only",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        reps,
+        auxWeightKg,
+    };
+}
+function parseDuration(record, effortFraction, restDurationSecs, guardrails) {
+    var _a, _b;
+    // Primary: parse the user's recorded duration
+    // Fallback: exercise's typical set duration → global fallback
+    const fallbackDuration = (_b = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.setDuration) === null || _a === void 0 ? void 0 : _a.typical) !== null && _b !== void 0 ? _b : constants_1.FALLBACK_SET_DURATION_SECS;
+    const durationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs, fallbackDuration);
+    const auxWeightKg = (0, helpers_1.safeParseFloat)(record.auxWeightKg);
+    if (durationSecs === 0)
+        return null;
+    // For duration exercises, the parsed durationMmSs IS the active duration
+    // We validate it against guardrails to get the final value
+    const activeDurationSecs = resolveWorkDuration(durationSecs, fallbackDuration, guardrails);
+    return {
+        type: "duration",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        // Use the SAME validated value for both — activeDurationSecs is used
+        // for calorie time calculation, durationSecs is used for the
+        // short/medium/long multiplier classification. They must agree.
+        durationSecs: activeDurationSecs,
+        auxWeightKg,
+    };
+}
+function parseCardioMachine(record, effortFraction, restDurationSecs) {
+    const speedMin = (0, helpers_1.safeParseFloat)(record.speedMin);
+    const speedMax = (0, helpers_1.safeParseFloat)(record.speedMax);
+    const distance = (0, helpers_1.safeParseFloat)(record.distance);
+    const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
+    // Need at least duration or distance to be meaningful
+    if (cardioDurationSecs === 0 && distance === 0)
+        return null;
+    const activeDurationSecs = cardioDurationSecs > 0 ? cardioDurationSecs : 0;
+    return {
+        type: "cardio-machine",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        speedMin,
+        speedMax,
+        distance,
+        cardioDurationSecs,
+    };
+}
+function parseCardioFree(record, effortFraction, restDurationSecs) {
+    const distance = (0, helpers_1.safeParseFloat)(record.distance);
+    const cardioDurationSecs = (0, helpers_1.parseDurationMmSs)(record.durationMmSs);
+    if (cardioDurationSecs === 0 && distance === 0)
+        return null;
+    const activeDurationSecs = cardioDurationSecs > 0 ? cardioDurationSecs : 0;
+    return {
+        type: "cardio-free",
+        activeDurationSecs,
+        restDurationSecs,
+        effortFraction,
+        distance,
+        cardioDurationSecs,
+    };
+}
+// ---------------------------------------------------------------------------
+// Duration Resolution Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve and validate work duration for a set.
+ *
+ * Validation cascade:
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │ 1. Absolute sanity check (catches truly broken data)        │
+ * │    measured < 1s or > 14400s → reject                       │
+ * │                                                             │
+ * │ 2. Exercise-specific validation (PRIMARY)                   │
+ * │    duration type: check against setDuration.min / max       │
+ * │    rep type: check against estimate ± tolerance             │
+ * │    Grace factor: 2× on max, 0.5× on min                    │
+ * │                                                             │
+ * │ 3. Passed all checks → use measured value                   │
+ * │                                                             │
+ * │ 4. No measured value → use estimated                        │
+ * └──────────────────────────────────────────────────────────────┘
+ */
+function resolveWorkDuration(measured, estimated, guardrails) {
+    var _a, _b;
+    if (measured !== undefined && measured > 0) {
+        // 1. Absolute sanity check
+        if (measured < constants_1.ABSOLUTE_WORK_MIN || measured > constants_1.ABSOLUTE_WORK_MAX) {
+            return Math.max(estimated, constants_1.ABSOLUTE_WORK_MIN);
+        }
+        // 2. Exercise-specific validation for duration-type exercises
+        if (guardrails === null || guardrails === void 0 ? void 0 : guardrails.setDuration) {
+            const minReasonable = ((_a = guardrails.setDuration.min) !== null && _a !== void 0 ? _a : 1) * 0.5;
+            const maxReasonable = ((_b = guardrails.setDuration.max) !== null && _b !== void 0 ? _b : constants_1.ABSOLUTE_WORK_MAX) * 2;
+            if (measured < minReasonable || measured > maxReasonable) {
+                return estimated; // Measured seems wrong for this exercise
+            }
+        }
+        // 2b. Exercise-specific validation for rep-based exercises
+        if ((guardrails === null || guardrails === void 0 ? void 0 : guardrails.singleRep) && estimated > 0) {
+            // Measured should be within 3× of our estimate
+            // (generous because user might pause mid-set)
+            if (measured > estimated * 3 || measured < estimated * 0.2) {
+                return estimated;
+            }
+        }
+        // 3. Passed validation
+        return measured;
+    }
+    // 4. No measured value
+    return Math.max(estimated, constants_1.ABSOLUTE_WORK_MIN);
+}
+/**
+ * Resolve and validate rest duration for a set.
+ *
+ * Validation cascade:
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │ 1. Last set with no data → null (no rest after final set)   │
+ * │                                                             │
+ * │ 2. Absolute sanity check (< 0 or > 3600s)                  │
+ * │    → use exercise typical rest                              │
+ * │                                                             │
+ * │ 3. Exercise-specific validation (PRIMARY)                   │
+ * │    Check against restPeriods.minimum / maximum              │
+ * │    Grace factor: 50% on each side                           │
+ * │    Outside → use exercise typical rest                      │
+ * │                                                             │
+ * │ 4. Passed checks → use measured value                       │
+ * │                                                             │
+ * │ 5. No measured data → exercise typical → global fallback    │
+ * └──────────────────────────────────────────────────────────────┘
+ */
+function resolveRestDuration(measured, setIndex, totalSets, guardrails) {
+    var _a, _b, _c;
+    // 1. Last set with no rest data → null
+    if (setIndex === totalSets - 1 &&
+        (measured === undefined || measured === 0)) {
+        return null;
+    }
+    // Extract exercise-specific rest config
+    const exerciseRestMin = (_a = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _a === void 0 ? void 0 : _a.minimum;
+    const exerciseRestMax = (_b = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _b === void 0 ? void 0 : _b.maximum;
+    const exerciseRestTypical = (_c = guardrails === null || guardrails === void 0 ? void 0 : guardrails.restPeriods) === null || _c === void 0 ? void 0 : _c.typical;
+    if (measured !== undefined && measured > 0) {
+        // 2. Absolute sanity check
+        if (measured < constants_1.ABSOLUTE_REST_MIN || measured > constants_1.ABSOLUTE_REST_MAX) {
+            return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+        }
+        // 3. Exercise-specific validation
+        if (exerciseRestMin !== undefined && exerciseRestMax !== undefined) {
+            const graceFactor = 0.5;
+            const lowerBound = exerciseRestMin * (1 - graceFactor);
+            const upperBound = exerciseRestMax * (1 + graceFactor);
+            if (measured < lowerBound || measured > upperBound) {
+                return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+            }
+        }
+        // 4. Passed validation
+        return measured;
+    }
+    // 5. No measured data → exercise typical → global fallback
+    return exerciseRestTypical !== null && exerciseRestTypical !== void 0 ? exerciseRestTypical : constants_1.FALLBACK_REST_SECS;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Types & Interfaces
+ * ============================================================================
+ *
+ * Central type definitions for the scoring algorithm.
+ * This file defines the output shape and internal types used across all three
+ * scoring pillars (Calories, Muscle Fatigue, Quality).
+ */
+import { TGender, TRecord } from "../../types";
+/**
+ * Quality score breakdown — lets the UI show users WHY they got their score.
+ * Each sub-score is 0–100.
+ */
+export interface IQualityBreakdown {
+    /** Did the user complete all sets? */
+    completion: number;
+    /** Were sets consistent in output (or intentionally progressive)? */
+    consistency: number;
+    /** Was effort in the productive RPE/RIR zone? */
+    effortAdequacy: number;
+    /** Were rest periods within the exercise's optimal range? */
+    restDiscipline: number;
+}
+/**
+ * The final result returned by calculateExerciseScore.
+ *
+ * - score:           0–100 overall quality of execution
+ * - muscleScores:    per-muscle fatigue map (keyed by EBodyParts key, value 0–100)
+ * - calorieBurn:     estimated kilocalories burned (gross, including EPOC)
+ * - qualityBreakdown: transparent sub-scores for the UI
+ */
+export interface IScoreResult {
+    score: number;
+    muscleScores: Record<string, number>;
+    calorieBurn: number;
+    qualityBreakdown: IQualityBreakdown;
+}
+/**
+ * A cleaned, parsed version of a single TRecord.
+ * All string fields are parsed to numbers, unreliable timings are replaced
+ * with fallbacks, and skipped sets are filtered out before this stage.
+ *
+ * This is the ONLY representation the scoring pillars work with — they never
+ * touch raw TRecord directly.
+ */
+export interface IParsedSet {
+    type: TRecord["type"];
+    /** Active work duration for this set in seconds (estimated or measured) */
+    activeDurationSecs: number;
+    /** Rest duration after this set in seconds (validated or fallback) */
+    restDurationSecs: number | null;
+    /**
+     * Effort fraction: 0.0 (no effort) to 1.0 (max effort).
+     * Derived from RPE, RIR, or fallback (0.6).
+     */
+    effortFraction: number;
+    /** weight-reps: weight in kg */
+    kg?: number;
+    /** weight-reps / reps-only: rep count */
+    reps?: number;
+    /** reps-only / duration: auxiliary weight in kg */
+    auxWeightKg?: number;
+    /** duration: hold time in seconds */
+    durationSecs?: number;
+    /** cardio-machine: min speed */
+    speedMin?: number;
+    /** cardio-machine: max speed */
+    speedMax?: number;
+    /** cardio-machine / cardio-free: distance (km) */
+    distance?: number;
+    /** cardio-free / cardio-machine: session duration in seconds */
+    cardioDurationSecs?: number;
+}
+/**
+ * Validated user context with guaranteed fallbacks.
+ * No optional fields — everything has a sensible default.
+ */
+export interface IUserContext {
+    weightKg: number;
+    heightCm: number;
+    gender: TGender;
+    age: number;
+}

package/dist/utils/scoring/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * ============================================================================
+ * FITFRIX EXERCISE SCORING SYSTEM — Types & Interfaces
+ * ============================================================================
+ *
+ * Central type definitions for the scoring algorithm.
+ * This file defines the output shape and internal types used across all three
+ * scoring pillars (Calories, Muscle Fatigue, Quality).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dgpholdings/greatoak-shared",
-	"version": "1.2.16",
+	"version": "1.2.17",
 	"description": "Shared TypeScript types and utilities for @dgpholdings projects",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",