@vue-skuilder/db 0.2.37 → 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 (46) hide show
  1. package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
  2. package/dist/core/index.cjs +112 -78
  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 +18 -13
  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 +134 -79
  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 +108 -78
  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 +144 -80
  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/package.json +3 -3
  37. package/src/core/interfaces/courseDB.ts +6 -0
  38. package/src/core/navigators/Pipeline.ts +8 -0
  39. package/src/impl/common/BaseUserDB.ts +27 -21
  40. package/src/impl/couch/CourseSyncService.ts +19 -2
  41. package/src/impl/couch/courseDB.ts +5 -0
  42. package/src/impl/couch/updateQueue.ts +86 -82
  43. package/src/study/SessionController.ts +4 -0
  44. package/src/util/index.ts +1 -0
  45. package/src/util/perfMarks.ts +35 -0
  46. 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);
@@ -8573,22 +8603,20 @@ Currently logged-in as ${this._username}.`
8573
8603
  async putCardRecord(record) {
8574
8604
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
8575
8605
  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
- );
8606
+ const append = (h) => {
8607
+ h.records.push(record);
8608
+ h.bestInterval = h.bestInterval || 0;
8609
+ if (areQuestionRecords(h)) {
8610
+ h.lapses = getLapses(h.records);
8611
+ h.streak = getStreak(h.records);
8612
+ } else {
8613
+ h.lapses = h.lapses || 0;
8614
+ h.streak = h.streak || 0;
8615
+ }
8616
+ return h;
8617
+ };
8618
+ const appendToExisting = async () => {
8619
+ const cardHistory = await this.update(cardHistoryID, append);
8592
8620
  cardHistory.records = cardHistory.records.map((record2) => {
8593
8621
  const ret = {
8594
8622
  ...record2
@@ -8597,6 +8625,9 @@ Currently logged-in as ${this._username}.`
8597
8625
  return ret;
8598
8626
  });
8599
8627
  return cardHistory;
8628
+ };
8629
+ try {
8630
+ return await appendToExisting();
8600
8631
  } catch (e) {
8601
8632
  const reason = e;
8602
8633
  if (reason.status === 404) {
@@ -8613,6 +8644,9 @@ Currently logged-in as ${this._username}.`
8613
8644
  const putResult = await this.writeDB.put(initCardHistory);
8614
8645
  return { ...initCardHistory, _rev: putResult.rev };
8615
8646
  } catch (creationError) {
8647
+ if (creationError.name === "conflict") {
8648
+ return appendToExisting();
8649
+ }
8616
8650
  throw new Error(
8617
8651
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
8618
8652
  );