@vue-skuilder/db 0.2.17 → 0.2.18

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.17",
+  "version": "0.2.18",
   "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.17",
+    "@vue-skuilder/common": "0.2.18",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -57,10 +57,11 @@
   },
   "devDependencies": {
     "@types/uuid": "^10.0.0",
+    "pouchdb-adapter-memory": "^9.0.0",
     "tsup": "^8.0.2",
     "typescript": "~5.9.3",
     "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
-  "stableVersion": "0.2.17"
+  "stableVersion": "0.2.18"
 }

package/src/core/index.ts

@@ -5,6 +5,7 @@ export * from './types/types-legacy';
 export * from './types/user';
 export * from './types/strategyState';
 export * from './types/userOutcome';
+export * from './types/hydration';
 export * from '../util/Loggable';
 export * from './util';
 export * from './navigators';

package/src/core/interfaces/userDB.ts

@@ -9,6 +9,7 @@ import { Moment } from 'moment';
 import { CardHistory, CardRecord, QualifiedCardID } from '../types/types-legacy';
 import { UserOutcomeRecord } from '../types/userOutcome';
 import { UserConfig } from '../types/user';
+import { UserHydrationStatus } from '../types/hydration';
 import { DocumentUpdater } from '@db/study';
 
 /**
@@ -19,6 +20,16 @@ export interface UserDBReader {
   getUsername(): string;
   isLoggedIn(): boolean;
 
+  /**
+   * How far this device's local mirror of the user's data can be trusted.
+   *
+   * 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}.
+   */
+  hydrationStatus(): UserHydrationStatus;
+
   /**
    * Get user configuration
    */

package/src/core/types/hydration.ts

@@ -0,0 +1,78 @@
+/**
+ * User database hydration.
+ *
+ * A logged-in user's data lives in a remote CouchDB `userdb-<hex>` and is
+ * mirrored into a browser-local PouchDB. On a device that has never synced
+ * that account, the local mirror starts EMPTY — and every local read
+ * (`getStrategyState`, `getConfig`, `getCourseRegistrationsDoc`, ...) answers
+ * "no such document", which is indistinguishable from "brand new user".
+ *
+ * Consumers acting on that answer render a new-user experience to an existing
+ * user, and — worse — compute writes from empty state that then lose to the
+ * real remote document at replication time. Hydration closes that window by
+ * pulling the account's documents down BEFORE the user object is handed out.
+ */
+
+/**
+ * Where a user's local database stands relative to its remote counterpart.
+ *
+ * Only `failed` is a blocking condition. `stale` explicitly is not: it means a
+ * full pull completed on this device previously, so local data is real and
+ * merely possibly-behind — live sync closes the gap in the background. That is
+ * the ordinary offline case and it must keep working.
+ */
+export type UserHydrationState =
+  /** Guest, or a data layer with no remote. There is nothing to hydrate from. */
+  | 'not-required'
+  /** Initial pull in flight. */
+  | 'hydrating'
+  /** Initial pull completed this session. Local is a faithful mirror. */
+  | 'hydrated'
+  /**
+   * A previous session completed a full pull on this device (recorded by the
+   * `_local/hydration` marker). Local data is real; live sync is catching up.
+   */
+  | 'stale'
+  /**
+   * No pull has ever completed on this device and one could not be completed
+   * now. Local reads CANNOT be trusted to mean "no data" — callers must not
+   * present a new-user experience or compute writes from what they read.
+   */
+  | 'failed';
+
+/**
+ * Hydration state plus observability detail.
+ *
+ * Shaped to mirror `CourseSyncStatus` in CourseSyncService, which solves the
+ * same problem for course databases.
+ */
+export interface UserHydrationStatus {
+  state: UserHydrationState;
+  /** Documents pulled by the initial replication (set when state is `hydrated`). */
+  docsWritten?: number;
+  /** Wall-clock duration of the initial pull attempt, successful or not. */
+  durationMs?: number;
+  /** Failure detail, set when state is `failed`. */
+  error?: string;
+}
+
+/**
+ * ID of the per-device marker recording that a full pull once completed.
+ *
+ * `_local/*` documents are deliberately excluded from replication by CouchDB
+ * and PouchDB alike, which is exactly the semantics wanted here: the marker
+ * describes THIS device's mirror, and must never travel to another one.
+ */
+export const HYDRATION_MARKER_ID = '_local/hydration';
+
+/**
+ * Payload of {@link HYDRATION_MARKER_ID}.
+ */
+export interface HydrationMarker {
+  _id: typeof HYDRATION_MARKER_ID;
+  _rev?: string;
+  /** Account the mirror was hydrated for — guards against a stale marker after an account switch. */
+  username: string;
+  /** ISO timestamp of the most recent successful full pull. */
+  hydratedAt: string;
+}

