@vue-skuilder/db 0.2.13 → 0.2.15

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.2.13",
+    "@vue-skuilder/common": "0.2.15",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.13"
+  "stableVersion": "0.2.15"
 }

package/src/core/interfaces/userDB.ts

@@ -55,6 +55,14 @@ export interface UserDBReader {
    */
   getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
 
+  /**
+   * Get all scheduled reviews due within the next `daysCount` days —
+   * including ones not yet due. `getPendingReviews` is the `daysCount = 0`
+   * special case: it returns only reviews already due, so a review scheduled
+   * moments ago (necessarily in the future) will never appear in it.
+   */
+  getReviewsForcast(daysCount: number, courseId?: string): Promise<ScheduledCard[]>;
+
   getActivityRecords(): Promise<ActivityRecord[]>;
 
   /**

package/src/impl/common/BaseUserDB.ts

@@ -416,9 +416,9 @@ Currently logged-in as ${this._username}.`
       .map((r) => r.doc!);
   }
 
-  public async getReviewsForcast(daysCount: number) {
+  public async getReviewsForcast(daysCount: number, course_id?: string) {
     const time = moment.utc().add(daysCount, 'days');
-    return this.getReviewstoDate(time);
+    return this.getReviewstoDate(time, course_id);
   }
 
   public async getPendingReviews(course_id?: string) {

package/src/impl/common/userDBHelpers.ts

@@ -7,6 +7,19 @@ import { ScheduledCard } from '@db/core/types/user';
 
 export const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';
 
+/**
+ * Build a ScheduledCard `_id` for the given review time.
+ *
+ * The id suffix is not a mere uniquifier: `getReviewstoDate` PARSES the id
+ * (with {@link REVIEW_TIME_FORMAT}) to decide due-ness, so the id is the
+ * datum. Anything that writes or rewrites scheduled-card docs (scheduling,
+ * user-state snapshot rebasing) must construct ids through this helper —
+ * a hand-rolled formatter will get moment's `kk` token (01-24 hours) wrong.
+ */
+export function makeScheduledCardId(reviewTime: string | Date | moment.Moment): string {
+  return DocTypePrefixes[DocType.SCHEDULED_CARD] + moment.utc(reviewTime).format(REVIEW_TIME_FORMAT);
+}
+
 import pouch from '../couch/pouchdb-setup';
 import { getDbPath } from '../../util/dataDirectory';
 
@@ -123,7 +136,7 @@ export function scheduleCardReviewLocal(
   const now = moment.utc();
   logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);
   void userDB.put<ScheduledCard>({
-    _id: DocTypePrefixes[DocType.SCHEDULED_CARD] + review.time.format(REVIEW_TIME_FORMAT),
+    _id: makeScheduledCardId(review.time),
     cardId: review.card_id,
     reviewTime: review.time.toISOString(),
     courseId: review.course_id,

package/src/index.ts

@@ -9,6 +9,12 @@ export * from './study';
 export * from './util';
 export * from './factory';
 
+// Scheduled-card id construction: the id embeds the review time and is parsed
+// by the due-review read path, so out-of-tree writers (e.g. user-state
+// snapshot rebasing) must build ids with this rather than reimplementing the
+// moment format.
+export { REVIEW_TIME_FORMAT, makeScheduledCardId } from './impl/common/userDBHelpers';
+
 // Export CouchDB user types for use in Express backend
 export type {
   UserAccountStatus,

package/src/study/SessionOverlay.ts

@@ -81,6 +81,19 @@ export interface SessionDebugTarget {
   getDebugSnapshot(): SessionDebugSnapshot;
 }
 
+/**
+ * The live-session surface available to out-of-tree callers through the
+ * active-controller registry: the debug snapshot, plus the small set of
+ * user-facing session controls a view may need without holding a ref into
+ * the `<StudySession>` component's internals (e.g. wiring a timer's
+ * add-time button from a composable). Keep this narrow — it is not a
+ * general escape hatch to `SessionController`.
+ */
+export interface ActiveSessionHandle extends SessionDebugTarget {
+  /** Extend the session clock by `seconds`. */
+  addTime(seconds: number): void;
+}
+
 // ----------------------------------------------------------------------------
 // Active-controller registry
 // ----------------------------------------------------------------------------
@@ -90,14 +103,14 @@ export interface SessionDebugTarget {
 // registrar without pulling in the overlay's DOM code or risking an import
 // cycle with SessionDebugger.
 
-let activeController: SessionDebugTarget | null = null;
+let activeController: ActiveSessionHandle | null = null;
 
 /** Called by SessionController's constructor. Pass `null` to deregister. */
-export function registerActiveController(controller: SessionDebugTarget | null): void {
+export function registerActiveController(controller: ActiveSessionHandle | null): void {
   activeController = controller;
 }
 
-export function getActiveController(): SessionDebugTarget | null {
+export function getActiveController(): ActiveSessionHandle | null {
   return activeController;
 }
 

package/src/study/index.ts

@@ -4,3 +4,7 @@ export * from './SpacedRepetition';
 export * from './TagFilteredContentSource';
 export * from './MixerDebugger';
 export * from './SessionDebugger';
+// `getActiveController()` + `SessionDebugSnapshot` — the live-state read the
+// SessionOverlay renders internally. Exported so hosts can build their own UI
+// over the same snapshot (LettersPractice's /showHN annotated view does).
+export * from './SessionOverlay';

package/src/study/services/EloService.ts

@@ -41,14 +41,20 @@ export class EloService {
       logger.warn(`k value interpretation not currently implemented`);
     }
     const courseDB = this.dataLayer.getCourseDB(currentCard.card.course_id);
-    const userElo = toCourseElo(
-      userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo
-    );
+    const courseReg = userCourseRegDoc.courses.find((c) => c.courseID === course_id);
+    if (!courseReg) {
+      logger.error(
+        `[EloService] No registration for course ${course_id} on user's registration doc — ` +
+          `skipping ELO update for card ${card_id}. (Is the user registered for this course?)`
+      );
+      return;
+    }
+    const userElo = toCourseElo(courseReg.elo);
     const cardElo = (await courseDB.getCardEloData([currentCard.card.card_id]))[0];
 
     if (cardElo && userElo) {
       const eloUpdate = adjustCourseScores(userElo, cardElo, userScore);
-      userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo = eloUpdate.userElo;
+      courseReg.elo = eloUpdate.userElo;
 
       const results = await Promise.allSettled([
         this.user.updateUserElo(course_id, eloUpdate.userElo),
@@ -108,9 +114,15 @@ export class EloService {
     currentCard: StudySessionRecord
   ): Promise<void> {
     const courseDB = this.dataLayer.getCourseDB(currentCard.card.course_id);
-    const userElo = toCourseElo(
-      userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo
-    );
+    const courseReg = userCourseRegDoc.courses.find((c) => c.courseID === course_id);
+    if (!courseReg) {
+      logger.error(
+        `[EloService] No registration for course ${course_id} on user's registration doc — ` +
+          `skipping per-tag ELO update for card ${card_id}. (Is the user registered for this course?)`
+      );
+      return;
+    }
+    const userElo = toCourseElo(courseReg.elo);
 
     const [cardEloResults, cardTagsMap] = await Promise.all([
       courseDB.getCardEloData([currentCard.card.card_id]),
@@ -134,7 +146,7 @@ export class EloService {
 
     if (cardElo && userElo) {
       const eloUpdate = adjustCourseScoresPerTag(userElo, cardElo, enriched);
-      userCourseRegDoc.courses.find((c) => c.courseID === course_id)!.elo = eloUpdate.userElo;
+      courseReg.elo = eloUpdate.userElo;
 
       const results = await Promise.allSettled([
         this.user.updateUserElo(course_id, eloUpdate.userElo),

package/src/study/services/ResponseProcessor.ts

@@ -35,6 +35,16 @@ export class ResponseProcessor {
     this.eloService = eloService;
   }
 
+  /**
+   * ELO updates are fired without awaiting so response handling isn't blocked
+   * on DB writes — but an unhandled rejection silently drops the update.
+   * This produces a catch handler that surfaces the failure in logs.
+   */
+  private logEloFailure(context: string, cardId: string): (e: unknown) => void {
+    return (e) =>
+      logger.error(`[ResponseProcessor] ELO update failed (${context}) for ${cardId}:`, e);
+  }
+
   /**
    * Parses performance data into global score and optional per-tag scores.
    *
@@ -194,37 +204,37 @@ export class ResponseProcessor {
             `scored=[${scoredTags.join(', ')}] count-only=[${nullTags.join(', ')}]`
         );
 
-        void this.eloService.updateUserAndCardEloPerTag(
-          taggedPerformance,
-          courseId,
-          cardId,
-          courseRegistrationDoc,
-          currentCard
-        );
+        void this.eloService
+          .updateUserAndCardEloPerTag(
+            taggedPerformance,
+            courseId,
+            cardId,
+            courseRegistrationDoc,
+            currentCard
+          )
+          .catch(this.logEloFailure('correct per-tag', cardId));
       } else {
         // Standard single-score ELO update (backward compatible)
         const userScore = 0.5 + globalScore / 2;
 
         if (history.records.length === 1) {
           // First interaction with this card - standard ELO update
-          void this.eloService.updateUserAndCardElo(
-            userScore,
-            courseId,
-            cardId,
-            courseRegistrationDoc,
-            currentCard
-          );
+          void this.eloService
+            .updateUserAndCardElo(userScore, courseId, cardId, courseRegistrationDoc, currentCard)
+            .catch(this.logEloFailure('correct', cardId));
         } else {
           // Multiple interactions - reduce K-factor to limit ELO volatility
           const k = Math.ceil(32 / history.records.length);
-          void this.eloService.updateUserAndCardElo(
-            userScore,
-            courseId,
-            cardId,
-            courseRegistrationDoc,
-            currentCard,
-            k
-          );
+          void this.eloService
+            .updateUserAndCardElo(
+              userScore,
+              courseId,
+              cardId,
+              courseRegistrationDoc,
+              currentCard,
+              k
+            )
+            .catch(this.logEloFailure('correct repeat-view', cardId));
         }
         logger.info(
           `[FirstContactElo] correct first-attempt ELO update (score=${userScore.toFixed(3)}) ` +
@@ -286,13 +296,15 @@ export class ResponseProcessor {
     if (cardRecord.priorAttemps === 0) {
       if (taggedPerformance) {
         // Per-tag ELO update for incorrect response
-        void this.eloService.updateUserAndCardEloPerTag(
-          taggedPerformance,
-          courseId,
-          cardId,
-          courseRegistrationDoc,
-          currentCard
-        );
+        void this.eloService
+          .updateUserAndCardEloPerTag(
+            taggedPerformance,
+            courseId,
+            cardId,
+            courseRegistrationDoc,
+            currentCard
+          )
+          .catch(this.logEloFailure('incorrect per-tag', cardId));
         logger.info(
           `[FirstContactElo] incorrect first-attempt per-tag ELO update for ${cardId} ` +
             `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps}, ` +
@@ -300,13 +312,15 @@ export class ResponseProcessor {
         );
       } else {
         // Standard single-score ELO update
-        void this.eloService.updateUserAndCardElo(
-          0, // Failed response = 0 score
-          courseId,
-          cardId,
-          courseRegistrationDoc,
-          currentCard
-        );
+        void this.eloService
+          .updateUserAndCardElo(
+            0, // Failed response = 0 score
+            courseId,
+            cardId,
+            courseRegistrationDoc,
+            currentCard
+          )
+          .catch(this.logEloFailure('incorrect', cardId));
         logger.info(
           `[FirstContactElo] incorrect first-attempt ELO update (score=0) for ${cardId} ` +
             `(historyLen=${history.records.length}, priorAttemps=${cardRecord.priorAttemps})`
@@ -329,21 +343,19 @@ export class ResponseProcessor {
         if (!eloUpdated) {
           if (taggedPerformance) {
             // Use tagged performance for final failure
-            void this.eloService.updateUserAndCardEloPerTag(
-              taggedPerformance,
-              courseId,
-              cardId,
-              courseRegistrationDoc,
-              currentCard
-            );
+            void this.eloService
+              .updateUserAndCardEloPerTag(
+                taggedPerformance,
+                courseId,
+                cardId,
+                courseRegistrationDoc,
+                currentCard
+              )
+              .catch(this.logEloFailure('dismiss-failed per-tag', cardId));
           } else {
-            void this.eloService.updateUserAndCardElo(
-              0,
-              courseId,
-              cardId,
-              courseRegistrationDoc,
-              currentCard
-            );
+            void this.eloService
+              .updateUserAndCardElo(0, courseId, cardId, courseRegistrationDoc, currentCard)
+              .catch(this.logEloFailure('dismiss-failed', cardId));
           }
           logger.info(
             `[FirstContactElo] dismiss-failed final ELO penalty for ${cardId} ` +