@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,8 +1,8 @@
1
- import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-fT5Y1Wuy.js';
1
+ import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-DdVjg81H.js';
2
2
  import { Moment } from 'moment';
3
3
  export { h as hexEncode } from '../../userDBKeys-ne1g4Xuq.js';
4
- import { o as StudyContentSource, U as UserDBInterface, G as GeneratorResult, a as CoursesDBInterface, C as CourseDBInterface, b as CourseInfo, D as DataLayerResult, c as ContentNavigationStrategyData, d as ContentNavigator, R as ReplanHints, S as StudySessionItem, f as ScheduledCard } from '../../contentSource-D_E7JaxR.js';
5
- export { v as ContentSourceID, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, s as StudySessionNewItem, t as StudySessionReviewItem, w as getStudySource, u as isReview } from '../../contentSource-D_E7JaxR.js';
4
+ import { o as StudyContentSource, U as UserDBInterface, G as GeneratorResult, a as CoursesDBInterface, C as CourseDBInterface, b as CourseInfo, D as DataLayerResult, c as ContentNavigationStrategyData, d as ContentNavigator, R as ReplanHints, S as StudySessionItem, f as ScheduledCard } from '../../contentSource-2zVmcjKA.js';
5
+ export { v as ContentSourceID, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, s as StudySessionNewItem, t as StudySessionReviewItem, w as getStudySource, u as isReview } from '../../contentSource-2zVmcjKA.js';
6
6
  import { A as AdminDBInterface, a as AssignedContent, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from '../../classroomDB-DLTtLZct.js';
7
7
  import * as _vue_skuilder_common from '@vue-skuilder/common';
8
8
  import { ClassroomConfig, DataShape, CourseElo, CourseConfig as CourseConfig$1 } from '@vue-skuilder/common';
@@ -224,6 +224,8 @@ declare class CourseDB implements CourseDBInterface {
224
224
  * values may be stale, so read-modify-write cycles must go through
225
225
  * the remote DB to avoid conflicts).
226
226
  */
227
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
228
+ get readsLocal(): boolean;
227
229
  constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database);
228
230
  getCourseID(): string;
229
231
  getCourseInfo(): Promise<CourseInfo>;
@@ -2,10 +2,17 @@ import "../../_virtual/_rolldown/runtime.mjs";
2
2
  import { logger } from "../../util/logger.mjs";
3
3
  import { Loggable } from "../../util/Loggable.mjs";
4
4
  //#region src/impl/couch/updateQueue.ts
5
+ /**
6
+ * Serialises updates per document. Updates queued while a write is in flight
7
+ * go out together in the next write; each one settles exactly once, with the
8
+ * outcome of the write that carried it, and is never applied again.
9
+ */
5
10
  var UpdateQueue = class extends Loggable {
6
11
  _className = "UpdateQueue";
7
- pendingUpdates = {};
8
- inprogressUpdates = {};
12
+ /** Updates not yet taken by a write, per doc. */
13
+ pending = /* @__PURE__ */ new Map();
14
+ /** Docs with a drain loop running. */
15
+ draining = /* @__PURE__ */ new Set();
9
16
  readDB;
10
17
  writeDB;
11
18
  /**
@@ -21,6 +28,9 @@ var UpdateQueue = class extends Loggable {
21
28
  * **Error Handling Pattern:**
22
29
  * - This method does NOT create documents if they don't exist
23
30
  * - Callers are responsible for handling 404 errors and creating documents
31
+ * - A rejected update is dropped from the queue: a caller that creates the
32
+ * doc after a 404 has already applied its change and must not see it
33
+ * re-applied by a later update to the same doc
24
34
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
25
35
  *
26
36
  * @example
@@ -37,9 +47,16 @@ var UpdateQueue = class extends Loggable {
37
47
  */
38
48
  update(id, update) {
39
49
  logger.debug(`Update requested on doc: ${id}`);
40
- if (this.pendingUpdates[id]) this.pendingUpdates[id].push(update);
41
- else this.pendingUpdates[id] = [update];
42
- return this.applyUpdates(id);
50
+ return new Promise((resolve, reject) => {
51
+ const queue = this.pending.get(id) ?? [];
52
+ queue.push({
53
+ update,
54
+ resolve,
55
+ reject
56
+ });
57
+ this.pending.set(id, queue);
58
+ if (!this.draining.has(id)) this.drain(id);
59
+ });
43
60
  }
44
61
  constructor(readDB, writeDB) {
45
62
  super();
@@ -50,49 +67,55 @@ var UpdateQueue = class extends Loggable {
50
67
  logger.debug(`db info: ${JSON.stringify(i)}`);
51
68
  });
52
69
  }
