@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
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.2.37",
16
+ "version": "0.3.0",
17
17
  "description": "Database layer for vue-skuilder",
18
18
  "main": "dist/index.cjs",
19
19
  "module": "dist/index.mjs",
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "@nilock2/pouchdb-authentication": "^1.0.2",
72
- "@vue-skuilder/common": "0.2.37",
72
+ "@vue-skuilder/common": "0.3.0",
73
73
  "cross-fetch": "^4.1.0",
74
74
  "moment": "^2.29.4",
75
75
  "pouchdb": "^9.0.0",
@@ -87,5 +87,5 @@
87
87
  "vite": "^8.0.0",
88
88
  "vitest": "^4.1.0"
89
89
  },
90
- "stableVersion": "0.2.37"
90
+ "stableVersion": "0.3.0"
91
91
  }
@@ -27,6 +27,12 @@ export interface CourseInfo {
27
27
  }
28
28
 
29
29
  export interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
30
+ /**
31
+ * Whether reads go to a local replica rather than the server. Optional: only
32
+ * implementations with both (couch) report it; perf marks read it.
33
+ */
34
+ readonly readsLocal?: boolean;
35
+
30
36
  /**
31
37
  * Get course config
32
38
  */
@@ -7,6 +7,7 @@ import type { CardFilter, FilterContext } from './filters/types';
7
7
  import type { CardGenerator, GeneratorContext } from './generators/types';
8
8
  import type { GeneratorResult } from './generators/types';
9
9
  import { logger } from '../../util/logger';
10
+ import { perfMeasure } from '../../util/perfMarks';
10
11
  import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
11
12
  import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
12
13
  import { diversityRerank } from './diversityRerank';
@@ -572,6 +573,13 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
572
573
  `(context=${(tContext - t0).toFixed(0)} generate=${(tGenerate - tContext).toFixed(0)} ` +
573
574
  `hydrate=${(tHydrate - tGenerate).toFixed(0)} filter=${(tFilter - tHydrate).toFixed(0)})`
574
575
  );
576
+ perfMeasure('sk:pipeline-run', t0, tFilter, {
577
+ context: Math.round(tContext - t0),
578
+ generate: Math.round(tGenerate - tContext),
579
+ hydrate: Math.round(tHydrate - tGenerate),
580
+ filter: Math.round(tFilter - tHydrate),
581
+ binding: this.course?.readsLocal === undefined ? 'unknown' : this.course.readsLocal ? 'local' : 'remote',
582
+ });
575
583
 
576
584
  // Toggle execution summary logging:
577
585
  const topScores = result.slice(0, 3).map((c) => c.score);
@@ -1063,27 +1063,24 @@ Currently logged-in as ${this._username}.`
1063
1063
  // stringify the current record to make it writable to couchdb
1064
1064
  record.timeStamp = moment.utc(record.timeStamp).toString() as unknown as Moment;
1065
1065
 
1066
- try {
1067
- const cardHistory = await this.update<CardHistory<T>>(
1068
- cardHistoryID,
1069
- function (h: CardHistory<T>) {
1070
- h.records.push(record);
1071
- h.bestInterval = h.bestInterval || 0;
1072
- // Scheduling (SpacedRepetition.newQuestionInterval) re-derives
1073
- // lapses/streak from `records` on every call, so these persisted
1074
- // fields are informational — kept current so the stored doc reads
1075
- // truthfully when inspected outside a session.
1076
- if (areQuestionRecords(h)) {
1077
- h.lapses = getLapses(h.records);
1078
- h.streak = getStreak(h.records);
1079
- } else {
1080
- h.lapses = h.lapses || 0;
1081
- h.streak = h.streak || 0;
1082
- }
1083
- return h;
1084
- }
1085
- );
1086
-
1066
+ const append = (h: CardHistory<T>): CardHistory<T> => {
1067
+ h.records.push(record);
1068
+ h.bestInterval = h.bestInterval || 0;
1069
+ // Scheduling (SpacedRepetition.newQuestionInterval) re-derives
1070
+ // lapses/streak from `records` on every call, so these persisted
1071
+ // fields are informational — kept current so the stored doc reads
1072
+ // truthfully when inspected outside a session.
1073
+ if (areQuestionRecords(h)) {
1074
+ h.lapses = getLapses(h.records);
1075
+ h.streak = getStreak(h.records);
1076
+ } else {
1077
+ h.lapses = h.lapses || 0;
1078
+ h.streak = h.streak || 0;
1079
+ }
1080
+ return h;
1081
+ };
1082
+ const appendToExisting = async () => {
1083
+ const cardHistory = await this.update<CardHistory<T>>(cardHistoryID, append);
1087
1084
  // Convert timestamps to moment objects
1088
1085
  cardHistory.records = cardHistory.records.map<T>((record) => {
1089
1086
  const ret: T = {
@@ -1093,6 +1090,10 @@ Currently logged-in as ${this._username}.`
1093
1090
  return ret;
