@vue-skuilder/db 0.2.36 → 0.2.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/dist/core/index.cjs +91 -70
  2. package/dist/core/index.cjs.map +1 -1
  3. package/dist/core/navigators/generators/prescribed.mjs +29 -11
  4. package/dist/core/navigators/generators/prescribed.mjs.map +1 -1
  5. package/dist/core/versionStamps.mjs +1 -1
  6. package/dist/impl/common/BaseUserDB.mjs +14 -2
  7. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  8. package/dist/impl/couch/CourseSyncService.mjs +88 -10
  9. package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
  10. package/dist/impl/couch/PouchDataLayerProvider.mjs +16 -1
  11. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -1
  12. package/dist/impl/couch/courseAPI.mjs +24 -10
  13. package/dist/impl/couch/courseAPI.mjs.map +1 -1
  14. package/dist/impl/couch/courseDB.mjs +15 -9
  15. package/dist/impl/couch/courseDB.mjs.map +1 -1
  16. package/dist/impl/couch/index.cjs +163 -62
  17. package/dist/impl/couch/index.cjs.map +1 -1
  18. package/dist/impl/couch/index.d.ts +22 -1
  19. package/dist/impl/couch/index.mjs +20 -3
  20. package/dist/impl/couch/index.mjs.map +1 -1
  21. package/dist/impl/static/index.cjs +39 -15
  22. package/dist/impl/static/index.cjs.map +1 -1
  23. package/dist/index.cjs +202 -92
  24. package/dist/index.cjs.map +1 -1
  25. package/package.json +3 -3
  26. package/src/core/navigators/generators/prescribed.ts +42 -16
  27. package/src/impl/common/BaseUserDB.ts +15 -2
  28. package/src/impl/couch/CourseSyncService.ts +130 -20
  29. package/src/impl/couch/PouchDataLayerProvider.ts +14 -1
  30. package/src/impl/couch/courseAPI.ts +26 -12
  31. package/src/impl/couch/courseDB.ts +20 -12
  32. package/src/impl/couch/index.ts +16 -5
  33. package/tests/impl/courseSync.test.ts +139 -0
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.2.36",
16
+ "version": "0.2.37",
17
17
  "description": "Database layer for vue-skuilder",
18
18
  "main": "dist/index.cjs",
19
19
  "module": "dist/index.mjs",
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "@nilock2/pouchdb-authentication": "^1.0.2",
72
- "@vue-skuilder/common": "0.2.36",
72
+ "@vue-skuilder/common": "0.2.37",
73
73
  "cross-fetch": "^4.1.0",
74
74
  "moment": "^2.29.4",
75
75
  "pouchdb": "^9.0.0",
@@ -87,5 +87,5 @@
87
87
  "vite": "^8.0.0",
88
88
  "vitest": "^4.1.0"
89
89
  },
90
- "stableVersion": "0.2.36"
90
+ "stableVersion": "0.2.37"
91
91
  }
