@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.
- package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
- package/dist/core/index.cjs +112 -78
- package/dist/core/index.cjs.map +1 -1
- package/dist/core/index.d.ts +5 -5
- package/dist/core/navigators/Pipeline.mjs +8 -0
- package/dist/core/navigators/Pipeline.mjs.map +1 -1
- package/dist/core/versionStamps.mjs +1 -1
- package/dist/{dataLayerProvider-BDshhSp_.d.ts → dataLayerProvider-rGyLQ93v.d.ts} +1 -1
- package/dist/diagnostics/index.d.ts +3 -3
- package/dist/impl/common/BaseUserDB.mjs +18 -13
- package/dist/impl/common/BaseUserDB.mjs.map +1 -1
- package/dist/impl/couch/CourseSyncService.mjs +23 -1
- package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
- package/dist/impl/couch/courseDB.mjs +4 -0
- package/dist/impl/couch/courseDB.mjs.map +1 -1
- package/dist/impl/couch/index.cjs +134 -79
- package/dist/impl/couch/index.cjs.map +1 -1
- package/dist/impl/couch/index.d.ts +5 -3
- package/dist/impl/couch/updateQueue.mjs +69 -46
- package/dist/impl/couch/updateQueue.mjs.map +1 -1
- package/dist/impl/static/index.cjs +108 -78
- package/dist/impl/static/index.cjs.map +1 -1
- package/dist/impl/static/index.d.ts +4 -4
- package/dist/{index-BLDpFYG3.d.ts → index-C745YB_6.d.ts} +1 -1
- package/dist/index.cjs +144 -80
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +23 -10
- package/dist/index.mjs +2 -1
- package/dist/study/SessionController.mjs +4 -0
- package/dist/study/SessionController.mjs.map +1 -1
- package/dist/{types-DChCz22D.d.ts → types-DF0JuPbs.d.ts} +1 -1
- package/dist/{types-legacy-fT5Y1Wuy.d.ts → types-legacy-DdVjg81H.d.ts} +1 -1
- package/dist/util/packer/index.d.ts +3 -3
- package/dist/util/perfMarks.mjs +30 -0
- package/dist/util/perfMarks.mjs.map +1 -0
- package/package.json +3 -3
- package/src/core/interfaces/courseDB.ts +6 -0
- package/src/core/navigators/Pipeline.ts +8 -0
- package/src/impl/common/BaseUserDB.ts +27 -21
- package/src/impl/couch/CourseSyncService.ts +19 -2
- package/src/impl/couch/courseDB.ts +5 -0
- package/src/impl/couch/updateQueue.ts +86 -82
- package/src/study/SessionController.ts +4 -0
- package/src/util/index.ts +1 -0
- package/src/util/perfMarks.ts +35 -0
- 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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
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
|
-
//
|
|
556
|
-
|
|
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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
private
|
|
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
|
-
|
|
51
|
-
this.
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
108
|
-
|
|
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
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
@@ -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
|
+
});
|