1094
1091
  });
1095
1092
  return cardHistory;
1093
+ };
1094
+
1095
+ try {
1096
+ return await appendToExisting();
1096
1097
  } catch (e) {
1097
1098
  const reason = e as PouchError;
1098
1099
  if (reason.status === 404) {
@@ -1109,6 +1110,11 @@ Currently logged-in as ${this._username}.`
1109
1110
  const putResult = await this.writeDB.put<CardHistory<T>>(initCardHistory);
1110
1111
  return { ...initCardHistory, _rev: putResult.rev };
1111
1112
  } catch (creationError) {
1113
+ // Another record for this card created the doc first (two first
1114
+ // records in flight at once): it exists now, so append to it.
1115
+ if ((creationError as PouchError).name === 'conflict') {
1116
+ return appendToExisting();
1117
+ }
1112
1118
  throw new Error(
1113
1119
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
1114
1120
  );
@@ -1,6 +1,7 @@
1
1
  import pouch from './pouchdb-setup';
2
2
  import { getCourseDB } from '.';
3
3
  import { logger } from '../../util/logger';
4
+ import { perfMark } from '../../util/perfMarks';
4
5
  import type { CourseConfig } from '@vue-skuilder/common';
5
6
 
6
7
  // ============================================================================
@@ -236,6 +237,7 @@ export class CourseSyncService {
236
237
  entry.localDB = localDB;
237
238
  entry.status = { state: 'ready' };
238
239
  entry.readyPromise = null;
240
+ perfMark('sk:course-sync-ready', { courseId, from: 'marker' });
239
241
  logger.info(
240
242
  `[CourseSyncService] Using this device's replica of course ${courseId}; refreshing in the background`
241
243
  );
@@ -286,6 +288,12 @@ export class CourseSyncService {
286
288
  syncTimeMs,
287
289
  viewWarmTimeMs,
288
290
  };
291
+ perfMark('sk:course-sync-refreshed', {
292
+ courseId,
293
+ docs: result.docs_written,
294
+ syncTimeMs,
295
+ viewWarmTimeMs,
296
+ });
289
297
  logger.info(
290
298
  `[CourseSyncService] Background refresh of course ${courseId}: ` +
291
299
  `${result.docs_written} docs in ${syncTimeMs}ms, views ${viewWarmTimeMs}ms`
@@ -420,6 +428,11 @@ export class CourseSyncService {
420
428
 
421
429
  const result = await this.replicate(remoteDB, localDB);
422
430
  const syncTimeMs = Date.now() - syncStart;
431
+ perfMark('sk:course-sync-replicated', {
432
+ courseId,
433
+ docs: result.docs_written,
434
+ ms: syncTimeMs,
435
+ });
423
436
 
424
437
  logger.info(
425
438
  `[CourseSyncService] Replication complete for course ${courseId}: ` +
@@ -445,6 +458,7 @@ export class CourseSyncService {
445
458
  syncTimeMs,
446
459
  viewWarmTimeMs,
447
460
  };
461
+ perfMark('sk:course-sync-ready', { courseId, from: 'sync', viewWarmTimeMs });
448
462
  } catch (e) {
449
463
  const errorMsg = e instanceof Error ? e.message : String(e);
450
464
  logger.error(
@@ -552,8 +566,11 @@ export class CourseSyncService {
552
566
  try {
553
567
  localEpoch = await localDB.get<{ epoch: number }>('db-epoch');
554
568
  } catch {
555
- // Local doesn't have the epoch doc — stale
556
- return true;
569
+ // No epoch doc locally: a DB never written to (this device's first
570
+ // sync) has nothing to be stale; anything else (e.g. an interrupted
571
+ // earlier sync) is.
572
+ const info = await localDB.info();
573
+ return info.doc_count > 0 || !!info.update_seq;
557
574
  }
558
575
 
559
576
  return remoteEpoch.epoch !== localEpoch.epoch;
@@ -134,6 +134,11 @@ export class CourseDB implements CourseDBInterface {
134
134
  * values may be stale, so read-modify-write cycles must go through
135
135
  * the remote DB to avoid conflicts).
136
136
  */
137
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
138
+ public get readsLocal(): boolean {
139
+ return this.db !== this.remoteDB;
140
+ }
141
+
137
142
  constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database) {
138
143
  this.id = id;
139
144
  const remote = getCourseDB(this.id);
@@ -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
+ });