add read / write db mini abstractions...

clarifies intent. allows SyncStrategy to configure the targets for reads
and writes.

Author: NiloCK

packages/db/src/impl/common/BaseUserDB.ts

@@ -79,11 +79,14 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
     return !this._username.startsWith(GuestUsername);
   }
 
-  private remoteDB!: PouchDB.Database;
   public remote(): PouchDB.Database {
     return this.remoteDB;
   }
+
   private localDB!: PouchDB.Database;
+  private remoteDB!: PouchDB.Database;
+  private writeDB!: PouchDB.Database; // Database to use for write operations (local-first approach)
+
   private updateQueue!: UpdateQueue;
 
   public async createAccount(
@@ -597,7 +600,11 @@ Currently logged-in as ${this._username}.`
   private setDBandQ() {
     this.localDB = getLocalUserDB(this._username);
     this.remoteDB = this.syncStrategy.setupRemoteDB(this._username);
-    this.updateQueue = new UpdateQueue(this.localDB);
+    // writeDB follows local-first pattern: static mode writes to local, CouchDB writes to remote/local as appropriate
+    this.writeDB = this.syncStrategy.getWriteDB
+      ? this.syncStrategy.getWriteDB(this._username)
+      : this.localDB;
+    this.updateQueue = new UpdateQueue(this.localDB, this.writeDB);
   }
 
   private async init() {
@@ -697,7 +704,9 @@ Currently logged-in as ${this._username}.`
    * @returns The updated state of the card's CardHistory data
    */
 
-  public async putCardRecord<T extends CardRecord>(record: T): Promise<CardHistory<CardRecord>> {
+  public async putCardRecord<T extends CardRecord>(
+    record: T
+  ): Promise<CardHistory<CardRecord> & PouchDB.Core.RevisionIdMeta> {
     const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
     // stringify the current record to make it writable to couchdb
     record.timeStamp = moment.utc(record.timeStamp).toString() as unknown as Moment;
@@ -735,8 +744,8 @@ Currently logged-in as ${this._username}.`
           streak: 0,
           bestInterval: 0,
         };
-        void this.remoteDB.put<CardHistory<T>>(initCardHistory);
-        return initCardHistory;
+        const putResult = await this.writeDB.put<CardHistory<T>>(initCardHistory);
+        return { ...initCardHistory, _rev: putResult.rev };
       } else {
         throw new Error(`putCardRecord failed because of:
   name:${reason.name}
@@ -793,7 +802,7 @@ Currently logged-in as ${this._username}.`
         const deletePromises = duplicateDocIds.map(async (docId) => {
           try {
             const doc = await this.remoteDB.get(docId);
-            await this.remoteDB.remove(doc);
+            await this.writeDB.remove(doc);
             log(`Successfully removed duplicate review: ${docId}`);
           } catch (error) {
             log(`Failed to remove duplicate review ${docId}: ${error}`);
@@ -891,7 +900,7 @@ Currently logged-in as ${this._username}.`
 
       if (err.status === 404) {
         // doc does not exist. Create it and then run this fcn again.
-        await this.remoteDB.put<ClassroomRegistrationDoc>({
+        await this.writeDB.put<ClassroomRegistrationDoc>({
           _id: BaseUser.DOC_IDS.CLASSROOM_REGISTRATIONS,
           registrations: [],
         });

packages/db/src/impl/common/SyncStrategy.ts

@@ -14,6 +14,13 @@ export interface SyncStrategy {
    */
   setupRemoteDB(username: string): PouchDB.Database;
 
+  /**
+   * Get the database to use for write operations (local-first approach)
+   * @param username The username to get write DB for
+   * @returns PouchDB database instance for write operations
+   */
+  getWriteDB?(username: string): PouchDB.Database;
+
   /**
    * Start synchronization between local and remote databases
    * @param localDB The local PouchDB instance

packages/db/src/impl/couch/CouchDBSyncStrategy.ts

@@ -32,6 +32,16 @@ export class CouchDBSyncStrategy implements SyncStrategy {
     }
   }
 
+  getWriteDB(username: string): PouchDB.Database {
+    if (username === GuestUsername || username.startsWith(GuestUsername)) {
+      // Guest users write to local database
+      return getLocalUserDB(username);
+    } else {
+      // Authenticated users write to remote (which will sync to local)
+      return this.getUserDB(username);
+    }
+  }
+
   startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void {
     // Only sync if local and remote are different instances
     if (localDB !== remoteDB) {

packages/db/src/impl/couch/updateQueue.ts

@@ -12,7 +12,8 @@ export default class UpdateQueue extends Loggable {
     [index: string]: boolean;
   } = {};
 
-  private db: PouchDB.Database;
+  private readDB: PouchDB.Database; // Database for read operations
+  private writeDB: PouchDB.Database; // Database for write operations (local-first)
 
   public update<T extends PouchDB.Core.Document<object>>(
     id: PouchDB.Core.DocumentId,
@@ -27,29 +28,32 @@ export default class UpdateQueue extends Loggable {
     return this.applyUpdates<T>(id);
   }
 
-  constructor(db: PouchDB.Database) {
+  constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {
     super();
     // PouchDB.debug.enable('*');
-    this.db = db;
+    this.readDB = readDB;
+    this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided
     logger.debug(`UpdateQ initialized...`);
-    void this.db.info().then((i) => {
+    void this.readDB.info().then((i) => {
       logger.debug(`db info: ${JSON.stringify(i)}`);
     });
   }
 
-  private async applyUpdates<T extends PouchDB.Core.Document<object>>(id: string): Promise<T> {
+  private async applyUpdates<T extends PouchDB.Core.Document<object>>(
+    id: string
+  ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {
     logger.debug(`Applying updates on doc: ${id}`);
     if (this.inprogressUpdates[id]) {
       // console.log(`Updates in progress...`);
-      await this.db.info(); // stall for a round trip
+      await this.readDB.info(); // stall for a round trip
       // console.log(`Retrying...`);
       return this.applyUpdates<T>(id);
     } else {
       if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
         this.inprogressUpdates[id] = true;
 
         try {
-          let doc = await this.db.get<T>(id);
+          let doc = await this.readDB.get<T>(id);
           logger.debug(`Retrieved doc: ${id}`);
           while (this.pendingUpdates[id].length !== 0) {
             const update = this.pendingUpdates[id].splice(0, 1)[0];
@@ -66,7 +70,7 @@ export default class UpdateQueue extends Loggable {
           //   console.log(`${k}: ${typeof k}`);
           // }
           // console.log(`Applied updates to doc: ${JSON.stringify(doc)}`);
-          await this.db.put<T>(doc);
+          await this.writeDB.put<T>(doc);
           logger.debug(`Put doc: ${id}`);
 
           if (this.pendingUpdates[id].length === 0) {

packages/db/src/impl/static/NoOpSyncStrategy.ts

@@ -17,6 +17,11 @@ export class NoOpSyncStrategy implements SyncStrategy {
     return getLocalUserDB(username);
   }
 
+  getWriteDB(username: string): PouchDB.Database {
+    // In static mode, always write to local database
+    return getLocalUserDB(username);
+  }
+
   startSync(_localDB: PouchDB.Database, _remoteDB: PouchDB.Database): void {
     // No-op - in static mode, local and remote are the same database instance
     // PouchDB sync with itself is harmless and efficient