@vue-skuilder/db 0.2.36 → 0.3.0

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 (59) hide show
  1. package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
  2. package/dist/core/index.cjs +203 -148
  3. package/dist/core/index.cjs.map +1 -1
  4. package/dist/core/index.d.ts +5 -5
  5. package/dist/core/navigators/Pipeline.mjs +8 -0
  6. package/dist/core/navigators/Pipeline.mjs.map +1 -1
  7. package/dist/core/navigators/generators/prescribed.mjs +29 -11
  8. package/dist/core/navigators/generators/prescribed.mjs.map +1 -1
  9. package/dist/core/versionStamps.mjs +1 -1
  10. package/dist/{dataLayerProvider-BDshhSp_.d.ts → dataLayerProvider-rGyLQ93v.d.ts} +1 -1
  11. package/dist/diagnostics/index.d.ts +3 -3
  12. package/dist/impl/common/BaseUserDB.mjs +32 -15
  13. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  14. package/dist/impl/couch/CourseSyncService.mjs +111 -11
  15. package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
  16. package/dist/impl/couch/PouchDataLayerProvider.mjs +16 -1
  17. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -1
  18. package/dist/impl/couch/courseAPI.mjs +24 -10
  19. package/dist/impl/couch/courseAPI.mjs.map +1 -1
  20. package/dist/impl/couch/courseDB.mjs +19 -9
  21. package/dist/impl/couch/courseDB.mjs.map +1 -1
  22. package/dist/impl/couch/index.cjs +297 -141
  23. package/dist/impl/couch/index.cjs.map +1 -1
  24. package/dist/impl/couch/index.d.ts +27 -4
  25. package/dist/impl/couch/index.mjs +20 -3
  26. package/dist/impl/couch/index.mjs.map +1 -1
  27. package/dist/impl/couch/updateQueue.mjs +69 -46
  28. package/dist/impl/couch/updateQueue.mjs.map +1 -1
  29. package/dist/impl/static/index.cjs +147 -93
  30. package/dist/impl/static/index.cjs.map +1 -1
  31. package/dist/impl/static/index.d.ts +4 -4
  32. package/dist/{index-BLDpFYG3.d.ts → index-C745YB_6.d.ts} +1 -1
  33. package/dist/index.cjs +345 -171
  34. package/dist/index.cjs.map +1 -1
  35. package/dist/index.d.ts +23 -10
  36. package/dist/index.mjs +2 -1
  37. package/dist/study/SessionController.mjs +4 -0
  38. package/dist/study/SessionController.mjs.map +1 -1
  39. package/dist/{types-DChCz22D.d.ts → types-DF0JuPbs.d.ts} +1 -1
  40. package/dist/{types-legacy-fT5Y1Wuy.d.ts → types-legacy-DdVjg81H.d.ts} +1 -1
  41. package/dist/util/packer/index.d.ts +3 -3
  42. package/dist/util/perfMarks.mjs +30 -0
  43. package/dist/util/perfMarks.mjs.map +1 -0
  44. package/package.json +3 -3
  45. package/src/core/interfaces/courseDB.ts +6 -0
  46. package/src/core/navigators/Pipeline.ts +8 -0
  47. package/src/core/navigators/generators/prescribed.ts +42 -16
  48. package/src/impl/common/BaseUserDB.ts +42 -23
  49. package/src/impl/couch/CourseSyncService.ts +149 -22
  50. package/src/impl/couch/PouchDataLayerProvider.ts +14 -1
  51. package/src/impl/couch/courseAPI.ts +26 -12
  52. package/src/impl/couch/courseDB.ts +25 -12
  53. package/src/impl/couch/index.ts +16 -5
  54. package/src/impl/couch/updateQueue.ts +86 -82
  55. package/src/study/SessionController.ts +4 -0
  56. package/src/util/index.ts +1 -0
  57. package/src/util/perfMarks.ts +35 -0
  58. package/tests/impl/courseSync.test.ts +139 -0
  59. package/tests/impl/updateQueue.test.ts +57 -0