package/src/impl/common/BaseUserDB.ts

@@ -1,4 +1,12 @@
-import { DocType, DocTypePrefixes, StrategyStateDoc, buildStrategyStateId } from '@db/core';
+import {
+  DocType,
+  DocTypePrefixes,
+  StrategyStateDoc,
+  buildStrategyStateId,
+  HYDRATION_MARKER_ID,
+  type HydrationMarker,
+  type UserHydrationStatus,
+} from '@db/core';
 import { getCardHistoryID } from '@db/core/util';
 import { CourseElo, Status } from '@vue-skuilder/common';
 import moment, { Moment } from 'moment';
@@ -50,6 +58,35 @@ interface DesignDoc {
   };
 }
 
+/**
+ * Ceiling on the initial pull of a user's data before we give up and report
+ * `failed`. Generous relative to the expected payload (a user database is a
+ * config doc, registrations, strategy state, and per-card history), so hitting
+ * it indicates a genuinely unusable connection rather than a large account.
+ */
+const HYDRATION_TIMEOUT_MS = 15_000;
+
+/**
+ * Reject if `p` has not settled within `ms`.
+ *
+ * Note the underlying work is not cancelled by this — callers that need the
+ * operation stopped must do so themselves.
+ */
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  return Promise.race([
+    p,
+    new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    }),
+  ]).finally(() => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }) as Promise<T>;
+}
+
 /**
  * Base user database implementation that uses a pluggable sync strategy.
  * Handles local storage operations and delegates sync/remote operations to the strategy.
@@ -87,9 +124,34 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
   private localDB!: PouchDB.Database;
   private remoteDB!: PouchDB.Database;
   private writeDB!: PouchDB.Database; // Database to use for write operations (local-first approach)
-
   private updateQueue!: UpdateQueue;
 
+  private _hydration: UserHydrationStatus = { state: 'not-required' };
+
+  /**
+   * How far the local mirror can be trusted. 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.
+   */
+  public hydrationStatus(): UserHydrationStatus {
+    return { ...this._hydration };
+  }
+
+  /**
+   * 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.
+   */
+  private canMaterializeDefaults(): boolean {
+    return this._hydration.state !== 'failed' && this._hydration.state !== 'hydrating';
+  }
+
   public async createAccount(
     username: string,
     password: string
@@ -257,6 +319,14 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       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 — that would report an existing user as unregistered, and ` +
+              `then lose to their real document once sync resumes.`
+          );
+        }
         await this.localDB.put<CourseRegistrationDoc>({
           _id: BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
           courses: [],
@@ -556,6 +626,13 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       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<UserConfig>(defaultConfig);
         return this.getConfig();
       } else {
@@ -643,8 +720,24 @@ Currently logged-in as ${this._username}.`
       return;
     }
 
+    // Cancel replication left over from the previous identity BEFORE rebinding
+    // the DB handles below. init() runs on every identity change (login,
+    // logout, account creation, data reset), and each one points localDB /
+    // remoteDB somewhere new — so without this, the prior sync keeps running
+    // against handles nobody holds a reference to anymore.
+    //
+    // Logout is the case that bites: the guest branch of startSync() never
+    // replaces the handle (it only ever assigns when a sync is actually
+    // started), so the departing user's live sync survived indefinitely. Its
+    // session cookie is gone by then, leaving it to 401-and-retry forever.
+    this.syncStrategy.stopSync?.();
+
     this.setDBandQ();
 
