@vue-skuilder/db 0.1.14-2 → 0.1.15

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.14-2",
+  "version": "0.1.15",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.14-2",
+    "@vue-skuilder/common": "0.1.15",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -57,5 +57,5 @@
     "tsup": "^8.0.2",
     "typescript": "~5.7.2"
   },
-  "stableVersion": "0.1.13"
+  "stableVersion": "0.1.15"
 }

package/src/impl/common/BaseUserDB.ts

@@ -722,12 +722,22 @@ Currently logged-in as ${this._username}.`
 
   /**
    * Logs a record of the user's interaction with the card and returns the card's
-   * up-to-date history
+   * up-to-date history.
+   *
+   * **Automatic Initialization:**
+   * If this is the user's first interaction with the card (CardHistory doesn't exist),
+   * this method automatically creates the CardHistory document with initial values
+   * (lapses: 0, streak: 0, bestInterval: 0).
+   *
+   * **Error Handling:**
+   * - Handles 404 errors by creating initial CardHistory document
+   * - Re-throws all other errors from UpdateQueue
    *
    * // [ ] #db-refactor extract to a smaller scope - eg, UserStudySession
    *
-   * @param record the recent recorded interaction between user and card
+   * @param record - The recent recorded interaction between user and card
    * @returns The updated state of the card's CardHistory data
+   * @throws Error if document creation fails or non-404 database error occurs
    */
 
   public async putCardRecord<T extends CardRecord>(

package/src/impl/couch/updateQueue.ts

@@ -15,6 +15,33 @@ export default class UpdateQueue extends Loggable {
   private readDB: PouchDB.Database; // Database for read operations
   private writeDB: PouchDB.Database; // Database for write operations (local-first)
 
+  /**
+   * Queues an update for a document and applies it with conflict resolution.
+   *
+   * @param id - Document ID to update
+   * @param update - Partial object or function that transforms the document
+   * @returns Promise resolving to the updated document
+   *
+   * @throws {PouchError} with status 404 if document doesn't exist
+   *
+   * @remarks
+   * **Error Handling Pattern:**
+   * - This method does NOT create documents if they don't exist
+   * - Callers are responsible for handling 404 errors and creating documents
+   * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await updateQueue.update(docId, (doc) => ({ ...doc, field: newValue }));
+   * } catch (e) {
+   *   if ((e as PouchError).status === 404) {
+   *     // Create the document with initial values
+   *     await db.put({ _id: docId, field: newValue, ...initialFields });
+   *   }
+   * }
+   * ```
+   */
   public update<T extends PouchDB.Core.Document<object>>(
     id: PouchDB.Core.DocumentId,
     update: Update<T>
@@ -57,7 +84,6 @@ export default class UpdateQueue extends Loggable {
         for (let i = 0; i < MAX_RETRIES; i++) {
           try {
             const doc = await this.readDB.get<T>(id);
-            logger.debug(`Retrieved doc: ${id}`);
 
             // Create a new doc object to apply updates to for this attempt
             let updatedDoc = { ...doc };
@@ -77,7 +103,6 @@ export default class UpdateQueue extends Loggable {
             }
 
             await this.writeDB.put<T>(updatedDoc);
-            logger.debug(`Put doc: ${id}`);
 
             // Success! Remove the updates we just applied.
             this.pendingUpdates[id].splice(0, updatesToApply.length);
@@ -98,6 +123,7 @@ export default class UpdateQueue extends Loggable {
             } else if (e.name === 'not_found' && i === 0) {
               // Document not present - throw to caller for initialization
               logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
+              delete this.inprogressUpdates[id];
               throw e; // Let caller handle
             } else {
               // Max retries reached or a non-conflict error

package/src/impl/static/StaticDataLayerProvider.ts

@@ -37,6 +37,8 @@ export class StaticDataLayerProvider implements DataLayerProvider {
   private initialized: boolean = false;
   private courseUnpackers: Map<string, StaticDataUnpacker> = new Map();
   private manifests: Record<string, StaticCourseManifest> = {};
+  // Mapping from dependency name to actual courseId for backwards compatibility
+  private dependencyNameToCourseId: Map<string, string> = new Map();
 
   constructor(config: Partial<StaticDataLayerConfig>) {
     this.config = {
@@ -70,12 +72,22 @@ export class StaticDataLayerProvider implements DataLayerProvider {
             throw new Error(`Failed to fetch final content manifest for ${courseName} at ${finalManifestUrl}`);
           }
           const finalManifest = await finalManifestResponse.json();
-          
-          this.manifests[courseName] = finalManifest;
+
+          // Extract courseId from the manifest to use as the lookup key
+          const courseId = finalManifest.courseId || finalManifest.courseConfig?.courseID;
+          if (!courseId) {
+            throw new Error(`Course manifest for ${courseName} missing courseId`);
+          }
+
+          this.manifests[courseId] = finalManifest;
           const unpacker = new StaticDataUnpacker(finalManifest, baseUrl);
-          this.courseUnpackers.set(courseName, unpacker);
+          this.courseUnpackers.set(courseId, unpacker);
 
-          logger.info(`[StaticDataLayerProvider] Successfully resolved and prepared course: ${courseName}`);
+          // Also store mapping from dependency name to courseId for backwards compatibility
+          // This allows lookup by either dependency name or courseId
+          this.dependencyNameToCourseId.set(courseName, courseId);
+
+          logger.info(`[StaticDataLayerProvider] Successfully resolved and prepared course: ${courseName} (courseId: ${courseId})`);
         }
       } catch (e) {
         logger.error(`[StaticDataLayerProvider] Failed to resolve dependency ${courseName}:`, e);
@@ -105,16 +117,28 @@ export class StaticDataLayerProvider implements DataLayerProvider {
   }
 
   getCourseDB(courseId: string): CourseDBInterface {
-    const unpacker = this.courseUnpackers.get(courseId);
+    // Try direct lookup by courseId first
+    let unpacker = this.courseUnpackers.get(courseId);
+    let actualCourseId = courseId;
+
+    // If not found, try lookup by dependency name (backwards compatibility)
+    if (!unpacker) {
+      const mappedCourseId = this.dependencyNameToCourseId.get(courseId);
+      if (mappedCourseId) {
+        unpacker = this.courseUnpackers.get(mappedCourseId);
+        actualCourseId = mappedCourseId;
+      }
+    }
+
     if (!unpacker) {
       throw new Error(`Course ${courseId} not found or failed to initialize in static data layer.`);
     }
-    const manifest = this.manifests[courseId];
-    return new StaticCourseDB(courseId, unpacker, this.getUserDB(), manifest);
+    const manifest = this.manifests[actualCourseId];
+    return new StaticCourseDB(actualCourseId, unpacker, this.getUserDB(), manifest);
   }
 
   getCoursesDB(): CoursesDBInterface {
-    return new StaticCoursesDB(this.manifests);
+    return new StaticCoursesDB(this.manifests, this.dependencyNameToCourseId);
   }
 
   async getClassroomDB(

package/src/impl/static/coursesDB.ts

@@ -6,10 +6,23 @@ import { StaticCourseManifest } from '../../util/packer/types';
 import { logger } from '../../util/logger';
 
 export class StaticCoursesDB implements CoursesDBInterface {
-  constructor(private manifests: Record<string, StaticCourseManifest>) {}
+  constructor(
+    private manifests: Record<string, StaticCourseManifest>,
+    private dependencyNameToCourseId?: Map<string, string>
+  ) {}
 
   async getCourseConfig(courseId: string): Promise<CourseConfig> {
-    const manifest = this.manifests[courseId];
+    // Try direct lookup by courseId first
+    let manifest = this.manifests[courseId];
+
+    // If not found, try lookup by dependency name (backwards compatibility)
+    if (!manifest && this.dependencyNameToCourseId) {
+      const mappedCourseId = this.dependencyNameToCourseId.get(courseId);
+      if (mappedCourseId) {
+        manifest = this.manifests[mappedCourseId];
+      }
+    }
+
     if (!manifest) {
       logger.warn(`Course manifest for ${courseId} not found`);
       throw new Error(`Course ${courseId} not found`);

package/src/study/SessionController.ts

@@ -208,6 +208,56 @@ export class SessionController<TView = unknown> extends Loggable {
     return `${this.reviewQ.dequeueCount} Reviews, ${this.newQ.dequeueCount} New, ${this.failedQ.dequeueCount} failed`;
   }
 
+  /**
+   * Returns debug information about the current session state.
+   * Used by SessionControllerDebug component for runtime inspection.
+   */
+  public getDebugInfo() {
+    const extractQueueItems = (queue: ItemQueue<any>, limit: number = 10) => {
+      const items = [];
+      for (let i = 0; i < Math.min(queue.length, limit); i++) {
+        const item = queue.peek(i);
+        items.push({
+          courseID: item.courseID || 'unknown',
+          cardID: item.cardID || 'unknown',
+          status: item.status || 'unknown',
+        });
+      }
+      return items;
+    };
+
+    const extractHydratedItems = () => {
+      // We can't easily iterate the hydrated queue without dequeuing,
+      // so we'll just report the count via hydratedCache.count below
+
+      const items: any[] = [];
+      return items;
+    };
+
+    return {
+      reviewQueue: {
+        length: this.reviewQ.length,
+        dequeueCount: this.reviewQ.dequeueCount,
+        items: extractQueueItems(this.reviewQ),
+      },
+      newQueue: {
+        length: this.newQ.length,
+        dequeueCount: this.newQ.dequeueCount,
+        items: extractQueueItems(this.newQ),
+      },
+      failedQueue: {
+        length: this.failedQ.length,
+        dequeueCount: this.failedQ.dequeueCount,
+        items: extractQueueItems(this.failedQ),
+      },
+      hydratedCache: {
+        count: this.hydrationService.hydratedCount,
+        failedCacheSize: this.hydrationService.failedCacheSize,
+        items: extractHydratedItems(),
+      },
+    };
+  }
+
   private async getScheduledReviews() {
     const reviews = await Promise.all(
       this.sources.map((c) =>

package/src/study/services/CardHydrationService.ts

@@ -79,6 +79,13 @@ export class CardHydrationService<TView = unknown> {
     return this.hydratedQ.length;
   }
 
+  /**
+   * Get current failed card cache size.
+   */
+  public get failedCacheSize(): number {
+    return this.failedCardCache.size;
+  }
+
   /**
    * Fill the hydrated queue up to BUFFER_SIZE with pre-fetched cards.
    */

package/src/study/services/ResponseProcessor.ts

@@ -60,32 +60,71 @@ export class ResponseProcessor {
       };
     }
 
-    const history = await cardHistory;
+    // Debug logging for response processing
+    // logger.debug('[ResponseProcessor] Processing response', {
+    //   cardId,
+    //   courseId,
+    //   isCorrect: cardRecord.isCorrect,
+    //   performance: cardRecord.performance,
+    //   priorAttempts: cardRecord.priorAttemps,
+    //   currentSessionViews: sessionViews,
+    //   maxSessionViews,
+    //   maxAttemptsPerView,
+    //   currentCardRecordsLength: currentCard.records.length,
+    //   studySessionSourceType: studySessionItem.contentSourceType,
+    //   studySessionSourceID: studySessionItem.contentSourceID,
+    //   studySessionItemId: studySessionItem.cardID,
+    //   studySessionItemType: studySessionItem.contentSourceType,
 
-    // 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
-      );
+    //   cardRecordTimestamp: cardRecord.timeStamp,
+    //   cardRecordResponseTime: cardRecord.timeSpent,
+    // });
+
+    try {
+      const history = await cardHistory;
+
+      // Debug logging for card history
+      // logger.debug('[ResponseProcessor] History loaded:', {
+      //   cardId,
+      //   historyRecordsCount: history.records.length,
+      //   historyRecords: history.records.map((record) => ({
+      //     timeStamp: record.timeStamp,
+      //     isCorrect: 'isCorrect' in record ? record.isCorrect : 'N/A',
+      //     performance: 'performance' in record ? record.performance : 'N/A',
+      //     priorAttempts: 'priorAttemps' in record ? record.priorAttemps : 'N/A',
+      //   })),
+      //   firstInteraction: history.records.length === 1,
+      //   lastRecord: history.records[history.records.length - 1],
+      // });
+
+      // 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
+        );
+      }
+    } catch (e: unknown) {
+      logger.error('[ResponseProcessor] Failed to load card history', { e, cardId });
+      throw e;
     }
   }