@@ -1472,8 +1472,10 @@ var init_updateQueue = __esm({
1472
1472
  init_logger();
1473
1473
  UpdateQueue = class extends Loggable {
1474
1474
  _className = "UpdateQueue";
1475
- pendingUpdates = {};
1476
- inprogressUpdates = {};
1475
+ /** Updates not yet taken by a write, per doc. */
1476
+ pending = /* @__PURE__ */ new Map();
1477
+ /** Docs with a drain loop running. */
1478
+ draining = /* @__PURE__ */ new Set();
1477
1479
  readDB;
1478
1480
  // Database for read operations
1479
1481
  writeDB;
@@ -1491,6 +1493,9 @@ var init_updateQueue = __esm({
1491
1493
  * **Error Handling Pattern:**
1492
1494
  * - This method does NOT create documents if they don't exist
1493
1495
  * - Callers are responsible for handling 404 errors and creating documents
1496
+ * - A rejected update is dropped from the queue: a caller that creates the
1497
+ * doc after a 404 has already applied its change and must not see it
1498
+ * re-applied by a later update to the same doc
1494
1499
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
1495
1500
  *
1496
1501
  * @example
@@ -1507,12 +1512,16 @@ var init_updateQueue = __esm({
1507
1512
  */
1508
1513
  update(id, update) {
1509
1514
  logger.debug(`Update requested on doc: ${id}`);
1510
- if (this.pendingUpdates[id]) {
1511
- this.pendingUpdates[id].push(update);
1512
- } else {
1513
- this.pendingUpdates[id] = [update];
1514
- }
1515
- return this.applyUpdates(id);
1515
+ return new Promise((resolve, reject) => {
1516
+ const queue = this.pending.get(id) ?? [];
1517
+ queue.push({
1518
+ update,
1519
+ resolve,
1520
+ reject
1521
+ });
1522
+ this.pending.set(id, queue);
1523
+ if (!this.draining.has(id)) void this.drain(id);
1524
+ });
1516
1525
  }
1517
1526
  constructor(readDB, writeDB) {
1518
1527
  super();
@@ -1523,64 +1532,56 @@ var init_updateQueue = __esm({
1523
1532
  logger.debug(`db info: ${JSON.stringify(i)}`);
1524
1533
  });
1525
1534
  }
1526
- async applyUpdates(id) {
1527
- logger.debug(`Applying updates on doc: ${id}`);
1528
- if (this.inprogressUpdates[id]) {
1529
- while (this.inprogressUpdates[id]) {
1530
- await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
1535
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
1536
+ async drain(id) {
1537
+ this.draining.add(id);
1538
+ try {
1539
+ let batch;
1540
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
1541
+ this.pending.delete(id);
1542
+ try {
1543
+ const doc = await this.write(
1544
+ id,
1545
+ batch.map((p) => p.update)
1546
+ );
1547
+ batch.forEach((p) => p.resolve(doc));
1548
+ } catch (e) {
1549
+ batch.forEach((p) => p.reject(e));
1550
+ }
1531
1551
  }
1532
- return this.applyUpdates(id);
1533
- } else {
1534
- if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
1535
- this.inprogressUpdates[id] = true;
1536
- const MAX_RETRIES = 5;
1537
- for (let i = 0; i < MAX_RETRIES; i++) {
1538
- try {
1539
- const doc = await this.readDB.get(id);
1540
- let updatedDoc = { ...doc };
1541
- const updatesToApply = [...this.pendingUpdates[id]];
1542
- for (const update of updatesToApply) {
1543
- if (typeof update === "function") {
1544
- updatedDoc = { ...updatedDoc, ...update(updatedDoc) };
1545
- } else {
1546
- updatedDoc = {
1547
- ...updatedDoc,
1548
- ...update
1549
- };
1550
- }
1551
- }
1552
- await this.writeDB.put(updatedDoc);
1553
- this.pendingUpdates[id].splice(0, updatesToApply.length);
1554
- if (this.pendingUpdates[id].length === 0) {
1555
- this.inprogressUpdates[id] = false;
1556
- delete this.inprogressUpdates[id];
1557
- } else {
1558
- return this.applyUpdates(id);
1559
- }
1560
- return updatedDoc;
1561
- } catch (e) {
1562
- if (e.name === "conflict" && i < MAX_RETRIES - 1) {
1563
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
1564
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
1565
- } else if (e.name === "not_found" && i === 0) {
1566
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
1567
- delete this.inprogressUpdates[id];
1568
- throw e;
1569
- } else {
1570
- delete this.inprogressUpdates[id];
1571
- if (this.pendingUpdates[id]) {
1572
- delete this.pendingUpdates[id];
1573
- }
1574
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
1575
- throw e;
1576
- }
1577
- }
1552
+ } finally {
1553
+ this.draining.delete(id);
1554
+ }
1555
+ }
1556
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
1557
+ async write(id, updates) {
1558
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
1559
+ const MAX_RETRIES = 5;
1560
+ for (let i = 0; i < MAX_RETRIES; i++) {
1561
+ try {
1562
+ const doc = await this.readDB.get(id);
1563
+ let updatedDoc = {
1564
+ ...doc
1565
+ };
1566
+ for (const update of updates) {
1567
+ updatedDoc = typeof update === "function" ? { ...updatedDoc, ...update(updatedDoc) } : { ...updatedDoc, ...update };
1568
+ }
1569
+ const res = await this.writeDB.put(updatedDoc);
1570
+ return { ...updatedDoc, _rev: res.rev };
1571
+ } catch (e) {
1572
+ if (e.name === "conflict" && i < MAX_RETRIES - 1) {
1573
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
1574
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
1575
+ } else if (e.name === "not_found" && i === 0) {
1576
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
1577
+ throw e;
1578
+ } else {
1579
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
1580
+ throw e;
1578
1581
  }
1579
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
1580
- } else {
1581
- throw new Error(`Empty Updates Queue Triggered`);
1582
1582
  }
1583
1583
  }
1584
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
1584
1585
  }
1585
1586
  };
1586
1587
  }
@@ -1885,6 +1886,29 @@ var init_dataDirectory = __esm({
1885
1886
  }
1886
1887
  });
1887
1888
 
1889
+ // src/util/perfMarks.ts
1890
+ function perfMark(name, detail) {
1891
+ try {
1892
+ globalThis.performance?.mark(name, detail ? { detail } : void 0);
1893
+ } catch {
1894
+ }
1895
+ }
1896
+ function perfMeasure(name, start, end, detail) {
1897
+ try {
1898
+ globalThis.performance?.measure(name, {
1899
+ start,
1900
+ ...end !== void 0 ? { end } : {},
1901
+ ...detail ? { detail } : {}
1902
+ });
1903
+ } catch {
1904
+ }
1905
+ }
1906
+ var init_perfMarks = __esm({
1907
+ "src/util/perfMarks.ts"() {
1908
+ "use strict";
1909
+ }
1910
+ });
1911
+
1888
1912
  // src/core/navigators/regulators.ts
1889
1913
  function clamp01(x) {
1890
1914
  return Math.min(1, Math.max(0, x));
@@ -2099,6 +2123,7 @@ var init_Pipeline = __esm({
2099
2123
  import_common3 = require("@vue-skuilder/common");
2100
2124
  init_navigators();
2101
2125
  init_logger();
2126
+ init_perfMarks();
2102
2127
  init_orchestration();
2103
2128
  init_PipelineDebugger();
2104
2129
  init_diversityRerank();
@@ -2302,6 +2327,13 @@ var init_Pipeline = __esm({
2302
2327
  logger.info(
2303
2328
  `[Pipeline:timing] total=${(tFilter - t0).toFixed(0)}ms (context=${(tContext - t0).toFixed(0)} generate=${(tGenerate - tContext).toFixed(0)} hydrate=${(tHydrate - tGenerate).toFixed(0)} filter=${(tFilter - tHydrate).toFixed(0)})`
2304
2329
  );
2330
+ perfMeasure("sk:pipeline-run", t0, tFilter, {
2331
+ context: Math.round(tContext - t0),
2332
+ generate: Math.round(tGenerate - tContext),
2333
+ hydrate: Math.round(tHydrate - tGenerate),
2334
+ filter: Math.round(tFilter - tHydrate),
2335
+ binding: this.course?.readsLocal === void 0 ? "unknown" : this.course.readsLocal ? "local" : "remote"
2336
+ });
2305
2337
  const topScores = result.slice(0, 3).map((c) => c.score);
2306
2338
  logExecutionSummary(
2307
2339
  this.generator.name,
@@ -4448,6 +4480,18 @@ Currently logged-in as ${this._username}.`
4448
4480
  update(id, update) {
4449
4481
  return this.updateQueue.update(id, update);
4450
4482
  }
4483
+ /**
4484
+ * Create a default doc after a 404. Concurrent first reads (e.g. two
4485
+ * components on a brand-new user) both see the 404 and both create; the
4486
+ * loser's conflict just means the doc now exists, which is what it wanted.
4487
+ */
4488
+ async putDefaultUnlessCreated(doc) {
4489
+ try {
4490
+ await this.localDB.put(doc);
4491
+ } catch (e) {
4492
+ if (e.status !== 409) throw e;
4493
+ }
4494
+ }
4451
4495
  async getCourseRegistrationsDoc() {
4452
4496
  logger.debug(`Fetching courseRegistrations for ${this.getUsername()}`);
4453
4497
  let ret;
@@ -4464,7 +4508,7 @@ Currently logged-in as ${this._username}.`
4464
4508
  `Cannot read course registrations for ${this._username}: the local mirror is unavailable (hydration state '${this._hydration.state}'). Refusing to create an empty registration doc \u2014 that would report an existing user as unregistered, and then lose to their real document once sync resumes.`
4465
4509
  );
4466
4510
  }
4467
- await this.localDB.put({
4511
+ await this.putDefaultUnlessCreated({
4468
4512
  _id: _BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
4469
4513
  courses: [],
4470
4514
  studyWeight: {}
@@ -4711,7 +4755,7 @@ Currently logged-in as ${this._username}.`
4711
4755
  `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.`
4712
4756
  );
4713
4757
  }
4714
- await this.localDB.put(defaultConfig);
4758
+ await this.putDefaultUnlessCreated(defaultConfig);
4715
4759
  return this.getConfig();
4716
4760
  } else {
4717
4761
  logger.error(`Error setting user default config:`, e);
@@ -4972,22 +5016,20 @@ Currently logged-in as ${this._username}.`
4972
5016
  async putCardRecord(record) {
4973
5017
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
4974
5018
  record.timeStamp = import_moment5.default.utc(record.timeStamp).toString();
4975
- try {
4976
- const cardHistory = await this.update(
4977
- cardHistoryID,
4978
- function(h) {
4979
- h.records.push(record);
4980
- h.bestInterval = h.bestInterval || 0;
4981
- if (areQuestionRecords(h)) {
4982
- h.lapses = getLapses(h.records);
4983
- h.streak = getStreak(h.records);
4984
- } else {
4985
- h.lapses = h.lapses || 0;
4986
- h.streak = h.streak || 0;
4987
- }
4988
- return h;
4989
- }
4990
- );
5019
+ const append = (h) => {
5020
+ h.records.push(record);
5021
+ h.bestInterval = h.bestInterval || 0;
5022
+ if (areQuestionRecords(h)) {
5023
+ h.lapses = getLapses(h.records);
5024
+ h.streak = getStreak(h.records);
5025
+ } else {
5026
+ h.lapses = h.lapses || 0;
5027
+ h.streak = h.streak || 0;
5028
+ }
5029
+ return h;
5030
+ };
5031
+ const appendToExisting = async () => {
5032
+ const cardHistory = await this.update(cardHistoryID, append);
4991
5033
  cardHistory.records = cardHistory.records.map((record2) => {
4992
5034
  const ret = {
4993
5035
  ...record2
@@ -4996,6 +5038,9 @@ Currently logged-in as ${this._username}.`
4996
5038
  return ret;
4997
5039
  });
4998
5040
  return cardHistory;
5041
+ };
5042
+ try {
5043
+ return await appendToExisting();
4999
5044
  } catch (e) {
5000
5045
  const reason = e;
5001
5046
  if (reason.status === 404) {
@@ -5012,6 +5057,9 @@ Currently logged-in as ${this._username}.`
5012
5057
  const putResult = await this.writeDB.put(initCardHistory);
5013
5058
  return { ...initCardHistory, _rev: putResult.rev };
5014
5059
  } catch (creationError) {
5060
+ if (creationError.name === "conflict") {
5061
+ return appendToExisting();
5062
+ }
5015
5063
  throw new Error(
5016
5064
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
5017
5065
  );
@@ -5418,14 +5466,26 @@ async function addCard(courseID, course, id_displayable_data, id_view, elo, tags
5418
5466
  }
5419
5467
  return card;
5420
5468
  }
5469
+ function invalidateCourseConfigCache(courseID) {
5470
+ courseConfigCache.delete(courseID);
5471
+ }
5421
5472
  async function getCredentialledCourseConfig(courseID) {
5422
- try {
5473
+ const hit = courseConfigCache.get(courseID);
5474
+ if (hit && Date.now() - hit.at < COURSE_CONFIG_TTL_MS) {
5475
+ return structuredClone(await hit.config);
5476
+ }
5477
+ const config = (async () => {
5423
5478
  const db = getCourseDB(courseID);
5424
5479
  const ret = await db.get("CourseConfig");
5425
5480
  ret.courseID = courseID;
5426
- logger.info(`Returning course config: ${JSON.stringify(ret)}`);
5481
+ logger.debug(`Fetched course config for ${courseID}`);
5427
5482
  return ret;
5483
+ })();
5484
+ courseConfigCache.set(courseID, { at: Date.now(), config });
5485
+ try {
5486
+ return structuredClone(await config);
5428
5487
  } catch (e) {
5488
+ courseConfigCache.delete(courseID);
5429
5489
  logger.error(`Error fetching config for ${courseID}:`, e);
5430
5490
  throw e;
5431
5491
  }
@@ -5490,20 +5550,11 @@ function getTagID(tagName) {
5490
5550
  return tagPrefix + tagName;
5491
5551
  }
5492
5552
  }
5493
- function getCourseDB(courseID) {
5494
- const dbName = `coursedb-${courseID}`;
5495
- return new pouchdb_setup_default(
5496
- ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + dbName,
5497
- createPouchDBConfig()
5498
- );
5499
- }
5500
- var import_common6, import_common7, import_common8, import_uuid, AlreadyTaggedErr;
5553
+ var import_common6, import_common7, import_common8, import_uuid, COURSE_CONFIG_TTL_MS, courseConfigCache, AlreadyTaggedErr;
5501
5554
  var init_courseAPI = __esm({
5502
5555
  "src/impl/couch/courseAPI.ts"() {
5503
5556
  "use strict";
5504
- init_pouchdb_setup();
5505
5557
  init_couch();
5506
- init_factory();
5507
5558
  import_common6 = require("@vue-skuilder/common");
5508
5559
  import_common7 = require("@vue-skuilder/common");
5509
5560
  init_courseDB2();
@@ -5512,6 +5563,8 @@ var init_courseAPI = __esm({
5512
5563
  init_common();
5513
5564
  init_logger();
5514
5565
  import_uuid = require("uuid");
5566
+ COURSE_CONFIG_TTL_MS = 5 * 60 * 1e3;
5567
+ courseConfigCache = /* @__PURE__ */ new Map();
5515
5568
  AlreadyTaggedErr = class extends Error {
5516
5569
  constructor(message) {
5517
5570
  super(message);
@@ -6623,7 +6676,7 @@ async function getCourseQuestionTypes(courseID) {
6623
6676
  async function getCourseTagStubs(courseID) {
6624
6677
  logger.debug(`Getting tag stubs for course: ${courseID}`);
6625
6678
  const stubs = await filterAllDocsByPrefix2(
6626
- getCourseDB2(courseID),
6679
+ getCourseDB(courseID),
6627
6680
  "TAG" /* TAG */.valueOf() + "-"
6628
6681
  );
6629
6682
  stubs.rows.forEach((row) => {
@@ -6633,7 +6686,7 @@ async function getCourseTagStubs(courseID) {
6633
6686
  }
6634
6687
  async function deleteTag(courseID, tagName) {
6635
6688
  tagName = getTagID(tagName);
6636
- const courseDB = getCourseDB2(courseID);
6689
+ const courseDB = getCourseDB(courseID);
6637
6690
  const doc = await courseDB.get("TAG" /* TAG */.valueOf() + "-" + tagName);
6638
6691
  const resp = await courseDB.remove(doc);
6639
6692
  return resp;
@@ -6641,7 +6694,7 @@ async function deleteTag(courseID, tagName) {
6641
6694
  async function createTag(courseID, tagName, author) {
6642
6695
  logger.debug(`Creating tag: ${tagName}...`);
6643
6696
  const tagID = getTagID(tagName);
6644
- const courseDB = getCourseDB2(courseID);
6697
+ const courseDB = getCourseDB(courseID);
6645
6698
  const resp = await courseDB.put({
6646
6699
  course: courseID,
6647
6700
  docType: "TAG" /* TAG */,
@@ -6656,19 +6709,19 @@ async function createTag(courseID, tagName, author) {
6656
6709
  }
6657
6710
  async function updateTag(tag) {
6658
6711
  const prior = await getTag(tag.course, tag.name);
6659
- return await getCourseDB2(tag.course).put({
6712
+ return await getCourseDB(tag.course).put({
6660
6713
  ...tag,
6661
6714
  _rev: prior._rev
6662
6715
  });
6663
6716
  }
6664
6717
  async function getTag(courseID, tagName) {
6665
6718
  const tagID = getTagID(tagName);
6666
- const courseDB = getCourseDB2(courseID);
6719
+ const courseDB = getCourseDB(courseID);
6667
6720
  return courseDB.get(tagID);
6668
6721
  }
6669
6722
  async function removeTagFromCard(courseID, cardID, tagID) {
6670
6723
  tagID = getTagID(tagID);
6671
- const courseDB = getCourseDB2(courseID);
6724
+ const courseDB = getCourseDB(courseID);
6672
6725
  const tag = await courseDB.get(tagID);
6673
6726
  tag.taggedCards = tag.taggedCards.filter((taggedID) => {
6674
6727
  return cardID !== taggedID;
@@ -6687,10 +6740,10 @@ function getAncestorTagIDs(courseID, tagID) {
6687
6740
  }
6688
6741
  }
6689
6742
  async function getChildTagStubs(courseID, tagID) {
6690
- return await filterAllDocsByPrefix2(getCourseDB2(courseID), tagID + ">");
6743
+ return await filterAllDocsByPrefix2(getCourseDB(courseID), tagID + ">");
6691
6744
  }
6692
6745
  async function getAppliedTags(id_course, id_card) {
6693
- const db = getCourseDB2(id_course);
6746
+ const db = getCourseDB(id_course);
6694
6747
  const result = await db.query("getTags", {
6695
6748
  startkey: id_card,
6696
6749
  endkey: id_card
@@ -6700,7 +6753,7 @@ async function getAppliedTags(id_course, id_card) {
6700
6753
  }
6701
6754
  async function updateCardElo2(courseID, cardID, elo) {
6702
6755
  if (elo) {
6703
- const cDB = getCourseDB2(courseID);
6756
+ const cDB = getCourseDB(courseID);
6704
6757
  const card = await cDB.get(cardID);
6705
6758
  logger.debug(`Replacing ${JSON.stringify(card.elo)} with ${JSON.stringify(elo)}`);
6706
6759
  card.elo = elo;
@@ -6712,12 +6765,17 @@ async function updateCredentialledCourseConfig(courseID, config) {
6712
6765
 
6713
6766
  ${JSON.stringify(config)}
6714
6767
  `);
6715
- const db = getCourseDB2(courseID);
6768
+ const db = getCourseDB(courseID);
6769
+ invalidateCourseConfigCache(courseID);
6716
6770
  const old = await getCredentialledCourseConfig(courseID);
6717
- return await db.put({
6718
- ...config,
6719
- _rev: old._rev
6720
- });
6771
+ try {
6772
+ return await db.put({
6773
+ ...config,
6774
+ _rev: old._rev
6775
+ });
6776
+ } finally {
6777
+ invalidateCourseConfigCache(courseID);
6778
+ }
6721
6779
  }
6722
6780
  function isSuccessRow(row) {
6723
6781
  return "doc" in row && row.doc !== null && row.doc !== void 0;
@@ -6814,9 +6872,13 @@ var init_courseDB2 = __esm({
6814
6872
  * values may be stale, so read-modify-write cycles must go through
6815
6873
  * the remote DB to avoid conflicts).
6816
6874
  */
6875
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
6876
+ get readsLocal() {
6877
+ return this.db !== this.remoteDB;
6878
+ }
6817
6879
  constructor(id, userLookup, localDB) {
6818
6880
  this.id = id;
6819
- const remote = getCourseDB2(this.id);
6881
+ const remote = getCourseDB(this.id);
6820
6882
  this.remoteDB = remote;
6821
6883
  this.db = localDB ?? remote;
6822
6884
  this._getCurrentUser = userLookup;
@@ -7020,12 +7082,7 @@ ${above.rows.map((r) => ` ${r.id}-${r.key}
7020
7082
  }
7021
7083
  }
7022
7084
  async getAppliedTags(cardId) {
7023
- const ret = await getAppliedTags(this.id, cardId);
7024
- if (ret) {
7025
- return ret;
7026
- } else {
7027
- throw new Error(`Failed to find tags for card ${this.id}-${cardId}`);
7028
- }
7085
+ return this.db.query("getTags", { startkey: cardId, endkey: cardId });
7029
7086
  }
7030
7087
  async getAppliedTagsBatch(cardIds) {
7031
7088
  if (cardIds.length === 0) {
@@ -7082,7 +7139,7 @@ ${above.rows.map((r) => ` ${r.id}-${r.key}
7082
7139
  return await updateTag(tag);
7083
7140
  }
7084
7141
  async getCourseTagStubs() {
7085
- return getCourseTagStubs(this.id);
7142
+ return filterAllDocsByPrefix2(this.db, "TAG" /* TAG */.valueOf() + "-");
7086
7143
  }
7087
7144
  async addNote(codeCourse, shape, data, author, tags, uploads, elo = (0, import_common12.blankCourseElo)()) {
7088
7145
  try {
@@ -7838,13 +7895,15 @@ var init_adminDB2 = __esm({
7838
7895
  });
7839
7896
 
7840
7897
  // src/impl/couch/CourseSyncService.ts
7841
- var DEFAULT_REPLICATION, CourseSyncService;
7898
+ var SYNC_MARKER_ID, DEFAULT_REPLICATION, CourseSyncService;
7842
7899
  var init_CourseSyncService = __esm({
7843
7900
  "src/impl/couch/CourseSyncService.ts"() {
7844
7901
  "use strict";
7845
7902
  init_pouchdb_setup();
7846
7903
  init_couch();
7847
7904
  init_logger();
7905
+ init_perfMarks();
7906
+ SYNC_MARKER_ID = "_local/sk-course-sync-complete";
7848
7907
  DEFAULT_REPLICATION = {
7849
7908
  batchSize: 1e3,
7850
7909
  batchesLimit: 5
@@ -7915,19 +7974,7 @@ var init_CourseSyncService = __esm({
7915
7974
  async ensureSynced(courseId, forceEnabled) {
7916
7975
  const existing = this.entries.get(courseId);
7917
7976
  if (existing?.status.state === "ready" && existing.localDB) {
7918
- const stale = await this.isLocalEpochStale(courseId, existing.localDB);
7919
- if (!stale) {
7920
- return;
7921
- }
7922
- logger.info(
7923
- `[CourseSyncService] Remote DB epoch changed for course ${courseId} \u2014 destroying stale local replica`
7924
- );
7925
- try {
7926
- await existing.localDB.destroy();
7927
- } catch {
7928
- }
7929
- existing.localDB = null;
7930
- existing.readyPromise = null;
7977
+ return;
7931
7978
  }
7932
7979
  if (existing?.status.state === "disabled") {
7933
7980
  return;
@@ -7941,9 +7988,104 @@ var init_CourseSyncService = __esm({
7941
7988
  readyPromise: null
7942
7989
  };
7943
7990
  this.entries.set(courseId, entry);
7944
- entry.readyPromise = this.performSync(courseId, entry, forceEnabled);
7991
+ entry.readyPromise = this.startSync(courseId, entry, forceEnabled);
7945
7992
  return entry.readyPromise;
7946
7993
  }
7994
+ /**
7995
+ * A replica completed on an earlier page load is ready now, refreshed in the
7996
+ * background; anything else goes through a full performSync.
7997
+ */
7998
+ async startSync(courseId, entry, forceEnabled) {
7999
+ const localDB = new pouchdb_setup_default(this.localDBName(courseId));
8000
+ if (await this.hasSyncMarker(localDB)) {
8001
+ entry.localDB = localDB;
8002
+ entry.status = { state: "ready" };
8003
+ entry.readyPromise = null;
8004
+ perfMark("sk:course-sync-ready", { courseId, from: "marker" });
8005
+ logger.info(
8006
+ `[CourseSyncService] Using this device's replica of course ${courseId}; refreshing in the background`
8007
+ );
8008
+ void this.refreshInBackground(courseId, entry, forceEnabled);
8009
+ return;
8010
+ }
8011
+ return this.performSync(courseId, entry, forceEnabled);
8012
+ }
8013
+ /**
8014
+ * Bring a ready replica up to date without taking it away from readers.
8015
+ * Failures leave it ready (and outdated).
8016
+ */
8017
+ async refreshInBackground(courseId, entry, forceEnabled) {
8018
+ const localDB = entry.localDB;
8019
+ try {
8020
+ if (!forceEnabled && !await this.checkLocalSyncEnabled(courseId)) {
8021
+ await this.clearSyncMarker(localDB);
8022
+ logger.info(
8023
+ `[CourseSyncService] Local sync no longer enabled for course ${courseId}; replica kept for this page only`
8024
+ );
8025
+ return;
8026
+ }
8027
+ if (await this.isLocalEpochStale(courseId, localDB)) {
8028
+ await this.clearSyncMarker(localDB);
8029
+ logger.info(
8030
+ `[CourseSyncService] Remote DB recreated for course ${courseId}: keeping the outdated replica for this page; it is rebuilt on the next page load`
8031
+ );
8032
+ return;
8033
+ }
8034
+ const start = Date.now();
8035
+ const result = await this.replicate(this.getRemoteDB(courseId), localDB);
8036
+ const syncTimeMs = Date.now() - start;
8037
+ const warmStart = Date.now();
8038
+ await this.warmViewIndices(localDB);
8039
+ const viewWarmTimeMs = Date.now() - warmStart;
8040
+ await this.writeSyncMarker(localDB);
8041
+ entry.status = {
8042
+ state: "ready",
8043
+ docsReplicated: result.docs_written,
8044
+ syncTimeMs,
8045
+ viewWarmTimeMs
8046
+ };
8047
+ perfMark("sk:course-sync-refreshed", {
8048
+ courseId,
8049
+ docs: result.docs_written,
8050
+ syncTimeMs,
8051
+ viewWarmTimeMs
8052
+ });
8053
+ logger.info(
8054
+ `[CourseSyncService] Background refresh of course ${courseId}: ${result.docs_written} docs in ${syncTimeMs}ms, views ${viewWarmTimeMs}ms`
8055
+ );
8056
+ } catch (e) {
8057
+ logger.warn(
8058
+ `[CourseSyncService] Background refresh of course ${courseId} failed; replica kept as is: ${e}`
8059
+ );
8060
+ }
8061
+ }
8062
+ async hasSyncMarker(localDB) {
8063
+ try {
8064
+ await localDB.get(SYNC_MARKER_ID);
8065
+ return true;
8066
+ } catch {
8067
+ return false;
8068
+ }
8069
+ }
8070
+ async writeSyncMarker(localDB) {
8071
+ try {
8072
+ let _rev;
8073
+ try {
8074
+ _rev = (await localDB.get(SYNC_MARKER_ID))._rev;
8075
+ } catch {
8076
+ }
8077
+ await localDB.put({ _id: SYNC_MARKER_ID, _rev, completedAt: (/* @__PURE__ */ new Date()).toISOString() });
8078
+ } catch (e) {
8079
+ logger.warn(`[CourseSyncService] Could not write sync marker: ${e}`);
8080
+ }
8081
+ }
8082
+ async clearSyncMarker(localDB) {
8083
+ try {
8084
+ const marker = await localDB.get(SYNC_MARKER_ID);
8085
+ await localDB.remove(marker);
8086
+ } catch {
8087
+ }
8088
+ }
7947
8089
  /**
7948
8090
  * Get the local PouchDB for a course, or null if not available.
7949
8091
  *
@@ -8008,6 +8150,11 @@ var init_CourseSyncService = __esm({
8008
8150
  );
8009
8151
  const result = await this.replicate(remoteDB, localDB);
8010
8152
  const syncTimeMs = Date.now() - syncStart;
8153
+ perfMark("sk:course-sync-replicated", {
8154
+ courseId,
8155
+ docs: result.docs_written,
8156
+ ms: syncTimeMs
8157
+ });
8011
8158
  logger.info(
8012
8159
  `[CourseSyncService] Replication complete for course ${courseId}: ${result.docs_written} docs in ${syncTimeMs}ms`
8013
8160
  );
@@ -8018,12 +8165,14 @@ var init_CourseSyncService = __esm({
8018
8165
  logger.info(
8019
8166
  `[CourseSyncService] View indices warmed for course ${courseId} in ${viewWarmTimeMs}ms`
8020
8167
  );
8168
+ await this.writeSyncMarker(localDB);
8021
8169
  entry.status = {
8022
8170
  state: "ready",
8023
8171
  docsReplicated: result.docs_written,
8024
8172
  syncTimeMs,
8025
8173
  viewWarmTimeMs
8026
8174
  };
8175
+ perfMark("sk:course-sync-ready", { courseId, from: "sync", viewWarmTimeMs });
8027
8176
  } catch (e) {
8028
8177
  const errorMsg = e instanceof Error ? e.message : String(e);
8029
8178
  logger.error(
@@ -8111,7 +8260,8 @@ var init_CourseSyncService = __esm({
8111
8260
  try {
8112
8261
  localEpoch = await localDB.get("db-epoch");
8113
8262
  } catch {
8114
- return true;
8263
+ const info = await localDB.info();
8264
+ return info.doc_count > 0 || !!info.update_seq;
8115
8265
  }
8116
8266
  return remoteEpoch.epoch !== localEpoch.epoch;
8117
8267
  } catch {
@@ -8122,7 +8272,7 @@ var init_CourseSyncService = __esm({
8122
8272
  * Get a remote PouchDB handle for a course.
8123
8273
  */
8124
8274
  getRemoteDB(courseId) {
8125
- return getCourseDB2(courseId);
8275
+ return getCourseDB(courseId);
8126
8276
  }
8127
8277
  /**
8128
8278
  * Local DB naming convention.
@@ -8521,7 +8671,7 @@ __export(couch_exports, {
8521
8671
  getClassroomConfig: () => getClassroomConfig,
8522
8672
  getClassroomDB: () => getClassroomDB,
8523
8673
  getCouchUserDB: () => getCouchUserDB,
8524
- getCourseDB: () => getCourseDB2,
8674
+ getCourseDB: () => getCourseDB,
8525
8675
  getCourseDataShapes: () => getCourseDataShapes,
8526
8676
  getCourseDoc: () => getCourseDoc,
8527
8677
  getCourseDocs: () => getCourseDocs,
@@ -8536,6 +8686,7 @@ __export(couch_exports, {
8536
8686
  getTag: () => getTag,
8537
8687
  getTagID: () => getTagID,
8538
8688
  hexEncode: () => hexEncode,
8689
+ invalidateCourseConfigCache: () => invalidateCourseConfigCache,
8539
8690
  isReview: () => isReview,
8540
8691
  localUserDB: () => localUserDB,
8541
8692
  removeTagFromCard: () => removeTagFromCard,
@@ -8572,11 +8723,14 @@ function getCouchDB(dbName) {
8572
8723
  createPouchDBConfig()
8573
8724
  );
8574
8725
  }
8575
- function getCourseDB2(courseID) {
8576
- return new pouchdb_setup_default(
8577
- ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + "coursedb-" + courseID,
8578
- createPouchDBConfig()
8579
- );
8726
+ function getCourseDB(courseID) {
8727
+ const url = ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + "coursedb-" + courseID;
8728
+ let db = courseDBHandles.get(url);
8729
+ if (!db) {
8730
+ db = new pouchdb_setup_default(url, { ...createPouchDBConfig(), skip_setup: true });
8731
+ courseDBHandles.set(url, db);
8732
+ }
8733
+ return db;
8580
8734
  }
8581
8735
  async function getLatestVersion() {
8582
8736
  try {
@@ -8621,13 +8775,13 @@ function updateGuestAccountExpirationDate2(guestDB) {
8621
8775
  });
8622
8776
  }
8623
8777
  function getCourseDocs(courseID, docIDs, options = {}) {
8624
- return getCourseDB2(courseID).allDocs({
8778
+ return getCourseDB(courseID).allDocs({
8625
8779
  ...options,
8626
8780
  keys: docIDs
8627
8781
  });
8628
8782
  }
8629
8783
  function getCourseDoc(courseID, docID, options = {}) {
8630
- return getCourseDB2(courseID).get(docID, options);
8784
+ return getCourseDB(courseID).get(docID, options);
8631
8785
  }
8632
8786
  async function getRandomCards(courseIDs) {
8633
8787
  if (courseIDs.length === 0) {
@@ -8636,7 +8790,7 @@ async function getRandomCards(courseIDs) {
8636
8790
  } else {
8637
8791
  const courseResults = await Promise.all(
8638
8792
  courseIDs.map((course) => {
8639
- return getCourseDB2(course).find({
8793
+ return getCourseDB(course).find({
8640
8794
  selector: {
8641
8795
  docType: "CARD" /* CARD */
8642
8796
  },
@@ -8697,7 +8851,7 @@ function getStartAndEndKeys2(key) {
8697
8851
  endkey: key + "\uFFF0"
8698
8852
  };
8699
8853
  }
8700
- var import_cross_fetch2, import_moment8, expiryDocID, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig, REVIEW_TIME_FORMAT2;
8854
+ var import_cross_fetch2, import_moment8, expiryDocID, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig, courseDBHandles, REVIEW_TIME_FORMAT2;
8701
8855
  var init_couch = __esm({
8702
8856
  "src/impl/couch/index.ts"() {
8703
8857
  init_factory();
@@ -8723,6 +8877,7 @@ var init_couch = __esm({
8723
8877
  return pouchdb_setup_default.fetch(url, opts);
8724
8878
  }
8725
8879
  };
8880
+ courseDBHandles = /* @__PURE__ */ new Map();
8726
8881
  REVIEW_TIME_FORMAT2 = "YYYY-MM-DD--kk:mm:ss-SSS";
8727
8882
  }
8728
8883
  });
@@ -8766,6 +8921,7 @@ init_couch();
8766
8921
  getTag,
8767
8922
  getTagID,
8768
8923
  hexEncode,
8924
+ invalidateCourseConfigCache,
8769
8925
  isReview,
8770
8926
  localUserDB,
8771
8927
  removeTagFromCard,