53
- async applyUpdates(id) {
54
- logger.debug(`Applying updates on doc: ${id}`);
55
- if (this.inprogressUpdates[id]) {
56
- while (this.inprogressUpdates[id]) await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
57
- return this.applyUpdates(id);
58
- } else if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
59
- this.inprogressUpdates[id] = true;
60
- const MAX_RETRIES = 5;
61
- for (let i = 0; i < MAX_RETRIES; i++) try {
62
- let updatedDoc = { ...await this.readDB.get(id) };
63
- const updatesToApply = [...this.pendingUpdates[id]];
64
- for (const update of updatesToApply) if (typeof update === "function") updatedDoc = {
65
- ...updatedDoc,
66
- ...update(updatedDoc)
67
- };
68
- else updatedDoc = {
69
- ...updatedDoc,
70
- ...update
71
- };
72
- await this.writeDB.put(updatedDoc);
73
- this.pendingUpdates[id].splice(0, updatesToApply.length);
74
- if (this.pendingUpdates[id].length === 0) {
75
- this.inprogressUpdates[id] = false;
76
- delete this.inprogressUpdates[id];
77
- } else return this.applyUpdates(id);
78
- return updatedDoc;
79
- } catch (e) {
80
- if (e.name === "conflict" && i < MAX_RETRIES - 1) {
81
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
82
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
83
- } else if (e.name === "not_found" && i === 0) {
84
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
85
- delete this.inprogressUpdates[id];
86
- throw e;
87
- } else {
88
- delete this.inprogressUpdates[id];
89
- if (this.pendingUpdates[id]) delete this.pendingUpdates[id];
90
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
91
- throw e;
70
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
71
+ async drain(id) {
72
+ this.draining.add(id);
73
+ try {
74
+ let batch;
75
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
76
+ this.pending.delete(id);
77
+ try {
78
+ const doc = await this.write(id, batch.map((p) => p.update));
79
+ batch.forEach((p) => p.resolve(doc));
80
+ } catch (e) {
81
+ batch.forEach((p) => p.reject(e));
92
82
  }
93
83
  }
94
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
95
- } else throw new Error(`Empty Updates Queue Triggered`);
84
+ } finally {
85
+ this.draining.delete(id);
86
+ }
87
+ }
88
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
89
+ async write(id, updates) {
90
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
91
+ const MAX_RETRIES = 5;
92
+ for (let i = 0; i < MAX_RETRIES; i++) try {
93
+ let updatedDoc = { ...await this.readDB.get(id) };
94
+ for (const update of updates) updatedDoc = typeof update === "function" ? {
95
+ ...updatedDoc,
96
+ ...update(updatedDoc)
97
+ } : {
98
+ ...updatedDoc,
99
+ ...update
100
+ };
101
+ const res = await this.writeDB.put(updatedDoc);
102
+ return {
103
+ ...updatedDoc,
104
+ _rev: res.rev
105
+ };
106
+ } catch (e) {
107
+ if (e.name === "conflict" && i < MAX_RETRIES - 1) {
108
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
109
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
110
+ } else if (e.name === "not_found" && i === 0) {
111
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
112
+ throw e;
113
+ } else {
114
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
115
+ throw e;
116
+ }
117
+ }
118
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
96
119
  }
97
120
  };
