@vue-skuilder/db 0.2.20 → 0.2.22

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 (49) hide show
  1. package/dist/{contentSource-BDRX_YYJ.d.ts → contentSource-B1pqryv6.d.ts} +87 -2
  2. package/dist/{contentSource-D-LQYFyx.d.cts → contentSource-CpTxVrFx.d.cts} +87 -2
  3. package/dist/core/index.d.cts +16 -6
  4. package/dist/core/index.d.ts +16 -6
  5. package/dist/core/index.js +79 -4
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +74 -4
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-Dpshuql4.d.ts → dataLayerProvider-BZqH27f4.d.ts} +1 -1
  10. package/dist/{dataLayerProvider-Dd2UcCif.d.cts → dataLayerProvider-D4c7iUc_.d.cts} +1 -1
  11. package/dist/impl/couch/index.d.cts +3 -3
  12. package/dist/impl/couch/index.d.ts +3 -3
  13. package/dist/impl/couch/index.js +63 -4
  14. package/dist/impl/couch/index.js.map +1 -1
  15. package/dist/impl/couch/index.mjs +63 -4
  16. package/dist/impl/couch/index.mjs.map +1 -1
  17. package/dist/impl/static/index.d.cts +4 -4
  18. package/dist/impl/static/index.d.ts +4 -4
  19. package/dist/impl/static/index.js +63 -4
  20. package/dist/impl/static/index.js.map +1 -1
  21. package/dist/impl/static/index.mjs +63 -4
  22. package/dist/impl/static/index.mjs.map +1 -1
  23. package/dist/{index-k9NFHpS1.d.cts → index-DGApnUZ-.d.cts} +1 -1
  24. package/dist/{index-BLLT5BYE.d.ts → index-rmNIwnkV.d.ts} +1 -1
  25. package/dist/index.d.cts +51 -14
  26. package/dist/index.d.ts +51 -14
  27. package/dist/index.js +231 -12
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.mjs +226 -12
  30. package/dist/index.mjs.map +1 -1
  31. package/dist/{types-CHgpWQAY.d.ts → types-B-Y3aoi5.d.ts} +1 -1
  32. package/dist/{types-legacy-4tlwHnXo.d.cts → types-legacy-BytY5eAR.d.cts} +9 -1
  33. package/dist/{types-legacy-4tlwHnXo.d.ts → types-legacy-BytY5eAR.d.ts} +9 -1
  34. package/dist/{types-BFUa1pa3.d.cts → types-r6fyuWP2.d.cts} +1 -1
  35. package/dist/util/packer/index.d.cts +3 -3
  36. package/dist/util/packer/index.d.ts +3 -3
  37. package/package.json +3 -3
  38. package/src/core/index.ts +1 -0
  39. package/src/core/interfaces/userDB.ts +7 -0
  40. package/src/core/navigators/PipelineDebugger.ts +41 -1
  41. package/src/core/navigators/index.ts +3 -0
  42. package/src/core/types/studySession.ts +100 -0
  43. package/src/core/types/types-legacy.ts +8 -0
  44. package/src/core/types/user.ts +6 -1
  45. package/src/impl/common/BaseUserDB.ts +36 -0
  46. package/src/study/SessionController.ts +179 -2
  47. package/src/study/SessionDebugger.ts +4 -3
  48. package/src/study/SessionOverlay.ts +1 -0
  49. package/src/study/services/ResponseProcessor.ts +32 -4
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-4tlwHnXo.js';
2
+ import { D as DocType } from './types-legacy-BytY5eAR.js';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -16,7 +16,8 @@ declare enum DocType {
16
16
  NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
17
17
  STRATEGY_STATE = "STRATEGY_STATE",
18
18
  USER_OUTCOME = "USER_OUTCOME",
19
- STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE"
19
+ STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE",
20
+ STUDY_SESSION = "STUDY_SESSION"
20
21
  }
