@vue-skuilder/db 0.1.39 → 0.1.40

package/package.json

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

package/src/factory.ts

@@ -37,6 +37,18 @@ export interface DataLayerConfig {
     COUCHDB_PASSWORD?: string;
 
     COURSE_IDS?: string[];
+
+    /**
+     * Per-app tuning for the CouchDB→PouchDB course sync. Only applies when
+     * `type === 'couch'` and the course has `localSync.enabled === true`.
+     * See CourseSyncService.ReplicationOptions for defaults.
+     */
+    courseSync?: {
+      replication?: {
+        batchSize?: number;
+        batchesLimit?: number;
+      };
+    };
   };
 }
 
@@ -69,6 +81,11 @@ export async function initializeDataLayer(config: DataLayerConfig): Promise<Data
     ENV.COUCHDB_USERNAME = config.options.COUCHDB_USERNAME;
     ENV.COUCHDB_PASSWORD = config.options.COUCHDB_PASSWORD;
 
+    if (config.options.courseSync) {
+      const { CourseSyncService } = await import('./impl/couch/CourseSyncService');
+      CourseSyncService.getInstance().configure(config.options.courseSync);
+    }
+
     if (
       config.options.COUCHDB_PASSWORD &&
       config.options.COUCHDB_USERNAME &&

package/src/impl/couch/CourseSyncService.ts

@@ -82,10 +82,33 @@ interface SyncEntry {
  *
  * The service is a singleton — course sync state is shared across the app.
  */
+/**
+ * Tuning knobs for one-shot remote→local replication.
+ * Defaults are chosen for one-shot snapshot replication of bounded course
+ * corpora (text/JSON docs, no large attachments). PouchDB's built-in
+ * defaults (100/10) target live continuous sync — too conservative for
+ * cold-load UX on a course of a few thousand docs.
+ *
+ * Apps with smaller/larger corpora can override via
+ * `initializeDataLayer({ options: { courseSync: { replication: {...} } } })`.
+ */
+export interface ReplicationOptions {
+  /** Docs per `_bulk_get` HTTP request. Higher = fewer roundtrips. */
+  batchSize?: number;
+  /** Concurrent batches in flight. */
+  batchesLimit?: number;
+}
+
+const DEFAULT_REPLICATION: Required<ReplicationOptions> = {
+  batchSize: 1000,
+  batchesLimit: 5,
+};
+
 export class CourseSyncService {
   private static instance: CourseSyncService | null = null;
 
   private entries: Map<string, SyncEntry> = new Map();
+  private replicationOptions: Required<ReplicationOptions> = DEFAULT_REPLICATION;
 
   private constructor() {}
 
@@ -96,6 +119,24 @@ export class CourseSyncService {
     return CourseSyncService.instance;
   }
 
+  /**
+   * Apply replication tuning. Typically called once from `initializeDataLayer`.
+   * Partial overrides merge with defaults.
+   */
+  configure(opts: { replication?: ReplicationOptions }): void {
+    if (opts.replication) {
+      this.replicationOptions = {
+        ...DEFAULT_REPLICATION,
+        ...opts.replication,
+      };
+      logger.info(
+        `[CourseSyncService] Replication configured: ` +
+          `batch_size=${this.replicationOptions.batchSize}, ` +
+          `batches_limit=${this.replicationOptions.batchesLimit}`
+      );
+    }
+  }
+
   /**
    * Reset the singleton (for testing).
    */
@@ -264,7 +305,9 @@ export class CourseSyncService {
       const syncStart = Date.now();
 
       logger.info(
-        `[CourseSyncService] Starting one-shot replication for course ${courseId}`
+        `[CourseSyncService] Starting one-shot replication for course ${courseId} ` +
+          `(batch_size=${this.replicationOptions.batchSize}, ` +
+          `batches_limit=${this.replicationOptions.batchesLimit})`
       );
 
       const result = await this.replicate(remoteDB, localDB);
@@ -339,6 +382,8 @@ export class CourseSyncService {
     return new Promise((resolve, reject) => {
       void pouch.replicate(source, target, {
         // One-shot, not live. Local is a read-only snapshot.
+        batch_size: this.replicationOptions.batchSize,
+        batches_limit: this.replicationOptions.batchesLimit,
       })
         .on('complete', (info) => {
           resolve(info);

package/src/study/SessionController.ts

@@ -933,11 +933,18 @@ export class SessionController<TView = unknown> extends Loggable {
       this.log(`[CardGuarantee] ${this._minCardsGuarantee} guaranteed cards remaining`);
     }
 
-    // If a replan is in flight, wait for it to complete before drawing.
-    // This ensures the user sees cards scored against their latest state
-    // (e.g. after a GPC intro unlocked new content).
-    if (this._replanPromise) {
-      this.log('nextCard: awaiting in-flight replan before drawing');
+    // If a replan is in flight AND we have nothing queued to serve, wait for
+    // it. When queues still have cards, draw from them immediately and let
+    // the replan land asynchronously — blocking here adds visible lag
+    // between cards for a marginal scoring-freshness benefit. The
+    // wedge-breaker below handles the genuinely-empty case.
+    if (
+      this._replanPromise &&
+      this.newQ.length === 0 &&
+      this.reviewQ.length === 0 &&
+      this.failedQ.length === 0
+    ) {
+      this.log('nextCard: queues empty, awaiting in-flight replan before drawing');
       await this._replanPromise;
     }