@vue-skuilder/db 0.1.14-2 → 0.1.14

package/dist/index.d.mts

@@ -331,6 +331,44 @@ declare class SessionController<TView = unknown> extends Loggable {
     get failedCount(): number;
     toString(): string;
     reportString(): string;
+    /**
+     * Returns debug information about the current session state.
+     * Used by SessionControllerDebug component for runtime inspection.
+     */
+    getDebugInfo(): {
+        reviewQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        newQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        failedQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        hydratedCache: {
+            count: number;
+            failedCacheSize: number;
+            items: any[];
+        };
+    };
     private getScheduledReviews;
     private getNewCards;
     private _selectNextItemToHydrate;

package/dist/index.d.ts

@@ -331,6 +331,44 @@ declare class SessionController<TView = unknown> extends Loggable {
     get failedCount(): number;
     toString(): string;
     reportString(): string;
+    /**
+     * Returns debug information about the current session state.
+     * Used by SessionControllerDebug component for runtime inspection.
+     */
+    getDebugInfo(): {
+        reviewQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        newQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        failedQueue: {
+            length: number;
+            dequeueCount: number;
+            items: {
+                courseID: any;
+                cardID: any;
+                status: any;
+            }[];
+        };
+        hydratedCache: {
+            count: number;
+            failedCacheSize: number;
+            items: any[];
+        };
+    };
     private getScheduledReviews;
     private getNewCards;
     private _selectNextItemToHydrate;

package/dist/index.js

@@ -447,6 +447,33 @@ var init_updateQueue = __esm({
       // Database for read operations
       writeDB;
       // 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 });
+       *   }
+       * }
+       * ```
+       */
       update(id, update) {
         logger.debug(`Update requested on doc: ${id}`);
         if (this.pendingUpdates[id]) {
@@ -479,7 +506,6 @@ var init_updateQueue = __esm({
             for (let i = 0; i < MAX_RETRIES; i++) {
               try {
                 const doc = await this.readDB.get(id);
-                logger.debug(`Retrieved doc: ${id}`);
                 let updatedDoc = { ...doc };
                 const updatesToApply = [...this.pendingUpdates[id]];
                 for (const update of updatesToApply) {
@@ -493,7 +519,6 @@ var init_updateQueue = __esm({
                   }
                 }
                 await this.writeDB.put(updatedDoc);
-                logger.debug(`Put doc: ${id}`);
                 this.pendingUpdates[id].splice(0, updatesToApply.length);
                 if (this.pendingUpdates[id].length === 0) {
                   this.inprogressUpdates[id] = false;
@@ -508,6 +533,7 @@ var init_updateQueue = __esm({
                   await new Promise((res) => setTimeout(res, 50 * Math.random()));
                 } else if (e.name === "not_found" && i === 0) {
                   logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
+                  delete this.inprogressUpdates[id];
                   throw e;
                 } else {
                   delete this.inprogressUpdates[id];
@@ -3158,12 +3184,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
        */
       async putCardRecord(record) {
         const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
@@ -4336,6 +4372,8 @@ var init_StaticDataLayerProvider = __esm({
       initialized = false;
       courseUnpackers = /* @__PURE__ */ new Map();
       manifests = {};
+      // Mapping from dependency name to actual courseId for backwards compatibility
+      dependencyNameToCourseId = /* @__PURE__ */ new Map();
       constructor(config) {
         this.config = {
           localStoragePrefix: config.localStoragePrefix || "skuilder-static",
@@ -4363,10 +4401,15 @@ var init_StaticDataLayerProvider = __esm({
                 throw new Error(`Failed to fetch final content manifest for ${courseName} at ${finalManifestUrl}`);
               }
               const finalManifest = await finalManifestResponse.json();
-              this.manifests[courseName] = finalManifest;
+              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);
-              logger.info(`[StaticDataLayerProvider] Successfully resolved and prepared course: ${courseName}`);
+              this.courseUnpackers.set(courseId, unpacker);
+              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);
@@ -4389,12 +4432,20 @@ var init_StaticDataLayerProvider = __esm({
         return BaseUser.Dummy(syncStrategy);
       }
       getCourseDB(courseId) {
-        const unpacker = this.courseUnpackers.get(courseId);
+        let unpacker = this.courseUnpackers.get(courseId);
+        let actualCourseId = courseId;
+        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() {
         return new StaticCoursesDB(this.manifests);
@@ -4952,29 +5003,34 @@ var ResponseProcessor = class {
         shouldClearFeedbackShadow: true
       };
     }
-    const history = await cardHistory;
-    if (cardRecord.isCorrect) {
-      return this.processCorrectResponse(
-        cardRecord,
-        history,
-        studySessionItem,
-        courseRegistrationDoc,
-        currentCard,
-        courseId,
-        cardId
-      );
-    } else {
-      return this.processIncorrectResponse(
-        cardRecord,
-        history,
-        courseRegistrationDoc,
-        currentCard,
-        courseId,
-        cardId,
-        maxAttemptsPerView,
-        maxSessionViews,
-        sessionViews
-      );
+    try {
+      const history = await cardHistory;
+      if (cardRecord.isCorrect) {
+        return this.processCorrectResponse(
+          cardRecord,
+          history,
+          studySessionItem,
+          courseRegistrationDoc,
+          currentCard,
+          courseId,
+          cardId
+        );
+      } else {
+        return this.processIncorrectResponse(
+          cardRecord,
+          history,
+          courseRegistrationDoc,
+          currentCard,
+          courseId,
+          cardId,
+          maxAttemptsPerView,
+          maxSessionViews,
+          sessionViews
+        );
+      }
+    } catch (e) {
+      logger.error("[ResponseProcessor] Failed to load card history", { e, cardId });
+      throw e;
     }
   }
   /**
@@ -5175,6 +5231,12 @@ var CardHydrationService = class {
   get hydratedCount() {
     return this.hydratedQ.length;
   }
+  /**
+   * Get current failed card cache size.
+   */
+  get failedCacheSize() {
+    return this.failedCardCache.size;
+  }
   /**
    * Fill the hydrated queue up to BUFFER_SIZE with pre-fetched cards.
    */
@@ -6787,6 +6849,50 @@ var SessionController = class extends Loggable {
   reportString() {
     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.
+   */
+  getDebugInfo() {
+    const extractQueueItems = (queue, limit = 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 = () => {
+      const items = [];
+      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()
+      }
+    };
+  }
   async getScheduledReviews() {
     const reviews = await Promise.all(
       this.sources.map(