@vue-skuilder/db 0.1.14-2 → 0.1.14

package/dist/impl/static/index.mjs

@@ -258,6 +258,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]) {
@@ -290,7 +317,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) {
@@ -304,7 +330,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;
@@ -319,6 +344,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];
@@ -1483,12 +1509,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);
@@ -2676,6 +2712,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",
@@ -2703,10 +2741,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);
@@ -2729,12 +2772,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);