@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
@@ -1473,8 +1473,10 @@ var init_updateQueue = __esm({
1473
1473
  init_logger();
1474
1474
  UpdateQueue = class extends Loggable {
1475
1475
  _className = "UpdateQueue";
1476
- pendingUpdates = {};
1477
- inprogressUpdates = {};
1476
+ /** Updates not yet taken by a write, per doc. */
1477
+ pending = /* @__PURE__ */ new Map();
1478
+ /** Docs with a drain loop running. */
1479
+ draining = /* @__PURE__ */ new Set();
1478
1480
  readDB;
1479
1481
  // Database for read operations
1480
1482
  writeDB;
@@ -1492,6 +1494,9 @@ var init_updateQueue = __esm({
1492
1494
  * **Error Handling Pattern:**
1493
1495
  * - This method does NOT create documents if they don't exist
1494
1496
  * - Callers are responsible for handling 404 errors and creating documents
1497
+ * - A rejected update is dropped from the queue: a caller that creates the
1498
+ * doc after a 404 has already applied its change and must not see it
1499
+ * re-applied by a later update to the same doc
1495
1500
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
1496
1501
  *
1497
1502
  * @example
@@ -1508,12 +1513,16 @@ var init_updateQueue = __esm({
1508
1513
  */
1509
1514
  update(id, update) {
1510
1515
  logger.debug(`Update requested on doc: ${id}`);
1511
- if (this.pendingUpdates[id]) {
1512
- this.pendingUpdates[id].push(update);
1513
- } else {
1514
- this.pendingUpdates[id] = [update];
1515
- }
1516
- return this.applyUpdates(id);
1516
+ return new Promise((resolve, reject) => {
1517
+ const queue = this.pending.get(id) ?? [];
1518
+ queue.push({
1519
+ update,
1520
+ resolve,
1521
+ reject
1522
+ });
1523
+ this.pending.set(id, queue);
1524
+ if (!this.draining.has(id)) void this.drain(id);
1525
+ });
1517
1526
  }
1518
1527
  constructor(readDB, writeDB) {
1519
1528
  super();
@@ -1524,64 +1533,56 @@ var init_updateQueue = __esm({
1524
1533
  logger.debug(`db info: ${JSON.stringify(i)}`);
1525
1534
  });
1526
1535
  }
1527
- async applyUpdates(id) {
1528
- logger.debug(`Applying updates on doc: ${id}`);
1529
- if (this.inprogressUpdates[id]) {
1530
- while (this.inprogressUpdates[id]) {
1531
- await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
1536
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
1537
+ async drain(id) {
1538
+ this.draining.add(id);
1539
+ try {
1540
+ let batch;
1541
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
1542
+ this.pending.delete(id);
1543
+ try {
1544
+ const doc = await this.write(
1545
+ id,
1546
+ batch.map((p) => p.update)
1547
+ );
1548
+ batch.forEach((p) => p.resolve(doc));
1549
+ } catch (e) {
1550
+ batch.forEach((p) => p.reject(e));
1551
+ }
1532
1552
  }
1533
- return this.applyUpdates(id);
1534
- } else {
1535
- if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
1536
- this.inprogressUpdates[id] = true;
1537
- const MAX_RETRIES = 5;
1538
- for (let i = 0; i < MAX_RETRIES; i++) {
1539
- try {
1540
- const doc = await this.readDB.get(id);
1541
- let updatedDoc = { ...doc };
1542
- const updatesToApply = [...this.pendingUpdates[id]];
1543
- for (const update of updatesToApply) {
1544
- if (typeof update === "function") {
1545
- updatedDoc = { ...updatedDoc, ...update(updatedDoc) };
1546
- } else {
1547
- updatedDoc = {
1548
- ...updatedDoc,
1549
- ...update
1550
- };
1551
- }
1552
- }
1553
- await this.writeDB.put(updatedDoc);
1554
- this.pendingUpdates[id].splice(0, updatesToApply.length);
1555
- if (this.pendingUpdates[id].length === 0) {
1556
- this.inprogressUpdates[id] = false;
1557
- delete this.inprogressUpdates[id];
1558
- } else {
1559
- return this.applyUpdates(id);
1560
- }
1561
- return updatedDoc;
1562
- } catch (e) {
1563
- if (e.name === "conflict" && i < MAX_RETRIES - 1) {
1564
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
1565
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
1566
- } else if (e.name === "not_found" && i === 0) {
1567
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
1568
- delete this.inprogressUpdates[id];
1569
- throw e;
1570
- } else {
1571
- delete this.inprogressUpdates[id];
1572
- if (this.pendingUpdates[id]) {
1573
- delete this.pendingUpdates[id];
1574
- }
1575
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
1576
- throw e;
1577
- }
1578
- }
1553
+ } finally {
1554
+ this.draining.delete(id);
1555
+ }
1556
+ }
1557
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
1558
+ async write(id, updates) {
1559
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
1560
+ const MAX_RETRIES = 5;
1561
+ for (let i = 0; i < MAX_RETRIES; i++) {
1562
+ try {
1563
+ const doc = await this.readDB.get(id);
1564
+ let updatedDoc = {
1565
+ ...doc
1566
+ };
1567
+ for (const update of updates) {
1568
+ updatedDoc = typeof update === "function" ? { ...updatedDoc, ...update(updatedDoc) } : { ...updatedDoc, ...update };
1569
+ }
1570
+ const res = await this.writeDB.put(updatedDoc);
1571
+ return { ...updatedDoc, _rev: res.rev };
1572
+ } catch (e) {
1573
+ if (e.name === "conflict" && i < MAX_RETRIES - 1) {
1574
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
1575
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
1576
+ } else if (e.name === "not_found" && i === 0) {
1577
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
1578
+ throw e;
1579
+ } else {
1580
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
1581
+ throw e;
1579
1582
  }
1580
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
1581
- } else {
1582
- throw new Error(`Empty Updates Queue Triggered`);
1583
1583
  }
1584
1584
  }
1585
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
1585
1586
  }
1586
1587
  };
1587
1588
  }
@@ -1681,6 +1682,23 @@ var init_WeightedFilter = __esm({
1681
1682
  }
1682
1683
  });
1683
1684
 
1685
+ // src/util/perfMarks.ts
1686
+ function perfMeasure(name, start, end, detail) {
1687
+ try {
1688
+ globalThis.performance?.measure(name, {
1689
+ start,
1690
+ ...end !== void 0 ? { end } : {},
1691
+ ...detail ? { detail } : {}
1692
+ });
1693
+ } catch {
1694
+ }
1695
+ }
1696
+ var init_perfMarks = __esm({
1697
+ "src/util/perfMarks.ts"() {
1698
+ "use strict";
1699
+ }
1700
+ });
1701
+
1684
1702
  // src/core/orchestration/index.ts
1685
1703
  function fnv1a(str) {
1686
1704
  let hash = 2166136261;
@@ -1967,6 +1985,7 @@ var init_Pipeline = __esm({
1967
1985
  import_common = require("@vue-skuilder/common");
1968
1986
  init_navigators();
1969
1987
  init_logger();
1988
+ init_perfMarks();
1970
1989
  init_orchestration();
1971
1990
  init_PipelineDebugger();
1972
1991
  init_diversityRerank();
@@ -2170,6 +2189,13 @@ var init_Pipeline = __esm({
2170
2189
  logger.info(
2171
2190
  `[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)})`
2172
2191
  );
2192
+ perfMeasure("sk:pipeline-run", t0, tFilter, {
2193
+ context: Math.round(tContext - t0),
2194
+ generate: Math.round(tGenerate - tContext),
2195
+ hydrate: Math.round(tHydrate - tGenerate),
2196
+ filter: Math.round(tFilter - tHydrate),
2197
+ binding: this.course?.readsLocal === void 0 ? "unknown" : this.course.readsLocal ? "local" : "remote"
2198
+ });
2173
2199
  const topScores = result.slice(0, 3).map((c) => c.score);
2174
2200
  logExecutionSummary(
2175
2201
  this.generator.name,
@@ -5097,6 +5123,18 @@ Currently logged-in as ${this._username}.`
5097
5123
  update(id, update) {
5098
5124
  return this.updateQueue.update(id, update);
5099
5125
  }
5126
+ /**
5127
+ * Create a default doc after a 404. Concurrent first reads (e.g. two
5128
+ * components on a brand-new user) both see the 404 and both create; the
5129
+ * loser's conflict just means the doc now exists, which is what it wanted.
5130
+ */
5131
+ async putDefaultUnlessCreated(doc) {
5132
+ try {
5133
+ await this.localDB.put(doc);
5134
+ } catch (e) {
5135
+ if (e.status !== 409) throw e;
5136
+ }
5137
+ }
5100
5138
  async getCourseRegistrationsDoc() {
5101
5139
  logger.debug(`Fetching courseRegistrations for ${this.getUsername()}`);
5102
5140
  let ret;
@@ -5113,7 +5151,7 @@ Currently logged-in as ${this._username}.`
5113
5151
  `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.`
5114
5152
  );
5115
5153
  }
5116
- await this.localDB.put({
5154
+ await this.putDefaultUnlessCreated({
5117
5155
  _id: _BaseUser.DOC_IDS.COURSE_REGISTRATIONS,
5118
5156
  courses: [],
5119
5157
  studyWeight: {}
@@ -5360,7 +5398,7 @@ Currently logged-in as ${this._username}.`
5360
5398
  `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.`
5361
5399
  );
5362
5400
  }
5363
- await this.localDB.put(defaultConfig);
5401
+ await this.putDefaultUnlessCreated(defaultConfig);
5364
5402
  return this.getConfig();
5365
5403
  } else {
5366
5404
  logger.error(`Error setting user default config:`, e);
@@ -5621,22 +5659,20 @@ Currently logged-in as ${this._username}.`
5621
5659
  async putCardRecord(record) {
5622
5660
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
5623
5661
  record.timeStamp = import_moment6.default.utc(record.timeStamp).toString();
5624
- try {
5625
- const cardHistory = await this.update(
5626
- cardHistoryID,
5627
- function(h) {
5628
- h.records.push(record);
5629
- h.bestInterval = h.bestInterval || 0;
5630
- if (areQuestionRecords(h)) {
5631
- h.lapses = getLapses(h.records);
5632
- h.streak = getStreak(h.records);
5633
- } else {
5634
- h.lapses = h.lapses || 0;
5635
- h.streak = h.streak || 0;
5636
- }
5637
- return h;
5638
- }
5639
- );
5662
+ const append = (h) => {
5663
+ h.records.push(record);
5664
+ h.bestInterval = h.bestInterval || 0;
5665
+ if (areQuestionRecords(h)) {
5666
+ h.lapses = getLapses(h.records);
5667
+ h.streak = getStreak(h.records);
5668
+ } else {
5669
+ h.lapses = h.lapses || 0;
5670
+ h.streak = h.streak || 0;
5671
+ }
5672
+ return h;
5673
+ };
5674
+ const appendToExisting = async () => {
5675
+ const cardHistory = await this.update(cardHistoryID, append);
5640
5676
  cardHistory.records = cardHistory.records.map((record2) => {
5641
5677
  const ret = {
5642
5678
  ...record2
@@ -5645,6 +5681,9 @@ Currently logged-in as ${this._username}.`
5645
5681
  return ret;
5646
5682
  });
5647
5683
  return cardHistory;
5684
+ };
5685
+ try {
5686
+ return await appendToExisting();
5648
5687
  } catch (e) {
5649
5688
  const reason = e;
5650
5689
  if (reason.status === 404) {
@@ -5661,6 +5700,9 @@ Currently logged-in as ${this._username}.`
5661
5700
  const putResult = await this.writeDB.put(initCardHistory);
5662
5701
  return { ...initCardHistory, _rev: putResult.rev };
5663
5702
  } catch (creationError) {
5703
+ if (creationError.name === "conflict") {
5704
+ return appendToExisting();
5705
+ }
5664
5706
  throw new Error(
5665
5707
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
5666
5708
  );
@@ -5976,36 +6018,38 @@ var init_common = __esm({
5976
6018
 
5977
6019
  // src/impl/couch/courseAPI.ts
5978
6020
  async function getCredentialledCourseConfig(courseID) {
5979
- try {
6021
+ const hit = courseConfigCache.get(courseID);
6022
+ if (hit && Date.now() - hit.at < COURSE_CONFIG_TTL_MS) {
6023
+ return structuredClone(await hit.config);
6024
+ }
6025
+ const config = (async () => {
5980
6026
  const db = getCourseDB(courseID);
5981
6027
  const ret = await db.get("CourseConfig");
5982
6028
  ret.courseID = courseID;
5983
- logger.info(`Returning course config: ${JSON.stringify(ret)}`);
6029
+ logger.debug(`Fetched course config for ${courseID}`);
5984
6030
  return ret;
6031
+ })();
6032
+ courseConfigCache.set(courseID, { at: Date.now(), config });
6033
+ try {
6034
+ return structuredClone(await config);
5985
6035
  } catch (e) {
6036
+ courseConfigCache.delete(courseID);
5986
6037
  logger.error(`Error fetching config for ${courseID}:`, e);
5987
6038
  throw e;
5988
6039
  }
5989
6040
  }
5990
- function getCourseDB(courseID) {
5991
- const dbName = `coursedb-${courseID}`;
5992
- return new pouchdb_setup_default(
5993
- ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + dbName,
5994
- createPouchDBConfig()
5995
- );
5996
- }
5997
- var import_common8, import_common9, import_common10, import_uuid;
6041
+ var import_common8, import_common9, import_common10, import_uuid, COURSE_CONFIG_TTL_MS, courseConfigCache;
5998
6042
  var init_courseAPI = __esm({
5999
6043
  "src/impl/couch/courseAPI.ts"() {
6000
6044
  "use strict";
6001
- init_pouchdb_setup();
6002
6045
  init_couch();
6003
- init_factory();
6004
6046
  import_common8 = require("@vue-skuilder/common");
6005
6047
  import_common9 = require("@vue-skuilder/common");
6006
6048
  import_common10 = require("@vue-skuilder/common");
6007
6049
  init_logger();
6008
6050
  import_uuid = require("uuid");
6051
+ COURSE_CONFIG_TTL_MS = 5 * 60 * 1e3;
6052
+ courseConfigCache = /* @__PURE__ */ new Map();
6009
6053
  }
6010
6054
  });
6011
6055
 
@@ -6045,7 +6089,16 @@ function createPouchDBConfig() {
6045
6089
  }
6046
6090
  return pouchDBincludeCredentialsConfig;
6047
6091
  }
6048
- var import_cross_fetch, import_moment7, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig;
6092
+ function getCourseDB(courseID) {
6093
+ const url = ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + "coursedb-" + courseID;
6094
+ let db = courseDBHandles.get(url);
6095
+ if (!db) {
6096
+ db = new pouchdb_setup_default(url, { ...createPouchDBConfig(), skip_setup: true });
6097
+ courseDBHandles.set(url, db);
6098
+ }
6099
+ return db;
6100
+ }
6101
+ var import_cross_fetch, import_moment7, GUEST_LOCAL_DB, localUserDB, pouchDBincludeCredentialsConfig, courseDBHandles;
6049
6102
  var init_couch = __esm({
6050
6103
  "src/impl/couch/index.ts"() {
6051
6104
  "use strict";
@@ -6069,6 +6122,7 @@ var init_couch = __esm({
6069
6122
  return pouchdb_setup_default.fetch(url, opts);
6070
6123
  }
6071
6124
  };
6125
+ courseDBHandles = /* @__PURE__ */ new Map();
6072
6126
  }
6073
6127
  });
6074
6128