21
22
  interface QualifiedCardID {
22
23
  courseID: string;
@@ -95,6 +96,7 @@ declare const DocTypePrefixes: {
95
96
  readonly STRATEGY_STATE: "STRATEGY_STATE";
96
97
  readonly USER_OUTCOME: "USER_OUTCOME";
97
98
  readonly STRATEGY_LEARNING_STATE: "STRATEGY_LEARNING_STATE";
99
+ readonly STUDY_SESSION: "SESSION";
98
100
  };
99
101
  interface CardHistory<T extends CardRecord> {
100
102
  _id: PouchDB.Core.DocumentId;
@@ -145,6 +147,12 @@ interface CardRecord {
145
147
  * time of user submission.
146
148
  */
147
149
  timeStamp: Moment;
150
+ /**
151
+ * The study session this response was produced in. Absent on records
152
+ * predating session stamping, and on responses made outside a
153
+ * SessionController.
154
+ */
155
+ sessionId?: string;
148
156
  }
149
157
  interface QuestionRecord extends CardRecord, Evaluation {
150
158
  userAnswer: Answer;
@@ -16,7 +16,8 @@ declare enum DocType {
16
16
  NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
17
17
  STRATEGY_STATE = "STRATEGY_STATE",
18
18
  USER_OUTCOME = "USER_OUTCOME",
19
- STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE"
19
+ STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE",
20
+ STUDY_SESSION = "STUDY_SESSION"
20
21
  }
21
22
  interface QualifiedCardID {
22
23
  courseID: string;
@@ -95,6 +96,7 @@ declare const DocTypePrefixes: {
95
96
  readonly STRATEGY_STATE: "STRATEGY_STATE";
96
97
  readonly USER_OUTCOME: "USER_OUTCOME";
97
98
  readonly STRATEGY_LEARNING_STATE: "STRATEGY_LEARNING_STATE";
99
+ readonly STUDY_SESSION: "SESSION";
98
100
  };
99
101
  interface CardHistory<T extends CardRecord> {
100
102
  _id: PouchDB.Core.DocumentId;
@@ -145,6 +147,12 @@ interface CardRecord {
145
147
  * time of user submission.
146
148
  */
147
149
  timeStamp: Moment;
150
+ /**
151
+ * The study session this response was produced in. Absent on records
152
+ * predating session stamping, and on responses made outside a
153
+ * SessionController.
154
+ */
155
+ sessionId?: string;
148
156
  }
149
157
  interface QuestionRecord extends CardRecord, Evaluation {
150
158
  userAnswer: Answer;
@@ -1,5 +1,5 @@
1
1
  import { CourseConfig } from '@vue-skuilder/common';
2
- import { D as DocType } from './types-legacy-4tlwHnXo.cjs';
2
+ import { D as DocType } from './types-legacy-BytY5eAR.cjs';
3
3
 
4
4
  interface StaticCourseManifest {
5
5
  version: string;
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-BFUa1pa3.cjs';
2
- export { C as CouchDBToStaticPacker } from '../../index-k9NFHpS1.cjs';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-r6fyuWP2.cjs';
2
+ export { C as CouchDBToStaticPacker } from '../../index-DGApnUZ-.cjs';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-4tlwHnXo.cjs';
4
+ import '../../types-legacy-BytY5eAR.cjs';
5
5
  import 'moment';
@@ -1,5 +1,5 @@
1
- export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CHgpWQAY.js';
2
- export { C as CouchDBToStaticPacker } from '../../index-BLLT5BYE.js';
1
+ export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-B-Y3aoi5.js';
2
+ export { C as CouchDBToStaticPacker } from '../../index-rmNIwnkV.js';
3
3
  import '@vue-skuilder/common';
4
- import '../../types-legacy-4tlwHnXo.js';
4
+ import '../../types-legacy-BytY5eAR.js';
5
5
  import 'moment';
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.20",
7
+ "version": "0.2.22",
8
8
  "description": "Database layer for vue-skuilder",
9
9
  "main": "dist/index.js",
10
10
  "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "dependencies": {
50
50
  "@nilock2/pouchdb-authentication": "^1.0.2",
51
- "@vue-skuilder/common": "0.2.20",
51
+ "@vue-skuilder/common": "0.2.22",
52
52
  "cross-fetch": "^4.1.0",
53
53
  "moment": "^2.29.4",
54
54
  "pouchdb": "^9.0.0",
@@ -63,5 +63,5 @@
63
63
  "vite": "^8.0.0",
64
64
  "vitest": "^4.1.0"
65
65
  },
66
- "stableVersion": "0.2.20"
66
+ "stableVersion": "0.2.22"
67
67
  }
package/src/core/index.ts CHANGED
@@ -5,6 +5,7 @@ export * from './types/types-legacy';
5
5
  export * from './types/user';
6
6
  export * from './types/strategyState';
7
7
  export * from './types/userOutcome';
8
+ export * from './types/studySession';
8
9
  export * from './types/hydration';
9
10
  export * from '../util/Loggable';
10
11
  export * from './util';
@@ -8,6 +8,7 @@ import { CourseElo, Status } from '@vue-skuilder/common';
8
8
  import { Moment } from 'moment';
9
9
  import { CardHistory, CardRecord, QualifiedCardID } from '../types/types-legacy';
10
10
  import { UserOutcomeRecord } from '../types/userOutcome';
11
+ import { StudySessionDoc } from '../types/studySession';
11
12
  import { UserConfig } from '../types/user';
12
13
  import { UserHydrationStatus } from '../types/hydration';
13
14
  import { DocumentUpdater } from '@db/study';
@@ -79,6 +80,9 @@ export interface UserDBReader {
79
80
  */
80
81
  getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
81
82
 
83
+ /** Study-session records for a course, newest session-start first. */
84
+ getStudySessions(courseId?: string): Promise<StudySessionDoc[]>;
85
+
82
86
  /**
83
87
  * Get all scheduled reviews due within the next `daysCount` days —
84
88
  * including ones not yet due. `getPendingReviews` is the `daysCount = 0`
@@ -215,6 +219,9 @@ export interface UserDBWriter extends DocumentUpdater {
215
219
  * Record a user learning outcome for evolutionary orchestration.
216
220
  */
217
221
  putUserOutcome(record: UserOutcomeRecord): Promise<void>;
222
+
223
+ /** Write or overwrite a study-session record. */
224
+ putStudySession(doc: StudySessionDoc): Promise<void>;
218
225
  }
219
226
 
220
227
  /**
@@ -79,6 +79,8 @@ export interface FilterImpact {
79
79
  */
80
80
  export interface PipelineRunReport {
81
81
  runId: string;
82
+ /** Absent for runs fired outside a session (forecasts, editor probes). */
83
+ sessionId?: string;
82
84
  timestamp: Date;
83
85
  courseId: string;
84
86
  courseName?: string;
@@ -155,6 +157,38 @@ export interface PipelineRunReport {
155
157
  const MAX_RUNS = 10;
156
158
  const runHistory: PipelineRunReport[] = [];
157
159
 
160
+ /**
161
+ * Ambient, like `registerPipelineForDebug` — a pipeline is per content-source
162
+ * and can outlive any one session. Set by `SessionController`.
163
+ */
164
+ let _currentSessionId: string | undefined;
165
+
166
+ export function setDebugSessionId(sessionId: string | undefined): void {
167
+ _currentSessionId = sessionId;
168
+ }
169
+
170
+ /**
171
+ * Runs captured since the last drain. `SessionController` drains after each
172
+ * plan and applies its own label — one plan can be several runs (one per
173
+ * source), and the label is the controller's knowledge, not the pipeline's.
174
+ */
175
+ let _pendingRuns: PipelineRunReport[] = [];
176
+
177
+ /** Take and clear the runs captured since the previous call, in execution order. */
178
+ export function drainCapturedRuns(): PipelineRunReport[] {
179
+ const drained = _pendingRuns;
180
+ _pendingRuns = [];
181
+ return drained;
182
+ }
183
+
184
+ /**
185
+ * Runs for `sessionId`, oldest first. Bounded by {@link MAX_RUNS} — the
186
+ * complete record is `StudySessionDoc.runs`.
187
+ */
188
+ export function getRunsForSession(sessionId: string): PipelineRunReport[] {
189
+ return runHistory.filter((r) => r.sessionId === sessionId).reverse();
190
+ }
191
+
158
192
  /**
159
193
  * Cap on non-selected ("discarded") cards retained per run report.
160
194
  *
@@ -177,6 +211,7 @@ const DISCARDED_KEEP_TOP = 25;
177
211
  */
178
212
  export function clearRunHistory(): void {
179
213
  runHistory.length = 0;
214
+ _pendingRuns = [];
180
215
  }
181
216
 
182
217
  /**
@@ -196,10 +231,13 @@ function getOrigin(card: WeightedCard): 'new' | 'review' | 'unknown' {
196
231
  /**
197
232
  * Capture a pipeline run for later inspection.
198
233
  */
199
- export function captureRun(report: Omit<PipelineRunReport, 'runId' | 'timestamp'>): void {
234
+ export function captureRun(
235
+ report: Omit<PipelineRunReport, 'runId' | 'timestamp' | 'sessionId'>
236
+ ): PipelineRunReport {
200
237
  const fullReport: PipelineRunReport = {
201
238
  ...report,
202
239
  runId: `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
240
+ sessionId: _currentSessionId,
203
241
  timestamp: new Date(),
204
242
  };
205
243
 
@@ -207,6 +245,8 @@ export function captureRun(report: Omit<PipelineRunReport, 'runId' | 'timestamp'
207
245
  if (runHistory.length > MAX_RUNS) {
208
246
  runHistory.pop();
209
247
  }
248
+ _pendingRuns.push(fullReport);
249
+ return fullReport;
210
250
  }
211
251
 
212
252
  /**
@@ -20,6 +20,9 @@ export {
20
20
  pipelineDebugAPI,
21
21
  mountPipelineDebugger,
22
22
  getActivePipeline,
23
+ setDebugSessionId,
24
+ getRunsForSession,
25
+ drainCapturedRuns,
23
26
  type PipelineRunReport,
24
27
  type GeneratorSummary,
25
28
  type FilterImpact,
@@ -0,0 +1,100 @@
1
+ import { DocType, DocTypePrefixes } from './types-legacy';
2
+ import type { ReplanHints } from '../navigators/generators/types';
3
+
4
+ /**
5
+ * Durable per-sitting record. Join target for `CardRecord.sessionId`.
6
+ *
7
+ * Written twice: `open` at `prepareSession()`, overwritten at termination.
8
+ */
9
+ export interface StudySessionDoc {
10
+ /** `SESSION::{courseId}::{userId}::{sessionId}` */
11
+ _id: string;
12
+ _rev?: string;
13
+ docType: DocType.STUDY_SESSION;
14
+
15
+ sessionId: string;
16
+ courseId: string;
17
+ userId: string;
18
+
19
+ /** Session construction time, not first-card time. */
20
+ startTime: string;
21
+ endTime?: string;
22
+
23
+ /**
24
+ * `closed` — ran to natural termination.
25
+ * `abandoned` — host tore the study view down mid-session.
26
+ * `open` — never closed: tab closed, reload, crash. No tally or end state.
27
+ */
28
+ status: 'open' | 'closed' | 'abandoned';
29
+
30
+ plannedSeconds: number;
31
+
32
+ config: {
33
+ defaultBatchLimit: number;
34
+ sourceCount: number;
35
+ initHints?: ReplanHints | null;
36
+ };
37
+
38
+ /** Queue depths after the bootstrap run, before the first draw. */
39
+ initialQueues: { supplyQ: number; failedQ: number };
40
+
41
+ tally?: {
42
+ /** Distinct cards; a re-presented failed card counts once. */
43
+ cardsPresented: number;
44
+ /** Total responses, including repeat attempts on one card. */
45
+ responses: number;
46
+ correct: number;
47
+ incorrect: number;
48
+ failedQRemaining: number;
49
+ secondsRemaining: number;
50
+ };
51
+
52
+ /** Bootstrap run plus every replan, in execution order. */
53
+ runs?: StudySessionRunSummary[];
54
+
55
+ finalHints?: ReplanHints | null;
56
+
57
+ stateAtStart?: SessionStateSnapshot;
58
+ stateAtEnd?: SessionStateSnapshot;
59
+ }
60
+
61
+ export interface StudySessionRunSummary {
62
+ /** Joins to `PipelineRunReport.runId` while that run is still in memory. */
63
+ runId: string;
64
+ at: string;
65
+ /** `'bootstrap'`, a replan's label, or `'(auto)'`. */
66
+ label: string;
67
+ mode?: string;
68
+ generatedCount: number;
69
+ finalCount: number;
70
+ reviewsSelected: number;
71
+ newSelected: number;
72
+ }
73
+
74
+ /**
75
+ * Host-defined learner state at a session boundary. Keep it thin — this is
76
+ * written on every session, and the deltas between consecutive snapshots are
77
+ * what it's read for.
78
+ */
79
+ export type SessionStateSnapshot = Record<string, unknown>;
80
+
81
+ /**
82
+ * Invoked at session open and close. Errors and slow calls are absorbed by
83
+ * the controller.
84
+ */
85
+ export type SessionStateSnapshotProvider = (
86
+ phase: 'start' | 'end'
87
+ ) => SessionStateSnapshot | Promise<SessionStateSnapshot>;
88
+
89
+ /** Stable across the open and close writes, unlike a timestamp-keyed id. */
90
+ export function makeStudySessionId(
91
+ courseId: string,
92
+ userId: string,
93
+ sessionId: string
94
+ ): string {
95
+ return `${DocTypePrefixes[DocType.STUDY_SESSION]}::${courseId}::${userId}::${sessionId}`;
96
+ }
97
+
98
+ export function newSessionId(): string {
99
+ return `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
100
+ }
@@ -22,6 +22,7 @@ export enum DocType {
22
22
  STRATEGY_STATE = 'STRATEGY_STATE',
23
23
  USER_OUTCOME = 'USER_OUTCOME',
24
24
  STRATEGY_LEARNING_STATE = 'STRATEGY_LEARNING_STATE',
25
+ STUDY_SESSION = 'STUDY_SESSION',
25
26
  }
26
27
 
27
28
  export interface QualifiedCardID {
@@ -109,6 +110,7 @@ export const DocTypePrefixes = {
109
110
  [DocType.STRATEGY_STATE]: 'STRATEGY_STATE',
110
111
  [DocType.USER_OUTCOME]: 'USER_OUTCOME',
111
112
  [DocType.STRATEGY_LEARNING_STATE]: 'STRATEGY_LEARNING_STATE',
113
+ [DocType.STUDY_SESSION]: 'SESSION',
112
114
  } as const;
113
115
 
114
116
  export interface CardHistory<T extends CardRecord> {
@@ -166,6 +168,12 @@ export interface CardRecord {
166
168
  * time of user submission.
167
169
  */
168
170
  timeStamp: Moment;
171
+ /**
172
+ * The study session this response was produced in. Absent on records
173
+ * predating session stamping, and on responses made outside a
174
+ * SessionController.
175
+ */
176
+ sessionId?: string;
169
177
  }
170
178
 
171
179
  export interface QuestionRecord extends CardRecord, Evaluation {
@@ -16,7 +16,12 @@ export interface UserConfig {
16
16
  darkMode: boolean;
17
17
  likesConfetti: boolean;
18
18
  sessionTimeLimit: number; // Session time limit in minutes
19
- email?: string; // Optional email for verification flows (added for enhanced auth)
19
+ /**
20
+ * @deprecated Retired in favour of the _users-doc email (the single source of
21
+ * truth, written by /auth/send-verification and read by /auth/status). No
22
+ * live code writes or reads this field; it may linger on older CONFIG docs.
23
+ */
24
+ email?: string;
20
25
 
21
26
  // Session tracking for trial enforcement (per-course)
22
27
  // Key is courseId (e.g., 'letterspractice-basic')
@@ -29,6 +29,7 @@ import {
29
29
  import { DocumentUpdater } from '@db/study';
30
30
  import { CardHistory, CardRecord } from '../../core/types/types-legacy';
31
31
  import { UserOutcomeRecord } from '../../core/types/userOutcome';
32
+ import { StudySessionDoc } from '../../core/types/studySession';
32
33
  import type { SyncStrategy } from './SyncStrategy';
33
34
  import {
34
35
  filterAllDocsByPrefix,
@@ -1364,6 +1365,41 @@ Currently logged-in as ${this._username}.`
1364
1365
  await this.localDB.put(doc);
1365
1366
  }
1366
1367
 
1368
+ /**
1369
+ * Open and close write the same `_id`, so the 409 path is the expected
1370
+ * route for the second write, not an error case.
1371
+ */
1372
+ public async putStudySession(doc: StudySessionDoc): Promise<void> {
1373
+ try {
1374
+ await this.localDB.put(doc);
1375
+ } catch (err: any) {
1376
+ if (err.status === 409) {
1377
+ const existing = await this.localDB.get(doc._id);
1378
+ await this.localDB.put({ ...doc, _rev: existing._rev });
1379
+ } else {
1380
+ throw err;
1381
+ }
1382
+ }
1383
+ }
1384
+
1385
+ public async getStudySessions(courseId?: string): Promise<StudySessionDoc[]> {
1386
+ const prefix = courseId
1387
+ ? `${DocTypePrefixes[DocType.STUDY_SESSION]}::${courseId}::`
1388
+ : `${DocTypePrefixes[DocType.STUDY_SESSION]}::`;
1389
+ const keys = getStartAndEndKeys(prefix);
1390
+
1391
+ const res = await this.localDB.allDocs<StudySessionDoc>({
1392
+ startkey: keys.startkey,
1393
+ endkey: keys.endkey,
1394
+ include_docs: true,
1395
+ });
1396
+
1397
+ return res.rows
1398
+ .map((r) => r.doc)
1399
+ .filter((d): d is StudySessionDoc & PouchDB.Core.RevisionIdMeta => !!d)
1400
+ .sort((a, b) => b.startTime.localeCompare(a.startTime));
1401
+ }
1402
+
1367
1403
  public async putUserOutcome(record: UserOutcomeRecord): Promise<void> {
1368
1404
  try {
1369
1405
  await this.localDB.put(record);