98
121
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"updateQueue.mjs","names":[],"sources":["../../../src/impl/couch/updateQueue.ts"],"sourcesContent":["import { Loggable } from '../../util/Loggable';\nimport { logger } from '../../util/logger';\n\nexport type Update<T> = Partial<T> | ((x: T) => T);\n\nexport default class UpdateQueue extends Loggable {\n _className: string = 'UpdateQueue';\n private pendingUpdates: {\n [index: string]: Update<unknown>[];\n } = {};\n private inprogressUpdates: {\n [index: string]: boolean;\n } = {};\n\n private readDB: PouchDB.Database; // Database for read operations\n private writeDB: PouchDB.Database; // Database for write operations (local-first)\n\n /**\n * Queues an update for a document and applies it with conflict resolution.\n *\n * @param id - Document ID to update\n * @param update - Partial object or function that transforms the document\n * @returns Promise resolving to the updated document\n *\n * @throws {PouchError} with status 404 if document doesn't exist\n *\n * @remarks\n * **Error Handling Pattern:**\n * - This method does NOT create documents if they don't exist\n * - Callers are responsible for handling 404 errors and creating documents\n * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)\n *\n * @example\n * ```typescript\n * try {\n * await updateQueue.update(docId, (doc) => ({ ...doc, field: newValue }));\n * } catch (e) {\n * if ((e as PouchError).status === 404) {\n * // Create the document with initial values\n * await db.put({ _id: docId, field: newValue, ...initialFields });\n * }\n * }\n * ```\n */\n public update<T extends PouchDB.Core.Document<object>>(\n id: PouchDB.Core.DocumentId,\n update: Update<T>\n ) {\n logger.debug(`Update requested on doc: ${id}`);\n if (this.pendingUpdates[id]) {\n this.pendingUpdates[id].push(update);\n } else {\n this.pendingUpdates[id] = [update];\n }\n return this.applyUpdates<T>(id);\n }\n\n constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {\n super();\n // PouchDB.debug.enable('*');\n this.readDB = readDB;\n this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided\n logger.debug(`UpdateQ initialized...`);\n void this.readDB.info().then((i) => {\n logger.debug(`db info: ${JSON.stringify(i)}`);\n });\n }\n\n private async applyUpdates<T extends PouchDB.Core.Document<object>>(\n id: string\n ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {\n logger.debug(`Applying updates on doc: ${id}`);\n if (this.inprogressUpdates[id]) {\n // Poll instead of recursing to avoid infinite recursion\n while (this.inprogressUpdates[id]) {\n await new Promise(resolve => setTimeout(resolve, Math.random() * 50));\n }\n return this.applyUpdates<T>(id);\n } else {\n if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {\n this.inprogressUpdates[id] = true;\n\n const MAX_RETRIES = 5;\n for (let i = 0; i < MAX_RETRIES; i++) {\n try {\n const doc = await this.readDB.get<T>(id);\n\n // Create a new doc object to apply updates to for this attempt\n let updatedDoc = { ...doc };\n\n // Note: This loop is not fully safe if updates are functions that depend on a specific doc state\n // that might change between retries. But for simple object merges, it's okay.\n const updatesToApply = [...this.pendingUpdates[id]];\n for (const update of updatesToApply) {\n if (typeof update === 'function') {\n updatedDoc = { ...updatedDoc, ...update(updatedDoc) };\n } else {\n updatedDoc = {\n ...updatedDoc,\n ...update,\n };\n }\n }\n\n await this.writeDB.put<T>(updatedDoc);\n\n // Success! Remove the updates we just applied.\n this.pendingUpdates[id].splice(0, updatesToApply.length);\n\n if (this.pendingUpdates[id].length === 0) {\n this.inprogressUpdates[id] = false;\n delete this.inprogressUpdates[id];\n } else {\n // More updates came in, run again.\n return this.applyUpdates<T>(id);\n }\n return updatedDoc as any; // success, exit loop and function\n } catch (e: any) {\n if (e.name === 'conflict' && i < MAX_RETRIES - 1) {\n logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);\n await new Promise((res) => setTimeout(res, 50 * Math.random()));\n // continue to next iteration of the loop\n } else if (e.name === 'not_found' && i === 0) {\n // Document not present - throw to caller for initialization\n logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);\n delete this.inprogressUpdates[id];\n throw e; // Let caller handle\n } else {\n // Max retries reached or a non-conflict error\n delete this.inprogressUpdates[id];\n if (this.pendingUpdates[id]) {\n delete this.pendingUpdates[id];\n }\n logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);\n throw e; // Let caller handle\n }\n }\n }\n // This should be unreachable, but it satisfies the compiler that a value is always returned or an error thrown.\n throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);\n } else {\n throw new Error(`Empty Updates Queue Triggered`);\n }\n }\n }\n}\n"],"mappings":";;;;AAKA,IAAqB,cAArB,cAAyC,SAAS;CAChD,aAAqB;CACrB,iBAEI,EAAE;CACN,oBAEI,EAAE;CAEN;CACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BA,OACE,IACA,QACA;AACA,SAAO,MAAM,4BAA4B,KAAK;AAC9C,MAAI,KAAK,eAAe,IACtB,MAAK,eAAe,IAAI,KAAK,OAAO;MAEpC,MAAK,eAAe,MAAM,CAAC,OAAO;AAEpC,SAAO,KAAK,aAAgB,GAAG;;CAGjC,YAAY,QAA0B,SAA4B;AAChE,SAAO;AAEP,OAAK,SAAS;AACd,OAAK,UAAU,WAAW;AAC1B,SAAO,MAAM,yBAAyB;AACjC,OAAK,OAAO,MAAM,CAAC,MAAM,MAAM;AAClC,UAAO,MAAM,YAAY,KAAK,UAAU,EAAE,GAAG;IAC7C;;CAGJ,MAAc,aACZ,IACiE;AACjE,SAAO,MAAM,4BAA4B,KAAK;AAC9C,MAAI,KAAK,kBAAkB,KAAK;AAE9B,UAAO,KAAK,kBAAkB,IAC5B,OAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,KAAK,QAAQ,GAAG,GAAG,CAAC;AAEvE,UAAO,KAAK,aAAgB,GAAG;aAE3B,KAAK,eAAe,OAAO,KAAK,eAAe,IAAI,SAAS,GAAG;AACjE,QAAK,kBAAkB,MAAM;GAE7B,MAAM,cAAc;AACpB,QAAK,IAAI,IAAI,GAAG,IAAI,aAAa,IAC/B,KAAI;IAIF,IAAI,aAAa,EAAE,GAHP,MAAM,KAAK,OAAO,IAAO,GAAG,EAGb;IAI3B,MAAM,iBAAiB,CAAC,GAAG,KAAK,eAAe,IAAI;AACnD,SAAK,MAAM,UAAU,eACnB,KAAI,OAAO,WAAW,WACpB,cAAa;KAAE,GAAG;KAAY,GAAG,OAAO,WAAW;KAAE;QAErD,cAAa;KACX,GAAG;KACH,GAAG;KACJ;AAIL,UAAM,KAAK,QAAQ,IAAO,WAAW;AAGrC,SAAK,eAAe,IAAI,OAAO,GAAG,eAAe,OAAO;AAExD,QAAI,KAAK,eAAe,IAAI,WAAW,GAAG;AACxC,UAAK,kBAAkB,MAAM;AAC7B,YAAO,KAAK,kBAAkB;UAG9B,QAAO,KAAK,aAAgB,GAAG;AAEjC,WAAO;YACA,GAAQ;AACf,QAAI,EAAE,SAAS,cAAc,IAAI,cAAc,GAAG;AAChD,YAAO,KAAK,8BAA8B,GAAG,WAAW,IAAI,IAAI;AAChE,WAAM,IAAI,SAAS,QAAQ,WAAW,KAAK,KAAK,KAAK,QAAQ,CAAC,CAAC;eAEtD,EAAE,SAAS,eAAe,MAAM,GAAG;AAE5C,YAAO,KAAK,qBAAqB,GAAG,wCAAwC;AAC5E,YAAO,KAAK,kBAAkB;AAC9B,WAAM;WACD;AAEL,YAAO,KAAK,kBAAkB;AAC9B,SAAI,KAAK,eAAe,IACtB,QAAO,KAAK,eAAe;AAE7B,YAAO,MAAM,mCAAmC,EAAE,KAAK,KAAK,UAAU,EAAE,GAAG;AAC3E,WAAM;;;AAKZ,SAAM,IAAI,MAAM,8BAA8B,GAAG,SAAS,YAAY,WAAW;QAEjF,OAAM,IAAI,MAAM,gCAAgC"}
1
+ {"version":3,"file":"updateQueue.mjs","names":[],"sources":["../../../src/impl/couch/updateQueue.ts"],"sourcesContent":["import { Loggable } from '../../util/Loggable';\nimport { logger } from '../../util/logger';\n\nexport type Update<T> = Partial<T> | ((x: T) => T);\n\ntype Applied<T> = T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta;\n\n/** A queued update and the caller waiting on it. */\ninterface Pending {\n update: Update<unknown>;\n resolve: (doc: unknown) => void;\n reject: (e: unknown) => void;\n}\n\n/**\n * Serialises updates per document. Updates queued while a write is in flight\n * go out together in the next write; each one settles exactly once, with the\n * outcome of the write that carried it, and is never applied again.\n */\nexport default class UpdateQueue extends Loggable {\n _className: string = 'UpdateQueue';\n /** Updates not yet taken by a write, per doc. */\n private pending: Map<string, Pending[]> = new Map();\n /** Docs with a drain loop running. */\n private draining: Set<string> = new Set();\n\n private readDB: PouchDB.Database; // Database for read operations\n private writeDB: PouchDB.Database; // Database for write operations (local-first)\n\n /**\n * Queues an update for a document and applies it with conflict resolution.\n *\n * @param id - Document ID to update\n * @param update - Partial object or function that transforms the document\n * @returns Promise resolving to the updated document\n *\n * @throws {PouchError} with status 404 if document doesn't exist\n *\n * @remarks\n * **Error Handling Pattern:**\n * - This method does NOT create documents if they don't exist\n * - Callers are responsible for handling 404 errors and creating documents\n * - A rejected update is dropped from the queue: a caller that creates the\n * doc after a 404 has already applied its change and must not see it\n * re-applied by a later update to the same doc\n * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)\n *\n * @example\n * ```typescript\n * try {\n * await updateQueue.update(docId, (doc) => ({ ...doc, field: newValue }));\n * } catch (e) {\n * if ((e as PouchError).status === 404) {\n * // Create the document with initial values\n * await db.put({ _id: docId, field: newValue, ...initialFields });\n * }\n * }\n * ```\n */\n public update<T extends PouchDB.Core.Document<object>>(\n id: PouchDB.Core.DocumentId,\n update: Update<T>\n ): Promise<Applied<T>> {\n logger.debug(`Update requested on doc: ${id}`);\n return new Promise<Applied<T>>((resolve, reject) => {\n const queue = this.pending.get(id) ?? [];\n queue.push({\n update: update as Update<unknown>,\n resolve: resolve as (doc: unknown) => void,\n reject,\n });\n this.pending.set(id, queue);\n if (!this.draining.has(id)) void this.drain(id);\n });\n }\n\n constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {\n super();\n // PouchDB.debug.enable('*');\n this.readDB = readDB;\n this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided\n logger.debug(`UpdateQ initialized...`);\n void this.readDB.info().then((i) => {\n logger.debug(`db info: ${JSON.stringify(i)}`);\n });\n }\n\n /** Writes the doc's queued updates, batch by batch, until none are left. */\n private async drain(id: string): Promise<void> {\n this.draining.add(id);\n try {\n let batch: Pending[] | undefined;\n while ((batch = this.pending.get(id)) && batch.length > 0) {\n // Take the batch: anything queued from here on goes in the next write.\n this.pending.delete(id);\n try {\n const doc = await this.write(\n id,\n batch.map((p) => p.update)\n );\n batch.forEach((p) => p.resolve(doc));\n } catch (e) {\n batch.forEach((p) => p.reject(e));\n }\n }\n } finally {\n this.draining.delete(id);\n }\n }\n\n /** One read-apply-put of `updates`, retried on conflict against a fresh read. */\n private async write(id: string, updates: Update<unknown>[]): Promise<unknown> {\n logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);\n const MAX_RETRIES = 5;\n for (let i = 0; i < MAX_RETRIES; i++) {\n try {\n const doc = await this.readDB.get<object>(id);\n\n // Applied to a fresh copy each attempt, so function updates see the\n // doc as read on this attempt.\n let updatedDoc: PouchDB.Core.Document<object> & Partial<PouchDB.Core.RevisionIdMeta> = {\n ...doc,\n };\n for (const update of updates) {\n updatedDoc =\n typeof update === 'function'\n ? { ...updatedDoc, ...(update as (x: unknown) => object)(updatedDoc) }\n : { ...updatedDoc, ...(update as object) };\n }\n\n const res = await this.writeDB.put(updatedDoc);\n return { ...updatedDoc, _rev: res.rev };\n } catch (e: any) {\n if (e.name === 'conflict' && i < MAX_RETRIES - 1) {\n logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);\n await new Promise((res) => setTimeout(res, 50 * Math.random()));\n } else if (e.name === 'not_found' && i === 0) {\n // Document not present - throw to caller for initialization\n logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);\n throw e;\n } else {\n logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);\n throw e;\n }\n }\n }\n // Unreachable: the last attempt returns or throws.\n throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);\n }\n}\n"],"mappings":";;;;;;;;;AAmBA,IAAqB,cAArB,cAAyC,SAAS;CAChD,aAAqB;;CAErB,0BAA0C,IAAI,KAAK;;CAEnD,2BAAgC,IAAI,KAAK;CAEzC;CACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCA,OACE,IACA,QACqB;AACrB,SAAO,MAAM,4BAA4B,KAAK;AAC9C,SAAO,IAAI,SAAqB,SAAS,WAAW;GAClD,MAAM,QAAQ,KAAK,QAAQ,IAAI,GAAG,IAAI,EAAE;AACxC,SAAM,KAAK;IACD;IACC;IACT;IACD,CAAC;AACF,QAAK,QAAQ,IAAI,IAAI,MAAM;AAC3B,OAAI,CAAC,KAAK,SAAS,IAAI,GAAG,CAAO,MAAK,MAAM,GAAG;IAC/C;;CAGJ,YAAY,QAA0B,SAA4B;AAChE,SAAO;AAEP,OAAK,SAAS;AACd,OAAK,UAAU,WAAW;AAC1B,SAAO,MAAM,yBAAyB;AACjC,OAAK,OAAO,MAAM,CAAC,MAAM,MAAM;AAClC,UAAO,MAAM,YAAY,KAAK,UAAU,EAAE,GAAG;IAC7C;;;CAIJ,MAAc,MAAM,IAA2B;AAC7C,OAAK,SAAS,IAAI,GAAG;AACrB,MAAI;GACF,IAAI;AACJ,WAAQ,QAAQ,KAAK,QAAQ,IAAI,GAAG,KAAK,MAAM,SAAS,GAAG;AAEzD,SAAK,QAAQ,OAAO,GAAG;AACvB,QAAI;KACF,MAAM,MAAM,MAAM,KAAK,MACrB,IACA,MAAM,KAAK,MAAM,EAAE,OAAO,CAC3B;AACD,WAAM,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;aAC7B,GAAG;AACV,WAAM,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC;;;YAG7B;AACR,QAAK,SAAS,OAAO,GAAG;;;;CAK5B,MAAc,MAAM,IAAY,SAA8C;AAC5E,SAAO,MAAM,YAAY,QAAQ,OAAO,qBAAqB,KAAK;EAClE,MAAM,cAAc;AACpB,OAAK,IAAI,IAAI,GAAG,IAAI,aAAa,IAC/B,KAAI;GAKF,IAAI,aAAmF,EACrF,GALU,MAAM,KAAK,OAAO,IAAY,GAAG,EAM5C;AACD,QAAK,MAAM,UAAU,QACnB,cACE,OAAO,WAAW,aACd;IAAE,GAAG;IAAY,GAAI,OAAkC,WAAW;IAAE,GACpE;IAAE,GAAG;IAAY,GAAI;IAAmB;GAGhD,MAAM,MAAM,MAAM,KAAK,QAAQ,IAAI,WAAW;AAC9C,UAAO;IAAE,GAAG;IAAY,MAAM,IAAI;IAAK;WAChC,GAAQ;AACf,OAAI,EAAE,SAAS,cAAc,IAAI,cAAc,GAAG;AAChD,WAAO,KAAK,8BAA8B,GAAG,WAAW,IAAI,IAAI;AAChE,UAAM,IAAI,SAAS,QAAQ,WAAW,KAAK,KAAK,KAAK,QAAQ,CAAC,CAAC;cACtD,EAAE,SAAS,eAAe,MAAM,GAAG;AAE5C,WAAO,KAAK,qBAAqB,GAAG,wCAAwC;AAC5E,UAAM;UACD;AACL,WAAO,MAAM,mCAAmC,EAAE,KAAK,KAAK,UAAU,EAAE,GAAG;AAC3E,UAAM;;;AAKZ,QAAM,IAAI,MAAM,8BAA8B,GAAG,SAAS,YAAY,WAAW"}
@@ -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,
@@ -5633,22 +5659,20 @@ Currently logged-in as ${this._username}.`
5633
5659
  async putCardRecord(record) {
5634
5660
  const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
5635
5661
  record.timeStamp = import_moment6.default.utc(record.timeStamp).toString();
5636
- try {
5637
- const cardHistory = await this.update(
5638
- cardHistoryID,
5639
- function(h) {
5640
- h.records.push(record);
5641
- h.bestInterval = h.bestInterval || 0;
5642
- if (areQuestionRecords(h)) {
5643
- h.lapses = getLapses(h.records);
5644
- h.streak = getStreak(h.records);
5645
- } else {
5646
- h.lapses = h.lapses || 0;
5647
- h.streak = h.streak || 0;
5648
- }
5649
- return h;
5650
- }
5651
- );
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);
5652
5676
  cardHistory.records = cardHistory.records.map((record2) => {
5653
5677
  const ret = {
5654
5678
  ...record2
@@ -5657,6 +5681,9 @@ Currently logged-in as ${this._username}.`
5657
5681
  return ret;
5658
5682
  });
5659
5683
  return cardHistory;
5684
+ };
5685
+ try {
5686
+ return await appendToExisting();
5660
5687
  } catch (e) {
5661
5688
  const reason = e;
5662
5689
  if (reason.status === 404) {
@@ -5673,6 +5700,9 @@ Currently logged-in as ${this._username}.`
5673
5700
  const putResult = await this.writeDB.put(initCardHistory);
5674
5701
  return { ...initCardHistory, _rev: putResult.rev };
5675
5702
  } catch (creationError) {
5703
+ if (creationError.name === "conflict") {
5704
+ return appendToExisting();
5705
+ }
5676
5706
  throw new Error(
5677
5707
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
5678
5708
  );