@vue-skuilder/db 0.2.19 → 0.2.21

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.19",
+  "version": "0.2.21",
   "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.19",
+    "@vue-skuilder/common": "0.2.21",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -63,5 +63,5 @@
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.19"
+  "stableVersion": "0.2.21"
 }

package/src/core/types/user.ts

@@ -16,7 +16,12 @@ export interface UserConfig {
   darkMode: boolean;
   likesConfetti: boolean;
   sessionTimeLimit: number; // Session time limit in minutes
-  email?: string; // Optional email for verification flows (added for enhanced auth)
+  /**
+   * @deprecated Retired in favour of the _users-doc email (the single source of
+   * truth, written by /auth/send-verification and read by /auth/status). No
+   * live code writes or reads this field; it may linger on older CONFIG docs.
+   */
+  email?: string;
 
   // Session tracking for trial enforcement (per-course)
   // Key is courseId (e.g., 'letterspractice-basic')

package/src/impl/common/BaseUserDB.ts

@@ -129,6 +129,14 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
   private _hydration: UserHydrationStatus = { state: 'not-required' };
   /** In-flight hydration, so concurrent callers can wait for a real answer. */
   private _hydrationPromise: Promise<void> | null = null;
+  /**
+   * 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().
+   */
+  private _hydratedSeq?: string | number;
 
   /**
    * How far the local mirror can be trusted, RIGHT NOW. See
@@ -769,7 +777,10 @@ Currently logged-in as ${this._username}.`
     this._hydrationPromise = this.hydrateLocalMirror();
     await this._hydrationPromise;
 
-    this.syncStrategy.startSync(this.localDB, this.remoteDB);
+    // _hydratedSeq is set only by a hydration that just succeeded above, for
+    // this identity — see hydrateLocalMirror(). Anything else leaves it
+    // undefined and the live sync resumes from its own checkpoint.
+    this.syncStrategy.startSync(this.localDB, this.remoteDB, this._hydratedSeq);
     this.applyDesignDocs().catch((error) => {
       log(`Error in applyDesignDocs background task: ${error}`);
       if (error && typeof error === 'object') {
@@ -798,6 +809,11 @@ Currently logged-in as ${this._username}.`
    * ceiling). Callers decide what a failure means for them.
    */
   private async hydrateLocalMirror(): Promise<void> {
+    // Clear first: init() reruns on every identity change, and a sequence from
+    // the departing account would be meaningless against the incoming one's
+    // database. Every path below either sets it or leaves it unset.
+    this._hydratedSeq = undefined;
+
     // Guests and static-mode users have no remote — setupRemoteDB() hands back
     // the local database itself, so there is nothing to pull from.
     if (this.localDB.name === this.remoteDB.name || !this.syncStrategy.hydrate) {
@@ -817,11 +833,12 @@ Currently logged-in as ${this._username}.`
     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',

package/src/impl/common/SyncStrategy.ts

@@ -33,19 +33,28 @@ export interface SyncStrategy {
    *
    * @param localDB The local PouchDB instance
    * @param remoteDB The remote PouchDB instance
-   * @returns Count of documents written locally
+   * @returns Count of documents written locally, and — only when the pull is
+   *   known to have landed the remote's complete current state — the sequence
+   *   it corresponds to, for startSync() to resume from. Omitted means "no
+   *   safe shortcut, walk from the checkpoint".
    */
   hydrate?(
     localDB: PouchDB.Database,
     remoteDB: PouchDB.Database
-  ): Promise<{ docsWritten: number }>;
+  ): Promise<{ docsWritten: number; lastSeq?: string | number }>;
 
   /**
    * Start synchronization between local and remote databases
    * @param localDB The local PouchDB instance
    * @param remoteDB The remote PouchDB instance
+   * @param since Sequence to start the pull from, as returned by a hydrate()
+   *   in the same session. Omit to resume from the stored checkpoint.
    */
-  startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+  startSync(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database,
+    since?: string | number
+  ): void;
 
   /**
    * Stop synchronization (optional - for cleanup)
@@ -93,7 +102,11 @@ export interface SyncStrategy {
  */
 export abstract class BaseSyncStrategy implements SyncStrategy {
   abstract setupRemoteDB(username: string): PouchDB.Database;
-  abstract startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+  abstract startSync(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database,
+    since?: string | number
+  ): void;
   abstract canCreateAccount(): boolean;
   abstract canAuthenticate(): boolean;
   abstract getCurrentUsername(): Promise<string>;

package/src/impl/couch/CouchDBSyncStrategy.ts

@@ -51,26 +51,61 @@ export 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.
    */
   async hydrate(
     localDB: PouchDB.Database,
     remoteDB: PouchDB.Database
-  ): Promise<{ docsWritten: number }> {
+  ): Promise<{ docsWritten: number; lastSeq?: string | number }> {
+    // Skipping tombstones is only sound when there is nothing local for a
+    // missed deletion to strand. A non-empty local DB here means a previous
+    // hydration failed partway (no marker was written, so we are retrying) and
+    // may hold documents the remote has since deleted — take the slow, honest
+    // path and let the full changes feed reconcile them.
+    const pristine = (await localDB.info()).doc_count === 0;
+
     // A one-shot Replication is itself a promise of the completed result, so
     // it can be awaited directly — the handle is retained only so a pull that
     // outlives its timeout can be cancelled.
-    const replication = pouch.replicate(remoteDB, localDB, {});
+    const replication = pouch.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 : undefined,
+      };
     } finally {
       this.hydrationHandle = undefined;
     }
   }
 
-  startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void {
+  startSync(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database,
+    since?: string | number
+  ): void {
     // Compare by NAME, not object identity. In guest mode setupRemoteDB()
     // returns getLocalUserDB(username) — the same database as localDB — but
     // getLocalUserDB() constructs a fresh PouchDB handle on every call rather
@@ -82,6 +117,19 @@ export class CouchDBSyncStrategy implements SyncStrategy {
       this.syncHandle = pouch.sync(localDB, remoteDB, {
         live: 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 !== undefined ? { pull: { since } } : {}),
       });
     }
     // If they're the same DB (guest mode), no sync needed