+    // 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);
     this.applyDesignDocs().catch((error) => {
       log(`Error in applyDesignDocs background task: ${error}`);
@@ -661,6 +754,104 @@ 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.
+   */
+  private async hydrateLocalMirror(): Promise<void> {
+    // 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) {
+      this._hydration = { state: 'not-required' };
+      return;
+    }
+
+    if (await this.hasHydrationMarker()) {
+      // A full pull already completed on this device, so local reads return
+      // real data and live sync will close any gap. Blocking here would break
+      // offline startup to re-fetch what we already have.
+      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,
+      };
+      log(
+        `Hydrated local mirror for ${this._username}: ` +
+          `${docsWritten} docs in ${this._hydration.durationMs}ms`
+      );
+    } catch (e) {
+      // Cancel the pull if it is merely slow rather than dead — otherwise it
+      // races the live sync we are about to start over the same documents.
+      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.
+   */
+  private async hasHydrationMarker(): Promise<boolean> {
+    try {
+      const marker = await this.localDB.get<HydrationMarker>(HYDRATION_MARKER_ID);
+      return marker.username === this._username;
+    } catch {
+      // Absent, or unreadable — either way, treat as never hydrated. The cost
+      // of a false negative is one redundant pull.
+      return false;
+    }
+  }
+
+  private async writeHydrationMarker(): Promise<void> {
+    try {
+      let existingRev: string | undefined;
+      try {
+        existingRev = (await this.localDB.get<HydrationMarker>(HYDRATION_MARKER_ID))._rev;
+      } catch {
+        // First hydration on this device.
+      }
+
+      await this.localDB.put<HydrationMarker>({
+        _id: HYDRATION_MARKER_ID,
+        _rev: existingRev,
+        username: this._username,
+        hydratedAt: new Date().toISOString(),
+      });
+    } catch (e) {
+      // Costs a redundant pull on next startup, not correctness.
+      logger.warn(`Could not write hydration marker for ${this._username}: ${e}`);
+    }
+  }
+
   private static designDocs: DesignDoc[] = [
     {
       _id: '_design/reviewCards',
@@ -1083,6 +1274,15 @@ Currently logged-in as ${this._username}.`
     } catch (e) {
       const err = e as PouchError;
       if (err.status === 404) {
+        // `null` here means "this user has no such state" — a first-run signal
+        // consumers act on. When the mirror is untrusted we cannot honestly say
+        // that, so fail instead of reporting an established user as new.
+        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;

package/src/impl/common/SyncStrategy.ts

@@ -21,6 +21,25 @@ export interface SyncStrategy {
    */
   getWriteDB?(username: string): PouchDB.Database;
 
+  /**
+   * Pull the remote database into the local one and RESOLVE WHEN DONE.
+   *
+   * Distinct from startSync(): this is a one-shot, awaitable catch-up used to
+   * populate an empty local mirror before the user object is handed out. A
+   * strategy that omits it declares that it has no remote worth waiting for.
+   *
+   * Mechanism only — BaseUser owns the policy (whether to run it, timeout,
+   * marker bookkeeping, resulting hydration state).
+   *
+   * @param localDB The local PouchDB instance
+   * @param remoteDB The remote PouchDB instance
+   * @returns Count of documents written locally
+   */
+  hydrate?(
+    localDB: PouchDB.Database,
+    remoteDB: PouchDB.Database
+  ): Promise<{ docsWritten: number }>;
+
   /**
    * Start synchronization between local and remote databases
    * @param localDB The local PouchDB instance

package/src/impl/couch/CouchDBSyncStrategy.ts

@@ -21,6 +21,8 @@ const log = (s: any) => {
  */
 export class CouchDBSyncStrategy implements SyncStrategy {
   private syncHandle?: any; // Handle to cancel sync if needed
+  /** In-flight one-shot hydration pull, so a timed-out pull can be abandoned. */
+  private hydrationHandle?: PouchDB.Replication.Replication<object>;
 
   setupRemoteDB(username: string): PouchDB.Database {
     if (username === GuestUsername || username.startsWith(GuestUsername)) {
@@ -42,20 +44,68 @@ export class CouchDBSyncStrategy implements SyncStrategy {
     }
   }
 
+  /**
+   * 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: PouchDB.Database,
+    remoteDB: PouchDB.Database
+  ): Promise<{ docsWritten: number }> {
+    // 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, {});
+    this.hydrationHandle = replication;
+
+    try {
+      const info = await replication;
+      return { docsWritten: info.docs_written };
+    } finally {
+      this.hydrationHandle = undefined;
+    }
+  }
+
   startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void {
-    // Only sync if local and remote are different instances
-    if (localDB !== remoteDB) {
+    // 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
+    // than caching, so `localDB !== remoteDB` was always true and guests ran a
+    // live sync of a database against itself. Names are unambiguous here:
+    // local DBs are named `userdb-<username>` (or a filesystem path in Node),
+    // remote ones are a full `protocol://host/userdb-<hex>` URL.
+    if (localDB.name !== remoteDB.name) {
       this.syncHandle = pouch.sync(localDB, remoteDB, {
         live: true,
         retry: true,
       });
     }
-    // If they're the same (guest mode), no sync needed
+    // If they're the same DB (guest mode), no sync needed
   }
 
   stopSync?(): void {
+    if (this.hydrationHandle) {
+      try {
+        this.hydrationHandle.cancel();
+      } catch (e) {
+        logger.warn(`Failed to cancel hydration pull (continuing anyway): ${e}`);
+      }
+      this.hydrationHandle = undefined;
+    }
+
     if (this.syncHandle) {
-      this.syncHandle.cancel();
+      // Called from BaseUser.init(), which is on the app boot path — a throw
+      // here would leave BaseUser._initialized false forever, and
+      // BaseUser.instance() polls that flag. Drop the handle regardless.
+      try {
+        this.syncHandle.cancel();
+      } catch (e) {
+        logger.warn(`Failed to cancel user sync (continuing anyway): ${e}`);
+      }
       this.syncHandle = undefined;
     }
   }