@vue-skuilder/db 0.1.11-9 → 0.1.12

package/src/study/SessionController.ts

@@ -1,3 +1,8 @@
+import { SrsService } from './services/SrsService';
+import { EloService } from './services/EloService';
+import { ResponseProcessor } from './services/ResponseProcessor';
+import { CardHydrationService, HydratedCard } from './services/CardHydrationService';
+import { ItemQueue } from './ItemQueue';
 import {
   isReview,
   StudyContentSource,
@@ -7,7 +12,7 @@ import {
   StudySessionReviewItem,
 } from '@db/impl/couch';
 
-import { CardRecord } from '@db/core';
+import { CardRecord, CardHistory, CourseRegistrationDoc } from '@db/core';
 import { Loggable } from '@db/util';
 import { ScheduledCard } from '@db/core/types/user';
 
@@ -25,65 +30,53 @@ export interface StudySessionRecord {
   records: CardRecord[];
 }
 
-class ItemQueue<T extends StudySessionItem> {
-  private q: T[] = [];
-  private seenCardIds: string[] = [];
-  private _dequeueCount: number = 0;
-  public get dequeueCount(): number {
-    return this._dequeueCount;
-  }
+import { DataLayerProvider } from '@db/core';
 
-  public add(item: T) {
-    if (this.seenCardIds.find((d) => d === item.cardID)) {
-      return; // do not re-add a card to the same queue
-    }
+export type SessionAction =
+  | 'dismiss-success'
+  | 'dismiss-failed'
+  | 'marked-failed'
+  | 'dismiss-error';
 
-    this.seenCardIds.push(item.cardID);
-    this.q.push(item);
-  }
-  public addAll(items: T[]) {
-    items.forEach((i) => this.add(i));
-  }
-  public get length() {
-    return this.q.length;
-  }
-  public peek(index: number): T {
-    return this.q[index];
-  }
+export interface ResponseResult {
+  // Navigation
+  nextCardAction: Exclude<SessionAction, 'dismiss-error'> | 'none';
+  shouldLoadNextCard: boolean;
 
-  public dequeue(): T | null {
-    if (this.q.length !== 0) {
-      this._dequeueCount++;
-      return this.q.splice(0, 1)[0];
-    } else {
-      return null;
-    }
-  }
+  // UI Data (let view decide how to render)
+  isCorrect: boolean;
+  performanceScore?: number; // for shadow color calculation
 
-  public get toString(): string {
-    return (
-      `${typeof this.q[0]}:\n` + this.q.map((i) => `\t${i.qualifiedID}: ${i.status}`).join('\n')
-    );
-  }
+  // Cleanup
+  shouldClearFeedbackShadow: boolean;
 }
 
-export class SessionController extends Loggable {
+interface SessionServices {
+  response: ResponseProcessor;
+}
+
+export class SessionController<TView = unknown> extends Loggable {
   _className = 'SessionController';
+
+  public services: SessionServices;
+  private srsService: SrsService;
+  private eloService: EloService;
+  private hydrationService: CardHydrationService<TView>;
+
   private sources: StudyContentSource[];
+  // dataLayer and getViewComponent now injected into CardHydrationService
   private _sessionRecord: StudySessionRecord[] = [];
   public set sessionRecord(r: StudySessionRecord[]) {
     this._sessionRecord = r;
   }
 
+  // Session card stores
+  private _currentCard: HydratedCard<TView> | null = null;
+
   private reviewQ: ItemQueue<StudySessionReviewItem> = new ItemQueue<StudySessionReviewItem>();
   private newQ: ItemQueue<StudySessionNewItem> = new ItemQueue<StudySessionNewItem>();
   private failedQ: ItemQueue<StudySessionFailedItem> = new ItemQueue<StudySessionFailedItem>();
-  private _currentCard: StudySessionItem | null = null;
-  /**
-   * Indicates whether the session has been initialized - eg, the
-   * queues have been populated.
-   */
-  private _isInitialized: boolean = false;
+  // END   Session card stores
 
   private startTime: Date;
   private endTime: Date;
@@ -103,9 +96,29 @@ export class SessionController extends Loggable {
   /**
    *
    */
-  constructor(sources: StudyContentSource[], time: number) {
+  constructor(
+    sources: StudyContentSource[],
+    time: number,
+    dataLayer: DataLayerProvider,
+    getViewComponent: (viewId: string) => TView
+  ) {
     super();
 
+    this.srsService = new SrsService(dataLayer.getUserDB());
+    this.eloService = new EloService(dataLayer, dataLayer.getUserDB());
+
+    this.hydrationService = new CardHydrationService<TView>(
+      getViewComponent,
+      (courseId: string) => dataLayer.getCourseDB(courseId),
+      () => this._selectNextItemToHydrate(),
+      (item: StudySessionItem) => this.removeItemFromQueue(item),
+      () => this.hasAvailableCards()
+    );
+
+    this.services = {
+      response: new ResponseProcessor(this.srsService, this.eloService),
+    };
+
     this.sources = sources;
     this.startTime = new Date();
     this._secondsRemaining = time;
@@ -120,7 +133,7 @@ export class SessionController extends Loggable {
     this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1000);
     // this.log(this.secondsRemaining);
 
-    if (this._secondsRemaining === 0) {
+    if (this._secondsRemaining <= 0) {
       clearInterval(this._intervalHandle);
     }
   }
@@ -173,7 +186,7 @@ export class SessionController extends Loggable {
       this.error('Error preparing study session:', e);
     }
 
-    this._isInitialized = true;
+    await this.hydrationService.ensureHydratedCards();
 
     this._intervalHandle = setInterval(() => {
       this.tick();
@@ -221,11 +234,8 @@ export class SessionController extends Loggable {
     }
 
     let report = 'Review session created with:\n';
-    for (let i = 0; i < dueCards.length; i++) {
-      const card = dueCards[i];
-      this.reviewQ.add(card);
-      report += `\t${card.qualifiedID}}\n`;
-    }
+    this.reviewQ.addAll(dueCards, (c) => c.cardID);
+    report += dueCards.map((card) => `Card ${card.courseID}::${card.cardID} `).join('\n');
     this.log(report);
   }
 
@@ -244,55 +254,41 @@ export class SessionController extends Loggable {
       for (let i = 0; i < newContent.length; i++) {
         if (newContent[i].length > 0) {
           const item = newContent[i].splice(0, 1)[0];
-          this.log(`Adding new card: ${item.qualifiedID}`);
-          this.newQ.add(item);
+          this.log(`Adding new card: ${item.courseID}::${item.cardID}`);
+          this.newQ.add(item, item.cardID);
           n--;
         }
       }
     }
   }
 
-  private nextNewCard(): StudySessionNewItem | null {
-    const item = this.newQ.dequeue();
-
-    // queue some more content if we are getting low
-    if (this._isInitialized && this.newQ.length < 5) {
-      void this.getNewCards();
-    }
-
-    return item;
-  }
-
-  public nextCard(
-    action:
-      | 'dismiss-success'
-      | 'dismiss-failed'
-      | 'marked-failed'
-      | 'dismiss-error' = 'dismiss-success'
-  ): StudySessionItem | null {
-    // dismiss (or sort to failedQ) the current card
-    this.dismissCurrentCard(action);
-
+  private _selectNextItemToHydrate(): StudySessionItem | null {
     const choice = Math.random();
     let newBound: number = 0.1;
     let reviewBound: number = 0.75;
 
     if (this.reviewQ.length === 0 && this.failedQ.length === 0 && this.newQ.length === 0) {
       // all queues empty - session is over (and course is complete?)
-      this._currentCard = null;
-      return this._currentCard;
+      return null;
     }
 
     if (this._secondsRemaining < 2 && this.failedQ.length === 0) {
       // session is over!
-      this._currentCard = null;
-      return this._currentCard;
+      return null;
+    }
+
+    // If timer expired, only return failed cards
+    if (this._secondsRemaining <= 0) {
+      if (this.failedQ.length > 0) {
+        return this.failedQ.peek(0);
+      } else {
+        return null; // No more failed cards, session over
+      }
     }
 
     // supply new cards at start of session
     if (this.newQ.dequeueCount < this.sources.length && this.newQ.length) {
-      this._currentCard = this.nextNewCard();
-      return this._currentCard;
+      return this.newQ.peek(0);
     }
 
     const cleanupTime = this.estimateCleanupTime();
@@ -318,12 +314,6 @@ export class SessionController extends Loggable {
       reviewBound = 0.1;
     }
 
-    // prevent (unless no other option available) re-display of
-    // most recent card
-    if (this.failedQ.length === 1 && action === 'marked-failed') {
-      reviewBound = 1;
-    }
-
     // exclude possibility of drawing from empty queues
     if (this.failedQ.length === 0) {
       reviewBound = 1;
@@ -333,26 +323,90 @@ export class SessionController extends Loggable {
     }
 
     if (choice < newBound && this.newQ.length) {
-      this._currentCard = this.nextNewCard();
+      return this.newQ.peek(0);
     } else if (choice < reviewBound && this.reviewQ.length) {
-      this._currentCard = this.reviewQ.dequeue();
+      return this.reviewQ.peek(0);
     } else if (this.failedQ.length) {
-      this._currentCard = this.failedQ.dequeue();
+      return this.failedQ.peek(0);
     } else {
       this.log(`No more cards available for the session!`);
+      return null;
+    }
+  }
+
+  public async nextCard(
+    action: SessionAction = 'dismiss-success'
+  ): Promise<HydratedCard<TView> | null> {
+    // dismiss (or sort to failedQ) the current card
+    this.dismissCurrentCard(action);
+
+    if (this._secondsRemaining <= 0 && this.failedQ.length === 0) {
       this._currentCard = null;
+      return null;
     }
 
-    return this._currentCard;
+    let card = this.hydrationService.dequeueHydratedCard();
+
+    // If no hydrated card but source cards available, wait for hydration
+    if (!card && this.hasAvailableCards()) {
+      card = await this.hydrationService.waitForHydratedCard();
+    }
+
+    // Trigger background hydration to maintain cache (async, non-blocking)
+    await this.hydrationService.ensureHydratedCards();
+
+    if (card) {
+      this._currentCard = card;
+    } else {
+      this._currentCard = null;
+    }
+
+    return card;
   }
 
-  private dismissCurrentCard(
-    action:
-      | 'dismiss-success'
-      | 'dismiss-failed'
-      | 'marked-failed'
-      | 'dismiss-error' = 'dismiss-success'
-  ) {
+  /**
+   * Public API for processing user responses to cards.
+   * @param cardRecord User's response record
+   * @param cardHistory Promise resolving to the card's history
+   * @param courseRegistrationDoc User's course registration document
+   * @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 submitResponse(
+    cardRecord: CardRecord,
+    cardHistory: Promise<CardHistory<CardRecord>>,
+    courseRegistrationDoc: CourseRegistrationDoc,
+    currentCard: StudySessionRecord,
+    courseId: string,
+    cardId: string,
+    maxAttemptsPerView: number,
+    maxSessionViews: number,
+    sessionViews: number
+  ): Promise<ResponseResult> {
+    const studySessionItem: StudySessionItem = {
+      ...currentCard.item,
+    };
+
+    return await this.services.response.processResponse(
+      cardRecord,
+      cardHistory,
+      studySessionItem,
+      courseRegistrationDoc,
+      currentCard,
+      courseId,
+      cardId,
+      maxAttemptsPerView,
+      maxSessionViews,
+      sessionViews
+    );
+  }
+
+  private dismissCurrentCard(action: SessionAction = 'dismiss-success') {
     if (this._currentCard) {
       // this.log(`Running dismissCurrentCard on ${this._currentCard!.qualifiedID}`);
       // if (action.includes('dismiss')) {
@@ -367,30 +421,30 @@ export class SessionController extends Loggable {
       if (action === 'dismiss-success') {
         // schedule a review - currently done in Study.vue
       } else if (action === 'marked-failed') {
+        this.hydrationService.cacheFailedCard(this._currentCard);
+
         let failedItem: StudySessionFailedItem;
 
-        if (isReview(this._currentCard)) {
+        if (isReview(this._currentCard.item)) {
           failedItem = {
-            cardID: this._currentCard.cardID,
-            courseID: this._currentCard.courseID,
-            qualifiedID: this._currentCard.qualifiedID,
-            contentSourceID: this._currentCard.contentSourceID,
-            contentSourceType: this._currentCard.contentSourceType,
+            cardID: this._currentCard.item.cardID,
+            courseID: this._currentCard.item.courseID,
+            contentSourceID: this._currentCard.item.contentSourceID,
+            contentSourceType: this._currentCard.item.contentSourceType,
             status: 'failed-review',
-            reviewID: this._currentCard.reviewID,
+            reviewID: this._currentCard.item.reviewID,
           };
         } else {
           failedItem = {
-            cardID: this._currentCard.cardID,
-            courseID: this._currentCard.courseID,
-            qualifiedID: this._currentCard.qualifiedID,
-            contentSourceID: this._currentCard.contentSourceID,
-            contentSourceType: this._currentCard.contentSourceType,
+            cardID: this._currentCard.item.cardID,
+            courseID: this._currentCard.item.courseID,
+            contentSourceID: this._currentCard.item.contentSourceID,
+            contentSourceType: this._currentCard.item.contentSourceType,
             status: 'failed-new',
           };
         }
 
-        this.failedQ.add(failedItem);
+        this.failedQ.add(failedItem, failedItem.cardID);
       } else if (action === 'dismiss-error') {
         // some error logging?
       } else if (action === 'dismiss-failed') {
@@ -398,4 +452,21 @@ export class SessionController extends Loggable {
       }
     }
   }
+
+  private hasAvailableCards(): boolean {
+    return this.reviewQ.length > 0 || this.newQ.length > 0 || this.failedQ.length > 0;
+  }
+
+  /**
+   * Helper method for CardHydrationService to remove items from appropriate queue.
+   */
+  private removeItemFromQueue(item: StudySessionItem): void {
+    if (this.reviewQ.peek(0) === item) {
+      this.reviewQ.dequeue((queueItem) => queueItem.cardID);
+    } else if (this.newQ.peek(0) === item) {
+      this.newQ.dequeue((queueItem) => queueItem.cardID);
+    } else {
+      this.failedQ.dequeue((queueItem) => queueItem.cardID);
+    }
+  }
 }

package/src/study/SpacedRepetition.ts

@@ -39,7 +39,7 @@ function newQuestionInterval(user: DocumentUpdater, cardHistory: CardHistory<Que
   }
 
   if (currentAttempt.isCorrect) {
-    const skill = currentAttempt.performance as number;
+    const skill = Math.min(1.0, Math.max(0.0, currentAttempt.performance as number));
     logger.debug(`Demontrated skill: \t${skill}`);
     const interval: number = lastInterval * (0.75 + skill);
     cardHistory.lapses = getLapses(cardHistory.records);

package/src/study/services/CardHydrationService.ts

@@ -0,0 +1,153 @@
+import {
+  displayableDataToViewData,
+  CardData,
+  DisplayableData,
+  isCourseElo,
+  toCourseElo,
+} from '@vue-skuilder/common';
+import { StudySessionItem } from '@db/impl/couch';
+import { logger } from '@db/util/logger';
+import { ItemQueue } from '../ItemQueue';
+import { CourseDBInterface } from '@db/core';
+
+export interface HydratedCard<TView = unknown> {
+  item: StudySessionItem;
+  view: TView;
+  data: any[];
+}
+
+// ItemQueue now imported from separate file
+
+/**
+ * Service responsible for managing a queue of hydrated (ready-to-display) cards.
+ * Handles pre-fetching card data, caching failed cards, and maintaining optimal buffer size.
+ */
+export class CardHydrationService<TView = unknown> {
+  private hydratedQ: ItemQueue<HydratedCard<TView>> = new ItemQueue<HydratedCard<TView>>();
+  private failedCardCache: Map<string, HydratedCard<TView>> = new Map();
+  private hydrationInProgress: boolean = false;
+  private readonly BUFFER_SIZE = 5;
+
+  constructor(
+    private getViewComponent: (viewId: string) => TView,
+    private getCourseDB: (courseId: string) => CourseDBInterface,
+    private selectNextItemToHydrate: () => StudySessionItem | null,
+    private removeItemFromQueue: (item: StudySessionItem) => void,
+    private hasAvailableCards: () => boolean
+  ) {}
+
+  /**
+   * Get the next hydrated card from the queue.
+   * @returns Hydrated card or null if none available
+   */
+  public dequeueHydratedCard(): HydratedCard<TView> | null {
+    return this.hydratedQ.dequeue((item) => item.item.cardID);
+  }
+
+  /**
+   * Check if hydration should be triggered and start background hydration if needed.
+   */
+  public async ensureHydratedCards(): Promise<void> {
+    // Trigger background hydration to maintain cache (async, non-blocking)
+    if (this.hydratedQ.length < 3) {
+      void this.fillHydratedQueue();
+    }
+  }
+
+  /**
+   * Wait for a hydrated card to become available.
+   * @returns Promise that resolves to a hydrated card or null
+   */
+  public async waitForHydratedCard(): Promise<HydratedCard<TView> | null> {
+    // If no hydrated card but source cards available, start hydration
+    if (this.hydratedQ.length === 0 && this.hasAvailableCards()) {
+      void this.fillHydratedQueue(); // Start hydration in background
+    }
+
+    // Wait for a card to become available in hydratedQ
+    while (this.hydratedQ.length === 0 && this.hasAvailableCards()) {
+      await new Promise((resolve) => setTimeout(resolve, 25)); // Short polling interval
+    }
+
+    return this.dequeueHydratedCard();
+  }
+
+  /**
+   * Get current hydrated queue length.
+   */
+  public get hydratedCount(): number {
+    return this.hydratedQ.length;
+  }
+
+  /**
+   * Fill the hydrated queue up to BUFFER_SIZE with pre-fetched cards.
+   */
+  private async fillHydratedQueue(): Promise<void> {
+    if (this.hydrationInProgress) {
+      return; // Prevent concurrent hydration
+    }
+
+    this.hydrationInProgress = true;
+
+    try {
+      while (this.hydratedQ.length < this.BUFFER_SIZE) {
+        const nextItem = this.selectNextItemToHydrate();
+        if (!nextItem) {
+          return; // No more cards to hydrate
+        }
+
+        try {
+          // Check cache first for failed cards
+          if (this.failedCardCache.has(nextItem.cardID)) {
+            const cachedCard = this.failedCardCache.get(nextItem.cardID)!;
+            this.hydratedQ.add(cachedCard, cachedCard.item.cardID);
+            this.failedCardCache.delete(nextItem.cardID);
+          } else {
+            // Hydrate new card using original logic pattern
+            const courseDB = this.getCourseDB(nextItem.courseID);
+            const cardData = await courseDB.getCourseDoc<CardData>(nextItem.cardID);
+
+            if (!isCourseElo(cardData.elo)) {
+              cardData.elo = toCourseElo(cardData.elo);
+            }
+
+            const view = this.getViewComponent(cardData.id_view);
+            const dataDocs = await Promise.all(
+              cardData.id_displayable_data.map((id: string) =>
+                courseDB.getCourseDoc<DisplayableData>(id, {
+                  attachments: true,
+                  binary: true,
+                })
+              )
+            );
+
+            const data = dataDocs.map(displayableDataToViewData).reverse();
+
+            this.hydratedQ.add(
+              {
+                item: nextItem,
+                view,
+                data,
+              },
+              nextItem.cardID
+            );
+          }
+        } catch (e) {
+          logger.error(`Error hydrating card ${nextItem.cardID}:`, e);
+        } finally {
+          // Remove the item from the original queue, regardless of success/failure/cache
+          this.removeItemFromQueue(nextItem);
+        }
+      }
+    } finally {
+      this.hydrationInProgress = false;
+    }
+  }
+
+  /**
+   * Cache a failed card for quick re-access.
+   */
+  public cacheFailedCard(card: HydratedCard<TView>): void {
+    this.failedCardCache.set(card.item.cardID, card);
+  }
+}

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);
+        }
+      }
+    }
+  }
+}