@vue-skuilder/db 0.2.18 → 0.2.20

package/dist/{dataLayerProvider-BBA8tJNx.d.cts → dataLayerProvider-Dd2UcCif.d.cts}

@@ -1,4 +1,4 @@
-import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-CBqZCoGU.cjs';
+import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-D-LQYFyx.cjs';
 
 /**
  * Main factory interface for data access

package/dist/{dataLayerProvider-C9WgkBzR.d.ts → dataLayerProvider-Dpshuql4.d.ts}

@@ -1,4 +1,4 @@
-import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-CudEz5Tm.js';
+import { U as UserDBInterface, a as UserDBReader, C as CourseDBInterface, b as CoursesDBInterface, c as ClassroomDBInterface, A as AdminDBInterface } from './contentSource-BDRX_YYJ.js';
 
 /**
  * Main factory interface for data access

package/dist/impl/couch/index.d.cts

@@ -1,10 +1,10 @@
 import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-4tlwHnXo.cjs';
 import { Moment } from 'moment';
-import { A as AdminDBInterface, g as AssignedContent, h as StudyContentSource, i as StudentClassroomDBInterface, U as UserDBInterface, G as GeneratorResult, T as TeacherClassroomDBInterface, b as CoursesDBInterface, C as CourseDBInterface, d as CourseInfo, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, S as StudySessionItem, j as ScheduledCard } from '../../contentSource-CBqZCoGU.cjs';
-export { q as ContentSourceID, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, r as getStudySource, p as isReview } from '../../contentSource-CBqZCoGU.cjs';
+import { A as AdminDBInterface, g as AssignedContent, h as StudyContentSource, i as StudentClassroomDBInterface, U as UserDBInterface, G as GeneratorResult, T as TeacherClassroomDBInterface, b as CoursesDBInterface, C as CourseDBInterface, d as CourseInfo, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, S as StudySessionItem, j as ScheduledCard } from '../../contentSource-D-LQYFyx.cjs';
+export { q as ContentSourceID, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, r as getStudySource, p as isReview } from '../../contentSource-D-LQYFyx.cjs';
 import * as _vue_skuilder_common from '@vue-skuilder/common';
 import { ClassroomConfig, DataShape, CourseElo, CourseConfig as CourseConfig$1 } from '@vue-skuilder/common';
-import { S as SyncStrategy, A as AccountCreationResult, a as AuthenticationResult } from '../../SyncStrategy-BJMZq3WO.cjs';
+import { S as SyncStrategy, A as AccountCreationResult, a as AuthenticationResult } from '../../SyncStrategy-CCU1H81I.cjs';
 
 type NamespacedDatashape = string;
 interface DataShape55 {
@@ -508,11 +508,27 @@ declare class CouchDBSyncStrategy implements SyncStrategy {
      * 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.
+     *
+     * Into an EMPTY local DB this skips deleted documents, because a mirror that
+     * never held a document does not need to be told it was removed. That
+     * matters more than it sounds: scheduled reviews (`card_review_*`) are
+     * created and deleted once per review completed, so the changes feed is
+     * dominated by tombstones and grows without bound, while the durable record
+     * lives in card history. One real account measured 385 live documents behind
+     * 8,370 deletions — an unfiltered pull moved 9,520 documents and took ~20s,
+     * blowing the hydration timeout on a phone; filtered, the same pull moves
+     * 404 and takes ~2s, reaching a byte-identical local state.
+     *
+     * The filter runs server-side, so `last_seq` still reports the source's true
+     * sequence. Returning it lets startSync() begin the live pull from there
+     * instead of re-walking the same history in the background — without that,
+     * the cost is merely deferred, not removed.
      */
     hydrate(localDB: PouchDB.Database, remoteDB: PouchDB.Database): Promise<{
         docsWritten: number;
+        lastSeq?: string | number;
     }>;
-    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database, since?: string | number): void;
     stopSync?(): void;
     canCreateAccount(): boolean;
     canAuthenticate(): boolean;

package/dist/impl/couch/index.d.ts

@@ -1,10 +1,10 @@
 import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-4tlwHnXo.js';
 import { Moment } from 'moment';
