@vue-skuilder/db 0.2.27 → 0.2.29

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 (82) hide show
  1. package/dist/classroomDB-DLTtLZct.d.cts +86 -0
  2. package/dist/classroomDB-DLTtLZct.d.ts +86 -0
  3. package/dist/{contentSource-LPf044hY.d.ts → contentSource-B6FrSihy.d.cts} +282 -99
  4. package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-CqJmbOZN.d.ts} +282 -99
  5. package/dist/core/index.d.cts +16 -92
  6. package/dist/core/index.d.ts +16 -92
  7. package/dist/core/index.js +607 -179
  8. package/dist/core/index.js.map +1 -1
  9. package/dist/core/index.mjs +606 -179
  10. package/dist/core/index.mjs.map +1 -1
  11. package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +2 -8
  12. package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +2 -8
  13. package/dist/diagnostics/index.d.cts +443 -0
  14. package/dist/diagnostics/index.d.ts +443 -0
  15. package/dist/diagnostics/index.js +932 -0
  16. package/dist/diagnostics/index.js.map +1 -0
  17. package/dist/diagnostics/index.mjs +881 -0
  18. package/dist/diagnostics/index.mjs.map +1 -0
  19. package/dist/impl/couch/index.d.cts +13 -3
  20. package/dist/impl/couch/index.d.ts +13 -3
  21. package/dist/impl/couch/index.js +605 -179
  22. package/dist/impl/couch/index.js.map +1 -1
  23. package/dist/impl/couch/index.mjs +605 -179
  24. package/dist/impl/couch/index.mjs.map +1 -1
  25. package/dist/impl/static/index.d.cts +11 -5
  26. package/dist/impl/static/index.d.ts +11 -5
  27. package/dist/impl/static/index.js +602 -185
  28. package/dist/impl/static/index.js.map +1 -1
  29. package/dist/impl/static/index.mjs +602 -185
  30. package/dist/impl/static/index.mjs.map +1 -1
  31. package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
  32. package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
  33. package/dist/index.d.cts +73 -11
  34. package/dist/index.d.ts +73 -11
  35. package/dist/index.js +696 -200
  36. package/dist/index.js.map +1 -1
  37. package/dist/index.mjs +683 -200
  38. package/dist/index.mjs.map +1 -1
  39. package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
  40. package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
  41. package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
  42. package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
  43. package/dist/util/packer/index.d.cts +3 -3
  44. package/dist/util/packer/index.d.ts +3 -3
  45. package/package.json +15 -3
  46. package/src/core/interfaces/contentSource.ts +7 -0
  47. package/src/core/interfaces/dataLayerProvider.ts +3 -8
  48. package/src/core/navigators/Pipeline.ts +149 -14
  49. package/src/core/navigators/PipelineAssembler.ts +19 -40
  50. package/src/core/navigators/PipelineDebugger.ts +74 -17
  51. package/src/core/navigators/SrsDebugger.ts +37 -12
  52. package/src/core/navigators/defaults.ts +29 -5
  53. package/src/core/navigators/filters/WeightedFilter.ts +5 -1
  54. package/src/core/navigators/filters/eloDistance.ts +261 -76
  55. package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
  56. package/src/core/navigators/filters/index.ts +2 -2
  57. package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
  58. package/src/core/navigators/filters/relativePriority.ts +5 -1
  59. package/src/core/navigators/filters/types.ts +24 -1
  60. package/src/core/navigators/filters/userTagPreference.ts +5 -1
  61. package/src/core/navigators/generators/elo.ts +23 -53
  62. package/src/core/navigators/generators/srs.ts +27 -124
  63. package/src/core/navigators/index.ts +32 -5
  64. package/src/core/navigators/pipelinePlan.ts +245 -0
  65. package/src/core/navigators/regulators.ts +230 -0
  66. package/src/core/types/studySession.ts +40 -0
  67. package/src/diagnostics/dataset.ts +242 -0
  68. package/src/diagnostics/derive.ts +555 -0
  69. package/src/diagnostics/index.ts +27 -0
  70. package/src/diagnostics/loader.ts +194 -0
  71. package/src/diagnostics/pipeline.ts +236 -0
  72. package/src/diagnostics/text.ts +265 -0
  73. package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
  74. package/src/impl/couch/courseDB.ts +13 -0
  75. package/src/impl/static/StaticDataLayerProvider.ts +0 -11
  76. package/src/impl/static/courseDB.ts +9 -0
  77. package/src/index.ts +4 -0
  78. package/src/study/SessionController.ts +76 -2
  79. package/src/study/SessionOverlay.ts +7 -4
  80. package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
  81. package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
  82. package/tsup.config.ts +1 -0
