@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
@@ -3,14 +3,26 @@ import { logger } from '../../util/logger';
3
3
 
4
4
  export type Update<T> = Partial<T> | ((x: T) => T);
5
5
 
6
+ type Applied<T> = T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta;
7
+
8
+ /** A queued update and the caller waiting on it. */
9
+ interface Pending {
10
+ update: Update<unknown>;
11
+ resolve: (doc: unknown) => void;
12
+ reject: (e: unknown) => void;
13
+ }
14
+
15
+ /**
16
+ * Serialises updates per document. Updates queued while a write is in flight
17
+ * go out together in the next write; each one settles exactly once, with the
18
+ * outcome of the write that carried it, and is never applied again.
19
+ */
6
20
  export default class UpdateQueue extends Loggable {
7
21
  _className: string = 'UpdateQueue';
8
- private pendingUpdates: {
9
- [index: string]: Update<unknown>[];
10
- } = {};
11
- private inprogressUpdates: {
12
- [index: string]: boolean;
13
- } = {};
22
+ /** Updates not yet taken by a write, per doc. */
23
+ private pending: Map<string, Pending[]> = new Map();
24
+ /** Docs with a drain loop running. */
25
+ private draining: Set<string> = new Set();
14
26
 
15
27
  private readDB: PouchDB.Database; // Database for read operations
16
28
  private writeDB: PouchDB.Database; // Database for write operations (local-first)
@@ -28,6 +40,9 @@ export default class UpdateQueue extends Loggable {
28
40
  * **Error Handling Pattern:**
29
41
  * - This method does NOT create documents if they don't exist
30
42
  * - Callers are responsible for handling 404 errors and creating documents
43
+ * - A rejected update is dropped from the queue: a caller that creates the
44
+ * doc after a 404 has already applied its change and must not see it
45
+ * re-applied by a later update to the same doc
31
46
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
32
47
  *
33
48
  * @example
@@ -45,14 +60,18 @@ export default class UpdateQueue extends Loggable {
45
60
  public update<T extends PouchDB.Core.Document<object>>(
46
61
  id: PouchDB.Core.DocumentId,
47
62
  update: Update<T>
48
- ) {
63
+ ): Promise<Applied<T>> {
49
64
  logger.debug(`Update requested on doc: ${id}`);
50
- if (this.pendingUpdates[id]) {
51
- this.pendingUpdates[id].push(update);
52
- } else {
53
- this.pendingUpdates[id] = [update];
54
- }
55
- return this.applyUpdates<T>(id);
65
+ return new Promise<Applied<T>>((resolve, reject) => {
66
+ const queue = this.pending.get(id) ?? [];
67
+ queue.push({
68
+ update: update as Update<unknown>,
69
+ resolve: resolve as (doc: unknown) => void,
70
+ reject,
71
+ });
72
+ this.pending.set(id, queue);
73
+ if (!this.draining.has(id)) void this.drain(id);
74
+ });
56
75
  }
57
76
 
58
77
  constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {
@@ -66,81 +85,66 @@ export default class UpdateQueue extends Loggable {
66
85
  });
67
86
  }
68
87
 
69
- private async applyUpdates<T extends PouchDB.Core.Document<object>>(
70
- id: string
71
- ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {
72
- logger.debug(`Applying updates on doc: ${id}`);
73
- if (this.inprogressUpdates[id]) {
74
- // Poll instead of recursing to avoid infinite recursion
75
- while (this.inprogressUpdates[id]) {
76
- await new Promise(resolve => setTimeout(resolve, Math.random() * 50));
88
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
89
+ private async drain(id: string): Promise<void> {
90
+ this.draining.add(id);
91
+ try {
92
+ let batch: Pending[] | undefined;
93
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
94
+ // Take the batch: anything queued from here on goes in the next write.
95
+ this.pending.delete(id);
96
+ try {
97
+ const doc = await this.write(
98
+ id,
99
+ batch.map((p) => p.update)
100
+ );
101
+ batch.forEach((p) => p.resolve(doc));
102
+ } catch (e) {
103
+ batch.forEach((p) => p.reject(e));
104
+ }
77
105
  }
78
- return this.applyUpdates<T>(id);
79
- } else {
80
- if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
81
- this.inprogressUpdates[id] = true;
82
-
83
- const MAX_RETRIES = 5;
84
- for (let i = 0; i < MAX_RETRIES; i++) {
85
- try {
86
- const doc = await this.readDB.get<T>(id);
87
-
88
- // Create a new doc object to apply updates to for this attempt
89
- let updatedDoc = { ...doc };
90
-
91
- // Note: This loop is not fully safe if updates are functions that depend on a specific doc state
92
- // that might change between retries. But for simple object merges, it's okay.
93
- const updatesToApply = [...this.pendingUpdates[id]];
94
- for (const update of updatesToApply) {
95
- if (typeof update === 'function') {
96
- updatedDoc = { ...updatedDoc, ...update(updatedDoc) };
97
- } else {
98
- updatedDoc = {
99
- ...updatedDoc,
100
- ...update,
101
- };
102
- }
103
- }
106
+ } finally {
107
+ this.draining.delete(id);
108
+ }
109
+ }
104
110
 
105
- await this.writeDB.put<T>(updatedDoc);
111
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
112
+ private async write(id: string, updates: Update<unknown>[]): Promise<unknown> {
113
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
114
+ const MAX_RETRIES = 5;
115
+ for (let i = 0; i < MAX_RETRIES; i++) {
116
+ try {
117
+ const doc = await this.readDB.get<object>(id);
106
118
 
107
- // Success! Remove the updates we just applied.
108
- this.pendingUpdates[id].splice(0, updatesToApply.length);
119
+ // Applied to a fresh copy each attempt, so function updates see the
120
+ // doc as read on this attempt.
121
+ let updatedDoc: PouchDB.Core.Document<object> & Partial<PouchDB.Core.RevisionIdMeta> = {
122
+ ...doc,
123
+ };
124
+ for (const update of updates) {
125
+ updatedDoc =
126
+ typeof update === 'function'
127
+ ? { ...updatedDoc, ...(update as (x: unknown) => object)(updatedDoc) }
128
+ : { ...updatedDoc, ...(update as object) };
129
+ }
109
130
 
110
- if (this.pendingUpdates[id].length === 0) {
111
- this.inprogressUpdates[id] = false;
112
- delete this.inprogressUpdates[id];
113
- } else {
114
- // More updates came in, run again.
115
- return this.applyUpdates<T>(id);
116
- }
117
- return updatedDoc as any; // success, exit loop and function
118
- } catch (e: any) {
119
- if (e.name === 'conflict' && i < MAX_RETRIES - 1) {
120
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
121
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
122
- // continue to next iteration of the loop
123
- } else if (e.name === 'not_found' && i === 0) {
124
- // Document not present - throw to caller for initialization
125
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
126
- delete this.inprogressUpdates[id];
127
- throw e; // Let caller handle
128
- } else {
129
- // Max retries reached or a non-conflict error
130
- delete this.inprogressUpdates[id];
131
- if (this.pendingUpdates[id]) {
132
- delete this.pendingUpdates[id];
133
- }
134
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
135
- throw e; // Let caller handle
136
- }
137
- }
131
+ const res = await this.writeDB.put(updatedDoc);
132
+ return { ...updatedDoc, _rev: res.rev };
133
+ } catch (e: any) {
134
+ if (e.name === 'conflict' && i < MAX_RETRIES - 1) {
135
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
136
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
137
+ } else if (e.name === 'not_found' && i === 0) {
138
+ // Document not present - throw to caller for initialization
139
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
140
+ throw e;
141
+ } else {
142
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
143
+ throw e;
138
144
  }
139
- // This should be unreachable, but it satisfies the compiler that a value is always returned or an error thrown.
140
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
141
- } else {
142
- throw new Error(`Empty Updates Queue Triggered`);
143
145
  }
144
146
  }
147
+ // Unreachable: the last attempt returns or throws.
148
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
145
149
  }
146
150
  }
@@ -27,6 +27,7 @@ import {
27
27
  } from '@db/core/types/studySession';
28
28
  import { recordUserOutcome } from '@db/core/orchestration/recording';
29
29
  import { Loggable } from '@db/util';
30
+ import { perfMark, perfMeasure } from '@db/util/perfMarks';
30
31
  import {
31
32
  getCardOrigin,
32
33
  WeightedCard,
@@ -603,6 +604,7 @@ export class SessionController<TView = unknown> extends Loggable {
603
604
  // bootstrap pipeline run fires, so that run's own report isn't wiped out.
604
605
  clearStaleSessionDebugState();
605
606
 
607
+ perfMark('sk:session-prepare-start');
606
608
  const wellIndicated = await this.getWeightedContent();
607
609
  this._recordRuns('bootstrap');
608
610
  this._wellIndicatedRemaining = wellIndicated;
@@ -612,6 +614,8 @@ export class SessionController<TView = unknown> extends Loggable {
612
614
  );
613
615
  }
614
616
  await this.hydrationService.ensureHydratedCards();
617
+ perfMark('sk:session-prepared');
618
+ perfMeasure('sk:session-prepare', 'sk:session-prepare-start', 'sk:session-prepared');
615
619
 
616
620
  // Start session tracking for debugging
617
621
  startSessionTracking(this.sessionId, this.supplyQ.length, this.failedQ.length);
package/src/util/index.ts CHANGED
@@ -2,3 +2,4 @@ export * from './Loggable';
2
2
  export * from './packer';
3
3
  export * from './migrator';
4
4
  export * from './dataDirectory';
5
+ export * from './perfMarks';
@@ -0,0 +1,35 @@
1
+ /**
2
+ * User Timing marks for session and sync milestones.
3
+ *
4
+ * Names are `sk:`-prefixed (apps add their own, e.g. LP's `lp:`). Read them with
5
+ * `performance.getEntriesByType('mark' | 'measure')`: synthetic runs (Playwright,
6
+ * Lighthouse's `user-timings`) and, later, real-user measurement.
7
+ *
8
+ * Marks never throw: a missing or partial User Timing API is a no-op.
9
+ */
10
+
11
+ export function perfMark(name: string, detail?: Record<string, unknown>): void {
12
+ try {
13
+ globalThis.performance?.mark(name, detail ? { detail } : undefined);
14
+ } catch {
15
+ // no User Timing (or no `detail` support): nothing to record
16
+ }
17
+ }
18
+
19
+ /** A measure from `start` (a mark name or a `performance.now()` value) to now or `end`. */
20
+ export function perfMeasure(
21
+ name: string,
22
+ start: string | number,
23
+ end?: string | number,
24
+ detail?: Record<string, unknown>
25
+ ): void {
26
+ try {
27
+ globalThis.performance?.measure(name, {
28
+ start,
29
+ ...(end !== undefined ? { end } : {}),
30
+ ...(detail ? { detail } : {}),
31
+ });
32
+ } catch {
33
+ // unknown start mark, or no User Timing: nothing to record
34
+ }
35
+ }
@@ -0,0 +1,57 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import PouchDB from 'pouchdb';
3
+ import memoryAdapter from 'pouchdb-adapter-memory';
4
+ import UpdateQueue from '@db/impl/couch/updateQueue';
5
+
6
+ PouchDB.plugin(memoryAdapter);
7
+
8
+ interface Doc {
9
+ _id: string;
10
+ _rev?: string;
11
+ records: number[];
12
+ }
13
+
14
+ let n = 0;
15
+ const freshDB = () => new PouchDB(`updatequeue-test-${n++}`, { adapter: 'memory' });
16
+ const push = (r: number) => (d: Doc) => ({ ...d, records: [...d.records, r] });
17
+
18
+ describe('UpdateQueue', () => {
19
+ it('drops an update rejected with 404: the caller creating the doc does not see it re-applied', async () => {
20
+ const db = freshDB();
21
+ const q = new UpdateQueue(db);
22
+
23
+ // putCardRecord's first-ever record: update → 404 → create holding the record.
24
+ await expect(q.update<Doc>('d', push(1))).rejects.toMatchObject({ status: 404 });
25
+ await db.put({ _id: 'd', records: [1] });
26
+
27
+ // The retry's record.
28
+ await q.update<Doc>('d', push(2));
29
+ expect((await db.get<Doc>('d')).records).toEqual([1, 2]);
30
+ });
31
+
32
+ it('settles every update queued while a write is in flight', async () => {
33
+ const db = freshDB();
34
+ await db.put({ _id: 'd', records: [] });
35
+ const q = new UpdateQueue(db);
36
+
37
+ const first = q.update<Doc>('d', push(1));
38
+ await Promise.resolve(); // the first write is under way
39
+ const rest = [2, 3, 4].map((r) => q.update<Doc>('d', push(r)));
40
+
41
+ const done = await Promise.race([
42
+ Promise.all([first, ...rest]).then(() => 'settled'),
43
+ new Promise((res) => setTimeout(() => res('hung'), 2000)),
44
+ ]);
45
+ expect(done).toBe('settled');
46
+ expect((await db.get<Doc>('d')).records).toEqual([1, 2, 3, 4]);
47
+ });
48
+
49
+ it('resolves with the written revision', async () => {
50
+ const db = freshDB();
51
+ await db.put({ _id: 'd', records: [] });
52
+ const q = new UpdateQueue(db);
53
+
54
+ const doc = await q.update<Doc>('d', push(1));
55
+ expect(doc._rev).toBe((await db.get<Doc>('d'))._rev);
56
+ });
57
+ });