@vue-skuilder/db 0.2.37 → 0.3.1

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 (47) hide show
  1. package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
  2. package/dist/core/index.cjs +155 -100
  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/versionStamps.mjs +1 -1
  8. package/dist/{dataLayerProvider-BDshhSp_.d.ts → dataLayerProvider-rGyLQ93v.d.ts} +1 -1
  9. package/dist/diagnostics/index.d.ts +3 -3
  10. package/dist/impl/common/BaseUserDB.mjs +61 -34
  11. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  12. package/dist/impl/couch/CourseSyncService.mjs +23 -1
  13. package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
  14. package/dist/impl/couch/courseDB.mjs +4 -0
  15. package/dist/impl/couch/courseDB.mjs.map +1 -1
  16. package/dist/impl/couch/index.cjs +177 -101
  17. package/dist/impl/couch/index.cjs.map +1 -1
  18. package/dist/impl/couch/index.d.ts +5 -3
  19. package/dist/impl/couch/updateQueue.mjs +69 -46
  20. package/dist/impl/couch/updateQueue.mjs.map +1 -1
  21. package/dist/impl/static/index.cjs +151 -100
  22. package/dist/impl/static/index.cjs.map +1 -1
  23. package/dist/impl/static/index.d.ts +4 -4
  24. package/dist/{index-BLDpFYG3.d.ts → index-C745YB_6.d.ts} +1 -1
  25. package/dist/index.cjs +187 -102
  26. package/dist/index.cjs.map +1 -1
  27. package/dist/index.d.ts +23 -10
  28. package/dist/index.mjs +2 -1
  29. package/dist/study/SessionController.mjs +4 -0
  30. package/dist/study/SessionController.mjs.map +1 -1
  31. package/dist/{types-DChCz22D.d.ts → types-DF0JuPbs.d.ts} +1 -1
  32. package/dist/{types-legacy-fT5Y1Wuy.d.ts → types-legacy-DdVjg81H.d.ts} +1 -1
  33. package/dist/util/packer/index.d.ts +3 -3
  34. package/dist/util/perfMarks.mjs +30 -0
  35. package/dist/util/perfMarks.mjs.map +1 -0
  36. package/docs/session-lifecycle-and-replan.md +71 -58
  37. package/package.json +3 -3
  38. package/src/core/interfaces/courseDB.ts +6 -0
  39. package/src/core/navigators/Pipeline.ts +8 -0
  40. package/src/impl/common/BaseUserDB.ts +74 -46
  41. package/src/impl/couch/CourseSyncService.ts +19 -2
  42. package/src/impl/couch/courseDB.ts +5 -0
  43. package/src/impl/couch/updateQueue.ts +86 -82
  44. package/src/study/SessionController.ts +4 -0
  45. package/src/util/index.ts +1 -0
  46. package/src/util/perfMarks.ts +35 -0
  47. package/tests/impl/updateQueue.test.ts +57 -0
@@ -1,6 +1,6 @@
1
1
  import { Status, CourseConfig, SkuilderCourseData as SkuilderCourseData$1, CourseElo, DataShape, TagFilter } from '@vue-skuilder/common';
2
2
  import { Moment } from 'moment';
