@aneuhold/be-ts-db-lib 4.2.11 → 4.2.13

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 🔖 [4.2.13] (2026-02-28)
+
+### ✅ Added
+
+- Added `WorkoutExerciseRepository.buildExerciseCTOsForUser()` to build `WorkoutExerciseCTO` objects for all of a user's exercises using parallel MongoDB aggregation pipelines (exercise + equipment + best calibration + best set; last accumulation session + first set).
+- Added `WorkoutMuscleGroupRepository.buildMuscleGroupVolumeCTOsForUser()` to build `WorkoutMuscleGroupVolumeCTO` objects for all of a user's muscle groups using a volume aggregation pipeline across completed mesocycles.
+
+### 🏗️ Changed
+
+- Updated dependencies: now requires `@aneuhold/be-ts-lib@^3.1.0`, `@aneuhold/core-ts-db-lib@^4.1.12`, and `@aneuhold/core-ts-lib@^2.4.1`.
+
+## 🔖 [4.2.12] (2026-02-23)
+
+### 🏗️ Changed
+
+- Updated dependencies: now requires `@aneuhold/be-ts-lib@^3.0.22` and `@aneuhold/core-ts-db-lib@^4.1.11`.
+
 ## 🔖 [4.2.11] (2026-02-23)
 
 ### 🏗️ Changed
