@vue-skuilder/db 0.1.11 → 0.1.12

package/src/study/services/EloService.ts

@@ -0,0 +1,85 @@
+import { adjustCourseScores, toCourseElo } from '@vue-skuilder/common';
+import { DataLayerProvider, UserDBInterface, CourseRegistrationDoc } from '@db/core';
+import { StudySessionRecord } from '../SessionController';
+import { logger } from '@db/util/logger';
+
+/**
+ * Service responsible for ELO rating calculations and updates.
+ */
+export class EloService {
+  private dataLayer: DataLayerProvider;
+  private user: UserDBInterface;
+
+  constructor(dataLayer: DataLayerProvider, user: UserDBInterface) {
+    this.dataLayer = dataLayer;
+    this.user = user;
+  }
+
+  /**
+   * Updates both user and card ELO ratings based on user performance.
+   * @param userScore Score between 0-1 representing user performance
+   * @param course_id Course identifier
+   * @param card_id Card identifier  
+   * @param userCourseRegDoc User's course registration document (will be mutated)
+   * @param currentCard Current card session record
+   * @param k Optional K-factor for ELO calculation
+   */
+  public async updateUserAndCardElo(
+    userScore: number,
+    course_id: string,
+    card_id: string,
+    userCourseRegDoc: CourseRegistrationDoc,
+    currentCard: StudySessionRecord,
+    k?: number
+  ): Promise<void> {
+    if (k) {
+      logger.warn(`k value interpretation not currently implemented`);
+    }
+    const courseDB = this.dataLayer.getCourseDB(currentCard.card.course_id);
+    const userElo = toCourseElo(userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo);
+    const cardElo = (await courseDB.getCardEloData([currentCard.card.card_id]))[0];
+
+    if (cardElo && userElo) {
+      const eloUpdate = adjustCourseScores(userElo, cardElo, userScore);
+      userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo = eloUpdate.userElo;
+
+      const results = await Promise.allSettled([
+        this.user.updateUserElo(course_id, eloUpdate.userElo),
+        courseDB.updateCardElo(card_id, eloUpdate.cardElo),
+      ]);
+
+      // Check the results of each operation
+      const userEloStatus = results[0].status === 'fulfilled';
+      const cardEloStatus = results[1].status === 'fulfilled';
+
+      if (userEloStatus && cardEloStatus) {
+        const user = (results[0] as PromiseFulfilledResult<any>).value;
+        const card = (results[1] as PromiseFulfilledResult<any>).value;
+
+        if (user.ok && card && card.ok) {
+          logger.info(
+            `[EloService] Updated ELOS:
+            \tUser: ${JSON.stringify(eloUpdate.userElo)})
+            \tCard: ${JSON.stringify(eloUpdate.cardElo)})
+            `
+          );
+        }
+      } else {
+        // Log which operations succeeded and which failed
+        logger.warn(
+          `[EloService] Partial ELO update:
+          \tUser ELO update: ${userEloStatus ? 'SUCCESS' : 'FAILED'}
+          \tCard ELO update: ${cardEloStatus ? 'SUCCESS' : 'FAILED'}`
+        );
+
+        if (!userEloStatus && results[0].status === 'rejected') {
+          logger.error('[EloService] User ELO update error:', results[0].reason);
+        }
+
+        if (!cardEloStatus && results[1].status === 'rejected') {
+          logger.error('[EloService] Card ELO update error:', results[1].reason);
+        }
+      }
+    }
+  }
+}

package/src/study/services/ResponseProcessor.ts

