@vue-skuilder/db 0.2.35 → 0.2.37

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 (263) hide show
  1. package/CLAUDE.md +15 -4
  2. package/build.entries.mjs +12 -0
  3. package/dist/_virtual/_rolldown/runtime.mjs +8 -0
  4. package/dist/{contentSource-BteiDpxH.d.ts → contentSource-D_E7JaxR.d.ts} +1 -1
  5. package/dist/core/UserDBDebugger.mjs +285 -0
  6. package/dist/core/UserDBDebugger.mjs.map +1 -0
  7. package/dist/core/bulkImport/cardProcessor.mjs +106 -0
  8. package/dist/core/bulkImport/cardProcessor.mjs.map +1 -0
  9. package/dist/core/{index.js → index.cjs} +6413 -7738
  10. package/dist/core/index.cjs.map +1 -0
  11. package/dist/core/index.d.ts +5 -5
  12. package/dist/core/index.mjs +20 -11368
  13. package/dist/core/interfaces/contentSource.mjs +20 -0
  14. package/dist/core/interfaces/contentSource.mjs.map +1 -0
  15. package/dist/core/navigators/Pipeline.mjs +723 -0
  16. package/dist/core/navigators/Pipeline.mjs.map +1 -0
  17. package/dist/core/navigators/PipelineAssembler.mjs +86 -0
  18. package/dist/core/navigators/PipelineAssembler.mjs.map +1 -0
  19. package/dist/core/navigators/PipelineDebugger.mjs +771 -0
  20. package/dist/core/navigators/PipelineDebugger.mjs.map +1 -0
  21. package/dist/core/navigators/SrsDebugger.mjs +34 -0
  22. package/dist/core/navigators/SrsDebugger.mjs.map +1 -0
  23. package/dist/core/navigators/StrategyPressureDebugger.mjs +19 -0
  24. package/dist/core/navigators/StrategyPressureDebugger.mjs.map +1 -0
  25. package/dist/core/navigators/defaults.mjs +96 -0
  26. package/dist/core/navigators/defaults.mjs.map +1 -0
  27. package/dist/core/navigators/diversityRerank.mjs +85 -0
  28. package/dist/core/navigators/diversityRerank.mjs.map +1 -0
  29. package/dist/core/navigators/filters/WeightedFilter.mjs +81 -0
  30. package/dist/core/navigators/filters/WeightedFilter.mjs.map +1 -0
  31. package/dist/core/navigators/filters/eloDistance.mjs +244 -0
  32. package/dist/core/navigators/filters/eloDistance.mjs.map +1 -0
  33. package/dist/core/navigators/filters/hierarchyDefinition.mjs +235 -0
  34. package/dist/core/navigators/filters/hierarchyDefinition.mjs.map +1 -0
  35. package/dist/core/navigators/filters/interferenceMitigator.mjs +201 -0
  36. package/dist/core/navigators/filters/interferenceMitigator.mjs.map +1 -0
  37. package/dist/core/navigators/filters/relativePriority.mjs +135 -0
  38. package/dist/core/navigators/filters/relativePriority.mjs.map +1 -0
  39. package/dist/core/navigators/filters/userTagPreference.mjs +101 -0
  40. package/dist/core/navigators/filters/userTagPreference.mjs.map +1 -0
  41. package/dist/core/navigators/generators/CompositeGenerator.mjs +203 -0
  42. package/dist/core/navigators/generators/CompositeGenerator.mjs.map +1 -0
  43. package/dist/core/navigators/generators/elo.mjs +77 -0
  44. package/dist/core/navigators/generators/elo.mjs.map +1 -0
  45. package/dist/core/navigators/generators/prescribed.mjs +694 -0
  46. package/dist/core/navigators/generators/prescribed.mjs.map +1 -0
  47. package/dist/core/navigators/generators/srs.mjs +158 -0
  48. package/dist/core/navigators/generators/srs.mjs.map +1 -0
  49. package/dist/core/navigators/index.mjs +345 -0
  50. package/dist/core/navigators/index.mjs.map +1 -0
  51. package/dist/core/navigators/pipelinePlan.mjs +109 -0
  52. package/dist/core/navigators/pipelinePlan.mjs.map +1 -0
  53. package/dist/core/navigators/regulators.mjs +128 -0
  54. package/dist/core/navigators/regulators.mjs.map +1 -0
  55. package/dist/core/orchestration/gradient.mjs +101 -0
  56. package/dist/core/orchestration/gradient.mjs.map +1 -0
  57. package/dist/core/orchestration/index.mjs +115 -0
  58. package/dist/core/orchestration/index.mjs.map +1 -0
  59. package/dist/core/orchestration/learning.mjs +140 -0
  60. package/dist/core/orchestration/learning.mjs.map +1 -0
  61. package/dist/core/orchestration/recording.mjs +64 -0
  62. package/dist/core/orchestration/recording.mjs.map +1 -0
  63. package/dist/core/orchestration/signal.mjs +40 -0
  64. package/dist/core/orchestration/signal.mjs.map +1 -0
  65. package/dist/core/types/contentNavigationStrategy.mjs +10 -0
  66. package/dist/core/types/contentNavigationStrategy.mjs.map +1 -0
  67. package/dist/core/types/hydration.mjs +13 -0
  68. package/dist/core/types/hydration.mjs.map +1 -0
  69. package/dist/core/types/strategyState.mjs +16 -0
  70. package/dist/core/types/strategyState.mjs.map +1 -0
  71. package/dist/core/types/studySession.mjs +14 -0
  72. package/dist/core/types/studySession.mjs.map +1 -0
  73. package/dist/core/types/types-legacy.mjs +44 -0
  74. package/dist/core/types/types-legacy.mjs.map +1 -0
  75. package/dist/core/util/index.mjs +31 -0
  76. package/dist/core/util/index.mjs.map +1 -0
  77. package/dist/core/versionStamps.mjs +46 -0
  78. package/dist/core/versionStamps.mjs.map +1 -0
  79. package/dist/courseConfigRegistration.mjs +306 -0
  80. package/dist/courseConfigRegistration.mjs.map +1 -0
  81. package/dist/{dataLayerProvider-C_QWzHf-.d.ts → dataLayerProvider-BDshhSp_.d.ts} +1 -1
  82. package/dist/diagnostics/dataset.mjs +118 -0
  83. package/dist/diagnostics/dataset.mjs.map +1 -0
  84. package/dist/diagnostics/derive.mjs +318 -0
  85. package/dist/diagnostics/derive.mjs.map +1 -0
  86. package/dist/diagnostics/{index.js → index.cjs} +1 -1
  87. package/dist/diagnostics/index.d.ts +3 -3
  88. package/dist/diagnostics/index.mjs +7 -1042
  89. package/dist/diagnostics/loader.mjs +151 -0
  90. package/dist/diagnostics/loader.mjs.map +1 -0
  91. package/dist/diagnostics/pipeline.mjs +161 -0
  92. package/dist/diagnostics/pipeline.mjs.map +1 -0
  93. package/dist/diagnostics/tagElo.mjs +177 -0
  94. package/dist/diagnostics/tagElo.mjs.map +1 -0
  95. package/dist/diagnostics/text.mjs +174 -0
  96. package/dist/diagnostics/text.mjs.map +1 -0
  97. package/dist/factory.mjs +70 -0
  98. package/dist/factory.mjs.map +1 -0
  99. package/dist/impl/common/BaseUserDB.mjs +1115 -0
  100. package/dist/impl/common/BaseUserDB.mjs.map +1 -0
  101. package/dist/impl/common/userDBHelpers.mjs +49 -0
  102. package/dist/impl/common/userDBHelpers.mjs.map +1 -0
  103. package/dist/impl/common/userDBKeys.mjs +45 -0
  104. package/dist/impl/common/userDBKeys.mjs.map +1 -0
  105. package/dist/impl/couch/CouchDBSyncStrategy.mjs +272 -0
  106. package/dist/impl/couch/CouchDBSyncStrategy.mjs.map +1 -0
  107. package/dist/impl/couch/CourseSyncService.mjs +320 -0
  108. package/dist/impl/couch/CourseSyncService.mjs.map +1 -0
  109. package/dist/impl/couch/PouchDataLayerProvider.mjs +89 -0
  110. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -0
  111. package/dist/impl/couch/adminDB.mjs +61 -0
  112. package/dist/impl/couch/adminDB.mjs.map +1 -0
  113. package/dist/impl/couch/auth.mjs +33 -0
  114. package/dist/impl/couch/auth.mjs.map +1 -0
  115. package/dist/impl/couch/classroomDB.mjs +227 -0
  116. package/dist/impl/couch/classroomDB.mjs.map +1 -0
  117. package/dist/impl/couch/clientCache.mjs +15 -0
  118. package/dist/impl/couch/clientCache.mjs.map +1 -0
  119. package/dist/impl/couch/courseAPI.mjs +197 -0
  120. package/dist/impl/couch/courseAPI.mjs.map +1 -0
  121. package/dist/impl/couch/courseDB.mjs +735 -0
  122. package/dist/impl/couch/courseDB.mjs.map +1 -0
  123. package/dist/impl/couch/courseLookupDB.mjs +94 -0
  124. package/dist/impl/couch/courseLookupDB.mjs.map +1 -0
  125. package/dist/impl/couch/{index.js → index.cjs} +7003 -10358
  126. package/dist/impl/couch/index.cjs.map +1 -0
  127. package/dist/impl/couch/index.d.ts +33 -5
  128. package/dist/impl/couch/index.mjs +152 -12147
  129. package/dist/impl/couch/index.mjs.map +1 -1
  130. package/dist/impl/couch/pouchdb-setup.mjs +15 -0
  131. package/dist/impl/couch/pouchdb-setup.mjs.map +1 -0
  132. package/dist/impl/couch/updateQueue.mjs +101 -0
  133. package/dist/impl/couch/updateQueue.mjs.map +1 -0
  134. package/dist/impl/couch/user-course-relDB.mjs +55 -0
  135. package/dist/impl/couch/user-course-relDB.mjs.map +1 -0
  136. package/dist/impl/static/NoOpSyncStrategy.mjs +49 -0
  137. package/dist/impl/static/NoOpSyncStrategy.mjs.map +1 -0
  138. package/dist/impl/static/StaticDataLayerProvider.mjs +94 -0
  139. package/dist/impl/static/StaticDataLayerProvider.mjs.map +1 -0
  140. package/dist/impl/static/StaticDataUnpacker.mjs +311 -0
  141. package/dist/impl/static/StaticDataUnpacker.mjs.map +1 -0
  142. package/dist/impl/static/courseDB.mjs +368 -0
  143. package/dist/impl/static/courseDB.mjs.map +1 -0
  144. package/dist/impl/static/coursesDB.mjs +38 -0
  145. package/dist/impl/static/coursesDB.mjs.map +1 -0
  146. package/dist/impl/static/{index.js → index.cjs} +2486 -5993
  147. package/dist/impl/static/index.cjs.map +1 -0
  148. package/dist/impl/static/index.d.ts +4 -4
  149. package/dist/impl/static/index.mjs +6 -10741
  150. package/dist/{index-C745YB_6.d.ts → index-BLDpFYG3.d.ts} +1 -1
  151. package/dist/{index.js → index.cjs} +14190 -14249
  152. package/dist/index.cjs.map +1 -0
  153. package/dist/index.d.ts +12 -23
  154. package/dist/index.mjs +38 -16937
  155. package/dist/pouch/{index.js → index.cjs} +5 -1
  156. package/dist/pouch/index.cjs.map +1 -0
  157. package/dist/pouch/index.mjs +2 -19
  158. package/dist/study/ItemQueue.mjs +95 -0
  159. package/dist/study/ItemQueue.mjs.map +1 -0
  160. package/dist/study/MixerDebugger.mjs +303 -0
  161. package/dist/study/MixerDebugger.mjs.map +1 -0
  162. package/dist/study/SessionController.mjs +1187 -0
  163. package/dist/study/SessionController.mjs.map +1 -0
  164. package/dist/study/SessionDebugger.mjs +271 -0
  165. package/dist/study/SessionDebugger.mjs.map +1 -0
  166. package/dist/study/SessionOverlay.mjs +407 -0
  167. package/dist/study/SessionOverlay.mjs.map +1 -0
  168. package/dist/study/SourceMixer.mjs +45 -0
  169. package/dist/study/SourceMixer.mjs.map +1 -0
  170. package/dist/study/SpacedRepetition.mjs +108 -0
  171. package/dist/study/SpacedRepetition.mjs.map +1 -0
  172. package/dist/study/TagFilteredContentSource.mjs +136 -0
  173. package/dist/study/TagFilteredContentSource.mjs.map +1 -0
  174. package/dist/study/services/CardHydrationService.mjs +172 -0
  175. package/dist/study/services/CardHydrationService.mjs.map +1 -0
  176. package/dist/study/services/EloService.mjs +217 -0
  177. package/dist/study/services/EloService.mjs.map +1 -0
  178. package/dist/study/services/ResponseProcessor.mjs +190 -0
  179. package/dist/study/services/ResponseProcessor.mjs.map +1 -0
  180. package/dist/study/services/SrsService.mjs +49 -0
  181. package/dist/study/services/SrsService.mjs.map +1 -0
  182. package/dist/study/services/tagRecent.mjs +65 -0
  183. package/dist/study/services/tagRecent.mjs.map +1 -0
  184. package/dist/{types-DF0JuPbs.d.ts → types-DChCz22D.d.ts} +1 -1
  185. package/dist/{types-legacy-DdVjg81H.d.cts → types-legacy-fT5Y1Wuy.d.ts} +1 -1
  186. package/dist/userDBKeys-ne1g4Xuq.d.ts +16 -0
  187. package/dist/util/Loggable.mjs +14 -0
  188. package/dist/util/Loggable.mjs.map +1 -0
  189. package/dist/util/dataDirectory.mjs +47 -0
  190. package/dist/util/dataDirectory.mjs.map +1 -0
  191. package/dist/util/logger.mjs +86 -0
  192. package/dist/util/logger.mjs.map +1 -0
  193. package/dist/util/migrator/FileSystemAdapter.mjs +18 -0
  194. package/dist/util/migrator/FileSystemAdapter.mjs.map +1 -0
  195. package/dist/util/migrator/StaticToCouchDBMigrator.mjs +428 -0
  196. package/dist/util/migrator/StaticToCouchDBMigrator.mjs.map +1 -0
  197. package/dist/util/migrator/types.mjs +11 -0
  198. package/dist/util/migrator/types.mjs.map +1 -0
  199. package/dist/util/migrator/validation.mjs +334 -0
  200. package/dist/util/migrator/validation.mjs.map +1 -0
  201. package/dist/util/packer/CouchDBToStaticPacker.mjs +438 -0
  202. package/dist/util/packer/CouchDBToStaticPacker.mjs.map +1 -0
  203. package/dist/util/packer/{index.js → index.cjs} +73 -9
  204. package/dist/util/packer/index.cjs.map +1 -0
  205. package/dist/util/packer/index.d.ts +3 -3
  206. package/dist/util/packer/index.mjs +2 -537
  207. package/eslint.config.mjs +9 -1
  208. package/package.json +25 -13
  209. package/rolldown.config.mjs +44 -0
  210. package/src/core/UserDBDebugger.ts +47 -46
  211. package/src/core/navigators/Pipeline.ts +10 -10
  212. package/src/core/navigators/PipelineDebugger.ts +55 -55
  213. package/src/core/navigators/filters/eloDistance.ts +1 -1
  214. package/src/core/navigators/generators/elo.ts +5 -1
  215. package/src/core/navigators/generators/prescribed.ts +42 -16
  216. package/src/core/navigators/index.ts +9 -3
  217. package/src/factory.ts +10 -1
  218. package/src/impl/common/BaseUserDB.ts +16 -5
  219. package/src/impl/common/index.ts +2 -0
  220. package/src/impl/common/userDBHelpers.ts +4 -58
  221. package/src/impl/common/userDBKeys.ts +64 -0
  222. package/src/impl/couch/CourseSyncService.ts +130 -20
  223. package/src/impl/couch/PouchDataLayerProvider.ts +14 -1
  224. package/src/impl/couch/courseAPI.ts +26 -12
  225. package/src/impl/couch/courseDB.ts +35 -15
  226. package/src/impl/couch/index.ts +18 -23
  227. package/src/impl/couch/pouchdb-setup.ts +8 -0
  228. package/src/index.ts +1 -1
  229. package/src/study/MixerDebugger.ts +46 -46
  230. package/src/study/SessionDebugger.ts +20 -20
  231. package/src/study/SessionOverlay.ts +4 -4
  232. package/src/util/logger.ts +112 -13
  233. package/tests/core/navigators/eloGenerator.test.ts +36 -0
  234. package/tests/impl/courseSync.test.ts +139 -0
  235. package/tsup.config.ts +24 -21
  236. package/dist/SyncStrategy-BXliog1m.d.cts +0 -116
  237. package/dist/classroomDB-DLTtLZct.d.cts +0 -86
  238. package/dist/contentSource-FQZcZopC.d.cts +0 -2007
  239. package/dist/core/index.d.cts +0 -521
  240. package/dist/core/index.js.map +0 -1
  241. package/dist/core/index.mjs.map +0 -1
  242. package/dist/dataLayerProvider-3y21KtF-.d.cts +0 -61
  243. package/dist/diagnostics/index.d.cts +0 -561
  244. package/dist/diagnostics/index.mjs.map +0 -1
  245. package/dist/impl/couch/index.d.cts +0 -620
  246. package/dist/impl/couch/index.js.map +0 -1
  247. package/dist/impl/static/index.d.cts +0 -232
  248. package/dist/impl/static/index.js.map +0 -1
  249. package/dist/impl/static/index.mjs.map +0 -1
  250. package/dist/index-BIum9Ue2.d.cts +0 -137
  251. package/dist/index.d.cts +0 -1663
  252. package/dist/index.js.map +0 -1
  253. package/dist/index.mjs.map +0 -1
  254. package/dist/pouch/index.d.cts +0 -1
  255. package/dist/pouch/index.js.map +0 -1
  256. package/dist/pouch/index.mjs.map +0 -1
  257. package/dist/types-BcWVH4ww.d.cts +0 -58
  258. package/dist/types-legacy-DdVjg81H.d.ts +0 -168
  259. package/dist/util/packer/index.d.cts +0 -5
  260. package/dist/util/packer/index.js.map +0 -1
  261. package/dist/util/packer/index.mjs.map +0 -1
  262. package/src/study/getCardDataShape.ts +0 -34
  263. /package/dist/diagnostics/{index.js.map → index.cjs.map} +0 -0