@@ -285,6 +302,8 @@ Updated dependencies: now requires `@aneuhold/core-ts-db-lib@^3.0.0`, `@aneuhold
 
 <!-- Link References -->
 
+[4.2.13]: https://github.com/aneuhold/ts-libs/compare/be-ts-db-lib-v4.2.12...be-ts-db-lib-v4.2.13
+[4.2.12]: https://github.com/aneuhold/ts-libs/compare/be-ts-db-lib-v4.2.11...be-ts-db-lib-v4.2.12
 [4.2.11]: https://github.com/aneuhold/ts-libs/compare/be-ts-db-lib-v4.2.10...be-ts-db-lib-v4.2.11
 [4.2.10]: https://github.com/aneuhold/ts-libs/compare/be-ts-db-lib-v4.2.9...be-ts-db-lib-v4.2.10
 [4.2.9]: https://github.com/aneuhold/ts-libs/compare/be-ts-db-lib-v4.2.8...be-ts-db-lib-v4.2.9

package/lib/repositories/workout/WorkoutExerciseRepository.d.ts

@@ -1,4 +1,5 @@
-import type { User, WorkoutExercise } from '@aneuhold/core-ts-db-lib';
+import type { User, WorkoutExercise, WorkoutExerciseCTO } from '@aneuhold/core-ts-db-lib';
+import type { UUID } from 'crypto';
 import type { RepoListeners } from '../../services/RepoSubscriptionService.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
 /**
@@ -10,5 +11,14 @@ export default class WorkoutExerciseRepository extends WorkoutBaseWithUserIdRepo
     static getListenersForUserRepo(): RepoListeners<User>;
     protected setupSubscribers(): void;
     static getRepo(): WorkoutExerciseRepository;
+    /**
+     * Builds {@link WorkoutExerciseCTO} objects for all exercises belonging to a user.
+     * Uses two parallel MongoDB aggregation pipelines:
+     * - Pipeline A: exercise + equipmentType + bestCalibration + bestSet
+     * - Pipeline B: lastSessionExercise + lastFirstSet (from most recent non-deload session)
+     *
+     * @param userId The user whose exercise CTOs to build.
+     */
+    buildExerciseCTOsForUser(userId: UUID): Promise<WorkoutExerciseCTO[]>;
 }
 //# sourceMappingURL=WorkoutExerciseRepository.d.ts.map

package/lib/repositories/workout/WorkoutExerciseRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutExerciseRepository.d.ts","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutExerciseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AAGnF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,yBAA0B,SAAQ,+BAA+B,CAAC,eAAe,CAAC;IACrG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAA4B;IAE7D,OAAO;IAIP,MAAM,CAAC,uBAAuB,IAAI,aAAa,CAAC,IAAI,CAAC;IAYrD,SAAS,CAAC,gBAAgB,IAAI,IAAI;WAIpB,OAAO,IAAI,yBAAyB;CAMnD"}
+{"version":3,"file":"WorkoutExerciseRepository.d.ts","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutExerciseRepository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EAEJ,eAAe,EAEf,kBAAkB,EAGnB,MAAM,0BAA0B,CAAC;AAWlC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AAGnF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,yBAA0B,SAAQ,+BAA+B,CAAC,eAAe,CAAC;IACrG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAA4B;IAE7D,OAAO;IAIP,MAAM,CAAC,uBAAuB,IAAI,aAAa,CAAC,IAAI,CAAC;IAYrD,SAAS,CAAC,gBAAgB,IAAI,IAAI;WAIpB,OAAO,IAAI,yBAAyB;IAOlD;;;;;;;OAOG;IACG,wBAAwB,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;CA0M5E"}

package/lib/repositories/workout/WorkoutExerciseRepository.js

@@ -1,4 +1,4 @@
-import { WorkoutExercise_docType } from '@aneuhold/core-ts-db-lib';
+import { WorkoutEquipmentType_docType, WorkoutExercise_docType, WorkoutExerciseCalibration_docType, WorkoutExerciseCalibrationService, WorkoutExerciseCTOSchema, WorkoutSession_docType, WorkoutSessionExercise_docType, WorkoutSet_docType } from '@aneuhold/core-ts-db-lib';
 import WorkoutExerciseValidator from '../../validators/workout/ExerciseValidator.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
 import WorkoutExerciseCalibrationRepository from './WorkoutExerciseCalibrationRepository.js';
@@ -30,5 +30,185 @@ export default class WorkoutExerciseRepository extends WorkoutBaseWithUserIdRepo
         }
         return WorkoutExerciseRepository.singletonInstance;
     }
+    /**
+     * Builds {@link WorkoutExerciseCTO} objects for all exercises belonging to a user.
+     * Uses two parallel MongoDB aggregation pipelines:
+     * - Pipeline A: exercise + equipmentType + bestCalibration + bestSet
+     * - Pipeline B: lastSessionExercise + lastFirstSet (from most recent non-deload session)
+     *
+     * @param userId The user whose exercise CTOs to build.
+     */
+    async buildExerciseCTOsForUser(userId) {
+        const collection = await this.getCollection();
+        const collName = this.collectionName;
+        // Pipeline A: Exercise base + equipmentType + bestCalibration + bestSet
+        const pipelineAPromise = collection
+            .aggregate([
+            // Start with all exercises for this user
+            { $match: { docType: WorkoutExercise_docType, userId } },
+            // Join equipment type by workoutEquipmentTypeId
+            {
+                $lookup: {
+                    from: collName,
+                    let: { equipId: '$workoutEquipmentTypeId' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$_id', '$$equipId'] },
+                                docType: WorkoutEquipmentType_docType
+                            }
+                        }
+                    ],
+                    as: '_equipArr'
+                }
+            },
+            // Find the best calibration by highest estimated 1RM
+            {
+                $lookup: {
+                    from: collName,
+                    let: { exId: '$_id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutExerciseId', '$$exId'] },
+                                docType: WorkoutExerciseCalibration_docType
+                            }
+                        },
+                        {
+                            $addFields: {
+                                _1rm: WorkoutExerciseCalibrationService.get1RMMongoExpr('$weight', '$reps')
+                            }
+                        },
+                        { $sort: { _1rm: -1 } },
+                        { $limit: 1 },
+                        { $project: { _1rm: 0 } }
+                    ],
+                    as: '_bestCalArr'
+                }
+            },
+            // Find the best completed set by highest estimated 1RM
+            {
+                $lookup: {
+                    from: collName,
+                    let: { exId: '$_id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutExerciseId', '$$exId'] },
+                                docType: WorkoutSet_docType,
+                                actualWeight: { $ne: null },
+                                actualReps: { $ne: null }
+                            }
+                        },
+                        {
+                            $addFields: {
+                                _1rm: WorkoutExerciseCalibrationService.get1RMMongoExpr('$actualWeight', '$actualReps')
+                            }
+                        },
+                        { $sort: { _1rm: -1 } },
+                        { $limit: 1 },
+                        { $project: { _1rm: 0 } }
+                    ],
+                    as: '_bestSetArr'
+                }
+            }
+        ])
+            .toArray();
+        // Pipeline B: lastSessionExercise + lastFirstSet per exercise
+        const pipelineBPromise = collection
+            .aggregate([
+            // Start with all completed sessions for this user
+            { $match: { docType: WorkoutSession_docType, userId, complete: true } },
+            // Most recent sessions first
+            { $sort: { startTime: -1 } },
+            // Join each session's session exercises
+            {
+                $lookup: {
+                    from: collName,
+                    let: { sessId: '$_id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutSessionId', '$$sessId'] },
+                                docType: WorkoutSessionExercise_docType
+                            }
+                        }
+                    ],
+                    as: '_se'
+                }
+            },
+            // One row per session exercise (unwind coalescence optimization)
+            { $unwind: '$_se' },
+            // Check for non-deload sets (plannedRir is not null)
+            {
+                $lookup: {
+                    from: collName,
+                    let: { seId: '$_se._id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutSessionExerciseId', '$$seId'] },
+                                docType: WorkoutSet_docType,
+                                plannedRir: { $ne: null }
+                            }
+                        },
+                        { $limit: 1 }
+                    ],
+                    as: '_nonDeload'
+                }
+            },
+            // Keep only session exercises with at least one non-deload set
+            { $match: { '_nonDeload.0': { $exists: true } } },
+            // Per exercise, keep only the most recent session exercise ($first after sort)
+            {
+                $group: {
+                    _id: '$_se.workoutExerciseId',
+                    lastSessionExercise: { $first: '$_se' }
+                }
+            },
+            // Join the first set from that session exercise's setOrder
+            {
+                $lookup: {
+                    from: collName,
+                    let: { firstSetId: { $arrayElemAt: ['$lastSessionExercise.setOrder', 0] } },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$_id', '$$firstSetId'] },
+                                docType: WorkoutSet_docType
+                            }
+                        }
+                    ],
+                    as: '_lastFirstSetArr'
+                }
+            }
+        ])
+            .toArray();
+        const [rawExercises, rawLastSessions] = await Promise.all([pipelineAPromise, pipelineBPromise]);
+        // Build lookup map from Pipeline B
+        const lastSessionMap = new Map();
+        for (const row of rawLastSessions) {
+            lastSessionMap.set(row._id, {
+                lastSessionExercise: row.lastSessionExercise,
+                lastFirstSet: row._lastFirstSetArr[0] ?? null
+            });
+        }
+        // Assemble and validate CTOs
+        return rawExercises.map((raw) => {
+            const { _equipArr, _bestCalArr, _bestSetArr, ...exerciseFields } = raw;
+            if (_equipArr.length === 0) {
+                throw new Error(`Equipment type not found for exercise ${raw._id}`);
+            }
+            const lastData = lastSessionMap.get(raw._id);
+            return WorkoutExerciseCTOSchema.parse({
+                ...exerciseFields,
+                equipmentType: _equipArr[0],
+                bestCalibration: _bestCalArr[0] ?? null,
+                bestSet: _bestSetArr[0] ?? null,
+                lastSessionExercise: lastData?.lastSessionExercise ?? null,
+                lastFirstSet: lastData?.lastFirstSet ?? null
+            });
+        });
+    }
 }
 //# sourceMappingURL=WorkoutExerciseRepository.js.map

package/lib/repositories/workout/WorkoutExerciseRepository.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutExerciseRepository.js","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutExerciseRepository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,wBAAwB,MAAM,+CAA+C,CAAC;AACrF,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AACnF,OAAO,oCAAoC,MAAM,2CAA2C,CAAC;AAE7F;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,yBAA0B,SAAQ,+BAAgD;IAC7F,MAAM,CAAC,iBAAiB,CAA6B;IAE7D;QACE,KAAK,CAAC,uBAAuB,EAAE,IAAI,wBAAwB,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,uBAAuB;QAC5B,MAAM,YAAY,GAAG,yBAAyB,CAAC,OAAO,EAAE,CAAC;QACzD,OAAO;YACL,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChC,MAAM,YAAY,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACpD,CAAC;YACD,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;gBAClC,MAAM,YAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACtD,CAAC;SACF,CAAC;IACJ,CAAC;IAES,gBAAgB;QACxB,IAAI,CAAC,kBAAkB,CAAC,oCAAoC,CAAC,2BAA2B,EAAE,CAAC,CAAC;IAC9F,CAAC;IAEM,MAAM,CAAC,OAAO;QACnB,IAAI,CAAC,yBAAyB,CAAC,iBAAiB,EAAE,CAAC;YACjD,yBAAyB,CAAC,iBAAiB,GAAG,IAAI,yBAAyB,EAAE,CAAC;QAChF,CAAC;QACD,OAAO,yBAAyB,CAAC,iBAAiB,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"WorkoutExerciseRepository.js","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutExerciseRepository.ts"],"names":[],"mappings":"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"}

package/lib/repositories/workout/WorkoutExerciseRepository.ts

@@ -1,5 +1,23 @@
-import type { User, WorkoutExercise } from '@aneuhold/core-ts-db-lib';
-import { WorkoutExercise_docType } from '@aneuhold/core-ts-db-lib';
+import type {
+  User,
+  WorkoutEquipmentType,
+  WorkoutExercise,
+  WorkoutExerciseCalibration,
+  WorkoutExerciseCTO,
+  WorkoutSessionExercise,
+  WorkoutSet
+} from '@aneuhold/core-ts-db-lib';
+import {
+  WorkoutEquipmentType_docType,
+  WorkoutExercise_docType,
+  WorkoutExerciseCalibration_docType,
+  WorkoutExerciseCalibrationService,
+  WorkoutExerciseCTOSchema,
+  WorkoutSession_docType,
+  WorkoutSessionExercise_docType,
+  WorkoutSet_docType
+} from '@aneuhold/core-ts-db-lib';
+import type { UUID } from 'crypto';
 import type { RepoListeners } from '../../services/RepoSubscriptionService.js';
 import WorkoutExerciseValidator from '../../validators/workout/ExerciseValidator.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
@@ -37,4 +55,215 @@ export default class WorkoutExerciseRepository extends WorkoutBaseWithUserIdRepo
     }
     return WorkoutExerciseRepository.singletonInstance;
   }
+
+  /**
+   * Builds {@link WorkoutExerciseCTO} objects for all exercises belonging to a user.
+   * Uses two parallel MongoDB aggregation pipelines:
+   * - Pipeline A: exercise + equipmentType + bestCalibration + bestSet
+   * - Pipeline B: lastSessionExercise + lastFirstSet (from most recent non-deload session)
+   *
+   * @param userId The user whose exercise CTOs to build.
+   */
+  async buildExerciseCTOsForUser(userId: UUID): Promise<WorkoutExerciseCTO[]> {
+    /** Raw shape of Pipeline A results. */
+    interface PipelineARow extends WorkoutExercise {
+      _equipArr: WorkoutEquipmentType[];
+      _bestCalArr: WorkoutExerciseCalibration[];
+      _bestSetArr: WorkoutSet[];
+    }
+
+    /** Raw shape of Pipeline B results. */
+    interface PipelineBRow {
+      _id: string;
+      lastSessionExercise: WorkoutSessionExercise;
+      _lastFirstSetArr: WorkoutSet[];
+    }
+
+    const collection = await this.getCollection();
+    const collName = this.collectionName;
+
+    // Pipeline A: Exercise base + equipmentType + bestCalibration + bestSet
+    const pipelineAPromise = collection
+      .aggregate<PipelineARow>([
+        // Start with all exercises for this user
+        { $match: { docType: WorkoutExercise_docType, userId } },
+        // Join equipment type by workoutEquipmentTypeId
+        {
+          $lookup: {
+            from: collName,
+            let: { equipId: '$workoutEquipmentTypeId' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$_id', '$$equipId'] },
+                  docType: WorkoutEquipmentType_docType
+                }
+              }
+            ],
+            as: '_equipArr'
+          }
+        },
+        // Find the best calibration by highest estimated 1RM
+        {
+          $lookup: {
+            from: collName,
+            let: { exId: '$_id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutExerciseId', '$$exId'] },
+                  docType: WorkoutExerciseCalibration_docType
+                }
+              },
+              {
+                $addFields: {
+                  _1rm: WorkoutExerciseCalibrationService.get1RMMongoExpr('$weight', '$reps')
+                }
+              },
+              { $sort: { _1rm: -1 } },
+              { $limit: 1 },
+              { $project: { _1rm: 0 } }
+            ],
+            as: '_bestCalArr'
+          }
+        },
+        // Find the best completed set by highest estimated 1RM
+        {
+          $lookup: {
+            from: collName,
+            let: { exId: '$_id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutExerciseId', '$$exId'] },
+                  docType: WorkoutSet_docType,
+                  actualWeight: { $ne: null },
+                  actualReps: { $ne: null }
+                }
+              },
+              {
+                $addFields: {
+                  _1rm: WorkoutExerciseCalibrationService.get1RMMongoExpr(
+                    '$actualWeight',
+                    '$actualReps'
+                  )
+                }
+              },
+              { $sort: { _1rm: -1 } },
+              { $limit: 1 },
+              { $project: { _1rm: 0 } }
+            ],
+            as: '_bestSetArr'
+          }
+        }
+      ])
+      .toArray();
+
+    // Pipeline B: lastSessionExercise + lastFirstSet per exercise
+    const pipelineBPromise = collection
+      .aggregate<PipelineBRow>([
+        // Start with all completed sessions for this user
+        { $match: { docType: WorkoutSession_docType, userId, complete: true } },
+        // Most recent sessions first
+        { $sort: { startTime: -1 } },
+        // Join each session's session exercises
+        {
+          $lookup: {
+            from: collName,
+            let: { sessId: '$_id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutSessionId', '$$sessId'] },
+                  docType: WorkoutSessionExercise_docType
+                }
+              }
+            ],
+            as: '_se'
+          }
+        },
+        // One row per session exercise (unwind coalescence optimization)
+        { $unwind: '$_se' },
+        // Check for non-deload sets (plannedRir is not null)
+        {
+          $lookup: {
+            from: collName,
+            let: { seId: '$_se._id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutSessionExerciseId', '$$seId'] },
+                  docType: WorkoutSet_docType,
+                  plannedRir: { $ne: null }
+                }
+              },
+              { $limit: 1 }
+            ],
+            as: '_nonDeload'
+          }
+        },
+        // Keep only session exercises with at least one non-deload set
+        { $match: { '_nonDeload.0': { $exists: true } } },
+        // Per exercise, keep only the most recent session exercise ($first after sort)
+        {
+          $group: {
+            _id: '$_se.workoutExerciseId',
+            lastSessionExercise: { $first: '$_se' }
+          }
+        },
+        // Join the first set from that session exercise's setOrder
+        {
+          $lookup: {
+            from: collName,
+            let: { firstSetId: { $arrayElemAt: ['$lastSessionExercise.setOrder', 0] } },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$_id', '$$firstSetId'] },
+                  docType: WorkoutSet_docType
+                }
+              }
+            ],
+            as: '_lastFirstSetArr'
+          }
+        }
+      ])
+      .toArray();
+
+    const [rawExercises, rawLastSessions] = await Promise.all([pipelineAPromise, pipelineBPromise]);
+
+    // Build lookup map from Pipeline B
+    const lastSessionMap = new Map<
+      string,
+      {
+        lastSessionExercise: WorkoutSessionExercise;
+        lastFirstSet: WorkoutSet | null;
+      }
+    >();
+    for (const row of rawLastSessions) {
+      lastSessionMap.set(row._id, {
+        lastSessionExercise: row.lastSessionExercise,
+        lastFirstSet: row._lastFirstSetArr[0] ?? null
+      });
+    }
+
+    // Assemble and validate CTOs
+    return rawExercises.map((raw) => {
+      const { _equipArr, _bestCalArr, _bestSetArr, ...exerciseFields } = raw;
+      if (_equipArr.length === 0) {
+        throw new Error(`Equipment type not found for exercise ${raw._id}`);
+      }
+
+      const lastData = lastSessionMap.get(raw._id as string);
+
+      return WorkoutExerciseCTOSchema.parse({
+        ...exerciseFields,
+        equipmentType: _equipArr[0],
+        bestCalibration: _bestCalArr[0] ?? null,
+        bestSet: _bestSetArr[0] ?? null,
+        lastSessionExercise: lastData?.lastSessionExercise ?? null,
+        lastFirstSet: lastData?.lastFirstSet ?? null
+      });
+    });
+  }
 }

package/lib/repositories/workout/WorkoutMuscleGroupRepository.d.ts

@@ -1,4 +1,5 @@
-import type { User, WorkoutMuscleGroup } from '@aneuhold/core-ts-db-lib';
+import type { User, WorkoutMuscleGroup, WorkoutMuscleGroupVolumeCTO } from '@aneuhold/core-ts-db-lib';
+import type { UUID } from 'crypto';
 import type { RepoListeners } from '../../services/RepoSubscriptionService.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
 /**
@@ -16,5 +17,13 @@ export default class WorkoutMuscleGroupRepository extends WorkoutBaseWithUserIdR
      * Gets the singleton instance of the {@link WorkoutMuscleGroupRepository}.
      */
     static getRepo(): WorkoutMuscleGroupRepository;
+    /**
+     * Builds {@link WorkoutMuscleGroupVolumeCTO} objects for all muscle groups
+     * belonging to a user. Fetches muscle groups directly, then runs an
+     * aggregation pipeline for volume history across completed mesocycles.
+     *
+     * @param userId The user whose muscle group volume CTOs to build.
+     */
+    buildMuscleGroupVolumeCTOsForUser(userId: UUID): Promise<WorkoutMuscleGroupVolumeCTO[]>;
 }
 //# sourceMappingURL=WorkoutMuscleGroupRepository.d.ts.map

package/lib/repositories/workout/WorkoutMuscleGroupRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutMuscleGroupRepository.d.ts","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutMuscleGroupRepository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AAEnF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA6B,SAAQ,+BAA+B,CAAC,kBAAkB,CAAC;IAC3G,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAA+B;IAEhE;;OAEG;IACH,OAAO;IAIP,MAAM,CAAC,uBAAuB,IAAI,aAAa,CAAC,IAAI,CAAC;IAYrD,SAAS,CAAC,gBAAgB,IAAI,IAAI;IAElC;;OAEG;WACW,OAAO,IAAI,4BAA4B;CAMtD"}
+{"version":3,"file":"WorkoutMuscleGroupRepository.d.ts","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutMuscleGroupRepository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,kBAAkB,EAClB,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAUlC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AAEnF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA6B,SAAQ,+BAA+B,CAAC,kBAAkB,CAAC;IAC3G,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAA+B;IAEhE;;OAEG;IACH,OAAO;IAIP,MAAM,CAAC,uBAAuB,IAAI,aAAa,CAAC,IAAI,CAAC;IAYrD,SAAS,CAAC,gBAAgB,IAAI,IAAI;IAElC;;OAEG;WACW,OAAO,IAAI,4BAA4B;IAOrD;;;;;;OAMG;IACG,iCAAiC,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC;CAsQ9F"}

package/lib/repositories/workout/WorkoutMuscleGroupRepository.js

@@ -1,4 +1,4 @@
-import { WorkoutMuscleGroup_docType } from '@aneuhold/core-ts-db-lib';
+import { WorkoutExercise_docType, WorkoutMesocycle_docType, WorkoutMicrocycle_docType, WorkoutMuscleGroup_docType, WorkoutMuscleGroupVolumeCTOSchema, WorkoutSession_docType, WorkoutSessionExercise_docType } from '@aneuhold/core-ts-db-lib';
 import WorkoutMuscleGroupValidator from '../../validators/workout/MuscleGroupValidator.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
 /**
@@ -33,5 +33,251 @@ export default class WorkoutMuscleGroupRepository extends WorkoutBaseWithUserIdR
         }
         return WorkoutMuscleGroupRepository.singletonInstance;
     }
+    /**
+     * Builds {@link WorkoutMuscleGroupVolumeCTO} objects for all muscle groups
+     * belonging to a user. Fetches muscle groups directly, then runs an
+     * aggregation pipeline for volume history across completed mesocycles.
+     *
+     * @param userId The user whose muscle group volume CTOs to build.
+     */
+    async buildMuscleGroupVolumeCTOsForUser(userId) {
+        const collection = await this.getCollection();
+        const collName = this.collectionName;
+        // Part A: fetch all muscle groups
+        const muscleGroupsPromise = this.getAllForUser(userId);
+        // Part B: aggregation pipeline for volume data
+        const volumePromise = collection
+            .aggregate([
+            // Start with completed mesocycles for this user
+            {
+                $match: {
+                    docType: WorkoutMesocycle_docType,
+                    userId,
+                    completedDate: { $type: 'date' }
+                }
+            },
+            // Most recent first
+            { $sort: { completedDate: -1 } },
+            // Limit to 10 most recent
+            { $limit: 10 },
+            // Join microcycles, sorted by start date
+            {
+                $lookup: {
+                    from: collName,
+                    let: { mesoId: '$_id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutMesocycleId', '$$mesoId'] },
+                                docType: WorkoutMicrocycle_docType
+                            }
+                        },
+                        { $sort: { startDate: 1 } }
+                    ],
+                    as: '_microcycles'
+                }
+            },
+            // One row per microcycle, tracking index for starting/peak logic
+            { $unwind: { path: '$_microcycles', includeArrayIndex: '_microIdx' } },
+            // Join sessions for each microcycle
+            {
+                $lookup: {
+                    from: collName,
+                    let: { microId: '$_microcycles._id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutMicrocycleId', '$$microId'] },
+                                docType: WorkoutSession_docType
+                            }
+                        }
+                    ],
+                    as: '_sessions'
+                }
+            },
+            // One row per session (drop empty microcycles)
+            { $unwind: { path: '$_sessions', preserveNullAndEmptyArrays: false } },
+            // Join session exercises
+            {
+                $lookup: {
+                    from: collName,
+                    let: { sessId: '$_sessions._id' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$workoutSessionId', '$$sessId'] },
+                                docType: WorkoutSessionExercise_docType
+                            }
+                        }
+                    ],
+                    as: '_se'
+                }
+            },
+            // One row per session exercise
+            { $unwind: '$_se' },
+            // Join exercise doc to get muscle group arrays
+            {
+                $lookup: {
+                    from: collName,
+                    let: { exId: '$_se.workoutExerciseId' },
+                    pipeline: [
+                        {
+                            $match: {
+                                $expr: { $eq: ['$_id', '$$exId'] },
+                                docType: WorkoutExercise_docType
+                            }
+                        }
+                    ],
+                    as: '_exercise'
+                }
+            },
+            // One row per exercise
+            { $unwind: '$_exercise' },
+            // Combine primary + secondary muscle group IDs
+            {
+                $addFields: {
+                    _muscleGroups: {
+                        $concatArrays: [
+                            { $ifNull: ['$_exercise.primaryMuscleGroups', []] },
+                            { $ifNull: ['$_exercise.secondaryMuscleGroups', []] }
+                        ]
+                    }
+                }
+            },
+            // One row per (mesocycle, microcycle, session exercise, muscle group)
+            { $unwind: '$_muscleGroups' },
+            // First group: per (mesocycle, muscleGroup, microcycleIndex) — count sets, sum metrics
+            {
+                $group: {
+                    _id: {
+                        mesocycleId: '$_id',
+                        muscleGroupId: '$_muscleGroups',
+                        microIdx: '$_microIdx'
+                    },
+                    setCount: { $sum: { $size: { $ifNull: ['$_se.setOrder', []] } } },
+                    rsmSum: {
+                        $sum: {
+                            $cond: [
+                                {
+                                    $and: [
+                                        { $ne: [{ $ifNull: ['$_se.rsm.mindMuscleConnection', null] }, null] },
+                                        { $ne: [{ $ifNull: ['$_se.rsm.pump', null] }, null] },
+                                        { $ne: [{ $ifNull: ['$_se.rsm.disruption', null] }, null] }
+                                    ]
+                                },
+                                {
+                                    $add: ['$_se.rsm.mindMuscleConnection', '$_se.rsm.pump', '$_se.rsm.disruption']
+                                },
+                                0
+                            ]
+                        }
+                    },
+                    rsmCount: {
+                        $sum: {
+                            $cond: [
+                                {
+                                    $and: [
+                                        { $ne: [{ $ifNull: ['$_se.rsm.mindMuscleConnection', null] }, null] },
+                                        { $ne: [{ $ifNull: ['$_se.rsm.pump', null] }, null] },
+                                        { $ne: [{ $ifNull: ['$_se.rsm.disruption', null] }, null] }
+                                    ]
+                                },
+                                1,
+                                0
+                            ]
+                        }
+                    },
+                    sorenessSum: {
+                        $sum: {
+                            $cond: [
+                                { $ne: [{ $ifNull: ['$_se.sorenessScore', null] }, null] },
+                                '$_se.sorenessScore',
+                                0
+                            ]
+                        }
+                    },
+                    sorenessCount: {
+                        $sum: {
+                            $cond: [{ $ne: [{ $ifNull: ['$_se.sorenessScore', null] }, null] }, 1, 0]
+                        }
+                    },
+                    performanceSum: {
+                        $sum: {
+                            $cond: [
+                                { $ne: [{ $ifNull: ['$_se.performanceScore', null] }, null] },
+                                '$_se.performanceScore',
+                                0
+                            ]
+                        }
+                    },
+                    performanceCount: {
+                        $sum: {
+                            $cond: [{ $ne: [{ $ifNull: ['$_se.performanceScore', null] }, null] }, 1, 0]
+                        }
+                    },
+                    recoveryCount: {
+                        $sum: { $cond: [{ $eq: ['$_se.isRecoveryExercise', true] }, 1, 0] }
+                    },
+                    cycleType: { $first: '$cycleType' },
+                    completedDate: { $first: '$completedDate' }
+                }
+            },
+            // Sort by microcycle index so $first gives the starting microcycle
+            { $sort: { '_id.microIdx': 1 } },
+            // Second group: per (mesocycle, muscleGroup) — starting/peak set counts, aggregate metrics
+            {
+                $group: {
+                    _id: {
+                        mesocycleId: '$_id.mesocycleId',
+                        muscleGroupId: '$_id.muscleGroupId'
+                    },
+                    startingSetCount: { $first: '$setCount' },
+                    peakSetCount: { $max: '$setCount' },
+                    rsmSum: { $sum: '$rsmSum' },
+                    rsmCount: { $sum: '$rsmCount' },
+                    sorenessSum: { $sum: '$sorenessSum' },
+                    sorenessCount: { $sum: '$sorenessCount' },
+                    performanceSum: { $sum: '$performanceSum' },
+                    performanceCount: { $sum: '$performanceCount' },
+                    recoverySessionCount: { $sum: '$recoveryCount' },
+                    cycleType: { $first: '$cycleType' },
+                    completedDate: { $first: '$completedDate' }
+                }
+            }
+        ])
+            .toArray();
+        const [muscleGroups, volumeRows] = await Promise.all([muscleGroupsPromise, volumePromise]);
+        // Group volume rows by muscleGroupId
+        const historyMap = new Map();
+        for (const row of volumeRows) {
+            const mgId = row._id.muscleGroupId;
+            if (!historyMap.has(mgId)) {
+                historyMap.set(mgId, []);
+            }
+            const arr = historyMap.get(mgId);
+            if (arr) {
+                arr.push(row);
+            }
+        }
+        // Assemble CTOs
+        return muscleGroups.map((mg) => {
+            const rows = historyMap.get(mg._id) ?? [];
+            const mesocycleHistory = rows.map((row) => ({
+                mesocycleId: row._id.mesocycleId,
+                cycleType: row.cycleType,
+                startingSetCount: row.startingSetCount,
+                peakSetCount: row.peakSetCount,
+                avgRsm: row.rsmCount > 0 ? row.rsmSum / row.rsmCount : null,
+                avgSorenessScore: row.sorenessCount > 0 ? row.sorenessSum / row.sorenessCount : null,
+                avgPerformanceScore: row.performanceCount > 0 ? row.performanceSum / row.performanceCount : null,
+                recoverySessionCount: row.recoverySessionCount,
+                completedDate: row.completedDate
+            }));
+            return WorkoutMuscleGroupVolumeCTOSchema.parse({
+                ...mg,
+                mesocycleHistory
+            });
+        });
+    }
 }
 //# sourceMappingURL=WorkoutMuscleGroupRepository.js.map

package/lib/repositories/workout/WorkoutMuscleGroupRepository.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkoutMuscleGroupRepository.js","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutMuscleGroupRepository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,2BAA2B,MAAM,kDAAkD,CAAC;AAC3F,OAAO,+BAA+B,MAAM,sCAAsC,CAAC;AAEnF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA6B,SAAQ,+BAAmD;IACnG,MAAM,CAAC,iBAAiB,CAAgC;IAEhE;;OAEG;IACH;QACE,KAAK,CAAC,0BAA0B,EAAE,IAAI,2BAA2B,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,CAAC,uBAAuB;QAC5B,MAAM,eAAe,GAAG,4BAA4B,CAAC,OAAO,EAAE,CAAC;QAC/D,OAAO;YACL,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;gBAChC,MAAM,eAAe,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACvD,CAAC;YACD,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;gBAClC,MAAM,eAAe,CAAC,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACzD,CAAC;SACF,CAAC;IACJ,CAAC;IAES,gBAAgB,KAAU,CAAC;IAErC;;OAEG;IACI,MAAM,CAAC,OAAO;QACnB,IAAI,CAAC,4BAA4B,CAAC,iBAAiB,EAAE,CAAC;YACpD,4BAA4B,CAAC,iBAAiB,GAAG,IAAI,4BAA4B,EAAE,CAAC;QACtF,CAAC;QACD,OAAO,4BAA4B,CAAC,iBAAiB,CAAC;IACxD,CAAC;CACF"}
+{"version":3,"file":"WorkoutMuscleGroupRepository.js","sourceRoot":"","sources":["../../../src/repositories/workout/WorkoutMuscleGroupRepository.ts"],"names":[],"mappings":"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"}

package/lib/repositories/workout/WorkoutMuscleGroupRepository.ts

@@ -1,5 +1,18 @@
-import type { User, WorkoutMuscleGroup } from '@aneuhold/core-ts-db-lib';
-import { WorkoutMuscleGroup_docType } from '@aneuhold/core-ts-db-lib';
+import type {
+  User,
+  WorkoutMuscleGroup,
+  WorkoutMuscleGroupVolumeCTO
+} from '@aneuhold/core-ts-db-lib';
+import {
+  WorkoutExercise_docType,
+  WorkoutMesocycle_docType,
+  WorkoutMicrocycle_docType,
+  WorkoutMuscleGroup_docType,
+  WorkoutMuscleGroupVolumeCTOSchema,
+  WorkoutSession_docType,
+  WorkoutSessionExercise_docType
+} from '@aneuhold/core-ts-db-lib';
+import type { UUID } from 'crypto';
 import type { RepoListeners } from '../../services/RepoSubscriptionService.js';
 import WorkoutMuscleGroupValidator from '../../validators/workout/MuscleGroupValidator.js';
 import WorkoutBaseWithUserIdRepository from './WorkoutBaseWithUserIdRepository.js';
@@ -40,4 +53,274 @@ export default class WorkoutMuscleGroupRepository extends WorkoutBaseWithUserIdR
     }
     return WorkoutMuscleGroupRepository.singletonInstance;
   }
+
+  /**
+   * Builds {@link WorkoutMuscleGroupVolumeCTO} objects for all muscle groups
+   * belonging to a user. Fetches muscle groups directly, then runs an
+   * aggregation pipeline for volume history across completed mesocycles.
+   *
+   * @param userId The user whose muscle group volume CTOs to build.
+   */
+  async buildMuscleGroupVolumeCTOsForUser(userId: UUID): Promise<WorkoutMuscleGroupVolumeCTO[]> {
+    /** Raw shape of volume pipeline results (grouped by mesocycle + muscle group). */
+    interface VolumeRow {
+      _id: { mesocycleId: string; muscleGroupId: string };
+      startingSetCount: number;
+      peakSetCount: number;
+      rsmSum: number;
+      rsmCount: number;
+      sorenessSum: number;
+      sorenessCount: number;
+      performanceSum: number;
+      performanceCount: number;
+      recoverySessionCount: number;
+      cycleType: string;
+      completedDate: Date | null;
+    }
+
+    const collection = await this.getCollection();
+    const collName = this.collectionName;
+
+    // Part A: fetch all muscle groups
+    const muscleGroupsPromise = this.getAllForUser(userId);
+
+    // Part B: aggregation pipeline for volume data
+    const volumePromise = collection
+      .aggregate<VolumeRow>([
+        // Start with completed mesocycles for this user
+        {
+          $match: {
+            docType: WorkoutMesocycle_docType,
+            userId,
+            completedDate: { $type: 'date' }
+          }
+        },
+        // Most recent first
+        { $sort: { completedDate: -1 } },
+        // Limit to 10 most recent
+        { $limit: 10 },
+        // Join microcycles, sorted by start date
+        {
+          $lookup: {
+            from: collName,
+            let: { mesoId: '$_id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutMesocycleId', '$$mesoId'] },
+                  docType: WorkoutMicrocycle_docType
+                }
+              },
+              { $sort: { startDate: 1 } }
+            ],
+            as: '_microcycles'
+          }
+        },
+        // One row per microcycle, tracking index for starting/peak logic
+        { $unwind: { path: '$_microcycles', includeArrayIndex: '_microIdx' } },
+        // Join sessions for each microcycle
+        {
+          $lookup: {
+            from: collName,
+            let: { microId: '$_microcycles._id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutMicrocycleId', '$$microId'] },
+                  docType: WorkoutSession_docType
+                }
+              }
+            ],
+            as: '_sessions'
+          }
+        },
+        // One row per session (drop empty microcycles)
+        { $unwind: { path: '$_sessions', preserveNullAndEmptyArrays: false } },
+        // Join session exercises
+        {
+          $lookup: {
+            from: collName,
+            let: { sessId: '$_sessions._id' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$workoutSessionId', '$$sessId'] },
+                  docType: WorkoutSessionExercise_docType
+                }
+              }
+            ],
+            as: '_se'
+          }
+        },
+        // One row per session exercise
+        { $unwind: '$_se' },
+        // Join exercise doc to get muscle group arrays
+        {
+          $lookup: {
+            from: collName,
+            let: { exId: '$_se.workoutExerciseId' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ['$_id', '$$exId'] },
+                  docType: WorkoutExercise_docType
+                }
+              }
+            ],
+            as: '_exercise'
+          }
+        },
+        // One row per exercise
+        { $unwind: '$_exercise' },
+        // Combine primary + secondary muscle group IDs
+        {
+          $addFields: {
+            _muscleGroups: {
+              $concatArrays: [
+                { $ifNull: ['$_exercise.primaryMuscleGroups', []] },
+                { $ifNull: ['$_exercise.secondaryMuscleGroups', []] }
+              ]
+            }
+          }
+        },
+        // One row per (mesocycle, microcycle, session exercise, muscle group)
+        { $unwind: '$_muscleGroups' },
+        // First group: per (mesocycle, muscleGroup, microcycleIndex) — count sets, sum metrics
+        {
+          $group: {
+            _id: {
+              mesocycleId: '$_id',
+              muscleGroupId: '$_muscleGroups',
+              microIdx: '$_microIdx'
+            },
+            setCount: { $sum: { $size: { $ifNull: ['$_se.setOrder', []] } } },
+            rsmSum: {
+              $sum: {
+                $cond: [
+                  {
+                    $and: [
+                      { $ne: [{ $ifNull: ['$_se.rsm.mindMuscleConnection', null] }, null] },
+                      { $ne: [{ $ifNull: ['$_se.rsm.pump', null] }, null] },
+                      { $ne: [{ $ifNull: ['$_se.rsm.disruption', null] }, null] }
+                    ]
+                  },
+                  {
+                    $add: ['$_se.rsm.mindMuscleConnection', '$_se.rsm.pump', '$_se.rsm.disruption']
+                  },
+                  0
+                ]
+              }
+            },
+            rsmCount: {
+              $sum: {
+                $cond: [
+                  {
+                    $and: [
+                      { $ne: [{ $ifNull: ['$_se.rsm.mindMuscleConnection', null] }, null] },
+                      { $ne: [{ $ifNull: ['$_se.rsm.pump', null] }, null] },
+                      { $ne: [{ $ifNull: ['$_se.rsm.disruption', null] }, null] }
+                    ]
+                  },
+                  1,
+                  0
+                ]
+              }
+            },
+            sorenessSum: {
+              $sum: {
+                $cond: [
+                  { $ne: [{ $ifNull: ['$_se.sorenessScore', null] }, null] },
+                  '$_se.sorenessScore',
+                  0
+                ]
+              }
+            },
+            sorenessCount: {
+              $sum: {
+                $cond: [{ $ne: [{ $ifNull: ['$_se.sorenessScore', null] }, null] }, 1, 0]
+              }
+            },
+            performanceSum: {
+              $sum: {
+                $cond: [
+                  { $ne: [{ $ifNull: ['$_se.performanceScore', null] }, null] },
+                  '$_se.performanceScore',
+                  0
+                ]
+              }
+            },
+            performanceCount: {
+              $sum: {
+                $cond: [{ $ne: [{ $ifNull: ['$_se.performanceScore', null] }, null] }, 1, 0]
+              }
+            },
+            recoveryCount: {
+              $sum: { $cond: [{ $eq: ['$_se.isRecoveryExercise', true] }, 1, 0] }
+            },
+            cycleType: { $first: '$cycleType' },
+            completedDate: { $first: '$completedDate' }
+          }
+        },
+        // Sort by microcycle index so $first gives the starting microcycle
+        { $sort: { '_id.microIdx': 1 } },
+        // Second group: per (mesocycle, muscleGroup) — starting/peak set counts, aggregate metrics
+        {
+          $group: {
+            _id: {
+              mesocycleId: '$_id.mesocycleId',
+              muscleGroupId: '$_id.muscleGroupId'
+            },
+            startingSetCount: { $first: '$setCount' },
+            peakSetCount: { $max: '$setCount' },
+            rsmSum: { $sum: '$rsmSum' },
+            rsmCount: { $sum: '$rsmCount' },
+            sorenessSum: { $sum: '$sorenessSum' },
+            sorenessCount: { $sum: '$sorenessCount' },
+            performanceSum: { $sum: '$performanceSum' },
+            performanceCount: { $sum: '$performanceCount' },
+            recoverySessionCount: { $sum: '$recoveryCount' },
+            cycleType: { $first: '$cycleType' },
+            completedDate: { $first: '$completedDate' }
+          }
+        }
+      ])
+      .toArray();
+
+    const [muscleGroups, volumeRows] = await Promise.all([muscleGroupsPromise, volumePromise]);
+
+    // Group volume rows by muscleGroupId
+    const historyMap = new Map<string, VolumeRow[]>();
+    for (const row of volumeRows) {
+      const mgId = row._id.muscleGroupId;
+      if (!historyMap.has(mgId)) {
+        historyMap.set(mgId, []);
+      }
+      const arr = historyMap.get(mgId);
+      if (arr) {
+        arr.push(row);
+      }
+    }
+
+    // Assemble CTOs
+    return muscleGroups.map((mg) => {
+      const rows = historyMap.get(mg._id as string) ?? [];
+      const mesocycleHistory = rows.map((row) => ({
+        mesocycleId: row._id.mesocycleId,
+        cycleType: row.cycleType,
+        startingSetCount: row.startingSetCount,
+        peakSetCount: row.peakSetCount,
+        avgRsm: row.rsmCount > 0 ? row.rsmSum / row.rsmCount : null,
+        avgSorenessScore: row.sorenessCount > 0 ? row.sorenessSum / row.sorenessCount : null,
+        avgPerformanceScore:
+          row.performanceCount > 0 ? row.performanceSum / row.performanceCount : null,
+        recoverySessionCount: row.recoverySessionCount,
+        completedDate: row.completedDate
+      }));
+
+      return WorkoutMuscleGroupVolumeCTOSchema.parse({
+        ...mg,
+        mesocycleHistory
+      });
+    });
+  }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@aneuhold/be-ts-db-lib",
   "author": "Anton G. Neuhold Jr.",
   "license": "MIT",
-  "version": "4.2.11",
+  "version": "4.2.13",
   "description": "A backend database library meant to actually interact with various databases in personal projects",
   "packageManager": "pnpm@10.25.0",
   "type": "module",
@@ -58,16 +58,16 @@
     "MongoDB"
   ],
   "dependencies": {
-    "@aneuhold/be-ts-lib": "^3.0.21",
-    "@aneuhold/core-ts-db-lib": "^4.1.10",
-    "@aneuhold/core-ts-lib": "^2.4.0",
+    "@aneuhold/be-ts-lib": "^3.1.0",
+    "@aneuhold/core-ts-db-lib": "^4.1.12",
+    "@aneuhold/core-ts-lib": "^2.4.1",
     "bson": "^7.0.0",
     "mongodb": "^7.0.0",
     "uuid": "^13.0.0",
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@aneuhold/local-npm-registry": "^0.2.27",
+    "@aneuhold/local-npm-registry": "^0.2.28",
     "@aneuhold/main-scripts": "^2.8.3",
     "@types/node": "^25.0.2",
     "@types/node-fetch": "^2.6.13",