@@ -269,6 +269,12 @@ function pickTopByScore(cards: WeightedCard[], limit: number): WeightedCard[] {
269
269
  export default class PrescribedCardsGenerator extends ContentNavigator implements CardGenerator {
270
270
  name: string;
271
271
  private config: PrescribedConfig;
272
+ /**
273
+ * Course-wide reads that don't change within a navigator's lifetime (the
274
+ * navigator is cached per CourseDB, minutes), loaded once, not per run.
275
+ */
276
+ private _cardsByTag: Promise<Map<string, string[]>> | null = null;
277
+ private _hierarchyConfigs: Promise<HierarchyConfig[]> | null = null;
272
278
 
273
279
  constructor(
274
280
  user: UserDBInterface,
@@ -326,21 +332,7 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
326
332
  ? await this.course.getAppliedTagsBatch(allRelevantIds)
327
333
  : new Map<string, string[]>();
328
334
 
329
- const courseTagDocs = await this.course.getCourseTagStubs().catch(
330
- () =>
331
- ({
332
- rows: [],
333
- offset: 0,
334
- total_rows: 0,
335
- }) as unknown as Awaited<ReturnType<CourseDBInterface['getCourseTagStubs']>>
336
- );
337
- const cardsByTag = new Map<string, string[]>();
338
- for (const row of courseTagDocs.rows ?? []) {
339
- const tagDoc = row.doc as { name?: string; taggedCards?: string[] } | undefined;
340
- if (tagDoc?.name && Array.isArray(tagDoc.taggedCards)) {
341
- cardsByTag.set(tagDoc.name, [...tagDoc.taggedCards]);
342
- }
343
- }
335
+ const cardsByTag = await this.loadCardsByTag();
344
336
 
345
337
  const nextState: PrescribedProgressState = {
346
338
  updatedAt: isoNow(),
@@ -677,7 +669,39 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
677
669
  }
678
670
  }
679
671
 
680
- private async loadHierarchyConfigs(): Promise<HierarchyConfig[]> {
672
+ /** Tag name → tagged card IDs, from the course's tag docs (once per instance). */
673
+ private loadCardsByTag(): Promise<Map<string, string[]>> {
674
+ if (!this._cardsByTag) {
675
+ this._cardsByTag = this.course
676
+ .getCourseTagStubs()
677
+ .then((docs) => {
678
+ const cardsByTag = new Map<string, string[]>();
679
+ for (const row of docs.rows ?? []) {
680
+ const tagDoc = row.doc as { name?: string; taggedCards?: string[] } | undefined;
681
+ if (tagDoc?.name && Array.isArray(tagDoc.taggedCards)) {
682
+ cardsByTag.set(tagDoc.name, [...tagDoc.taggedCards]);
683
+ }
684
+ }
685
+ return cardsByTag;
686
+ })
687
+ .catch((e) => {
688
+ // Not cached: the next run retries.
689
+ this._cardsByTag = null;
690
+ logger.debug(`[Prescribed] Failed to load tag docs: ${e}`);
691
+ return new Map<string, string[]>();
692
+ });
693
+ }
694
+ return this._cardsByTag;
695
+ }
696
+
697
+ private loadHierarchyConfigs(): Promise<HierarchyConfig[]> {
698
+ if (!this._hierarchyConfigs) {
699
+ this._hierarchyConfigs = this.fetchHierarchyConfigs();
700
+ }
701
+ return this._hierarchyConfigs;
702
+ }
703
+
704
+ private async fetchHierarchyConfigs(): Promise<HierarchyConfig[]> {
681
705
  try {
682
706
  const strategies = await this.course.getAllNavigationStrategies();
683
707
  return strategies
@@ -693,6 +717,8 @@ export default class PrescribedCardsGenerator extends ContentNavigator implement
693
717
  }
694
718
  });
695
719
  } catch (e) {
720
+ // Not cached: the next run retries.
721
+ this._hierarchyConfigs = null;
696
722
  logger.debug(`[Prescribed] Failed to load hierarchy configs: ${e}`);
697
723
  return [];
698
724
  }
@@ -376,6 +376,19 @@ Currently logged-in as ${this._username}.`
376
376
  return this.updateQueue.update(id, update);
377
377
  }
378
378
 
379
+ /**
380
+ * Create a default doc after a 404. Concurrent first reads (e.g. two
381
+ * components on a brand-new user) both see the 404 and both create; the
382
+ * loser's conflict just means the doc now exists, which is what it wanted.
383
+ */
384
+ private async putDefaultUnlessCreated<T extends object>(doc: PouchDB.Core.PutDocument<T>) {
385
+ try {
386
+ await this.localDB.put<T>(doc);
387
+ } catch (e) {
388
+ if ((e as PouchError).status !== 409) throw e;
389
+ }
390
+ }
391
+
379
392
  public async getCourseRegistrationsDoc(): Promise<
380
393
  CourseRegistrationDoc & PouchDB.Core.IdMeta & PouchDB.Core.GetMeta
381
394
  > {
@@ -399,7 +412,7 @@ Currently logged-in as ${this._username}.`
399
412
  `then lose to their real document once sync resumes.`
400
413
  );