3
- import { S as SkuilderCourseData, i as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, e as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-fT5Y1Wuy.js';
3
+ import { S as SkuilderCourseData, f as DocTypePrefixes, D as DocType, Q as QualifiedCardID, T as TagStub, a as Tag, e as CardHistory, c as CardRecord, d as QuestionRecord } from './types-legacy-DdVjg81H.js';
4
4
 
5
5
  interface DataLayerResult {
6
6
  status: Status;
@@ -106,6 +106,11 @@ interface CourseInfo {
106
106
  registeredUsers: number;
107
107
  }
108
108
  interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
109
+ /**
110
+ * Whether reads go to a local replica rather than the server. Optional: only
111
+ * implementations with both (couch) report it; perf marks read it.
112
+ */
113
+ readonly readsLocal?: boolean;
109
114
  /**
110
115
  * Get course config
111
116
  */
@@ -3775,8 +3775,10 @@ var init_updateQueue = __esm({
3775
3775
  init_logger();
3776
3776
  UpdateQueue = class extends Loggable {
3777
3777
  _className = "UpdateQueue";
3778
- pendingUpdates = {};
3779
- inprogressUpdates = {};
3778
+ /** Updates not yet taken by a write, per doc. */
3779
+ pending = /* @__PURE__ */ new Map();
3780
+ /** Docs with a drain loop running. */
3781
+ draining = /* @__PURE__ */ new Set();
3780
3782
  readDB;
3781
3783
  // Database for read operations
3782
3784
  writeDB;
@@ -3794,6 +3796,9 @@ var init_updateQueue = __esm({
3794
3796
  * **Error Handling Pattern:**
3795
3797
  * - This method does NOT create documents if they don't exist
3796
3798
  * - Callers are responsible for handling 404 errors and creating documents
3799
+ * - A rejected update is dropped from the queue: a caller that creates the
3800
+ * doc after a 404 has already applied its change and must not see it
3801
+ * re-applied by a later update to the same doc
3797
3802
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
3798
3803
  *
3799
3804
  * @example
@@ -3810,12 +3815,16 @@ var init_updateQueue = __esm({
3810
3815
  */
3811
3816
  update(id, update) {
3812
3817
  logger.debug(`Update requested on doc: ${id}`);
3813
- if (this.pendingUpdates[id]) {
3814
- this.pendingUpdates[id].push(update);
3815
- } else {
3816
- this.pendingUpdates[id] = [update];
3817
- }
3818
- return this.applyUpdates(id);
3818
+ return new Promise((resolve, reject) => {
3819
+ const queue = this.pending.get(id) ?? [];
3820
+ queue.push({
3821
+ update,
3822
+ resolve,
3823
+ reject
3824
+ });
3825
+ this.pending.set(id, queue);
3826
+ if (!this.draining.has(id)) void this.drain(id);
3827
+ });
3819
3828
  }
3820
3829
  constructor(readDB, writeDB) {
3821
3830
  super();
@@ -3826,64 +3835,56 @@ var init_updateQueue = __esm({
3826
3835
  logger.debug(`db info: ${JSON.stringify(i)}`);
3827
3836
  });
3828
3837
  }
3829
- async applyUpdates(id) {
3830
- logger.debug(`Applying updates on doc: ${id}`);
3831
- if (this.inprogressUpdates[id]) {
3832
- while (this.inprogressUpdates[id]) {
3833
- await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
3838
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
3839
+ async drain(id) {
3840
+ this.draining.add(id);
3841
+ try {
3842
+ let batch;
3843
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
3844
+ this.pending.delete(id);
3845
+ try {
3846
+ const doc = await this.write(
3847
+ id,
3848
+ batch.map((p) => p.update)
3849
+ );
3850
+ batch.forEach((p) => p.resolve(doc));
3851
+ } catch (e) {
3852
+ batch.forEach((p) => p.reject(e));
3853
+ }
3834
3854
  }
3835
- return this.applyUpdates(id);
3836
- } else {
3837
- if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
3838
- this.inprogressUpdates[id] = true;
3839
- const MAX_RETRIES = 5;
3840
- for (let i = 0; i < MAX_RETRIES; i++) {
3841
- try {
3842
- const doc = await this.readDB.get(id);
3843
- let updatedDoc = { ...doc };
3844
- const updatesToApply = [...this.pendingUpdates[id]];
3845
- for (const update of updatesToApply) {
3846
- if (typeof update === "function") {
3847
- updatedDoc = { ...updatedDoc, ...update(updatedDoc) };
3848
- } else {
3849
- updatedDoc = {
3850
- ...updatedDoc,
3851
- ...update
3852
- };
3853
- }
3854
- }
3855
- await this.writeDB.put(updatedDoc);
3856
- this.pendingUpdates[id].splice(0, updatesToApply.length);
3857
- if (this.pendingUpdates[id].length === 0) {
3858
- this.inprogressUpdates[id] = false;
3859
- delete this.inprogressUpdates[id];
3860
- } else {
3861
- return this.applyUpdates(id);
3862
- }
3863
- return updatedDoc;
3864
- } catch (e) {
3865
- if (e.name === "conflict" && i < MAX_RETRIES - 1) {
3866
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
3867
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
3868
- } else if (e.name === "not_found" && i === 0) {
3869
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
3870
- delete this.inprogressUpdates[id];
3871
- throw e;
3872
- } else {
3873
- delete this.inprogressUpdates[id];
3874
- if (this.pendingUpdates[id]) {
3875
- delete this.pendingUpdates[id];
3876
- }
3877
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
3878
- throw e;
3879
- }
3880
- }
3855
+ } finally {
3856
+ this.draining.delete(id);
3857
+ }
3858
+ }
3859
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
3860
+ async write(id, updates) {
3861
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
3862
+ const MAX_RETRIES = 5;
3863
+ for (let i = 0; i < MAX_RETRIES; i++) {
3864
+ try {
3865
+ const doc = await this.readDB.get(id);
3866
+ let updatedDoc = {
3867
+ ...doc
3868
+ };
3869
+ for (const update of updates) {
3870
+ updatedDoc = typeof update === "function" ? { ...updatedDoc, ...update(updatedDoc) } : { ...updatedDoc, ...update };
3871
+ }
3872
+ const res = await this.writeDB.put(updatedDoc);
3873
+ return { ...updatedDoc, _rev: res.rev };
3874
+ } catch (e) {
3875
+ if (e.name === "conflict" && i < MAX_RETRIES - 1) {
3876
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
3877
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
3878
+ } else if (e.name === "not_found" && i === 0) {
3879
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
3880
+ throw e;
3881
+ } else {
3882
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
3883
+ throw e;
3881
3884
  }
3882
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
3883
- } else {
3884
- throw new Error(`Empty Updates Queue Triggered`);
3885
3885
  }
3886
3886
  }
3887
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
3887
3888
  }
3888
3889
  };
3889
3890
  }
@@ -4002,6 +4003,23 @@ var init_WeightedFilter = __esm({
4002
4003
  }
4003
4004
  });
4004
4005
 
4006
+ // src/util/perfMarks.ts
4007
+ function perfMeasure(name, start, end, detail) {
4008
+ try {
4009
+ globalThis.performance?.measure(name, {
4010
+ start,
4011
+ ...end !== void 0 ? { end } : {},
4012
+ ...detail ? { detail } : {}
4013
+ });
4014
+ } catch {
4015
+ }
4016
+ }
4017
+ var init_perfMarks = __esm({
4018
+ "src/util/perfMarks.ts"() {
4019
+ "use strict";
4020
+ }
4021
+ });
4022
+
4005
4023
  // src/core/orchestration/gradient.ts
4006
4024
  function aggregateOutcomesForGradient(outcomes, strategyId) {
4007
4025
  const observations = [];
@@ -4478,6 +4496,7 @@ var init_Pipeline = __esm({
4478
4496
  import_common6 = require("@vue-skuilder/common");
4479
4497
  init_navigators();
4480
4498
  init_logger();
4499
+ init_perfMarks();
4481
4500
  init_orchestration();
4482
4501
  init_PipelineDebugger();
4483
4502
  init_diversityRerank();
@@ -4681,6 +4700,13 @@ var init_Pipeline = __esm({
4681
4700
  logger.info(
4682
4701
  `[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)})`
4683
4702
  );
4703
+ perfMeasure("sk:pipeline-run", t0, tFilter, {
4704
+ context: Math.round(tContext - t0),
4705
+ generate: Math.round(tGenerate - tContext),
4706
+ hydrate: Math.round(tHydrate - tGenerate),
4707
+ filter: Math.round(tFilter - tHydrate),
4708
+ binding: this.course?.readsLocal === void 0 ? "unknown" : this.course.readsLocal ? "local" : "remote"
4709
+ });
4684
4710
  const topScores = result.slice(0, 3).map((c) => c.score);
4685
4711
  logExecutionSummary(
4686
4712
  this.generator.name,
@@ -5791,6 +5817,10 @@ var init_courseDB = __esm({
5791
5817
  * values may be stale, so read-modify-write cycles must go through
5792
5818
  * the remote DB to avoid conflicts).
5793
5819
  */
5820
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
5821
+ get readsLocal() {
5822
+ return this.db !== this.remoteDB;
5823
+ }
5794
5824
  constructor(id, userLookup, localDB) {
5795
5825
  this.id = id;
5796
5826
  const remote = getCourseDB(this.id);
@@ -7847,6 +7877,9 @@ var init_BaseUserDB = __esm({
7847
7877
  // Database to use for write operations (local-first approach)
7848
7878
  updateQueue;
7849
7879
  _hydration = { state: "not-required" };
7880
+ /** See scanScheduledCards. Bumped by every write to scheduled reviews. */
7881
+ _scheduledScan = null;
7882
+ _scheduledGeneration = 0;
7850
7883
  /** In-flight hydration, so concurrent callers can wait for a real answer. */
7851
7884
  _hydrationPromise = null;
7852
7885
  /**
@@ -8091,18 +8124,38 @@ Currently logged-in as ${this._username}.`
8091
8124
  *
8092
8125
  */
8093
8126
  async getActiveCards() {
8127
+ return (await this.scanScheduledCards()).map((doc) => ({
8128
+ courseID: doc.courseId,
8129
+ cardID: doc.cardId
8130
+ }));
8131
+ }
8132
+ /**
8133
+ * The user's scheduled reviews (`card_review_*`), all of them: one `allDocs`
8134
+ * scan shared by concurrent readers. A pipeline run's generators start
8135
+ * together (`CompositeGenerator`), and each used to scan the range itself
8136
+ * (`getActiveCards` from ELO and Prescribed, `getReviewstoDate` from SRS).
8137
+ * Sharing only an in-flight scan keeps reads as fresh as before; a schedule
8138
+ * or removal of a review starts a new scan for anyone reading after it.
8139
+ * Docs are shared between callers: copy before mutating.
8140
+ */
8141
+ scanScheduledCards() {
8142
+ const inFlight = this._scheduledScan;
8143
+ if (inFlight && inFlight.generation === this._scheduledGeneration) return inFlight.scan;
8094
8144
  const keys = getStartAndEndKeys(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */]);
8095
- const reviews = await this.remoteDB.allDocs({
8096
- startkey: keys.startkey,
8097
- endkey: keys.endkey,
8098
- include_docs: true
8099
- });
8100
- return reviews.rows.map((r) => {
8101
- return {
8102
- courseID: r.doc.courseId,
8103
- cardID: r.doc.cardId
8104
- };
8105
- });
8145
+ const entry = {
8146
+ generation: this._scheduledGeneration,
8147
+ scan: this.remoteDB.allDocs({
8148
+ startkey: keys.startkey,
8149
+ endkey: keys.endkey,
8150
+ include_docs: true
8151
+ }).then((res) => res.rows.map((row) => row.doc))
8152
+ };
8153
+ this._scheduledScan = entry;
8154
+ const done = () => {
8155
+ if (this._scheduledScan === entry) this._scheduledScan = null;
8156
+ };
8157
+ entry.scan.then(done, done);
8158
+ return entry.scan;
8106
8159
  }
8107
8160
  async getActivityRecords() {
8108
8161
  try {
@@ -8168,28 +8221,23 @@ Currently logged-in as ${this._username}.`
8168
8221
  }
8169
8222
  }
8170
8223
  async getReviewstoDate(targetDate, course_id) {
8171
- const keys = getStartAndEndKeys(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */]);
8172
- const reviews = await this.remoteDB.allDocs({
8173
- startkey: keys.startkey,
8174
- endkey: keys.endkey,
8175
- include_docs: true
8176
- });
8224
+ const reviews = await this.scanScheduledCards();
8177
8225
  log3(
8178
8226
  `Fetching ${this._username}'s scheduled reviews${course_id ? ` for course ${course_id}` : ""}.`
8179
8227
  );
8180
- return reviews.rows.filter((r) => {
8181
- if (r.id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
8228
+ return reviews.filter((doc) => {
8229
+ if (doc._id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
8182
8230
  const date = import_moment6.default.utc(
8183
- r.id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
8231
+ doc._id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
8184
8232
  REVIEW_TIME_FORMAT
8185
8233
  );
8186
8234
  if (targetDate.isAfter(date)) {
8187
- if (course_id === void 0 || r.doc.courseId === course_id) {
8235
+ if (course_id === void 0 || doc.courseId === course_id) {
8188
8236
  return true;
8189
8237
  }
8190
8238
  }
8191
8239
  }
8192
- }).map((r) => r.doc);
8240
+ }).map((doc) => ({ ...doc }));
8193
8241
  }
8194
8242
  async getReviewsForcast(daysCount, course_id) {
8195
8243
  const time = import_moment6.default.utc().add(daysCount, "days");
@@ -8573,22 +8621,20 @@ Currently logged-in as ${this._username}.`
8573
8621
  async putCardRecord(record) {
8574
8622
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
8575
8623
  record.timeStamp = import_moment6.default.utc(record.timeStamp).toString();
8576
- try {
8577
- const cardHistory = await this.update(
8578
- cardHistoryID,
8579
- function(h) {
8580
- h.records.push(record);
8581
- h.bestInterval = h.bestInterval || 0;
8582
- if (areQuestionRecords(h)) {
8583
- h.lapses = getLapses(h.records);
8584
- h.streak = getStreak(h.records);
8585
- } else {
8586
- h.lapses = h.lapses || 0;
8587
- h.streak = h.streak || 0;
8588
- }
8589
- return h;
8590
- }
8591
- );
8624
+ const append = (h) => {
8625
+ h.records.push(record);
8626
+ h.bestInterval = h.bestInterval || 0;
8627
+ if (areQuestionRecords(h)) {
8628
+ h.lapses = getLapses(h.records);
8629
+ h.streak = getStreak(h.records);
8630
+ } else {
8631
+ h.lapses = h.lapses || 0;
8632
+ h.streak = h.streak || 0;
8633
+ }
8634
+ return h;
8635
+ };
8636
+ const appendToExisting = async () => {
8637
+ const cardHistory = await this.update(cardHistoryID, append);
8592
8638
  cardHistory.records = cardHistory.records.map((record2) => {
8593
8639
  const ret = {
8594
8640
  ...record2
@@ -8597,6 +8643,9 @@ Currently logged-in as ${this._username}.`
8597
8643
  return ret;
8598
8644
  });
8599
8645
  return cardHistory;
8646
+ };
8647
+ try {
8648
+ return await appendToExisting();
8600
8649
  } catch (e) {
8601
8650
  const reason = e;
8602
8651
  if (reason.status === 404) {
@@ -8613,6 +8662,9 @@ Currently logged-in as ${this._username}.`
8613
8662
  const putResult = await this.writeDB.put(initCardHistory);
8614
8663
  return { ...initCardHistory, _rev: putResult.rev };
8615
8664
  } catch (creationError) {
8665
+ if (creationError.name === "conflict") {
8666
+ return appendToExisting();
8667
+ }
8616
8668
  throw new Error(
8617
8669
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
8618
8670
  );
@@ -8656,6 +8708,7 @@ Currently logged-in as ${this._username}.`
8656
8708
  const deletePromises = duplicateDocIds.map(async (docId) => {
8657
8709
  try {
8658
8710
  const doc = await this.remoteDB.get(docId);
8711
+ this._scheduledGeneration++;
8659
8712
  await this.writeDB.remove(doc);
8660
8713
  log3(`Successfully removed duplicate review: ${docId}`);
8661
8714
  } catch (error) {
@@ -8801,9 +8854,11 @@ Currently logged-in as ${this._username}.`
8801
8854
  }
8802
8855
  }
8803
8856
  async scheduleCardReview(review) {
8857
+ this._scheduledGeneration++;
8804
8858
  return scheduleCardReviewLocal(this.writeDB, review);
8805
8859
  }
8806
8860
  async removeScheduledCardReview(reviewId) {
8861
+ this._scheduledGeneration++;
8807
8862
  return removeScheduledCardReviewLocal(this.writeDB, reviewId);
8808
8863
  }
8809
8864
  async registerForClassroom(_classId, _registerAs) {