@@ -0,0 +1,242 @@
1
+ import type {
2
+ CardData,
3
+ CardHistory,
4
+ CardRecord,
5
+ DisplayableData,
6
+ QuestionRecord,
7
+ Tag,
8
+ } from '../core/types/types-legacy';
9
+ import type { CourseRegistrationDoc, ScheduledCard } from '../core/types/user';
10
+ import type { StudySessionDoc } from '../core/types/studySession';
11
+ import type { ContentNavigationStrategyData } from '../core/types/contentNavigationStrategy';
12
+
13
+ // Literal prefixes rather than `DocTypePrefixes`: this entry stays free of
14
+ // runtime imports from `core`, so it loads in the browser, node, and the CLI
15
+ // without the rest of the db package.
16
+ const PREFIX = {
17
+ cardHistory: 'cardH',
18
+ scheduled: 'card_review_',
19
+ session: 'SESSION::',
20
+ strategyState: 'STRATEGY_STATE::',
21
+ registrations: 'CourseRegistrations',
22
+ } as const;
23
+
24
+ type RawDoc = { _id: string; [key: string]: unknown };
25
+
26
+ /**
27
+ * A learner's raw records, as fetched. This is the on-disk dump format: the
28
+ * `dump-user` CLI writes it, an admin UI can load it from a file, and every
29
+ * loader produces it. Readers must tolerate every past version.
30
+ *
31
+ * - v0 (LP `scripts/dump-user-db.ts` before 2026-09-30): no `formatVersion`,
32
+ * `courseId`, `tombstones`, or `course`.
33
+ * - v1: adds all four. Later v1 dumps also carry `course.strategies` (optional).
34
+ */
35
+ export interface LearnerDump {
36
+ formatVersion?: 1;
37
+ username: string;
38
+ dbName: string;
39
+ /** The couch base URL the records came from. */
40
+ source: string;
41
+ fetchedAt: string;
42
+ courseId?: string;
43
+ /** The couch `GET /{db}` response. */
44
+ info?: unknown;
45
+ /** Every user-DB doc, raw (`_id`/`_rev` kept, `_design` docs included). */
46
+ docs: RawDoc[];
47
+ /**
48
+ * Deleted user-DB docs. Completed reviews are deleted, so deleted
49
+ * `card_review_<reviewTime>` ids are the only record of past due times.
50
+ * `seq` is the numeric prefix of the couch seq: order, not time.
51
+ */
52
+ tombstones?: Array<{ id: string; rev?: string; seq: number }>;
53
+ course?: CourseSlice;
54
+ }
55
+
56
+ export interface CourseSlice {
57
+ courseId: string;
58
+ source?: string;
59
+ /** `touched`: cards the user has history, schedule, or ELO events for. `all`: every card. */
60
+ scope: 'touched' | 'all';
61
+ cards: Array<CardData & { _id: string }>;
62
+ displayableData: Array<DisplayableData & { _id: string }>;
63
+ /**
64
+ * TAG docs. Under `touched`, `taggedCards` is narrowed to the included cards
65
+ * and `taggedCount` keeps the full length.
66
+ */
67
+ tags: Array<Tag & { _id: string; taggedCount: number }>;
68
+ /**
69
+ * The course's NAVIGATION_STRATEGY docs, as they stood when the dump was
70
+ * taken (current state, not as of any session). Absent in older dumps.
71
+ */
72
+ strategies?: ContentNavigationStrategyData[];
73
+ }
74
+
75
+ /** A card-history record with an ISO `timeStamp`. Question fields exist on question records only. */
76
+ export type DatasetRecord = Omit<CardRecord, 'timeStamp'> &
77
+ Partial<Omit<QuestionRecord, keyof CardRecord>> & { timeStamp: string };
78
+
79
+ /** A `CardHistory` whose records carry ISO timestamps. */
80
+ export type DatasetCardHistory = Omit<CardHistory<CardRecord>, 'records'> & {
81
+ records: DatasetRecord[];
82
+ };
83
+
84
+ /** What a view or detector needs to know about a card, joined from the course slice. */
85
+ export interface CardSummary {
86
+ cardId: string;
87
+ /** The question type's name, from `id_view` ("Course.question.Spelling.SpellingView" → "Spelling"). */
88
+ questionType?: string;
89
+ elo?: CardData['elo'];
90
+ /** Applied tags, from the course's TAG docs. */
91
+ tags: string[];
92
+ /** The card's displayable-data fields by name (the word, the answer, etc). */
93
+ data: Record<string, unknown>;
94
+ }
95
+
96
+ /** One learner in one course, indexed for reading. Built from a {@link LearnerDump} by {@link fromDump}. */
97
+ export interface LearnerDataset {
98
+ username: string;
99
+ courseId: string;
100
+ /** When the records were read. Derivations take "now" from here, never the wall clock. */
101
+ asOf: string;
102
+ /** Oldest first. */
103
+ sessions: StudySessionDoc[];
104
+ /** Records oldest first, timestamps normalized to ISO. */
105
+ cardHistories: DatasetCardHistory[];
106
+ /** Pending reviews, soonest first. */
107
+ scheduled: ScheduledCard[];
108
+ registration?: CourseRegistrationDoc;
109
+ /** `STRATEGY_STATE` docs' `data`, by strategy key. */
110
+ strategyState: Record<string, unknown>;
111
+ tombstones: Array<{ id: string; seq: number }>;
112
+ /** Absent when the dump carried no course slice. */
113
+ cards?: Map<string, CardSummary>;
114
+ /** The course's strategy docs at dump time. Absent when the dump didn't carry them. */
115
+ strategies?: ContentNavigationStrategyData[];
116
+ }
117
+
118
+ /**
119
+ * Normalize a stored timestamp to ISO. Card-history `timeStamp`s persist as
120
+ * `Moment.toString()` ("Sat Jul 18 2026 23:26:16 GMT+0000"), which sorts by
121
+ * weekday name, not time. Returns the input unchanged if it doesn't parse.
122
+ */
123
+ export function toIsoTimestamp(value: unknown): string {
124
+ if (typeof value === 'number') return new Date(value).toISOString();
125
+ const s = String(value ?? '');
126
+ const ms = Date.parse(s);
127
+ return Number.isNaN(ms) ? s : new Date(ms).toISOString();
128
+ }
129
+
130
+ /** `userdb-<username>-2026-09-30T1412Z.json`: sortable and filename-safe. */
131
+ export function dumpFileName(dump: Pick<LearnerDump, 'username' | 'fetchedAt'>): string {
132
+ return `userdb-${dump.username}-${dump.fetchedAt.slice(0, 16).replace(':', '')}Z.json`;
133
+ }
134
+
135
+ /** Parse and minimally validate a dump file's text. */
136
+ export function parseLearnerDump(text: string): LearnerDump {
137
+ const dump = JSON.parse(text) as Partial<LearnerDump>;
138
+ if (!dump || typeof dump.username !== 'string' || !Array.isArray(dump.docs)) {
139
+ throw new Error('[diagnostics] Not a learner dump: expected `username` and a `docs` array');
140
+ }
141
+ return dump as LearnerDump;
142
+ }
143
+
144
+ function questionTypeOf(idView: unknown): string | undefined {
145
+ if (typeof idView !== 'string') return undefined;
146
+ const parts = idView.split('.');
147
+ return parts.length >= 2 ? parts[parts.length - 2] : idView;
148
+ }
149
+
150
+ function summarizeCards(slice: CourseSlice): Map<string, CardSummary> {
151
+ const data = new Map(slice.displayableData.map((dd) => [dd._id, dd]));
152
+ const cards = new Map<string, CardSummary>();
153
+ for (const card of slice.cards) {
154
+ const fields: Record<string, unknown> = {};
155
+ for (const f of data.get(card.id_displayable_data?.[0] ?? '')?.data ?? []) {
156
+ fields[f.name] = f.data;
157
+ }
158
+ cards.set(card._id, {
159
+ cardId: card._id,
160
+ questionType: questionTypeOf(card.id_view),
161
+ elo: card.elo,
162
+ tags: [],
163
+ data: fields,
164
+ });
165
+ }
166
+ for (const tag of slice.tags) {
167
+ for (const cardId of tag.taggedCards ?? []) cards.get(cardId)?.tags.push(tag.name);
168
+ }
169
+ return cards;
170
+ }
171
+
172
+ /** The dump's course, else the course most of its sessions belong to. */
173
+ function inferCourseId(dump: LearnerDump): string | undefined {
174
+ if (dump.courseId) return dump.courseId;
175
+ if (dump.course) return dump.course.courseId;
176
+ const counts = new Map<string, number>();
177
+ for (const d of dump.docs) {
178
+ if (d._id.startsWith(PREFIX.session) && typeof d.courseId === 'string') {
179
+ counts.set(d.courseId, (counts.get(d.courseId) ?? 0) + 1);
180
+ }
181
+ }
182
+ return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
183
+ }
184
+
185
+ /**
186
+ * Index a dump for one course. Records for other courses in the same user DB
187
+ * (retired or sibling courses) are left out.
188
+ */
189
+ export function fromDump(dump: LearnerDump, courseId?: string): LearnerDataset {
190
+ const course = courseId ?? inferCourseId(dump);
191
+ if (!course) throw new Error('[diagnostics] No course id given, and none found in the dump');
192
+
193
+ const sessions: StudySessionDoc[] = [];
194
+ const cardHistories: DatasetCardHistory[] = [];
195
+ const scheduled: ScheduledCard[] = [];
196
+ const strategyState: Record<string, unknown> = {};
197
+ let registration: CourseRegistrationDoc | undefined;
198
+
199
+ for (const doc of dump.docs) {
200
+ const id = doc._id;
201
+ if (id.startsWith(PREFIX.session)) {
202
+ if (doc.courseId === course) sessions.push(doc as unknown as StudySessionDoc);
203
+ } else if (id.startsWith(PREFIX.cardHistory)) {
204
+ if (doc.courseID !== course) continue;
205
+ const history = doc as unknown as DatasetCardHistory;
206
+ cardHistories.push({
207
+ ...history,
208
+ records: (history.records ?? [])
209
+ .map((r) => ({ ...r, timeStamp: toIsoTimestamp(r.timeStamp) }))
210
+ .sort((a, b) => a.timeStamp.localeCompare(b.timeStamp)),
211
+ });
212
+ } else if (id.startsWith(PREFIX.scheduled)) {
213
+ if (doc.courseId === course) scheduled.push(doc as unknown as ScheduledCard);
214
+ } else if (id.startsWith(PREFIX.strategyState)) {
215
+ const [, docCourse, key] = id.split('::');
216
+ if (docCourse === course && key) strategyState[key] = doc.data;
217
+ } else if (id === PREFIX.registrations) {
218
+ registration = doc as unknown as CourseRegistrationDoc;
219
+ }
220
+ }
221
+
222
+ sessions.sort((a, b) => a.startTime.localeCompare(b.startTime));
223
+ scheduled.sort((a, b) => String(a.reviewTime).localeCompare(String(b.reviewTime)));
224
+
225
+ return {
226
+ username: dump.username,
227
+ courseId: course,
228
+ asOf: dump.fetchedAt,
229
+ sessions,
230
+ cardHistories,
231
+ scheduled,
232
+ registration,
233
+ strategyState,
234
+ tombstones: (dump.tombstones ?? []).map(({ id, seq }) => ({ id, seq })),
235
+ ...(dump.course && dump.course.courseId === course
236
+ ? {
237
+ cards: summarizeCards(dump.course),
238
+ ...(dump.course.strategies ? { strategies: dump.course.strategies } : {}),
239
+ }
240
+ : {}),
241
+ };
242
+ }