-import { A as AdminDBInterface, g as AssignedContent, h as StudyContentSource, i as StudentClassroomDBInterface, U as UserDBInterface, G as GeneratorResult, T as TeacherClassroomDBInterface, b as CoursesDBInterface, C as CourseDBInterface, d as CourseInfo, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, S as StudySessionItem, j as ScheduledCard } from '../../contentSource-CudEz5Tm.js';
-export { q as ContentSourceID, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, r as getStudySource, p as isReview } from '../../contentSource-CudEz5Tm.js';
+import { A as AdminDBInterface, g as AssignedContent, h as StudyContentSource, i as StudentClassroomDBInterface, U as UserDBInterface, G as GeneratorResult, T as TeacherClassroomDBInterface, b as CoursesDBInterface, C as CourseDBInterface, d as CourseInfo, D as DataLayerResult, e as ContentNavigationStrategyData, f as ContentNavigator, R as ReplanHints, S as StudySessionItem, j as ScheduledCard } from '../../contentSource-BDRX_YYJ.js';
+export { q as ContentSourceID, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, n as StudySessionNewItem, o as StudySessionReviewItem, r as getStudySource, p as isReview } from '../../contentSource-BDRX_YYJ.js';
 import * as _vue_skuilder_common from '@vue-skuilder/common';
 import { ClassroomConfig, DataShape, CourseElo, CourseConfig as CourseConfig$1 } from '@vue-skuilder/common';
