@vue-skuilder/db 0.2.14 → 0.2.15

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.14",
+  "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.14",
+    "@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.14"
+  "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';