@@ -0,0 +1,224 @@
+import {
+  CardHistory,
+  CardRecord,
+  CourseRegistrationDoc,
+  isQuestionRecord,
+  QuestionRecord,
+  StudySessionItem,
+} from '@db/core';
+import { logger } from '@db/util/logger';
+import { ResponseResult, StudySessionRecord } from '../SessionController';
+import { EloService } from './EloService';
+import { SrsService } from './SrsService';
+
+/**
+ * Service responsible for orchestrating the complete response processing workflow.
+ * Coordinates SRS scheduling and ELO updates for user card interactions.
+ */
+export class ResponseProcessor {
+  private srsService: SrsService;
+  private eloService: EloService;
+
+  constructor(srsService: SrsService, eloService: EloService) {
+    this.srsService = srsService;
+    this.eloService = eloService;
+  }
+
+  /**
+   * Processes a user's response to a card, handling SRS scheduling and ELO updates.
+   * @param cardRecord User's response record
+   * @param cardHistory Promise resolving to the card's history
+   * @param studySessionItem Current study session item
+   * @param courseRegistrationDoc User's course registration (for ELO updates)
+   * @param currentCard Current study session record
+   * @param courseId Course identifier
+   * @param cardId Card identifier
+   * @param maxAttemptsPerView Maximum attempts allowed per view
+   * @param maxSessionViews Maximum session views for this card
+   * @param sessionViews Current number of session views
+   * @returns ResponseResult with navigation and UI instructions
+   */
+  public async processResponse(
+    cardRecord: CardRecord,
+    cardHistory: Promise<CardHistory<CardRecord>>,
+    studySessionItem: StudySessionItem,
+    courseRegistrationDoc: CourseRegistrationDoc,
+    currentCard: StudySessionRecord,
+    courseId: string,
+    cardId: string,
+    maxAttemptsPerView: number,
+    maxSessionViews: number,
+    sessionViews: number
+  ): Promise<ResponseResult> {
+    // Handle non-question records (simple dismiss)
+    if (!isQuestionRecord(cardRecord)) {
+      return {
+        nextCardAction: 'dismiss-success',
+        shouldLoadNextCard: true,
+        isCorrect: true, // non-question records are considered "correct"
+        shouldClearFeedbackShadow: true,
+      };
+    }
+
+    const history = await cardHistory;
+
+    // Handle correct responses
+    if (cardRecord.isCorrect) {
+      return this.processCorrectResponse(
+        cardRecord,
+        history,
+        studySessionItem,
+        courseRegistrationDoc,
+        currentCard,
+        courseId,
+        cardId
+      );
+    } else {
+      // Handle incorrect responses
+      return this.processIncorrectResponse(
+        cardRecord,
+        history,
+        courseRegistrationDoc,
+        currentCard,
+        courseId,
+        cardId,
+        maxAttemptsPerView,
+        maxSessionViews,
+        sessionViews
+      );
+    }
+  }
+
+  /**
+   * Handles processing for correct responses: SRS scheduling and ELO updates.
+   */
+  private processCorrectResponse(
+    cardRecord: QuestionRecord,
+    history: CardHistory<CardRecord>,
+    studySessionItem: StudySessionItem,
+    courseRegistrationDoc: CourseRegistrationDoc,
+    currentCard: StudySessionRecord,
+    courseId: string,
+    cardId: string
+  ): ResponseResult {
+    // Only schedule and update ELO for first-time attempts
+    if (cardRecord.priorAttemps === 0) {
+      // Schedule the card for future review based on performance (async, non-blocking)
+      void this.srsService.scheduleReview(history, studySessionItem);
+
+      // Update ELO ratings
+      if (history.records.length === 1) {
+        // First interaction with this card - standard ELO update (async, non-blocking)
+        const userScore = 0.5 + (cardRecord.performance as number) / 2;
+        void this.eloService.updateUserAndCardElo(
+          userScore,
+          courseId,
+          cardId,
+          courseRegistrationDoc,
+          currentCard
+        );
+      } else {
+        // Multiple interactions - reduce K-factor to limit ELO volatility (async, non-blocking)
+        const k = Math.ceil(32 / history.records.length);
+        const userScore = 0.5 + (cardRecord.performance as number) / 2;
+        void this.eloService.updateUserAndCardElo(
+          userScore,
+          courseId,
+          cardId,
+          courseRegistrationDoc,
+          currentCard,
+          k
+        );
+      }
+
+      logger.info(
+        '[ResponseProcessor] Processed correct response with SRS scheduling and ELO update'
+      );
+
+      return {
+        nextCardAction: 'dismiss-success',
+        shouldLoadNextCard: true,
+        isCorrect: true,
+        performanceScore: cardRecord.performance as number,
+        shouldClearFeedbackShadow: true,
+      };
+    } else {
+      logger.info(
+        '[ResponseProcessor] Processed correct response (retry attempt - no scheduling/ELO)'
+      );
+
+      return {
+        nextCardAction: 'marked-failed',
+        shouldLoadNextCard: true,
+        isCorrect: true,
+        performanceScore: cardRecord.performance as number,
+        shouldClearFeedbackShadow: true,
+      };
+    }
+  }
+
+  /**
+   * Handles processing for incorrect responses: ELO updates only.
+   */
+  private processIncorrectResponse(
+    cardRecord: QuestionRecord,
+    history: CardHistory<CardRecord>,
+    courseRegistrationDoc: CourseRegistrationDoc,
+    currentCard: StudySessionRecord,
+    courseId: string,
+    cardId: string,
+    maxAttemptsPerView: number,
+    maxSessionViews: number,
+    sessionViews: number
+  ): ResponseResult {
+    // Update ELO for first-time failures (not subsequent attempts on same card) (async, non-blocking)
+    if (history.records.length !== 1 && cardRecord.priorAttemps === 0) {
+      void this.eloService.updateUserAndCardElo(
+        0, // Failed response = 0 score
+        courseId,
+        cardId,
+        courseRegistrationDoc,
+        currentCard
+      );
+      logger.info('[ResponseProcessor] Processed incorrect response with ELO update');
+    } else {
+      logger.info('[ResponseProcessor] Processed incorrect response (no ELO update needed)');
+    }
+
+    // Determine navigation based on attempt limits
+    if (currentCard.records.length >= maxAttemptsPerView) {
+      if (sessionViews >= maxSessionViews) {
+        // Too many session views - dismiss completely with ELO penalty (async, non-blocking)
+        void this.eloService.updateUserAndCardElo(
+          0,
+          courseId,
+          cardId,
+          courseRegistrationDoc,
+          currentCard
+        );
+        return {
+          nextCardAction: 'dismiss-failed',
+          shouldLoadNextCard: true,
+          isCorrect: false,
+          shouldClearFeedbackShadow: true,
+        };
+      } else {
+        // Mark as failed for later retry
+        return {
+          nextCardAction: 'marked-failed',
+          shouldLoadNextCard: true,
+          isCorrect: false,
+          shouldClearFeedbackShadow: true,
+        };
+      }
+    } else {
+      // Allow more attempts on same card
+      return {
+        nextCardAction: 'none',
+        shouldLoadNextCard: false,
+        isCorrect: false,
+        shouldClearFeedbackShadow: true,
+      };
+    }
+  }
+}