@@ -1,620 +0,0 @@
1
- import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-DdVjg81H.cjs';
2
- import { Moment } from 'moment';
3
- import { o as StudyContentSource, U as UserDBInterface, G as GeneratorResult, a as CoursesDBInterface, C as CourseDBInterface, b as CourseInfo, D as DataLayerResult, c as ContentNavigationStrategyData, d as ContentNavigator, R as ReplanHints, S as StudySessionItem, f as ScheduledCard } from '../../contentSource-FQZcZopC.cjs';
4
- export { v as ContentSourceID, p as StudySessionFailedItem, q as StudySessionFailedNewItem, r as StudySessionFailedReviewItem, s as StudySessionNewItem, t as StudySessionReviewItem, w as getStudySource, u as isReview } from '../../contentSource-FQZcZopC.cjs';
5
- import { A as AdminDBInterface, a as AssignedContent, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from '../../classroomDB-DLTtLZct.cjs';
6
- import * as _vue_skuilder_common from '@vue-skuilder/common';
7
- import { ClassroomConfig, DataShape, CourseElo, CourseConfig as CourseConfig$1 } from '@vue-skuilder/common';
8
- import { S as SyncStrategy, A as AccountCreationResult, a as AuthenticationResult, b as AdoptSessionResult } from '../../SyncStrategy-BXliog1m.cjs';
9
-
10
- type NamespacedDatashape = string;
11
- interface DataShape55 {
12
- name: NamespacedDatashape;
13
- questionTypes: PouchDB.Core.DocumentId[];
14
- serializedZodSchema?: string;
15
- }
16
- type NamespacedQuestion = string;
17
- interface QuestionType55 {
18
- name: NamespacedQuestion;
19
- viewList: string[];
20
- dataShapeList: string[];
21
- }
22
- interface CourseOrchestrationConfig {
23
- /**
24
- * Random seed used to determine user cohort assignments.
25
- * Changing this value re-shuffles all users into new cohorts.
26
- */
27
- salt: string;
28
- }
29
- /**
30
- * metadata about a defined course
31
- *
32
- * Note: `courseID` is generated server-side. It is not present on
33
- * new courses at the time of writing, client-side, but always
34
- * present (!) when a CourseConfig is retrieved from the database
35
- */
36
- interface CourseConfig {
37
- courseID?: string;
38
- name: string;
39
- description: string;
40
- public: boolean;
41
- deleted: boolean;
42
- creator: string;
43
- admins: string[];
44
- moderators: string[];
45
- dataShapes: DataShape55[];
46
- questionTypes: QuestionType55[];
47
- disambiguator?: string;
48
- orchestration?: CourseOrchestrationConfig;
49
- /**
50
- * Opt-in client-side replication of the course database.
51
- *
52
- * When enabled, the client replicates the course DB to a local PouchDB
53
- * instance on first visit (full one-shot sync) and performs incremental
54
- * sync on subsequent visits. Pipeline scoring, tag hydration, and card
55
- * lookup then run against the local replica — eliminating network round
56
- * trips from the study-session hot path.
57
- *
58
- * **Read/write split:** The local DB is a read-only snapshot. All writes
59
- * (card ELO updates, tag mutations, etc.) continue to target the remote
60
- * CouchDB. This avoids propagating per-interaction ELO noise to every
61
- * syncing client — the remote DB aggregates writes from all users, and
62
- * each client's local snapshot is refreshed on the next page load.
63
- *
64
- * Defaults to `undefined` (disabled). Courses with small, relatively
65
- * static content databases (e.g. < 50 MB) are good candidates.
66
- */
67
- localSync?: {
68
- enabled: boolean;
69
- };
70
- /**
71
- * The course content's version, written by whatever deploys the content
72
- * (e.g. a git SHA and date). Opaque to the framework: each pipeline run
73
- * records it, so a content change shows up in learners' records.
74
- */
75
- contentVersion?: string;
76
- /**
77
- * Regex source (matched case-insensitively) for the usernames of QA / test
78
- * accounts, e.g. `@example\.com$` for throwaway signups on a domain the team
79
- * owns. A matching user's responses move their own ELO as usual, so a QA run
80
- * plays out like a real learner's, but never card ELO: an adult speedrunning
81
- * a fresh account through early content would otherwise drag those cards
82
- * easier, at the low counts where card K is largest. Unset: no QA accounts.
83
- */
84
- qaUsernamePattern?: string;
85
- }
86
-
87
- declare class AdminDB implements AdminDBInterface {
88
- private usersDB;
89
- constructor();
90
- getUsers(): Promise<PouchDB.Core.ExistingDocument<PouchDB.Core.AllDocsMeta>[]>;
91
- getCourses(): Promise<CourseConfig[]>;
92
- removeCourse(id: string): Promise<{
93
- ok: boolean;
94
- id: string;
95
- rev: string;
96
- }>;
97
- getClassrooms(): Promise<{
98
- _id: string;
99
- students: string[];
100
- teachers: string[];
101
- name: string;
102
- birthYear?: number;
103
- classMeetingSchedule: string;
104
- peerAssist: boolean;
105
- joinCode: string;
106
- }[]>;
107
- }
108
-
109
- declare const CLASSROOM_CONFIG = "ClassroomConfig";
110
- type ClassroomMessage = object;
111
- declare abstract class ClassroomDBBase {
112
- _id: string;
113
- protected _db: PouchDB.Database;
114
- protected _cfg: ClassroomConfig;
115
- protected _initComplete: boolean;
116
- protected readonly _content_prefix: string;
117
- protected get _content_searchkeys(): {
118
- startkey: string;
119
- endkey: string;
120
- };
121
- protected abstract init(): Promise<void>;
122
- getAssignedContent(): Promise<AssignedContent[]>;
123
- protected getContentId(content: AssignedContent): string;
124
- get ready(): boolean;
125
- getConfig(): ClassroomConfig;
126
- }
127
- declare class StudentClassroomDB extends ClassroomDBBase implements StudyContentSource, StudentClassroomDBInterface {
128
- private userMessages;
129
- private _user;
130
- private constructor();
131
- init(): Promise<void>;
132
- static factory(classID: string, user: UserDBInterface): Promise<StudentClassroomDB>;
133
- setChangeFcn(f: (value: unknown) => object): void;
134
- /**
135
- * Get cards with suitability scores for presentation.
136
- *
137
- * Gathers new cards from assigned content (courses, tags, cards) and
138
- * pending reviews scheduled for this classroom. Assigns score=1.0 to all.
139
- *
140
- * @param limit - Maximum number of cards to return
141
- * @returns Cards sorted by score descending (all scores = 1.0)
142
- */
143
- getWeightedCards(limit: number): Promise<GeneratorResult>;
144
- }
145
- /**
146
- * Interface for managing a classroom.
147
- */
148
- declare class TeacherClassroomDB extends ClassroomDBBase implements TeacherClassroomDBInterface {
149
- private _stuDb;
150
- private constructor();
151
- init(): Promise<void>;
152
- static factory(classID: string): Promise<TeacherClassroomDB>;
153
- removeContent(content: AssignedContent): Promise<void>;
154
- assignContent(content: AssignedContent): Promise<boolean>;
155
- }
156
- declare const ClassroomLookupDB: () => PouchDB.Database;
157
- declare function getClassroomDB(classID: string, version: 'student' | 'teacher'): PouchDB.Database;
158
- declare function getClassroomConfig(classID: string): Promise<ClassroomConfig>;
159
-
160
- /**
161
- *
162
- * @param courseID id of the course (quilt) being added to
163
- * @param codeCourse
164
- * @param shape
165
- * @param data the datashape data - data required for this shape
166
- * @param author
167
- * @param uploads optional additional media uploads: img0, img1, ..., aud0, aud1,...
168
- * @returns
169
- */
170
- declare function addNote55(courseID: string, codeCourse: string, shape: DataShape, data: unknown, author: string, tags: string[], uploads?: {
171
- [x: string]: PouchDB.Core.FullAttachment;
172
- }, elo?: CourseElo): Promise<PouchDB.Core.Response>;
173
- declare function getCredentialledCourseConfig(courseID: string): Promise<CourseConfig$1>;
174
- /**
175
- Assciates a tag with a card.
176
-
177
- NB: DB stores tags as separate documents, with a list of card IDs.
178
- Consider renaming to `addCardToTag` to reflect this.
179
-
180
- NB: tags are created if they don't already exist
181
-
182
- @param updateELO whether to update the ELO of the card with the new tag. Default true.
183
- @package
184
- */
185
- declare function addTagToCard(courseID: string, cardID: string, tagID: string, author: string, updateELO?: boolean): Promise<PouchDB.Core.Response>;
186
- declare function getTagID(tagName: string): string;
187
-
188
- declare class CoursesDB implements CoursesDBInterface {
189
- _courseIDs: string[] | undefined;
190
- constructor(courseIDs?: string[]);
191
- getCourseList(): Promise<CourseConfig$1[]>;
192
- getCourseConfig(courseId: string): Promise<CourseConfig$1>;
193
- disambiguateCourse(courseId: string, disambiguator: string): Promise<void>;
194
- }
195
- declare class CourseDB implements CourseDBInterface {
196
- /**
197
- * Primary database handle used for all **read** operations (queries, gets).
198
- *
199
- * When local sync is active, this points to the local PouchDB replica for
200
- * fast, network-free reads. Otherwise it points to the remote CouchDB.
201
- */
202
- private db;
203
- /**
204
- * Remote database handle used for all **write** operations.
205
- *
206
- * Always points to the remote CouchDB so that writes (ELO updates, tag
207
- * mutations, admin operations) aggregate on the server. The local replica
208
- * is a read-only snapshot that refreshes on the next page load.
209
- *
210
- * When local sync is NOT active, this is the same instance as `this.db`.
211
- */
212
- private remoteDB;
213
- private id;
214
- private _getCurrentUser;
215
- private updateQueue;
216
- /**
217
- * @param id - Course ID
218
- * @param userLookup - Async function returning the current user DB
219
- * @param localDB - Optional local PouchDB replica for reads. When provided,
220
- * `this.db` uses the local replica and `this.remoteDB` stays remote.
221
- * The UpdateQueue reads from remote and writes to remote (local `_rev`
222
- * values may be stale, so read-modify-write cycles must go through
223
- * the remote DB to avoid conflicts).
224
- */
225
- constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database);
226
- getCourseID(): string;
227
- getCourseInfo(): Promise<CourseInfo>;
228
- getInexperiencedCards(limit?: number): Promise<{
229
- courseId: string;
230
- cardId: any;
231
- count: any;
232
- elo: any;
233
- }[]>;
234
- getCardsByEloLimits(options?: {
235
- low: number;
236
- high: number;
237
- limit: number;
238
- page: number;
239
- }): Promise<string[]>;
240
- getCardEloData(id: string[]): Promise<CourseElo[]>;
241
- /**
242
- * Returns the lowest and highest `global` ELO ratings in the course
243
- */
244
- getELOBounds(): Promise<{
245
- low: any;
246
- high: any;
247
- }>;
248
- removeCard(id: string): Promise<PouchDB.Core.Response>;
249
- getCardDisplayableDataIDs(id: string[]): Promise<{
250
- [card: string]: string[];
251
- }>;
252
- getCardsByELO(elo: number, cardLimit?: number): Promise<{
253
- courseID: string;
254
- cardID: any;
255
- elo: any;
256
- }[]>;
257
- getCourseConfig(): Promise<CourseConfig$1>;
258
- updateCourseConfig(cfg: CourseConfig$1): Promise<PouchDB.Core.Response>;
259
- updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
260
- getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
261
- getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
262
- getAllCardIds(): Promise<string[]>;
263
- addTagToCard(cardId: string, tagId: string, updateELO?: boolean): Promise<PouchDB.Core.Response>;
264
- removeTagFromCard(cardId: string, tagId: string): Promise<PouchDB.Core.Response>;
265
- createTag(name: string, author: string): Promise<PouchDB.Core.Response>;
266
- getTag(tagId: string): Promise<PouchDB.Core.GetMeta & PouchDB.Core.Document<Tag>>;
267
- updateTag(tag: Tag): Promise<PouchDB.Core.Response>;
268
- getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>>;
269
- addNote(codeCourse: string, shape: DataShape, data: unknown, author: string, tags: string[], uploads?: {
270
- [key: string]: PouchDB.Core.FullAttachment;
271
- }, elo?: CourseElo): Promise<DataLayerResult>;
272
- getCourseDoc<T extends SkuilderCourseData>(id: string, options?: PouchDB.Core.GetOptions): Promise<PouchDB.Core.GetMeta & PouchDB.Core.Document<T>>;
273
- getCourseDocs<T extends SkuilderCourseData>(ids: string[], options?: PouchDB.Core.AllDocsOptions): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>>;
274
- getNavigationStrategy(id: string): Promise<ContentNavigationStrategyData>;
275
- getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]>;
276
- addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void>;
277
- updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
278
- /**
279
- * Creates an instantiated navigator for this course.
280
- *
281
- * Handles multiple generators by wrapping them in CompositeGenerator.
282
- * This is the preferred method for getting a ready-to-use navigator.
283
- *
284
- * @param user - User database interface
285
- * @returns Instantiated ContentNavigator ready for use
286
- */
287
- createNavigator(user: UserDBInterface): Promise<ContentNavigator>;
288
- /**
289
- * Get cards with suitability scores for presentation.
290
- *
291
- * This is the PRIMARY API for content sources going forward. Delegates to the
292
- * course's configured NavigationStrategy to get scored candidates.
293
- *
294
- * @param limit - Maximum number of cards to return
295
- * @returns Cards sorted by score descending
296
- */
297
- private _pendingHints;
298
- /**
299
- * Session-scoped cache of the broad ELO-neighbor pool used by
300
- * getCardsCenteredAtELO. The `elo` view query re-indexes on first touch per
301
- * call (PouchDB 9 ignores `stale`), so without this each plan/replan pays
302
- * ~1.5-2s. The pool is fetched once and re-ranked against the live (roaming)
303
- * ELO in memory on subsequent calls.
304
- */
305
- private _eloPoolCache;
306
- private readonly _eloPoolTtlMs;
307
- /**
308
- * Cached assembled navigator (Pipeline). createNavigator() reads strategy
309
- * docs and builds a fresh Pipeline every call — whose internal `_tagCache`
310
- * and `_cachedOrchestration` are designed to make replans cheap but never
311
- * survive, because the instance is discarded each run. Caching it lets those
312
- * caches persist across plan/replan within a session (SessionController holds
313
- * one CourseDB instance for the session's lifetime). Rebuilt on user change,
314
- * TTL expiry, or explicit invalidation after a strategy-doc write.
315
- */
316
- private _cachedNavigator;
317
- private readonly _navigatorTtlMs;
318
- setEphemeralHints(hints: ReplanHints): void;
319
- /**
320
- * Forward a presentation to the navigator (a new card restarts its intake
321
- * clock). Builds the navigator if the cached one has expired.
322
- */
323
- notePresented(card: {
324
- cardId: string;
325
- courseId: string;
326
- status: string;
327
- }): void;
328
- getWeightedCards(limit: number): Promise<GeneratorResult>;
329
- /**
330
- * Return the assembled navigator, reusing the cached instance when possible.
331
- * Reuse preserves the Pipeline's per-session caches (tags, orchestration
332
- * context) across replans, which is the dominant per-replan cost once the
333
- * ELO-pool cost is removed. Rebuilds on user change or TTL expiry.
334
- */
335
- private _getCachedNavigator;
336
- /**
337
- * Drop the cached navigator so the next getWeightedCards() rebuilds it.
338
- * Call after mutating this course's navigation strategy documents.
339
- */
340
- invalidateNavigatorCache(): void;
341
- getCardsCenteredAtELO(options?: {
342
- limit: number;
343
- elo: 'user' | 'random' | number;
344
- }, filter?: (a: QualifiedCardID) => boolean): Promise<StudySessionItem[]>;
345
- searchCards(query: string): Promise<any[]>;
346
- find(request: PouchDB.Find.FindRequest<any>): Promise<PouchDB.Find.FindResponse<any>>;
347
- }
348
- /**
349
- * Returns a list of registered datashapes for the specified
350
- * course.
351
- * @param courseID The ID of the course
352
- */
353
- declare function getCourseDataShapes(courseID: string): Promise<_vue_skuilder_common.DataShape55[]>;
354
- declare function getCredentialledDataShapes(courseID: string): Promise<_vue_skuilder_common.DataShape55[]>;
355
- declare function getCourseQuestionTypes(courseID: string): Promise<_vue_skuilder_common.QuestionType55[]>;
356
- declare function getCourseTagStubs(courseID: string): Promise<PouchDB.Core.AllDocsResponse<Tag>>;
357
- declare function deleteTag(courseID: string, tagName: string): Promise<PouchDB.Core.Response>;
358
- declare function createTag(courseID: string, tagName: string, author: string): Promise<PouchDB.Core.Response>;
359
- declare function updateTag(tag: Tag): Promise<PouchDB.Core.Response>;
360
- declare function getTag(courseID: string, tagName: string): Promise<Tag & PouchDB.Core.IdMeta & PouchDB.Core.GetMeta>;
361
- declare function removeTagFromCard(courseID: string, cardID: string, tagID: string): Promise<PouchDB.Core.Response>;
362
- /**
363
- * Returns an array of ancestor tag IDs, where:
364
- * return[0] = parent,
365
- * return[1] = grandparent,
366
- * return[2] = great grandparent,
367
- * etc.
368
- *
369
- * If ret is empty, the tag itself is a root
370
- */
371
- declare function getAncestorTagIDs(courseID: string, tagID: string): string[];
372
- declare function getChildTagStubs(courseID: string, tagID: string): Promise<PouchDB.Core.AllDocsResponse<{}>>;
373
- declare function getAppliedTags(id_course: string, id_card: string): Promise<PouchDB.Query.Response<TagStub>>;
374
- declare function updateCardElo(courseID: string, cardID: string, elo: CourseElo): Promise<PouchDB.Core.Response | undefined>;
375
- declare function updateCredentialledCourseConfig(courseID: string, config: CourseConfig$1): Promise<PouchDB.Core.Response>;
376
-
377
- /**
378
- * Sync state for a single course database.
379
- */
380
- type CourseSyncState = 'not-started' | 'checking-config' | 'syncing' | 'warming-views' | 'ready' | 'disabled' | 'error';
381
- /**
382
- * Detailed sync status for observability.
383
- */
384
- interface CourseSyncStatus {
385
- state: CourseSyncState;
386
- /** Number of documents replicated (set after sync completes) */
387
- docsReplicated?: number;
388
- /** Total replication time in ms */
389
- syncTimeMs?: number;
390
- /** View warming time in ms */
391
- viewWarmTimeMs?: number;
392
- /** Error message if state is 'error' */
393
- error?: string;
394
- }
395
- /**
396
- * Service that manages local PouchDB replicas of course databases.
397
- *
398
- * Usage:
399
- * ```typescript
400
- * const syncService = CourseSyncService.getInstance();
401
- *
402
- * // Trigger sync (typically on app load / pre-session)
403
- * await syncService.ensureSynced(courseId);
404
- *
405
- * // Get local DB for reads (returns null if sync not ready/enabled)
406
- * const localDB = syncService.getLocalDB(courseId);
407
- * ```
408
- *
409
- * The service is a singleton — course sync state is shared across the app.
410
- */
411
- /**
412
- * Tuning knobs for one-shot remote→local replication.
413
- * Defaults are chosen for one-shot snapshot replication of bounded course
414
- * corpora (text/JSON docs, no large attachments). PouchDB's built-in
415
- * defaults (100/10) target live continuous sync — too conservative for
416
- * cold-load UX on a course of a few thousand docs.
417
- *
418
- * Apps with smaller/larger corpora can override via
419
- * `initializeDataLayer({ options: { courseSync: { replication: {...} } } })`.
420
- */
421
- interface ReplicationOptions {
422
- /** Docs per `_bulk_get` HTTP request. Higher = fewer roundtrips. */
423
- batchSize?: number;
424
- /** Concurrent batches in flight. */
425
- batchesLimit?: number;
426
- }
427
- declare class CourseSyncService {
428
- private static instance;
429
- private entries;
430
- private replicationOptions;
431
- private constructor();
432
- static getInstance(): CourseSyncService;
433
- /**
434
- * Apply replication tuning. Typically called once from `initializeDataLayer`.
435
- * Partial overrides merge with defaults.
436
- */
437
- configure(opts: {
438
- replication?: ReplicationOptions;
439
- }): void;
440
- /**
441
- * Reset the singleton (for testing).
442
- */
443
- static resetInstance(): void;
444
- /**
445
- * Ensure a course's local replica is synced.
446
- *
447
- * On first call for a course:
448
- * 1. Fetches CourseConfig from remote to check localSync.enabled
449
- * 2. If enabled, performs one-shot replication remote → local
450
- * 3. Pre-warms PouchDB view indices (elo, getTags)
451
- *
452
- * On subsequent calls: returns immediately if already synced, or awaits
453
- * the in-flight sync if one is in progress.
454
- *
455
- * Safe to call multiple times — concurrent calls coalesce to one sync.
456
- *
457
- * @param courseId - The course to sync
458
- * @param forceEnabled - Skip the CourseConfig check and sync regardless.
459
- * Useful when the caller already knows local sync is desired (e.g.,
460
- * LettersPractice hardcodes this).
461
- */
462
- ensureSynced(courseId: string, forceEnabled?: boolean): Promise<void>;
463
- /**
464
- * Get the local PouchDB for a course, or null if not available.
465
- *
466
- * Returns null when:
467
- * - Local sync is not enabled for this course
468
- * - Sync has not been triggered yet
469
- * - Sync is still in progress
470
- * - Sync failed
471
- */
472
- getLocalDB(courseId: string): PouchDB.Database | null;
473
- /**
474
- * Check whether a course has a ready local replica.
475
- */
476
- isReady(courseId: string): boolean;
477
- /**
478
- * Get detailed sync status for a course.
479
- */
480
- getStatus(courseId: string): CourseSyncStatus;
481
- private performSync;
482
- /**
483
- * Check CourseConfig.localSync.enabled on the remote DB.
484
- */
485
- private checkLocalSyncEnabled;
486
- /**
487
- * One-shot replication from remote to local.
488
- */
489
- private replicate;
490
- /**
491
- * Pre-warm PouchDB view indices by running a minimal query against each
492
- * design doc. This forces PouchDB to build the MapReduce index now
493
- * (during a loading phase) rather than on first pipeline query.
494
- */
495
- private warmViewIndices;
496
- /**
497
- * Check whether the local replica's `db-epoch` doc matches the remote.
498
- *
499
- * The seed script (and optionally upload-cards) writes a `db-epoch`
500
- * document with a numeric timestamp. If the remote epoch differs from
501
- * the local copy, the remote DB was recreated (e.g., `yarn db:seed`)
502
- * and the local PouchDB is stale.
503
- *
504
- * Returns `true` if stale (epoch mismatch or remote has epoch but local
505
- * doesn't). Returns `false` (not stale) if epochs match, or if the
506
- * remote doesn't have an epoch doc at all (backwards compat).
507
- */
508
- private isLocalEpochStale;
509
- /**
510
- * Get a remote PouchDB handle for a course.
511
- */
512
- private getRemoteDB;
513
- /**
514
- * Local DB naming convention.
515
- */
516
- private localDBName;
517
- }
518
-
519
- /**
520
- * Sync strategy that implements full CouchDB remote synchronization
521
- * Handles account creation, authentication, and live sync with remote CouchDB server
522
- */
523
- declare class CouchDBSyncStrategy implements SyncStrategy {
524
- private syncHandle?;
525
- /** In-flight one-shot hydration pull, so a timed-out pull can be abandoned. */
526
- private hydrationHandle?;
527
- setupRemoteDB(username: string): PouchDB.Database;
528
- getWriteDB(username: string): PouchDB.Database;
529
- /**
530
- * One-shot remote → local pull. Resolves once the local mirror is caught up.
531
- *
532
- * Pull only: pushing here would upload whatever the local DB happens to hold
533
- * before we know what the remote already has, which is the conflict-leaf
534
- * problem hydration exists to avoid. Local changes go up when startSync()
535
- * takes over.
536
- *
537
- * Into an EMPTY local DB this skips deleted documents, because a mirror that
538
- * never held a document does not need to be told it was removed. That
539
- * matters more than it sounds: scheduled reviews (`card_review_*`) are
540
- * created and deleted once per review completed, so the changes feed is
541
- * dominated by tombstones and grows without bound, while the durable record
542
- * lives in card history. One real account measured 385 live documents behind
543
- * 8,370 deletions — an unfiltered pull moved 9,520 documents and took ~20s,
544
- * blowing the hydration timeout on a phone; filtered, the same pull moves
545
- * 404 and takes ~2s, reaching a byte-identical local state.
546
- *
547
- * The filter runs server-side, so `last_seq` still reports the source's true
548
- * sequence. Returning it lets startSync() begin the live pull from there
549
- * instead of re-walking the same history in the background — without that,
550
- * the cost is merely deferred, not removed.
551
- */
552
- hydrate(localDB: PouchDB.Database, remoteDB: PouchDB.Database): Promise<{
553
- docsWritten: number;
554
- lastSeq?: string | number;
555
- }>;
556
- startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database, since?: string | number): void;
557
- stopSync?(): void;
558
- canCreateAccount(): boolean;
559
- canAuthenticate(): boolean;
560
- createAccount(username: string, password: string): Promise<AccountCreationResult>;
561
- authenticate(username: string, password: string): Promise<AuthenticationResult>;
562
- adoptSession(migrateFromGuest?: string): Promise<AdoptSessionResult>;
563
- logout(): Promise<AuthenticationResult>;
564
- getCurrentUsername(): Promise<string>;
565
- /**
566
- * Migrate data from funnel account to real account
567
- */
568
- private migrateFunnelData;
569
- /**
570
- * Get remote CouchDB root database for authentication operations
571
- */
572
- private getRemoteCouchRootDB;
573
- /**
574
- * Get remote user database for a specific user
575
- */
576
- private getUserDB;
577
- }
578
-
579
- declare const localUserDB: PouchDB.Database;
580
- declare function hexEncode(str: string): string;
581
- /**
582
- * Creates PouchDB configuration with appropriate authentication method
583
- * - Uses HTTP Basic Auth when credentials are available (Node.js/MCP)
584
- * - Falls back to cookie auth for browser environments
585
- */
586
- declare function createPouchDBConfig(): PouchDB.Configuration.RemoteDatabaseConfiguration;
587
- declare function getCourseDB(courseID: string): PouchDB.Database;
588
- declare function getLatestVersion(): Promise<string>;
589
- /**
590
- * Checks the remote couchdb to see if a given username is available
591
- * @param username The username to be checked
592
- */
593
- declare function usernameIsAvailable(username: string): Promise<boolean>;
594
- declare function updateGuestAccountExpirationDate(guestDB: PouchDB.Database<object>): void;
595
- declare function getCourseDocs<T extends SkuilderCourseData>(courseID: string, docIDs: string[], options?: PouchDB.Core.AllDocsOptions): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>>;
596
- declare function getCourseDoc<T extends SkuilderCourseData>(courseID: string, docID: PouchDB.Core.DocumentId, options?: PouchDB.Core.GetOptions): Promise<T>;
597
- /**
598
- * Returns *all* cards from the parameter courses, in
599
- * 'qualified' card format ("courseid-cardid")
600
- *
601
- * @param courseIDs A list of all course_ids to get cards from
602
- */
603
- declare function getRandomCards(courseIDs: string[]): Promise<string[]>;
604
- declare const REVIEW_TIME_FORMAT: string;
605
- declare function getCouchUserDB(username: string): PouchDB.Database;
606
- declare function scheduleCardReview(review: {
607
- user: string;
608
- course_id: string;
609
- card_id: PouchDB.Core.DocumentId;
610
- time: Moment;
611
- scheduledFor: ScheduledCard['scheduledFor'];
612
- schedulingAgentId: ScheduledCard['schedulingAgentId'];
613
- }): void;
614
- declare function filterAllDocsByPrefix<T>(db: PouchDB.Database, prefix: string, opts?: PouchDB.Core.AllDocsOptions): Promise<PouchDB.Core.AllDocsResponse<{} & T>>;
615
- declare function getStartAndEndKeys(key: string): {
616
- startkey: string;
617
- endkey: string;
618
- };
619
-
620
- export { AdminDB, CLASSROOM_CONFIG, ClassroomLookupDB, type ClassroomMessage, CouchDBSyncStrategy, CourseDB, CourseSyncService, type CourseSyncState, type CourseSyncStatus, CoursesDB, REVIEW_TIME_FORMAT, type ReplicationOptions, StudentClassroomDB, StudyContentSource, StudySessionItem, TeacherClassroomDB, addNote55, addTagToCard, createPouchDBConfig, createTag, deleteTag, filterAllDocsByPrefix, getAncestorTagIDs, getAppliedTags, getChildTagStubs, getClassroomConfig, getClassroomDB, getCouchUserDB, getCourseDB, getCourseDataShapes, getCourseDoc, getCourseDocs, getCourseQuestionTypes, getCourseTagStubs, getCredentialledCourseConfig, getCredentialledDataShapes, getLatestVersion, getRandomCards, getStartAndEndKeys, getTag, getTagID, hexEncode, localUserDB, removeTagFromCard, scheduleCardReview, updateCardElo, updateCredentialledCourseConfig, updateGuestAccountExpirationDate, updateTag, usernameIsAvailable };