@vue-skuilder/db 0.2.18 → 0.2.19

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.18",
+  "version": "0.2.19",
   "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.19",
     "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.19"
 }

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,43 @@ 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;
 
   /**
-   * 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,7 +761,13 @@ 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();
+    //
+    // 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;
 
     this.syncStrategy.startSync(this.localDB, this.remoteDB);
     this.applyDesignDocs().catch((error) => {

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