@vue-skuilder/db 0.2.17 → 0.2.19

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-Brz42x7n.cjs';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-Brz42x7n.cjs';
-import { D as DataLayerProvider } from './dataLayerProvider-CpwpT1rM.cjs';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-D-LQYFyx.cjs';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ah as DocumentUpdater, a9 as GeneratorContext, P as HYDRATION_MARKER_ID, Q as HydrationMarker, ab as LearnableWeight, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, ac as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, a1 as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, M as UserOutcomeRecord, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, ai as newInterval, X as registerNavigator } from './contentSource-D-LQYFyx.cjs';
+import { D as DataLayerProvider } from './dataLayerProvider-Dd2UcCif.cjs';
 import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.cjs';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.cjs';
 import { SrsBacklogDebug, StrategyPressureDebug, Loggable } from './core/index.cjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-B1p-vdz7.js';
-export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a4 as CardGenerator, a6 as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ad as DocumentUpdater, a5 as GeneratorContext, a7 as LearnableWeight, N as NavigatorConstructor, a0 as NavigatorRole, a1 as NavigatorRoles, $ as Navigators, a8 as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, Z as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, M as UserOutcomeRecord, B as UsrCrsDataInterface, a9 as computeDeviation, ab as computeEffectiveWeight, aa as computeSpread, ac as createOrchestrationContext, _ as getCardOrigin, P as getRegisteredNavigator, X as getRegisteredNavigatorNames, V as getRegisteredNavigatorRole, r as getStudySource, Q as hasRegisteredNavigator, Y as initializeNavigatorRegistry, a3 as isFilter, a2 as isGenerator, p as isReview, ae as newInterval, O as registerNavigator } from './contentSource-B1p-vdz7.js';
-import { D as DataLayerProvider } from './dataLayerProvider-BWayUIoK.js';
+import { U as UserDBInterface, s as CourseRegistrationDoc, S as StudySessionItem, W as WeightedCard, R as ReplanHints, h as StudyContentSource, G as GeneratorResult, C as CourseDBInterface } from './contentSource-BDRX_YYJ.js';
+export { K as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, a8 as CardGenerator, aa as CardGeneratorFactory, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, H as ClassroomRegistrationDoc, e as ContentNavigationStrategyData, f as ContentNavigator, q as ContentSourceID, d as CourseInfo, L as CourseRegistration, b as CoursesDBInterface, ah as DocumentUpdater, a9 as GeneratorContext, P as HYDRATION_MARKER_ID, Q as HydrationMarker, ab as LearnableWeight, V as NavigatorConstructor, a4 as NavigatorRole, a5 as NavigatorRoles, a3 as Navigators, ac as OrchestrationContext, j as ScheduledCard, I as SessionTrackingData, a1 as StrategyContribution, i as StudentClassroomDBInterface, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, T as TeacherClassroomDBInterface, J as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, N as UserHydrationState, O as UserHydrationStatus, M as UserOutcomeRecord, B as UsrCrsDataInterface, ad as computeDeviation, af as computeEffectiveWeight, ae as computeSpread, ag as createOrchestrationContext, a2 as getCardOrigin, Y as getRegisteredNavigator, $ as getRegisteredNavigatorNames, _ as getRegisteredNavigatorRole, r as getStudySource, Z as hasRegisteredNavigator, a0 as initializeNavigatorRegistry, a7 as isFilter, a6 as isGenerator, p as isReview, ai as newInterval, X as registerNavigator } from './contentSource-BDRX_YYJ.js';
+import { D as DataLayerProvider } from './dataLayerProvider-Dpshuql4.js';
 import { C as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-4tlwHnXo.js';
 export { e as CardData, f as CourseListData, h as DataShapeData, g as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, i as QuestionData, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-4tlwHnXo.js';
 import { SrsBacklogDebug, StrategyPressureDebug, Loggable } from './core/index.js';

package/dist/index.js

@@ -7357,6 +7357,8 @@ var init_CouchDBSyncStrategy = __esm({
     CouchDBSyncStrategy = class {
       syncHandle;
       // Handle to cancel sync if needed
+      /** In-flight one-shot hydration pull, so a timed-out pull can be abandoned. */
+      hydrationHandle;
       setupRemoteDB(username) {
         if (username === GuestUsername || username.startsWith(GuestUsername)) {
           return getLocalUserDB(username);
@@ -7371,8 +7373,26 @@ var init_CouchDBSyncStrategy = __esm({
           return this.getUserDB(username);
         }
       }
+      /**
+       * One-shot remote → local pull. Resolves once the local mirror is caught up.
+       *
+       * Pull only: pushing here would upload whatever the local DB happens to hold
+       * before we know what the remote already has, which is the conflict-leaf
+       * problem hydration exists to avoid. Local changes go up when startSync()
+       * takes over.
+       */
+      async hydrate(localDB, remoteDB) {
+        const replication = pouchdb_setup_default.replicate(remoteDB, localDB, {});
+        this.hydrationHandle = replication;
+        try {
+          const info = await replication;
+          return { docsWritten: info.docs_written };
+        } finally {
+          this.hydrationHandle = void 0;
+        }
+      }
       startSync(localDB, remoteDB) {
-        if (localDB !== remoteDB) {
+        if (localDB.name !== remoteDB.name) {
           this.syncHandle = pouchdb_setup_default.sync(localDB, remoteDB, {
             live: true,
             retry: true
@@ -7380,8 +7400,20 @@ var init_CouchDBSyncStrategy = __esm({
         }
       }
       stopSync() {
+        if (this.hydrationHandle) {
+          try {
+            this.hydrationHandle.cancel();
+          } catch (e) {
+            logger.warn(`Failed to cancel hydration pull (continuing anyway): ${e}`);
+          }
+          this.hydrationHandle = void 0;
+        }
         if (this.syncHandle) {
-          this.syncHandle.cancel();
+          try {
+            this.syncHandle.cancel();
+          } catch (e) {
+            logger.warn(`Failed to cancel user sync (continuing anyway): ${e}`);
+          }
           this.syncHandle = void 0;
         }
       }
@@ -7650,6 +7682,19 @@ var init_couch = __esm({
 });
 
 // src/impl/common/BaseUserDB.ts
+function withTimeout(p, ms, label) {
+  let timer;
+  return Promise.race([
+    p,
+    new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    })
+  ]).finally(() => {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  });
+}
 function accomodateGuest() {
   logger.log("[funnel] accomodateGuest() called");
   if (typeof localStorage === "undefined") {
@@ -7823,7 +7868,7 @@ async function dropUserFromClassroom(user, classID) {
 async function getUserClassrooms(user) {
   return getOrCreateClassroomRegistrationsDoc(user);
 }
-var import_common12, import_moment6, log4, BaseUser, userCoursesDoc, userClassroomsDoc;
+var import_common12, import_moment6, log4, HYDRATION_TIMEOUT_MS, BaseUser, userCoursesDoc, userClassroomsDoc;
 var init_BaseUserDB = __esm({
   "src/impl/common/BaseUserDB.ts"() {
     "use strict";
@@ -7840,6 +7885,7 @@ var init_BaseUserDB = __esm({
     log4 = (s) => {
       logger.info(s);
     };
+    HYDRATION_TIMEOUT_MS = 15e3;
     BaseUser = class _BaseUser {
       static _instance;
       static _initialized = false;
@@ -7868,6 +7914,49 @@ var init_BaseUserDB = __esm({
       writeDB;
       // Database to use for write operations (local-first approach)
       updateQueue;
+      _hydration = { state: "not-required" };
+      /** In-flight hydration, so concurrent callers can wait for a real answer. */
+      _hydrationPromise = null;
+      /**
+       * How far the local mirror can be trusted, RIGHT NOW. See
+       * {@link UserHydrationStatus}.
+       *
+       * This is a snapshot, and during login it can legitimately read
+       * `hydrating` — prefer awaitHydration() anywhere a decision hangs on the
+       * answer.
+       */
+      hydrationStatus() {
+        return { ...this._hydration };
+      }
+      /**
+       * The hydration status once it has settled — never `hydrating`.
+       *
+       * Resolves immediately unless a pull is in flight. Exists for callers that
+       * must decide something (a route guard, a first-run branch) and would
+       * otherwise sample `hydrating` and guess. Since init() is awaited by both
+       * app startup and login(), that only happens when something navigates
+       * concurrently with a login still in progress — a window that stretches to
+       * HYDRATION_TIMEOUT_MS on a slow connection.
+       */
+      async awaitHydration() {
+        try {
+          await this._hydrationPromise;
+        } catch {
+        }
+        return this.hydrationStatus();
+      }
+      /**
+       * Whether a missing document may be treated as genuinely absent, allowing
+       * callers to create it with defaults.
+       *
+       * False only when hydration failed or is still running: a 404 then may just
+       * mean "not pulled down yet", and materializing a default would both lie to
+       * the user and, once live sync starts, push a rev-1 document that loses to
+       * the real one — silently discarding it.
+       */
+      canMaterializeDefaults() {
+        return this._hydration.state !== "failed" && this._hydration.state !== "hydrating";
+      }
       async createAccount(username, password) {
         if (!this.syncStrategy.canCreateAccount()) {
           throw new Error("Account creation not supported by current sync strategy");
@@ -7985,6 +8074,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           if (err.status === 404) {
+            if (!this.canMaterializeDefaults()) {
+              throw new Error(
+                `Cannot read course registrations for ${this._username}: the local mirror is unavailable (hydration state '${this._hydration.state}'). Refusing to create an empty registration doc \u2014 that would report an existing user as unregistered, and then lose to their real document once sync resumes.`
+              );
+            }
             await this.localDB.put({
               _id: _BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
               courses: [],
@@ -8227,6 +8321,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           if (err.name && err.name === "not_found") {
+            if (!this.canMaterializeDefaults()) {
+              throw new Error(
+                `Cannot read config for ${this._username}: the local mirror is unavailable (hydration state '${this._hydration.state}'). Refusing to write a default config over what may be an existing one.`
+              );
+            }
             await this.localDB.put(defaultConfig);
             return this.getConfig();
           } else {
@@ -8300,7 +8399,10 @@ Currently logged-in as ${this._username}.`
           _BaseUser._initialized = true;
           return;
         }
+        this.syncStrategy.stopSync?.();
         this.setDBandQ();
+        this._hydrationPromise = this.hydrateLocalMirror();
+        await this._hydrationPromise;
         this.syncStrategy.startSync(this.localDB, this.remoteDB);
         this.applyDesignDocs().catch((error) => {
           log4(`Error in applyDesignDocs background task: ${error}`);
@@ -8316,6 +8418,85 @@ Currently logged-in as ${this._username}.`
         });
         _BaseUser._initialized = true;
       }
+      /**
+       * Pull this account's documents into the local mirror, if that hasn't
+       * happened on this device before.
+       *
+       * Runs between setDBandQ() and startSync() — after the handles exist, before
+       * anything can observe an empty local DB or replicate one upward.
+       *
+       * Never throws: a failure is recorded as `failed` state and reported through
+       * hydrationStatus(), because throwing here would abort init() and leave
+       * BaseUser._initialized false forever (BaseUser.instance() polls it with no
+       * ceiling). Callers decide what a failure means for them.
+       */
+      async hydrateLocalMirror() {
+        if (this.localDB.name === this.remoteDB.name || !this.syncStrategy.hydrate) {
+          this._hydration = { state: "not-required" };
+          return;
+        }
+        if (await this.hasHydrationMarker()) {
+          this._hydration = { state: "stale" };
+          return;
+        }
+        this._hydration = { state: "hydrating" };
+        const start = Date.now();
+        try {
+          const { docsWritten } = await withTimeout(
+            this.syncStrategy.hydrate(this.localDB, this.remoteDB),
+            HYDRATION_TIMEOUT_MS,
+            `Hydration of local mirror for ${this._username}`
+          );
+          await this.writeHydrationMarker();
+          this._hydration = {
+            state: "hydrated",
+            docsWritten,
+            durationMs: Date.now() - start
+          };
+          log4(
+            `Hydrated local mirror for ${this._username}: ${docsWritten} docs in ${this._hydration.durationMs}ms`
+          );
+        } catch (e) {
+          this.syncStrategy.stopSync?.();
+          this._hydration = {
+            state: "failed",
+            durationMs: Date.now() - start,
+            error: e instanceof Error ? e.message : String(e)
+          };
+          logger.error(`Failed to hydrate local mirror for ${this._username}:`, e);
+        }
+      }
+      /**
+       * Has a full pull completed on this device for the CURRENT account?
+       *
+       * The marker is a `_local/` document, which never replicates — so its
+       * presence describes this device's mirror and cannot arrive from elsewhere.
+       */
+      async hasHydrationMarker() {
+        try {
+          const marker = await this.localDB.get(HYDRATION_MARKER_ID);
+          return marker.username === this._username;
+        } catch {
+          return false;
+        }
+      }
+      async writeHydrationMarker() {
+        try {
+          let existingRev;
+          try {
+            existingRev = (await this.localDB.get(HYDRATION_MARKER_ID))._rev;
+          } catch {
+          }
+          await this.localDB.put({
+            _id: HYDRATION_MARKER_ID,
+            _rev: existingRev,
+            username: this._username,
+            hydratedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch (e) {
+          logger.warn(`Could not write hydration marker for ${this._username}: ${e}`);
+        }
+      }
       static designDocs = [
         {
           _id: "_design/reviewCards",
@@ -8652,6 +8833,11 @@ Currently logged-in as ${this._username}.`
         } catch (e) {
           const err = e;
           if (err.status === 404) {
+            if (!this.canMaterializeDefaults()) {
+              throw new Error(
+                `Cannot read strategy state '${strategyKey}' for ${this._username}: the local mirror is unavailable (hydration state '${this._hydration.state}').`
+              );
+            }
             return null;
           }
           throw e;
@@ -10172,6 +10358,15 @@ var init_userOutcome = __esm({
   }
 });
 
+// src/core/types/hydration.ts
+var HYDRATION_MARKER_ID;
+var init_hydration = __esm({
+  "src/core/types/hydration.ts"() {
+    "use strict";
+    HYDRATION_MARKER_ID = "_local/hydration";
+  }
+});
+
 // src/core/bulkImport/cardProcessor.ts
 async function importParsedCards(parsedCards, courseDB, config) {
   const results = [];
@@ -10652,6 +10847,7 @@ var init_core = __esm({
     init_user();
     init_strategyState();
     init_userOutcome();
+    init_hydration();
     init_Loggable();
     init_util();
     init_navigators();
@@ -10674,6 +10870,7 @@ __export(index_exports, {
   ENV: () => ENV,
   FileSystemError: () => FileSystemError,
   GuestUsername: () => GuestUsername,
+  HYDRATION_MARKER_ID: () => HYDRATION_MARKER_ID,
   Loggable: () => Loggable,
   NOT_SET: () => NOT_SET,
   NavigatorRole: () => NavigatorRole,
@@ -15454,6 +15651,7 @@ init_userDBHelpers();
   ENV,
   FileSystemError,
   GuestUsername,
+  HYDRATION_MARKER_ID,
   Loggable,
   NOT_SET,
   NavigatorRole,