@vue-skuilder/db 0.2.18 → 0.2.20

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.18",
+  "version": "0.2.20",
   "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.18",
+    "@vue-skuilder/common": "0.2.20",
     "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.18"
+  "stableVersion": "0.2.20"
 }

package/src/core/interfaces/userDB.ts

@@ -21,15 +21,28 @@ export interface UserDBReader {
   isLoggedIn(): boolean;
 
   /**
-   * How far this device's local mirror of the user's data can be trusted.
+   * How far this device's local mirror of the user's data can be trusted,
+   * as of right now.
    *
    * Reads answer from the local mirror, so on a device that has never synced
    * this account "document not found" does not mean "no such data". Anything
    * that would otherwise interpret an empty read as a new user should check
    * for `failed` first. See {@link UserHydrationStatus}.
+   *
+   * Can return `hydrating`; use {@link awaitHydration} to decide on a settled
+   * answer instead of a snapshot.
    */
   hydrationStatus(): UserHydrationStatus;
 
+  /**
+   * The hydration status once settled — never `hydrating`.
+   *
+   * Resolves immediately unless a pull is in flight. Prefer this over
+   * hydrationStatus() wherever the answer gates behaviour, such as a route
+   * guard that may run while a login is still completing.
+   */
+  awaitHydration(): Promise<UserHydrationStatus>;
+
   /**
    * Get user configuration
    */

package/src/impl/common/BaseUserDB.ts

@@ -127,18 +127,51 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
   private updateQueue!: UpdateQueue;
 
   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. See {@link UserHydrationStatus}.
+   * 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.
    */
   public hydrationStatus(): UserHydrationStatus {
     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.
+   */
+  public async awaitHydration(): Promise<UserHydrationStatus> {
+    // hydrateLocalMirror() records failures rather than throwing, so this
+    // cannot reject — but a stray rejection must not become the caller's
+    // problem when a status is available either way.
+    try {
+      await this._hydrationPromise;
+    } catch {
+      // fall through to the recorded status
+    }
+    return this.hydrationStatus();
+  }
+
   /**
    * Whether a missing document may be treated as genuinely absent, allowing
    * callers to create it with defaults.
@@ -736,9 +769,18 @@ Currently logged-in as ${this._username}.`
 
     // Populate the local mirror BEFORE anything can read it, and before live
     // sync can push local state upward. See hydrateLocalMirror().
-    await this.hydrateLocalMirror();
-
-    this.syncStrategy.startSync(this.localDB, this.remoteDB);
+    //
+    // Retained (not just awaited) so awaitHydration() can hand the same
+    // promise to anything that asks mid-flight. Assigned synchronously with
+    // respect to init()'s entry, so no caller can observe a previous
+    // identity's promise here.
+    this._hydrationPromise = this.hydrateLocalMirror();
+    await this._hydrationPromise;
+
+    // _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') {
@@ -767,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) {
@@ -786,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

package/tests/impl/hydration.test.ts

@@ -246,6 +246,55 @@ describe('user DB hydration', () => {
     expect(order).toEqual(['hydrate', 'startSync']);
   });
 
+  it('awaitHydration resolves to the settled status, never "hydrating"', async () => {
+    // The race this closes: a route guard sampling status while a login is
+    // still pulling. It would see 'hydrating', fall through, and render an
+    // established learner as brand new — the original bug, via a side door.
+    const realName = freshUsername();
+    await seedRemote(realName);
+
+    let releaseHydrate: (v: { docsWritten: number }) => void = () => {};
+    const hydrate = vi.fn(
+      () =>
+        new Promise<{ docsWritten: number }>((resolve) => {
+          releaseHydrate = resolve;
+        })
+    );
+
+    const guestName = 'sk-guest-mid-login';
+    const strategy = {
+      ...authedStrategy(realName, { hydrate }),
+      // Guest before login, real remote after — mirroring setupRemoteDB.
+      setupRemoteDB: (u: string) => (u.startsWith('sk-guest-') ? localDB(u) : remoteDB(realName)),
+      getWriteDB: (u: string) => (u.startsWith('sk-guest-') ? localDB(u) : remoteDB(realName)),
+      authenticate: async () => ({ ok: true }),
+    } as SyncStrategy;
+
+    // Starts as a guest: nothing to hydrate.
+    const user = await BaseUser.instance(strategy, guestName);
+    expect(user.hydrationStatus().state).toBe('not-required');
+
+    // Log in, but do NOT await it — this is the window a stray navigation
+    // lands in.
+    const loginPromise = user.login(realName, 'password');
+
+    while (hydrate.mock.calls.length === 0) {
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+
+    // Mid-flight: the snapshot is honest about being unsettled...
+    expect(user.hydrationStatus().state).toBe('hydrating');
+
+    // ...and a caller that needs an answer waits for the real one.
+    const settled = user.awaitHydration();
+    releaseHydrate({ docsWritten: 3 });
+
+    expect((await settled).state).toBe('hydrated');
+    expect(user.hydrationStatus().state).toBe('hydrated');
+
+    await loginPromise;
+  });
+
   it('gives up on a pull that hangs', async () => {
     await seedRemote(username);
     // Fake setTimeout only — PouchDB's internals rely on the other async