@vue-skuilder/db 0.1.11 → 0.1.12

package/src/impl/static/coursesDB.ts

@@ -9,14 +9,18 @@ export class StaticCoursesDB implements CoursesDBInterface {
   constructor(private manifests: Record<string, StaticCourseManifest>) {}
 
   async getCourseConfig(courseId: string): Promise<CourseConfig> {
-    if (!this.manifests[courseId]) {
-      // throw new Error(`Course ${courseId} not found`);
-      logger.warn(`Course ${courseId} not found`);
-      return {} as CourseConfig; // Return empty config if course not found
+    const manifest = this.manifests[courseId];
+    if (!manifest) {
+      logger.warn(`Course manifest for ${courseId} not found`);
+      throw new Error(`Course ${courseId} not found`);
     }
 
-    // Would need to fetch the course config from static files
-    return {} as CourseConfig;
+    if (manifest.courseConfig) {
+      return manifest.courseConfig;
+    } else {
+      logger.warn(`Course config not found in manifest for course ${courseId}`);
+      throw new Error(`Course config not found for course ${courseId}`);
+    }
   }
 
   async getCourseList(): Promise<CourseConfig[]> {

package/src/study/ItemQueue.ts

@@ -0,0 +1,58 @@
+export class ItemQueue<T> {
+  private q: T[] = [];
+  private seenCardIds: string[] = [];
+  private _dequeueCount: number = 0;
+  public get dequeueCount(): number {
+    return this._dequeueCount;
+  }
+
+  public add(item: T, cardId: string) {
+    if (this.seenCardIds.find((d) => d === cardId)) {
+      return; // do not re-add a card to the same queue
+    }
+
+    this.seenCardIds.push(cardId);
+    this.q.push(item);
+  }
+
+  public addAll(items: T[], cardIdExtractor: (item: T) => string) {
+    items.forEach((i) => this.add(i, cardIdExtractor(i)));
+  }
+
+  public get length() {
+    return this.q.length;
+  }
+
+  public peek(index: number): T {
+    return this.q[index];
+  }
+
+  public dequeue(cardIdExtractor?: (item: T) => string): T | null {
+    if (this.q.length !== 0) {
+      this._dequeueCount++;
+      const item = this.q.splice(0, 1)[0];
+
+      // Remove cardId from seenCardIds when dequeuing to allow re-queueing
+      if (cardIdExtractor) {
+        const cardId = cardIdExtractor(item);
+        const index = this.seenCardIds.indexOf(cardId);
+        if (index > -1) {
+          this.seenCardIds.splice(index, 1);
+        }
+      }
+
+      return item;
+    } else {
+      return null;
+    }
+  }
+
+  public get toString(): string {
+    return (
+      `${typeof this.q[0]}:\n` +
+      this.q
+        .map((i) => `\t${(i as any).courseID}+${(i as any).cardID}: ${(i as any).status}`)
+        .join('\n')
+    );
+  }
+}

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,10 +12,9 @@ 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';
-import { ViewData } from '@vue-skuilder/common';
 
 function randomInt(min: number, max: number): number {
   return Math.floor(Math.random() * (max - min + 1)) + min;
@@ -26,83 +30,53 @@ export interface StudySessionRecord {
   records: CardRecord[];
 }
 
-export interface HydratedCard<TView = unknown> {
-  item: StudySessionItem;
-  view: TView;
-  data: ViewData[];
-}
-
-import {
-  CardData,
-  DisplayableData,
-  displayableDataToViewData,
-  isCourseElo,
-  toCourseElo,
-} from '@vue-skuilder/common';
-
-class ItemQueue<T> {
-  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, cardId: string) {
-    if (this.seenCardIds.find((d) => d === 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(cardId);
-    this.q.push(item);
-  }
-  public addAll(items: T[], cardIdExtractor: (item: T) => string) {
-    items.forEach((i) => this.add(i, cardIdExtractor(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 as any).courseID}+${(i as any).cardID}: ${(i as any).status}`)
-        .join('\n')
-    );
-  }
+  // Cleanup
+  shouldClearFeedbackShadow: boolean;
 }
 
-import { DataLayerProvider } from '@db/core';
+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[];
-  private dataLayer: DataLayerProvider;
-  private getViewComponent: (viewId: string) => TView;
+  // 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 hydratedQ: ItemQueue<HydratedCard<TView>> = new ItemQueue<HydratedCard<TView>>();
-  private _currentCard: StudySessionItem | null = null;
-  private hydration_in_progress: boolean = false;
+  // END   Session card stores
 
   private startTime: Date;
   private endTime: Date;
@@ -130,12 +104,25 @@ export class SessionController<TView = unknown> extends Loggable {
   ) {
     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;
     this.endTime = new Date(this.startTime.valueOf() + 1000 * this._secondsRemaining);
-    this.dataLayer = dataLayer;
-    this.getViewComponent = getViewComponent;
 
     this.log(`Session constructed:
     startTime: ${this.startTime}
@@ -146,7 +133,7 @@ export class SessionController<TView = unknown> 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);
     }
   }
@@ -199,7 +186,7 @@ export class SessionController<TView = unknown> extends Loggable {
       this.error('Error preparing study session:', e);
     }
 
-    await this._fillHydratedQueue();
+    await this.hydrationService.ensureHydratedCards();
 
     this._intervalHandle = setInterval(() => {
       this.tick();
@@ -275,13 +262,7 @@ export class SessionController<TView = unknown> extends Loggable {
     }
   }
 
-  private _selectNextItemToHydrate(
-    action:
-      | 'dismiss-success'
-      | 'dismiss-failed'
-      | 'marked-failed'
-      | 'dismiss-error' = 'dismiss-success'
-  ): StudySessionItem | null {
+  private _selectNextItemToHydrate(): StudySessionItem | null {
     const choice = Math.random();
     let newBound: number = 0.1;
     let reviewBound: number = 0.75;
@@ -333,12 +314,6 @@ export class SessionController<TView = unknown> 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;
@@ -360,38 +335,78 @@ export class SessionController<TView = unknown> extends Loggable {
   }
 
   public async nextCard(
-    action:
-      | 'dismiss-success'
-      | 'dismiss-failed'
-      | 'marked-failed'
-      | 'dismiss-error' = 'dismiss-success'
+    action: SessionAction = 'dismiss-success'
   ): Promise<HydratedCard<TView> | null> {
     // dismiss (or sort to failedQ) the current card
     this.dismissCurrentCard(action);
 
-    let card = this.hydratedQ.dequeue();
+    if (this._secondsRemaining <= 0 && this.failedQ.length === 0) {
+      this._currentCard = null;
+      return null;
+    }
+
+    let card = this.hydrationService.dequeueHydratedCard();
 
     // If no hydrated card but source cards available, wait for hydration
     if (!card && this.hasAvailableCards()) {
-      void this._fillHydratedQueue(); // Start hydration in background
-      card = await this.nextHydratedCard(); // Wait for first available card
+      card = await this.hydrationService.waitForHydratedCard();
     }
 
     // Trigger background hydration to maintain cache (async, non-blocking)
-    if (this.hydratedQ.length < 3) {
-      void this._fillHydratedQueue();
+    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')) {
@@ -406,23 +421,25 @@ export class SessionController<TView = unknown> 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,
-            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,
-            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',
           };
         }
@@ -440,79 +457,16 @@ export class SessionController<TView = unknown> extends Loggable {
     return this.reviewQ.length > 0 || this.newQ.length > 0 || this.failedQ.length > 0;
   }
 
-  private async nextHydratedCard(): Promise<HydratedCard<TView> | null> {
-    // 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.hydratedQ.dequeue();
-  }
-
-  private async _fillHydratedQueue() {
-    if (this.hydration_in_progress) {
-      return; // Prevent concurrent hydration
-    }
-
-    const BUFFER_SIZE = 5;
-    this.hydration_in_progress = true;
-
-    while (this.hydratedQ.length < BUFFER_SIZE) {
-      const nextItem = this._selectNextItemToHydrate();
-      if (!nextItem) {
-        return; // No more cards to hydrate
-      }
-
-      try {
-        const cardData = await this.dataLayer
-          .getCourseDB(nextItem.courseID)
-          .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) =>
-            this.dataLayer.getCourseDB(nextItem.courseID).getCourseDoc<DisplayableData>(id, {
-              attachments: true,
-              binary: true,
-            })
-          )
-        );
-
-        const data = dataDocs.map(displayableDataToViewData).reverse();
-
-        this.hydratedQ.add(
-          {
-            item: nextItem,
-            view,
-            data,
-          },
-          nextItem.cardID
-        );
-
-        // Remove the item from the original queue
-        if (this.reviewQ.peek(0) === nextItem) {
-          this.reviewQ.dequeue();
-        } else if (this.newQ.peek(0) === nextItem) {
-          this.newQ.dequeue();
-        } else {
-          this.failedQ.dequeue();
-        }
-      } catch (e) {
-        this.error(`Error hydrating card ${nextItem.cardID}:`, e);
-        // Remove the failed item from the queue
-        if (this.reviewQ.peek(0) === nextItem) {
-          this.reviewQ.dequeue();
-        } else if (this.newQ.peek(0) === nextItem) {
-          this.newQ.dequeue();
-        } else {
-          this.failedQ.dequeue();
-        }
-      }
+  /**
+   * 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);
     }
-
-    this.hydration_in_progress = false;
   }
 }

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