@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.
- package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
- package/dist/core/index.cjs +155 -100
- 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 +61 -34
- 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 +177 -101
- 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 +151 -100
- 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 +187 -102
- 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/docs/session-lifecycle-and-replan.md +71 -58
- 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 +74 -46
- 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
|
@@ -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
|
+
});
|