401
414
  }
402
- await this.localDB.put<CourseRegistrationDoc>({
415
+ await this.putDefaultUnlessCreated<CourseRegistrationDoc>({
403
416
  _id: BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
404
417
  courses: [],
405
418
  studyWeight: {},
@@ -705,7 +718,7 @@ Currently logged-in as ${this._username}.`
705
718
  `over what may be an existing one.`
706
719
  );
707
720
  }
708
- await this.localDB.put<UserConfig>(defaultConfig);
721
+ await this.putDefaultUnlessCreated<UserConfig>(defaultConfig);
709
722
  return this.getConfig();
710
723
  } else {
711
724
  logger.error(`Error setting user default config:`, e);
@@ -23,6 +23,15 @@ import type { CourseConfig } from '@vue-skuilder/common';
23
23
  // This avoids propagating per-interaction ELO write noise to every syncing
24
24
  // client. Each client's local snapshot refreshes on the next page load.
25
25
  //
26
+ // A replica that completed a sync on an earlier page load carries a
27
+ // `_local/` marker, and is handed out as ready immediately; its refresh
28
+ // (epoch check, incremental pull, view warming) runs in the background, into
29
+ // the same DB. Sessions may therefore start on the previous visit's data and
30
+ // catch up seconds later. If that refresh finds the remote DB recreated (an
31
+ // epoch change), the replica is NOT destroyed under running readers: the
32
+ // marker is dropped, this page keeps the outdated copy, and the next page
33
+ // load rebuilds it from scratch (the path a device without a replica takes).
34
+ //
26
35
  // Live replication is intentionally NOT supported. The remote course DB
27
36
  // receives high-frequency ELO updates from all concurrent users — live
28
37
  // sync would cause constant re-indexing of local PouchDB views.
@@ -41,6 +50,12 @@ export type CourseSyncState =
41
50
  | 'disabled'
42
51
  | 'error';
43
52
 
53
+ /**
54
+ * Written into the local replica when a sync completes. `_local/` docs don't
55
+ * replicate, so it describes this device's copy.
56
+ */
57
+ const SYNC_MARKER_ID = '_local/sk-course-sync-complete';
58
+
44
59
  /**
45
60
  * Detailed sync status for observability.
46
61
  */
@@ -178,26 +193,11 @@ export class CourseSyncService {
178
193
  async ensureSynced(courseId: string, forceEnabled?: boolean): Promise<void> {
179
194
  const existing = this.entries.get(courseId);
180
195
 
181
- // Already synced — but check if the remote DB has been recreated
182
- // (e.g., after a dev reseed). The seed script writes a `db-epoch`
183
- // doc; if the remote epoch differs from our local copy, the local
184
- // replica is stale and must be destroyed before re-syncing.
196
+ // Ready on this page load. Its epoch was checked on the way (by
197
+ // performSync, or by the background refresh, which keeps an outdated
198
+ // replica rather than destroy it under running sessions).
185
199
  if (existing?.status.state === 'ready' && existing.localDB) {
186
- const stale = await this.isLocalEpochStale(courseId, existing.localDB);
187
- if (!stale) {
188
- return;
189
- }
190
- logger.info(
191
- `[CourseSyncService] Remote DB epoch changed for course ${courseId} — destroying stale local replica`
192
- );
193
- try {
194
- await existing.localDB.destroy();
195
- } catch {
196
- // Ignore cleanup errors
197
- }
198
- existing.localDB = null;
199
- existing.readyPromise = null;
200
- // Fall through to start a fresh sync
200
+ return;
201
201
  }
202
202
 
203
203
  // Already disabled
@@ -218,10 +218,118 @@ export class CourseSyncService {
218
218
  };
219
219
  this.entries.set(courseId, entry);
220
220
 
221
- entry.readyPromise = this.performSync(courseId, entry, forceEnabled);
221
+ entry.readyPromise = this.startSync(courseId, entry, forceEnabled);
222
222
  return entry.readyPromise;
223
223
  }
224
224
 
225
+ /**
226
+ * A replica completed on an earlier page load is ready now, refreshed in the
227
+ * background; anything else goes through a full performSync.
228
+ */
229
+ private async startSync(
230
+ courseId: string,
231
+ entry: SyncEntry,
232
+ forceEnabled?: boolean
233
+ ): Promise<void> {
234
+ const localDB = new pouch(this.localDBName(courseId));
235
+ if (await this.hasSyncMarker(localDB)) {
236
+ entry.localDB = localDB;
237
+ entry.status = { state: 'ready' };
238
+ entry.readyPromise = null;
239
+ logger.info(
240
+ `[CourseSyncService] Using this device's replica of course ${courseId}; refreshing in the background`
241
+ );
242
+ void this.refreshInBackground(courseId, entry, forceEnabled);
243
+ return;
244
+ }
245
+ return this.performSync(courseId, entry, forceEnabled);
246
+ }
247
+
248
+ /**
249
+ * Bring a ready replica up to date without taking it away from readers.
250
+ * Failures leave it ready (and outdated).
251
+ */
252
+ private async refreshInBackground(
253
+ courseId: string,
254
+ entry: SyncEntry,
255
+ forceEnabled?: boolean
256
+ ): Promise<void> {
257
+ const localDB = entry.localDB!;
258
+ try {
259
+ if (!forceEnabled && !(await this.checkLocalSyncEnabled(courseId))) {
260
+ await this.clearSyncMarker(localDB);
261
+ logger.info(
262
+ `[CourseSyncService] Local sync no longer enabled for course ${courseId}; replica kept for this page only`
263
+ );
264
+ return;
265
+ }
266
+
267
+ if (await this.isLocalEpochStale(courseId, localDB)) {
268
+ await this.clearSyncMarker(localDB);
269
+ logger.info(
270
+ `[CourseSyncService] Remote DB recreated for course ${courseId}: keeping the outdated replica ` +
271
+ `for this page; it is rebuilt on the next page load`
272
+ );
273
+ return;
274
+ }
275
+
276
+ const start = Date.now();
277
+ const result = await this.replicate(this.getRemoteDB(courseId), localDB);
278
+ const syncTimeMs = Date.now() - start;
279
+ const warmStart = Date.now();
280
+ await this.warmViewIndices(localDB);
281
+ const viewWarmTimeMs = Date.now() - warmStart;
282
+ await this.writeSyncMarker(localDB);
283
+ entry.status = {
284
+ state: 'ready',
285
+ docsReplicated: result.docs_written,
286
+ syncTimeMs,
287
+ viewWarmTimeMs,
288
+ };
289
+ logger.info(
290
+ `[CourseSyncService] Background refresh of course ${courseId}: ` +
291
+ `${result.docs_written} docs in ${syncTimeMs}ms, views ${viewWarmTimeMs}ms`
292
+ );
293
+ } catch (e) {
294
+ logger.warn(
295
+ `[CourseSyncService] Background refresh of course ${courseId} failed; replica kept as is: ${e}`
296
+ );
297
+ }
298
+ }
299
+
300
+ private async hasSyncMarker(localDB: PouchDB.Database): Promise<boolean> {
301
+ try {
302
+ await localDB.get(SYNC_MARKER_ID);
303
+ return true;
304
+ } catch {
305
+ return false;
306
+ }
307
+ }
308
+
309
+ private async writeSyncMarker(localDB: PouchDB.Database): Promise<void> {
310
+ try {
311
+ let _rev: string | undefined;
312
+ try {
313
+ _rev = (await localDB.get(SYNC_MARKER_ID))._rev;
314
+ } catch {
315
+ // First completion on this device.
316
+ }
317
+ await localDB.put({ _id: SYNC_MARKER_ID, _rev, completedAt: new Date().toISOString() });
318
+ } catch (e) {
319
+ // Costs the next page load the full-sync path, not correctness.
320
+ logger.warn(`[CourseSyncService] Could not write sync marker: ${e}`);
321
+ }
322
+ }
323
+
324
+ private async clearSyncMarker(localDB: PouchDB.Database): Promise<void> {
325
+ try {
326
+ const marker = await localDB.get(SYNC_MARKER_ID);
327
+ await localDB.remove(marker);
328
+ } catch {
329
+ // Absent already.
330
+ }
331
+ }
332
+
225
333
  /**
226
334
  * Get the local PouchDB for a course, or null if not available.
227
335
  *
@@ -328,6 +436,8 @@ export class CourseSyncService {
328
436
  `[CourseSyncService] View indices warmed for course ${courseId} in ${viewWarmTimeMs}ms`
329
437
  );
330
438
 
439
+ await this.writeSyncMarker(localDB);
440
+
331
441
  // Done
332
442
  entry.status = {
333
443
  state: 'ready',
@@ -28,6 +28,14 @@ export class CouchDataLayerProvider implements DataLayerProvider {
28
28
  // or group of courses
29
29
  private _courseIDs: string[] = [];
30
30
 
31
+ /**
32
+ * One CourseDB per course, so its caches (navigator, ELO pool, tags) last
33
+ * across sessions and card hydration. Rebuilt when the local replica it reads
34
+ * from changes (becomes ready, or is replaced); a session keeps the instance
35
+ * it started with.
36
+ */
37
+ private _courseDBs = new Map<string, { db: CourseDB; localDB: PouchDB.Database | null }>();
38
+
31
39
  constructor(coursIDs?: string[]) {
32
40
  if (coursIDs) {
33
41
  this._courseIDs = coursIDs;
@@ -75,7 +83,12 @@ export class CouchDataLayerProvider implements DataLayerProvider {
75
83
  // pass it to CourseDB so reads (pipeline, card hydration) run locally.
76
84
  // Writes always go to the remote DB (handled inside CourseDB).
77
85
  const localDB = CourseSyncService.getInstance().getLocalDB(courseId);
78
- return new CourseDB(courseId, async () => this.getUserDB(), localDB ?? undefined);
86
+ const cached = this._courseDBs.get(courseId);
87
+ if (cached && cached.localDB === localDB) return cached.db;
88
+
89
+ const db = new CourseDB(courseId, async () => this.getUserDB(), localDB ?? undefined);
90
+ this._courseDBs.set(courseId, { db, localDB });
91
+ return db;
79
92
  }
80
93
 
81
94
  /**
@@ -1,6 +1,4 @@
1
- import pouch from './pouchdb-setup';
2
- import { createPouchDBConfig } from '.';
3
- import { ENV } from '@db/factory';
1
+ import { getCourseDB } from '.';
4
2
  // import { DataShape } from '../..base-course/Interfaces/DataShape';
5
3
  import { NameSpacer, ShapeDescriptor } from '@vue-skuilder/common';
6
4
  import { CourseConfig, DataShape } from '@vue-skuilder/common';
@@ -171,14 +169,37 @@ async function addCard(
171
169
  return card;
172
170
  }
173
171
 
172
+ /**
173
+ * CourseConfig reads, cached per course for a few minutes: a study session reads
174
+ * it several times per pipeline run and per card. An edit made elsewhere shows
175
+ * up after the TTL (or a reload); writes through this client invalidate.
176
+ */
177
+ const COURSE_CONFIG_TTL_MS = 5 * 60 * 1000;
178
+ const courseConfigCache = new Map<string, { at: number; config: Promise<CourseConfig> }>();
179
+
180
+ export function invalidateCourseConfigCache(courseID: string): void {
181
+ courseConfigCache.delete(courseID);
182
+ }
183
+
174
184
  export async function getCredentialledCourseConfig(courseID: string): Promise<CourseConfig> {
175
- try {
185
+ const hit = courseConfigCache.get(courseID);
186
+ if (hit && Date.now() - hit.at < COURSE_CONFIG_TTL_MS) {
187
+ // A copy: callers mutate configs (e.g. before writing them back).
188
+ return structuredClone(await hit.config);
189
+ }
190
+
191
+ const config = (async () => {
176
192
  const db = getCourseDB(courseID);
177
193
  const ret = await db.get<CourseConfig>('CourseConfig');
178
194
  ret.courseID = courseID;
179
- logger.info(`Returning course config: ${JSON.stringify(ret)}`);
195
+ logger.debug(`Fetched course config for ${courseID}`);
180
196
  return ret;
197
+ })();
198
+ courseConfigCache.set(courseID, { at: Date.now(), config });
199
+ try {
200
+ return structuredClone(await config);
181
201
  } catch (e) {
202
+ courseConfigCache.delete(courseID);
182
203
  logger.error(`Error fetching config for ${courseID}:`, e);
183
204
  throw e;
184
205
  }
@@ -275,10 +296,3 @@ export function getTagID(tagName: string): string {
275
296
  }
276
297
  }
277
298
 
278
- export function getCourseDB(courseID: string): PouchDB.Database {
279
- const dbName = `coursedb-${courseID}`;
280
- return new pouch(
281
- ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
282
- createPouchDBConfig()
283
- );
284
- }
@@ -25,7 +25,13 @@ import {
25
25
  } from '../../core/types/types-legacy';
26
26
  import { logger } from '../../util/logger';
27
27
  import { GET_CACHED } from './clientCache';
28
- import { addNote55, addTagToCard, getCredentialledCourseConfig, getTagID } from './courseAPI';
28
+ import {
29
+ addNote55,
30
+ addTagToCard,
31
+ getCredentialledCourseConfig,
32
+ getTagID,
33
+ invalidateCourseConfigCache,
34
+ } from './courseAPI';
29
35
  import { DataLayerResult } from '@db/core/types/db';
30
36
  import { PouchError } from './types';
31
37
  import CourseLookup from './courseLookupDB';
@@ -401,12 +407,8 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
401
407
  }
402
408
 
403
409
  async getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>> {
404
- const ret = await getAppliedTags(this.id, cardId);
405
- if (ret) {
406
- return ret;
407
- } else {
408
- throw new Error(`Failed to find tags for card ${this.id}-${cardId}`);
409
- }
410
+ // this.db: the local replica when one is ready (the module function is remote).
411
+ return this.db.query<TagStub>('getTags', { startkey: cardId, endkey: cardId });
410
412
  }
411
413
 
412
414
  async getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>> {
@@ -491,7 +493,8 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
491
493
  }
492
494
 
493
495
  async getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>> {
494
- return getCourseTagStubs(this.id);
496
+ // this.db: the local replica when one is ready (the module function is remote).
497
+ return filterAllDocsByPrefix<Tag>(this.db, DocType.TAG.valueOf() + '-');
495
498
  }
496
499
 
497
500
  async addNote(
@@ -1161,12 +1164,17 @@ ${JSON.stringify(config)}
1161
1164
  `);
1162
1165
 
1163
1166
  const db = getCourseDB(courseID);
1167
+ invalidateCourseConfigCache(courseID);
1164
1168
  const old = await getCredentialledCourseConfig(courseID);
1165
1169
 
1166
- return await db.put<CourseConfig>({
1167
- ...config,
1168
- _rev: (old as any)._rev,
1169
- });
1170
+ try {
1171
+ return await db.put<CourseConfig>({
1172
+ ...config,
1173
+ _rev: (old as any)._rev,
1174
+ });
1175
+ } finally {
1176
+ invalidateCourseConfigCache(courseID);
1177
+ }
1170
1178
  }
1171
1179
 
1172
1180
  function isSuccessRow<T>(
@@ -69,12 +69,23 @@ function getCouchDB(dbName: string): PouchDB.Database {
69
69
  );
70
70
  }
71
71
 
72
+ const courseDBHandles = new Map<string, PouchDB.Database>();
73
+
74
+ /**
75
+ * The remote course DB, one handle per URL for the page's lifetime.
76
+ *
77
+ * `skip_setup`: a fresh handle otherwise checks the DB exists (and would try to
78
+ * create it) before its first request: one extra round trip per handle. Course
79
+ * DBs are only created server-side (express), never through this handle.
80
+ */
72
81
  export function getCourseDB(courseID: string): PouchDB.Database {
73
- // todo: keep a cache of opened courseDBs? need to benchmark this somehow
74
- return new pouch(
75
- ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID,
76
- createPouchDBConfig()
77
- );
82
+ const url = ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID;
83
+ let db = courseDBHandles.get(url);
84
+ if (!db) {
85
+ db = new pouch(url, { ...createPouchDBConfig(), skip_setup: true });
86
+ courseDBHandles.set(url, db);
87
+ }
88
+ return db;
78
89
  }
79
90
 
80
91
  export async function getLatestVersion() {
@@ -0,0 +1,139 @@
1
+ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
2
+ import PouchDB from 'pouchdb';
3
+ import memoryAdapter from 'pouchdb-adapter-memory';
4
+
5
+ PouchDB.plugin(memoryAdapter);
6
+
7
+ // Local replicas: in-memory PouchDB. The memory adapter keys stores by name,
8
+ // so a new handle with the same name (a "page load") sees the same data, as an
9
+ // IndexedDB replica would.
10
+ vi.mock('@db/impl/couch/pouchdb-setup', async () => {
11
+ const Pouch = (await import('pouchdb')).default;
12
+ const memory = (await import('pouchdb-adapter-memory')).default;
13
+ Pouch.plugin(memory);
14
+ return { default: Pouch.defaults({ adapter: 'memory' }) };
15
+ });
16
+
17
+ const { CourseSyncService } = await import('@db/impl/couch/CourseSyncService');
18
+
19
+ // A course ID per test, so each test has its own local replica (no teardown).
20
+ let COURSE = '';
21
+ const MARKER = '_local/sk-course-sync-complete';
22
+
23
+ let remote: PouchDB.Database;
24
+ let n = 0;
25
+
26
+ /** A fresh service instance, i.e. a new page load, with `remote` as the server. */
27
+ function pageLoad() {
28
+ // Abandon the previous instance, as a reload does. (resetInstance() would
29
+ // start closing its handles, and a new handle on the same store waits on that.)
30
+ (CourseSyncService as any).instance = null;
31
+ const service = CourseSyncService.getInstance();
32
+ vi.spyOn(service as any, 'getRemoteDB').mockImplementation(() => remote);
33
+ return service;
34
+ }
35
+
36
+ function local() {
37
+ return new PouchDB(`coursedb-local-${COURSE}`, { adapter: 'memory' });
38
+ }
39
+
40
+ async function hasMarker(): Promise<boolean> {
41
+ try {
42
+ await local().get(MARKER);
43
+ return true;
44
+ } catch {
45
+ return false;
46
+ }
47
+ }
48
+
49
+ beforeEach(async () => {
50
+ COURSE = `course-sync-test-${n}`;
51
+ remote = new PouchDB(`remote-${COURSE}-${n++}`, { adapter: 'memory' });
52
+ await remote.bulkDocs([
53
+ { _id: 'db-epoch', epoch: 1 },
54
+ { _id: 'c-1', docType: 'CARD' },
55
+ { _id: 'c-2', docType: 'CARD' },
56
+ ]);
57
+ });
58
+
59
+ afterEach(() => {
60
+ (CourseSyncService as any).instance = null;
61
+ vi.restoreAllMocks();
62
+ });
63
+
64
+ describe('CourseSyncService: replica ready from the marker', () => {
65
+ it('first sync replicates everything and writes the marker', async () => {
66
+ const service = pageLoad();
67
+ await service.ensureSynced(COURSE, true);
68
+
69
+ expect(service.isReady(COURSE)).toBe(true);
70
+ expect(await hasMarker()).toBe(true);
71
+ await expect(service.getLocalDB(COURSE)!.get('c-2')).resolves.toBeTruthy();
72
+ });
73
+
74
+ it('next page load: ready immediately, refreshed in the background', async () => {
75
+ await pageLoad().ensureSynced(COURSE, true);
76
+ await remote.put({ _id: 'c-3', docType: 'CARD' });
77
+
78
+ const service = pageLoad();
79
+ const replicate = vi.spyOn(service as any, 'replicate');
80
+ await service.ensureSynced(COURSE, true);
81
+
82
+ // Ready before the refresh pulls the new doc (handed out from the marker).
83
+ expect(service.isReady(COURSE)).toBe(true);
84
+ const db = service.getLocalDB(COURSE)!;
85
+
86
+ await vi.waitFor(async () => {
87
+ expect(service.getStatus(COURSE)?.docsReplicated).toBe(1);
88
+ });
89
+ expect(replicate).toHaveBeenCalledTimes(1);
90
+ await expect(db.get('c-3')).resolves.toBeTruthy();
91
+ // Same DB throughout: readers keep their handle.
92
+ expect(service.getLocalDB(COURSE)).toBe(db);
93
+ });
94
+
95
+ it('remote recreated: keeps the outdated replica this page, rebuilds on the next', async () => {
96
+ await pageLoad().ensureSynced(COURSE, true);
97
+
98
+ // "Recreate" the remote: new epoch, different content.
99
+ remote = new PouchDB(`remote-${COURSE}-${n++}`, { adapter: 'memory' });
100
+ await remote.bulkDocs([
101
+ { _id: 'db-epoch', epoch: 2 },
102
+ { _id: 'c-new', docType: 'CARD' },
103
+ ]);
104
+
105
+ const service = pageLoad();
106
+ await service.ensureSynced(COURSE, true);
107
+ const db = service.getLocalDB(COURSE)!;
108
+
109
+ await vi.waitFor(async () => {
110
+ expect(await hasMarker()).toBe(false);
111
+ });
112
+ // Not destroyed under readers: still ready, still the old content.
113
+ expect(service.isReady(COURSE)).toBe(true);
114
+ await expect(db.get('c-1')).resolves.toBeTruthy();
115
+
116
+ // Next page load: no marker, so the full path rebuilds from the new remote.
117
+ const next = pageLoad();
118
+ await next.ensureSynced(COURSE, true);
119
+ const rebuilt = next.getLocalDB(COURSE)!;
120
+ await expect(rebuilt.get('c-new')).resolves.toBeTruthy();
121
+ await expect(rebuilt.get('c-1')).rejects.toBeTruthy();
122
+ expect(await hasMarker()).toBe(true);
123
+ });
124
+
125
+ it('a failed background refresh leaves the replica ready', async () => {
126
+ await pageLoad().ensureSynced(COURSE, true);
127
+
128
+ const service = pageLoad();
129
+ vi.spyOn(service as any, 'isLocalEpochStale').mockResolvedValue(false);
130
+ const replicate = vi
131
+ .spyOn(service as any, 'replicate')
132
+ .mockRejectedValue(new Error('network down'));
133
+ await service.ensureSynced(COURSE, true);
134
+
135
+ await vi.waitFor(() => expect(replicate).toHaveBeenCalled());
136
+ expect(service.isReady(COURSE)).toBe(true);
137
+ await expect(service.getLocalDB(COURSE)!.get('c-1')).resolves.toBeTruthy();
138
+ });
139
+ });