-import { S as SyncStrategy, A as AccountCreationResult, a as AuthenticationResult } from '../../SyncStrategy-BJMZq3WO.js';
+import { S as SyncStrategy, A as AccountCreationResult, a as AuthenticationResult } from '../../SyncStrategy-CCU1H81I.js';
 
 type NamespacedDatashape = string;
 interface DataShape55 {
@@ -508,11 +508,27 @@ declare class CouchDBSyncStrategy implements SyncStrategy {
      * 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.
+     *
+     * Into an EMPTY local DB this skips deleted documents, because a mirror that
+     * never held a document does not need to be told it was removed. That
+     * matters more than it sounds: scheduled reviews (`card_review_*`) are
+     * created and deleted once per review completed, so the changes feed is
+     * dominated by tombstones and grows without bound, while the durable record
+     * lives in card history. One real account measured 385 live documents behind
+     * 8,370 deletions — an unfiltered pull moved 9,520 documents and took ~20s,
+     * blowing the hydration timeout on a phone; filtered, the same pull moves
+     * 404 and takes ~2s, reaching a byte-identical local state.
+     *
+     * The filter runs server-side, so `last_seq` still reports the source's true
+     * sequence. Returning it lets startSync() begin the live pull from there
+     * instead of re-walking the same history in the background — without that,
+     * the cost is merely deferred, not removed.
      */
     hydrate(localDB: PouchDB.Database, remoteDB: PouchDB.Database): Promise<{
         docsWritten: number;
+        lastSeq?: string | number;
     }>;
-    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+    startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database, since?: string | number): void;
     stopSync?(): void;
     canCreateAccount(): boolean;
     canAuthenticate(): boolean;

package/dist/impl/couch/index.js

@@ -7561,16 +7561,44 @@ var init_BaseUserDB = __esm({
       // 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. See {@link UserHydrationStatus}.
+       * Sequence the local mirror was filled to by a hydration that succeeded in
+       * THIS init(), handed to startSync() so the live pull can skip history it
+       * would otherwise re-walk. Undefined whenever there is no such guarantee —
+       * hydration skipped, not required, or failed. Never persisted; see the
+       * `since` note in CouchDBSyncStrategy.startSync().
+       */
+      _hydratedSeq;
+      /**
+       * How far the local mirror can be trusted, RIGHT NOW. See
+       * {@link UserHydrationStatus}.
        *
-       * Consumers that would otherwise read a 404 as "new user" — onboarding
-       * gates, first-run experiences, progress dashboards — should check for
-       * `failed` and present a retry affordance rather than an empty state.
+       * 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.
@@ -8027,8 +8055,9 @@ Currently logged-in as ${this._username}.`
         }
         this.syncStrategy.stopSync?.();
         this.setDBandQ();
-        await this.hydrateLocalMirror();
-        this.syncStrategy.startSync(this.localDB, this.remoteDB);
+        this._hydrationPromise = this.hydrateLocalMirror();
+        await this._hydrationPromise;
+        this.syncStrategy.startSync(this.localDB, this.remoteDB, this._hydratedSeq);
         this.applyDesignDocs().catch((error) => {
           log3(`Error in applyDesignDocs background task: ${error}`);
           if (error && typeof error === "object") {
@@ -8056,6 +8085,7 @@ Currently logged-in as ${this._username}.`
        * ceiling). Callers decide what a failure means for them.
        */
       async hydrateLocalMirror() {
+        this._hydratedSeq = void 0;
         if (this.localDB.name === this.remoteDB.name || !this.syncStrategy.hydrate) {
           this._hydration = { state: "not-required" };
           return;
@@ -8067,11 +8097,12 @@ Currently logged-in as ${this._username}.`
         this._hydration = { state: "hydrating" };
         const start = Date.now();
         try {
-          const { docsWritten } = await withTimeout(
+          const { docsWritten, lastSeq } = await withTimeout(
             this.syncStrategy.hydrate(this.localDB, this.remoteDB),
             HYDRATION_TIMEOUT_MS,
             `Hydration of local mirror for ${this._username}`
           );
+          this._hydratedSeq = lastSeq;
           await this.writeHydrationMarker();
           this._hydration = {
             state: "hydrated",
@@ -9010,22 +9041,60 @@ var init_CouchDBSyncStrategy = __esm({
        * 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.
+       *
+       * Into an EMPTY local DB this skips deleted documents, because a mirror that
+       * never held a document does not need to be told it was removed. That
+       * matters more than it sounds: scheduled reviews (`card_review_*`) are
+       * created and deleted once per review completed, so the changes feed is
+       * dominated by tombstones and grows without bound, while the durable record
+       * lives in card history. One real account measured 385 live documents behind
+       * 8,370 deletions — an unfiltered pull moved 9,520 documents and took ~20s,
+       * blowing the hydration timeout on a phone; filtered, the same pull moves
+       * 404 and takes ~2s, reaching a byte-identical local state.
+       *
+       * The filter runs server-side, so `last_seq` still reports the source's true
+       * sequence. Returning it lets startSync() begin the live pull from there
+       * instead of re-walking the same history in the background — without that,
+       * the cost is merely deferred, not removed.
        */
       async hydrate(localDB, remoteDB) {
-        const replication = pouchdb_setup_default.replicate(remoteDB, localDB, {});
+        const pristine = (await localDB.info()).doc_count === 0;
+        const replication = pouchdb_setup_default.replicate(
+          remoteDB,
+          localDB,
+          pristine ? { selector: { _deleted: { $exists: false } } } : {}
+        );
         this.hydrationHandle = replication;
         try {
           const info = await replication;
-          return { docsWritten: info.docs_written };
+          return {
+            docsWritten: info.docs_written,
+            // Only a pristine pull is a trustworthy starting point for the live
+            // sync; otherwise leave startSync() to its own checkpoint.
+            lastSeq: pristine ? info.last_seq : void 0
+          };
         } finally {
           this.hydrationHandle = void 0;
         }
       }
-      startSync(localDB, remoteDB) {
+      startSync(localDB, remoteDB, since) {
         if (localDB.name !== remoteDB.name) {
           this.syncHandle = pouchdb_setup_default.sync(localDB, remoteDB, {
             live: true,
-            retry: true
+            retry: true,
+            // `since` applies to the pull only, and only when hydrate() just
+            // established that local matches remote at that sequence. Without it,
+            // a filtered hydration leaves the pull with no usable checkpoint (the
+            // filter changes the replication id), so it restarts from zero and
+            // re-walks in the background exactly the tombstone history hydration
+            // just skipped — same work, now competing with the study session.
+            //
+            // Deliberately NOT persisted across launches: on later boots hydration
+            // is skipped and the pull's own checkpoint is the correct resume
+            // point, so a stored sequence could only be stale. If the app dies
+            // before that first checkpoint is written, the next launch simply
+            // walks the full feed once.
+            ...since !== void 0 ? { pull: { since } } : {}
           });
         }
       }