package/src/study/services/SrsService.ts

@@ -0,0 +1,44 @@
+import moment from 'moment';
+import { CardHistory, CardRecord, UserDBInterface } from '@db/core';
+import { isReview, StudySessionItem } from '@db/impl/couch';
+import { newInterval } from '../SpacedRepetition';
+import { logger } from '@db/util/logger';
+
+/**
+ * Service responsible for Spaced Repetition System (SRS) scheduling logic.
+ */
+export class SrsService {
+  private user: UserDBInterface;
+
+  constructor(user: UserDBInterface) {
+    this.user = user;
+  }
+
+  /**
+   * Calculates the next review time for a card based on its history and
+   * schedules it in the user's database.
+   * @param history The full history of the card.
+   * @param item The study session item, used to determine if a previous review needs to be cleared.
+   */
+  public async scheduleReview(
+    history: CardHistory<CardRecord>,
+    item: StudySessionItem
+  ): Promise<void> {
+    const nextInterval = newInterval(this.user, history);
+    const nextReviewTime = moment.utc().add(nextInterval, 'seconds');
+
+    if (isReview(item)) {
+      logger.info(`[SrsService] Removing previously scheduled review for: ${item.cardID}`);
+      void this.user.removeScheduledCardReview(item.reviewID);
+    }
+
+    void this.user.scheduleCardReview({
+      user: this.user.getUsername(),
+      course_id: history.courseID,
+      card_id: history.cardID,
+      time: nextReviewTime,
+      scheduledFor: item.contentSourceType,
+      schedulingAgentId: item.contentSourceID,
+    });
+  }
+}