@vue-skuilder/db 0.1.14-2 → 0.1.15

package/dist/impl/couch/index.mjs

@@ -129,6 +129,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]) {
@@ -161,7 +188,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) {
@@ -175,7 +201,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;
@@ -190,6 +215,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];
@@ -2726,12 +2752,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);