@vue-skuilder/db 0.2.36 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
  2. package/dist/core/index.cjs +203 -148
  3. package/dist/core/index.cjs.map +1 -1
  4. package/dist/core/index.d.ts +5 -5
  5. package/dist/core/navigators/Pipeline.mjs +8 -0
  6. package/dist/core/navigators/Pipeline.mjs.map +1 -1
  7. package/dist/core/navigators/generators/prescribed.mjs +29 -11
  8. package/dist/core/navigators/generators/prescribed.mjs.map +1 -1
  9. package/dist/core/versionStamps.mjs +1 -1
  10. package/dist/{dataLayerProvider-BDshhSp_.d.ts → dataLayerProvider-rGyLQ93v.d.ts} +1 -1
  11. package/dist/diagnostics/index.d.ts +3 -3
  12. package/dist/impl/common/BaseUserDB.mjs +32 -15
  13. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  14. package/dist/impl/couch/CourseSyncService.mjs +111 -11
  15. package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
  16. package/dist/impl/couch/PouchDataLayerProvider.mjs +16 -1
  17. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -1
  18. package/dist/impl/couch/courseAPI.mjs +24 -10
  19. package/dist/impl/couch/courseAPI.mjs.map +1 -1
  20. package/dist/impl/couch/courseDB.mjs +19 -9
  21. package/dist/impl/couch/courseDB.mjs.map +1 -1
  22. package/dist/impl/couch/index.cjs +297 -141
  23. package/dist/impl/couch/index.cjs.map +1 -1
  24. package/dist/impl/couch/index.d.ts +27 -4
  25. package/dist/impl/couch/index.mjs +20 -3
  26. package/dist/impl/couch/index.mjs.map +1 -1
  27. package/dist/impl/couch/updateQueue.mjs +69 -46
  28. package/dist/impl/couch/updateQueue.mjs.map +1 -1
  29. package/dist/impl/static/index.cjs +147 -93
  30. package/dist/impl/static/index.cjs.map +1 -1
  31. package/dist/impl/static/index.d.ts +4 -4
  32. package/dist/{index-BLDpFYG3.d.ts → index-C745YB_6.d.ts} +1 -1
  33. package/dist/index.cjs +345 -171
  34. package/dist/index.cjs.map +1 -1
  35. package/dist/index.d.ts +23 -10
  36. package/dist/index.mjs +2 -1
  37. package/dist/study/SessionController.mjs +4 -0
  38. package/dist/study/SessionController.mjs.map +1 -1
  39. package/dist/{types-DChCz22D.d.ts → types-DF0JuPbs.d.ts} +1 -1
  40. package/dist/{types-legacy-fT5Y1Wuy.d.ts → types-legacy-DdVjg81H.d.ts} +1 -1
  41. package/dist/util/packer/index.d.ts +3 -3
  42. package/dist/util/perfMarks.mjs +30 -0
  43. package/dist/util/perfMarks.mjs.map +1 -0
  44. package/package.json +3 -3
  45. package/src/core/interfaces/courseDB.ts +6 -0
  46. package/src/core/navigators/Pipeline.ts +8 -0
  47. package/src/core/navigators/generators/prescribed.ts +42 -16
  48. package/src/impl/common/BaseUserDB.ts +42 -23
  49. package/src/impl/couch/CourseSyncService.ts +149 -22
  50. package/src/impl/couch/PouchDataLayerProvider.ts +14 -1
  51. package/src/impl/couch/courseAPI.ts +26 -12
  52. package/src/impl/couch/courseDB.ts +25 -12
  53. package/src/impl/couch/index.ts +16 -5
  54. package/src/impl/couch/updateQueue.ts +86 -82
  55. package/src/study/SessionController.ts +4 -0
  56. package/src/util/index.ts +1 -0
  57. package/src/util/perfMarks.ts +35 -0
  58. package/tests/impl/courseSync.test.ts +139 -0
  59. package/tests/impl/updateQueue.test.ts +57 -0
@@ -1,8 +1,8 @@
1
- import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-fT5Y1Wuy.js';
1
+ import { T as TagStub, a as Tag, S as SkuilderCourseData, Q as QualifiedCardID } from '../../types-legacy-DdVjg81H.js';
2
2
  import { Moment } from 'moment';
3
3
  export { h as hexEncode } from '../../userDBKeys-ne1g4Xuq.js';
4
- 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-D_E7JaxR.js';
5
- 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-D_E7JaxR.js';
4
+ 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-2zVmcjKA.js';
5
+ 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-2zVmcjKA.js';
6
6
  import { A as AdminDBInterface, a as AssignedContent, S as StudentClassroomDBInterface, T as TeacherClassroomDBInterface } from '../../classroomDB-DLTtLZct.js';
7
7
  import * as _vue_skuilder_common from '@vue-skuilder/common';
8
8
  import { ClassroomConfig, DataShape, CourseElo, CourseConfig as CourseConfig$1 } from '@vue-skuilder/common';
@@ -171,6 +171,7 @@ declare function getClassroomConfig(classID: string): Promise<ClassroomConfig>;
171
171
  declare function addNote55(courseID: string, codeCourse: string, shape: DataShape, data: unknown, author: string, tags: string[], uploads?: {
172
172
  [x: string]: PouchDB.Core.FullAttachment;
173
173
  }, elo?: CourseElo): Promise<PouchDB.Core.Response>;
174
+ declare function invalidateCourseConfigCache(courseID: string): void;
174
175
  declare function getCredentialledCourseConfig(courseID: string): Promise<CourseConfig$1>;
175
176
  /**
176
177
  Assciates a tag with a card.
@@ -223,6 +224,8 @@ declare class CourseDB implements CourseDBInterface {
223
224
  * values may be stale, so read-modify-write cycles must go through
224
225
  * the remote DB to avoid conflicts).
225
226
  */
227
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
228
+ get readsLocal(): boolean;
226
229
  constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database);
227
230
  getCourseID(): string;
228
231
  getCourseInfo(): Promise<CourseInfo>;
@@ -467,6 +470,19 @@ declare class CourseSyncService {
467
470
  * LettersPractice hardcodes this).
468
471
  */
469
472
  ensureSynced(courseId: string, forceEnabled?: boolean): Promise<void>;
473
+ /**
474
+ * A replica completed on an earlier page load is ready now, refreshed in the
475
+ * background; anything else goes through a full performSync.
476
+ */
477
+ private startSync;
478
+ /**
479
+ * Bring a ready replica up to date without taking it away from readers.
480
+ * Failures leave it ready (and outdated).
481
+ */
482
+ private refreshInBackground;
483
+ private hasSyncMarker;
484
+ private writeSyncMarker;
485
+ private clearSyncMarker;
470
486
  /**
471
487
  * Get the local PouchDB for a course, or null if not available.
472
488
  *
@@ -591,6 +607,13 @@ declare const localUserDB: PouchDB.Database;
591
607
  * - Falls back to cookie auth for browser environments
592
608
  */
593
609
  declare function createPouchDBConfig(): PouchDB.Configuration.RemoteDatabaseConfiguration;
610
+ /**
611
+ * The remote course DB, one handle per URL for the page's lifetime.
612
+ *
613
+ * `skip_setup`: a fresh handle otherwise checks the DB exists (and would try to
614
+ * create it) before its first request: one extra round trip per handle. Course
615
+ * DBs are only created server-side (express), never through this handle.
616
+ */
594
617
  declare function getCourseDB(courseID: string): PouchDB.Database;
595
618
  declare function getLatestVersion(): Promise<string>;
596
619
  /**
@@ -624,4 +647,4 @@ declare function getStartAndEndKeys(key: string): {
624
647
  endkey: string;
625
648
  };
626
649
 
627
- 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, localUserDB, removeTagFromCard, scheduleCardReview, updateCardElo, updateCredentialledCourseConfig, updateGuestAccountExpirationDate, updateTag, usernameIsAvailable };
650
+ 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, invalidateCourseConfigCache, localUserDB, removeTagFromCard, scheduleCardReview, updateCardElo, updateCredentialledCourseConfig, updateGuestAccountExpirationDate, updateTag, usernameIsAvailable };
@@ -6,7 +6,7 @@ import { DocType, DocTypePrefixes, GuestUsername, log } from "../../core/types/t
6
6
  import { hexEncode } from "../common/userDBKeys.mjs";
7
7
  import { AdminDB } from "./adminDB.mjs";
8
8
  import { CourseDB, CoursesDB, createTag, deleteTag, getAncestorTagIDs, getAppliedTags, getChildTagStubs, getCourseDataShapes, getCourseQuestionTypes, getCourseTagStubs, getCredentialledDataShapes, getTag, removeTagFromCard, updateCardElo, updateCredentialledCourseConfig, updateTag } from "./courseDB.mjs";
9
- import { addNote55, addTagToCard, getCredentialledCourseConfig, getTagID } from "./courseAPI.mjs";
9
+ import { addNote55, addTagToCard, getCredentialledCourseConfig, getTagID, invalidateCourseConfigCache } from "./courseAPI.mjs";
10
10
  import { CourseSyncService } from "./CourseSyncService.mjs";
11
11
  import { CouchDBSyncStrategy } from "./CouchDBSyncStrategy.mjs";
12
12
  import { CLASSROOM_CONFIG, ClassroomLookupDB, StudentClassroomDB, TeacherClassroomDB, getClassroomConfig, getClassroomDB } from "./classroomDB.mjs";
@@ -41,8 +41,25 @@ function createPouchDBConfig() {
41
41
  function getCouchDB(dbName) {
42
42
  return new pouchdb_setup_default(ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + dbName, createPouchDBConfig());
43
43
  }
44
+ const courseDBHandles = /* @__PURE__ */ new Map();
45
+ /**
46
+ * The remote course DB, one handle per URL for the page's lifetime.
47
+ *
48
+ * `skip_setup`: a fresh handle otherwise checks the DB exists (and would try to
49
+ * create it) before its first request: one extra round trip per handle. Course
50
+ * DBs are only created server-side (express), never through this handle.
51
+ */
44
52
  function getCourseDB(courseID) {
45
- return new pouchdb_setup_default(ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + "coursedb-" + courseID, createPouchDBConfig());
53
+ const url = ENV.COUCHDB_SERVER_PROTOCOL + "://" + ENV.COUCHDB_SERVER_URL + "coursedb-" + courseID;
54
+ let db = courseDBHandles.get(url);
55
+ if (!db) {
56
+ db = new pouchdb_setup_default(url, {
57
+ ...createPouchDBConfig(),
58
+ skip_setup: true
59
+ });
60
+ courseDBHandles.set(url, db);
61
+ }
62
+ return db;
46
63
  }
47
64
  async function getLatestVersion() {
48
65
  try {
@@ -152,6 +169,6 @@ function getStartAndEndKeys(key) {
152
169
  };
153
170
  }
154
171
  //#endregion
155
- export { AdminDB, CLASSROOM_CONFIG, ClassroomLookupDB, CouchDBSyncStrategy, CourseDB, CourseSyncService, CoursesDB, REVIEW_TIME_FORMAT, StudentClassroomDB, TeacherClassroomDB, addNote55, addTagToCard, createPouchDBConfig, createTag, deleteTag, filterAllDocsByPrefix, getAncestorTagIDs, getAppliedTags, getChildTagStubs, getClassroomConfig, getClassroomDB, getCouchUserDB, getCourseDB, getCourseDataShapes, getCourseDoc, getCourseDocs, getCourseQuestionTypes, getCourseTagStubs, getCredentialledCourseConfig, getCredentialledDataShapes, getLatestVersion, getRandomCards, getStartAndEndKeys, getStudySource, getTag, getTagID, hexEncode, isReview, localUserDB, removeTagFromCard, scheduleCardReview, updateCardElo, updateCredentialledCourseConfig, updateGuestAccountExpirationDate, updateTag, usernameIsAvailable };
172
+ export { AdminDB, CLASSROOM_CONFIG, ClassroomLookupDB, CouchDBSyncStrategy, CourseDB, CourseSyncService, CoursesDB, REVIEW_TIME_FORMAT, StudentClassroomDB, TeacherClassroomDB, addNote55, addTagToCard, createPouchDBConfig, createTag, deleteTag, filterAllDocsByPrefix, getAncestorTagIDs, getAppliedTags, getChildTagStubs, getClassroomConfig, getClassroomDB, getCouchUserDB, getCourseDB, getCourseDataShapes, getCourseDoc, getCourseDocs, getCourseQuestionTypes, getCourseTagStubs, getCredentialledCourseConfig, getCredentialledDataShapes, getLatestVersion, getRandomCards, getStartAndEndKeys, getStudySource, getTag, getTagID, hexEncode, invalidateCourseConfigCache, isReview, localUserDB, removeTagFromCard, scheduleCardReview, updateCardElo, updateCredentialledCourseConfig, updateGuestAccountExpirationDate, updateTag, usernameIsAvailable };
156
173
 
157
174
  //# sourceMappingURL=index.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":["pouch"],"sources":["../../../src/impl/couch/index.ts"],"sourcesContent":["import { ENV } from '@db/factory';\nimport {\n DocType,\n DocTypePrefixes,\n GuestUsername,\n log,\n SkuilderCourseData,\n} from '../../core/types/types-legacy';\nimport fetch from 'cross-fetch';\n// import { getCurrentUser } from '../../stores/useAuthStore';\nimport moment, { Moment } from 'moment';\nimport { logger } from '@db/util/logger';\n\nimport pouch from './pouchdb-setup';\nimport { hexEncode } from '../common/userDBKeys';\n\nimport { ScheduledCard } from '@db/core/types/user';\n\nconst expiryDocID: string = 'GuestAccountExpirationDate';\n\nconst GUEST_LOCAL_DB = `userdb-${GuestUsername}`;\nexport const localUserDB: PouchDB.Database = new pouch(GUEST_LOCAL_DB);\n\nexport { hexEncode };\nconst pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDatabaseConfiguration = {\n fetch(url: string | Request, opts: RequestInit): Promise<Response> {\n opts.credentials = 'include';\n\n return (pouch as any).fetch(url, opts);\n },\n} as PouchDB.Configuration.RemoteDatabaseConfiguration;\n\n/**\n * Creates PouchDB configuration with appropriate authentication method\n * - Uses HTTP Basic Auth when credentials are available (Node.js/MCP)\n * - Falls back to cookie auth for browser environments\n */\nexport function createPouchDBConfig(): PouchDB.Configuration.RemoteDatabaseConfiguration {\n // Check if running in Node.js with explicit credentials\n const hasExplicitCredentials = ENV.COUCHDB_USERNAME && ENV.COUCHDB_PASSWORD;\n const isNodeEnvironment = typeof window === 'undefined';\n \n if (hasExplicitCredentials && isNodeEnvironment) {\n // Use HTTP Basic Auth for Node.js environments (MCP server)\n return {\n fetch(url: string | Request, opts: RequestInit = {}): Promise<Response> {\n const basicAuth = btoa(`${ENV.COUCHDB_USERNAME}:${ENV.COUCHDB_PASSWORD}`);\n const headers = new Headers(opts.headers || {});\n headers.set('Authorization', `Basic ${basicAuth}`);\n \n const newOpts = {\n ...opts,\n headers: headers\n };\n \n return (pouch as any).fetch(url, newOpts);\n }\n } as PouchDB.Configuration.RemoteDatabaseConfiguration;\n }\n \n // Use cookie-based auth for browser environments or when no explicit credentials\n return pouchDBincludeCredentialsConfig;\n}\n\nfunction getCouchDB(dbName: string): PouchDB.Database {\n return new pouch(\n ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,\n createPouchDBConfig()\n );\n}\n\nexport function getCourseDB(courseID: string): PouchDB.Database {\n // todo: keep a cache of opened courseDBs? need to benchmark this somehow\n return new pouch(\n ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID,\n createPouchDBConfig()\n );\n}\n\nexport async function getLatestVersion() {\n try {\n const docs = await getCouchDB('version').allDocs({\n descending: true,\n limit: 1,\n });\n if (docs && docs.rows && docs.rows[0]) {\n return docs.rows[0].id;\n } else {\n return '0.0.0';\n }\n } catch {\n return '-1';\n }\n}\n\n/**\n * Checks the remote couchdb to see if a given username is available\n * @param username The username to be checked\n */\nexport async function usernameIsAvailable(username: string): Promise<boolean> {\n log(`Checking availability of ${username}`);\n \n // Legacy XMLHttpRequest implementation (browser sync)\n // const req = new XMLHttpRequest();\n // const url = ENV.COUCHDB_SERVER_URL + 'userdb-' + hexEncode(username);\n // req.open('HEAD', url, false);\n // req.send();\n // return req.status === 404;\n \n try {\n const url = ENV.COUCHDB_SERVER_URL + 'userdb-' + hexEncode(username);\n const response = await fetch(url, { method: 'HEAD' });\n return response.status === 404;\n } catch (error) {\n log(`Error checking username availability: ${error}`);\n return false;\n }\n}\n\nexport function updateGuestAccountExpirationDate(guestDB: PouchDB.Database<object>) {\n const currentTime = moment.utc();\n const expirationDate: string = currentTime.add(2, 'months').toISOString();\n\n void guestDB\n .get(expiryDocID)\n .then((doc) => {\n return guestDB.put({\n _id: expiryDocID,\n _rev: doc._rev,\n date: expirationDate,\n });\n })\n .catch(() => {\n return guestDB.put({\n _id: expiryDocID,\n date: expirationDate,\n });\n });\n}\n\nexport function getCourseDocs<T extends SkuilderCourseData>(\n courseID: string,\n docIDs: string[],\n options: PouchDB.Core.AllDocsOptions = {}\n) {\n return getCourseDB(courseID).allDocs<T>({\n ...options,\n keys: docIDs,\n });\n}\n\nexport function getCourseDoc<T extends SkuilderCourseData>(\n courseID: string,\n docID: PouchDB.Core.DocumentId,\n options: PouchDB.Core.GetOptions = {}\n): Promise<T> {\n return getCourseDB(courseID).get<T>(docID, options);\n}\n\n/**\n * Returns *all* cards from the parameter courses, in\n * 'qualified' card format (\"courseid-cardid\")\n *\n * @param courseIDs A list of all course_ids to get cards from\n */\nexport async function getRandomCards(courseIDs: string[]) {\n if (courseIDs.length === 0) {\n throw new Error(`getRandomCards:\\n\\tAttempted to get all cards from no courses!`);\n } else {\n const courseResults = await Promise.all(\n courseIDs.map((course) => {\n return getCourseDB(course).find({\n selector: {\n docType: DocType.CARD,\n },\n limit: 1000,\n });\n })\n );\n\n const ret: string[] = [];\n courseResults.forEach((courseCards, index) => {\n courseCards.docs.forEach((doc) => {\n ret.push(`${courseIDs[index]}-${doc._id}`);\n });\n });\n\n return ret;\n }\n}\n\nexport const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';\n\nexport function getCouchUserDB(username: string): PouchDB.Database {\n const guestAccount: boolean = false;\n // console.log(`Getting user db: ${username}`);\n\n const hexName = hexEncode(username);\n const dbName = `userdb-${hexName}`;\n log(`Fetching user database: ${dbName} (${username})`);\n\n // odd construction here the result of a bug in the\n // interaction between pouch, pouch-auth.\n // see: https://github.com/pouchdb-community/pouchdb-authentication/issues/239\n const ret = new pouch(\n ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,\n createPouchDBConfig()\n );\n if (guestAccount) {\n updateGuestAccountExpirationDate(ret);\n }\n\n return ret;\n}\n\nexport function scheduleCardReview(review: {\n user: string;\n course_id: string;\n card_id: PouchDB.Core.DocumentId;\n time: Moment;\n scheduledFor: ScheduledCard['scheduledFor'];\n schedulingAgentId: ScheduledCard['schedulingAgentId'];\n}) {\n const now = moment.utc();\n logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);\n void getCouchUserDB(review.user).put<ScheduledCard>({\n _id: DocTypePrefixes[DocType.SCHEDULED_CARD] + review.time.format(REVIEW_TIME_FORMAT),\n cardId: review.card_id,\n reviewTime: review.time.toISOString(),\n courseId: review.course_id,\n scheduledAt: now.toISOString(),\n scheduledFor: review.scheduledFor,\n schedulingAgentId: review.schedulingAgentId,\n });\n}\n\nexport function filterAllDocsByPrefix<T>(\n db: PouchDB.Database,\n prefix: string,\n opts?: PouchDB.Core.AllDocsOptions\n) {\n // see couchdb docs 6.2.2:\n // Guide to Views -> Views Collation -> String Ranges\n const options: PouchDB.Core.AllDocsWithinRangeOptions = {\n startkey: prefix,\n endkey: prefix + '\\ufff0',\n include_docs: true,\n };\n\n if (opts) {\n Object.assign(options, opts);\n }\n return db.allDocs<T>(options);\n}\n\nexport function getStartAndEndKeys(key: string): {\n startkey: string;\n endkey: string;\n} {\n return {\n startkey: key,\n endkey: key + '\\ufff0',\n };\n}\n\n//////////////////////\n// Package exports\n//////////////////////\n\nexport * from '../../core/interfaces/contentSource';\nexport * from './adminDB';\nexport * from './classroomDB';\nexport * from './courseAPI';\nexport * from './courseDB';\nexport * from './CourseSyncService';\nexport * from './CouchDBSyncStrategy';\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.mjs","names":["pouch"],"sources":["../../../src/impl/couch/index.ts"],"sourcesContent":["import { ENV } from '@db/factory';\nimport {\n DocType,\n DocTypePrefixes,\n GuestUsername,\n log,\n SkuilderCourseData,\n} from '../../core/types/types-legacy';\nimport fetch from 'cross-fetch';\n// import { getCurrentUser } from '../../stores/useAuthStore';\nimport moment, { Moment } from 'moment';\nimport { logger } from '@db/util/logger';\n\nimport pouch from './pouchdb-setup';\nimport { hexEncode } from '../common/userDBKeys';\n\nimport { ScheduledCard } from '@db/core/types/user';\n\nconst expiryDocID: string = 'GuestAccountExpirationDate';\n\nconst GUEST_LOCAL_DB = `userdb-${GuestUsername}`;\nexport const localUserDB: PouchDB.Database = new pouch(GUEST_LOCAL_DB);\n\nexport { hexEncode };\nconst pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDatabaseConfiguration = {\n fetch(url: string | Request, opts: RequestInit): Promise<Response> {\n opts.credentials = 'include';\n\n return (pouch as any).fetch(url, opts);\n },\n} as PouchDB.Configuration.RemoteDatabaseConfiguration;\n\n/**\n * Creates PouchDB configuration with appropriate authentication method\n * - Uses HTTP Basic Auth when credentials are available (Node.js/MCP)\n * - Falls back to cookie auth for browser environments\n */\nexport function createPouchDBConfig(): PouchDB.Configuration.RemoteDatabaseConfiguration {\n // Check if running in Node.js with explicit credentials\n const hasExplicitCredentials = ENV.COUCHDB_USERNAME && ENV.COUCHDB_PASSWORD;\n const isNodeEnvironment = typeof window === 'undefined';\n \n if (hasExplicitCredentials && isNodeEnvironment) {\n // Use HTTP Basic Auth for Node.js environments (MCP server)\n return {\n fetch(url: string | Request, opts: RequestInit = {}): Promise<Response> {\n const basicAuth = btoa(`${ENV.COUCHDB_USERNAME}:${ENV.COUCHDB_PASSWORD}`);\n const headers = new Headers(opts.headers || {});\n headers.set('Authorization', `Basic ${basicAuth}`);\n \n const newOpts = {\n ...opts,\n headers: headers\n };\n \n return (pouch as any).fetch(url, newOpts);\n }\n } as PouchDB.Configuration.RemoteDatabaseConfiguration;\n }\n \n // Use cookie-based auth for browser environments or when no explicit credentials\n return pouchDBincludeCredentialsConfig;\n}\n\nfunction getCouchDB(dbName: string): PouchDB.Database {\n return new pouch(\n ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,\n createPouchDBConfig()\n );\n}\n\nconst courseDBHandles = new Map<string, PouchDB.Database>();\n\n/**\n * The remote course DB, one handle per URL for the page's lifetime.\n *\n * `skip_setup`: a fresh handle otherwise checks the DB exists (and would try to\n * create it) before its first request: one extra round trip per handle. Course\n * DBs are only created server-side (express), never through this handle.\n */\nexport function getCourseDB(courseID: string): PouchDB.Database {\n const url = ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID;\n let db = courseDBHandles.get(url);\n if (!db) {\n db = new pouch(url, { ...createPouchDBConfig(), skip_setup: true });\n courseDBHandles.set(url, db);\n }\n return db;\n}\n\nexport async function getLatestVersion() {\n try {\n const docs = await getCouchDB('version').allDocs({\n descending: true,\n limit: 1,\n });\n if (docs && docs.rows && docs.rows[0]) {\n return docs.rows[0].id;\n } else {\n return '0.0.0';\n }\n } catch {\n return '-1';\n }\n}\n\n/**\n * Checks the remote couchdb to see if a given username is available\n * @param username The username to be checked\n */\nexport async function usernameIsAvailable(username: string): Promise<boolean> {\n log(`Checking availability of ${username}`);\n \n // Legacy XMLHttpRequest implementation (browser sync)\n // const req = new XMLHttpRequest();\n // const url = ENV.COUCHDB_SERVER_URL + 'userdb-' + hexEncode(username);\n // req.open('HEAD', url, false);\n // req.send();\n // return req.status === 404;\n \n try {\n const url = ENV.COUCHDB_SERVER_URL + 'userdb-' + hexEncode(username);\n const response = await fetch(url, { method: 'HEAD' });\n return response.status === 404;\n } catch (error) {\n log(`Error checking username availability: ${error}`);\n return false;\n }\n}\n\nexport function updateGuestAccountExpirationDate(guestDB: PouchDB.Database<object>) {\n const currentTime = moment.utc();\n const expirationDate: string = currentTime.add(2, 'months').toISOString();\n\n void guestDB\n .get(expiryDocID)\n .then((doc) => {\n return guestDB.put({\n _id: expiryDocID,\n _rev: doc._rev,\n date: expirationDate,\n });\n })\n .catch(() => {\n return guestDB.put({\n _id: expiryDocID,\n date: expirationDate,\n });\n });\n}\n\nexport function getCourseDocs<T extends SkuilderCourseData>(\n courseID: string,\n docIDs: string[],\n options: PouchDB.Core.AllDocsOptions = {}\n) {\n return getCourseDB(courseID).allDocs<T>({\n ...options,\n keys: docIDs,\n });\n}\n\nexport function getCourseDoc<T extends SkuilderCourseData>(\n courseID: string,\n docID: PouchDB.Core.DocumentId,\n options: PouchDB.Core.GetOptions = {}\n): Promise<T> {\n return getCourseDB(courseID).get<T>(docID, options);\n}\n\n/**\n * Returns *all* cards from the parameter courses, in\n * 'qualified' card format (\"courseid-cardid\")\n *\n * @param courseIDs A list of all course_ids to get cards from\n */\nexport async function getRandomCards(courseIDs: string[]) {\n if (courseIDs.length === 0) {\n throw new Error(`getRandomCards:\\n\\tAttempted to get all cards from no courses!`);\n } else {\n const courseResults = await Promise.all(\n courseIDs.map((course) => {\n return getCourseDB(course).find({\n selector: {\n docType: DocType.CARD,\n },\n limit: 1000,\n });\n })\n );\n\n const ret: string[] = [];\n courseResults.forEach((courseCards, index) => {\n courseCards.docs.forEach((doc) => {\n ret.push(`${courseIDs[index]}-${doc._id}`);\n });\n });\n\n return ret;\n }\n}\n\nexport const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';\n\nexport function getCouchUserDB(username: string): PouchDB.Database {\n const guestAccount: boolean = false;\n // console.log(`Getting user db: ${username}`);\n\n const hexName = hexEncode(username);\n const dbName = `userdb-${hexName}`;\n log(`Fetching user database: ${dbName} (${username})`);\n\n // odd construction here the result of a bug in the\n // interaction between pouch, pouch-auth.\n // see: https://github.com/pouchdb-community/pouchdb-authentication/issues/239\n const ret = new pouch(\n ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,\n createPouchDBConfig()\n );\n if (guestAccount) {\n updateGuestAccountExpirationDate(ret);\n }\n\n return ret;\n}\n\nexport function scheduleCardReview(review: {\n user: string;\n course_id: string;\n card_id: PouchDB.Core.DocumentId;\n time: Moment;\n scheduledFor: ScheduledCard['scheduledFor'];\n schedulingAgentId: ScheduledCard['schedulingAgentId'];\n}) {\n const now = moment.utc();\n logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);\n void getCouchUserDB(review.user).put<ScheduledCard>({\n _id: DocTypePrefixes[DocType.SCHEDULED_CARD] + review.time.format(REVIEW_TIME_FORMAT),\n cardId: review.card_id,\n reviewTime: review.time.toISOString(),\n courseId: review.course_id,\n scheduledAt: now.toISOString(),\n scheduledFor: review.scheduledFor,\n schedulingAgentId: review.schedulingAgentId,\n });\n}\n\nexport function filterAllDocsByPrefix<T>(\n db: PouchDB.Database,\n prefix: string,\n opts?: PouchDB.Core.AllDocsOptions\n) {\n // see couchdb docs 6.2.2:\n // Guide to Views -> Views Collation -> String Ranges\n const options: PouchDB.Core.AllDocsWithinRangeOptions = {\n startkey: prefix,\n endkey: prefix + '\\ufff0',\n include_docs: true,\n };\n\n if (opts) {\n Object.assign(options, opts);\n }\n return db.allDocs<T>(options);\n}\n\nexport function getStartAndEndKeys(key: string): {\n startkey: string;\n endkey: string;\n} {\n return {\n startkey: key,\n endkey: key + '\\ufff0',\n };\n}\n\n//////////////////////\n// Package exports\n//////////////////////\n\nexport * from '../../core/interfaces/contentSource';\nexport * from './adminDB';\nexport * from './classroomDB';\nexport * from './courseAPI';\nexport * from './courseDB';\nexport * from './CourseSyncService';\nexport * from './CouchDBSyncStrategy';\n"],"mappings":"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"}
@@ -2,10 +2,17 @@ import "../../_virtual/_rolldown/runtime.mjs";
2
2
  import { logger } from "../../util/logger.mjs";
3
3
  import { Loggable } from "../../util/Loggable.mjs";
4
4
  //#region src/impl/couch/updateQueue.ts
5
+ /**
6
+ * Serialises updates per document. Updates queued while a write is in flight
7
+ * go out together in the next write; each one settles exactly once, with the
8
+ * outcome of the write that carried it, and is never applied again.
9
+ */
5
10
  var UpdateQueue = class extends Loggable {
6
11
  _className = "UpdateQueue";
7
- pendingUpdates = {};
8
- inprogressUpdates = {};
12
+ /** Updates not yet taken by a write, per doc. */
13
+ pending = /* @__PURE__ */ new Map();
14
+ /** Docs with a drain loop running. */
15
+ draining = /* @__PURE__ */ new Set();
9
16
  readDB;
10
17
  writeDB;
11
18
  /**
@@ -21,6 +28,9 @@ var UpdateQueue = class extends Loggable {
21
28
  * **Error Handling Pattern:**
22
29
  * - This method does NOT create documents if they don't exist
23
30
  * - Callers are responsible for handling 404 errors and creating documents
31
+ * - A rejected update is dropped from the queue: a caller that creates the
32
+ * doc after a 404 has already applied its change and must not see it
33
+ * re-applied by a later update to the same doc
24
34
  * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)
25
35
  *
26
36
  * @example
@@ -37,9 +47,16 @@ var UpdateQueue = class extends Loggable {
37
47
  */
38
48
  update(id, update) {
39
49
  logger.debug(`Update requested on doc: ${id}`);
40
- if (this.pendingUpdates[id]) this.pendingUpdates[id].push(update);
41
- else this.pendingUpdates[id] = [update];
42
- return this.applyUpdates(id);
50
+ return new Promise((resolve, reject) => {
51
+ const queue = this.pending.get(id) ?? [];
52
+ queue.push({
53
+ update,
54
+ resolve,
55
+ reject
56
+ });
57
+ this.pending.set(id, queue);
58
+ if (!this.draining.has(id)) this.drain(id);
59
+ });
43
60
  }
44
61
  constructor(readDB, writeDB) {
45
62
  super();
@@ -50,49 +67,55 @@ var UpdateQueue = class extends Loggable {
50
67
  logger.debug(`db info: ${JSON.stringify(i)}`);
51
68
  });
52
69
  }
53
- async applyUpdates(id) {
54
- logger.debug(`Applying updates on doc: ${id}`);
55
- if (this.inprogressUpdates[id]) {
56
- while (this.inprogressUpdates[id]) await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
57
- return this.applyUpdates(id);
58
- } else if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
59
- this.inprogressUpdates[id] = true;
60
- const MAX_RETRIES = 5;
61
- for (let i = 0; i < MAX_RETRIES; i++) try {
62
- let updatedDoc = { ...await this.readDB.get(id) };
63
- const updatesToApply = [...this.pendingUpdates[id]];
64
- for (const update of updatesToApply) if (typeof update === "function") updatedDoc = {
65
- ...updatedDoc,
66
- ...update(updatedDoc)
67
- };
68
- else updatedDoc = {
69
- ...updatedDoc,
70
- ...update
71
- };
72
- await this.writeDB.put(updatedDoc);
73
- this.pendingUpdates[id].splice(0, updatesToApply.length);
74
- if (this.pendingUpdates[id].length === 0) {
75
- this.inprogressUpdates[id] = false;
76
- delete this.inprogressUpdates[id];
77
- } else return this.applyUpdates(id);
78
- return updatedDoc;
79
- } catch (e) {
80
- if (e.name === "conflict" && i < MAX_RETRIES - 1) {
81
- logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
82
- await new Promise((res) => setTimeout(res, 50 * Math.random()));
83
- } else if (e.name === "not_found" && i === 0) {
84
- logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
85
- delete this.inprogressUpdates[id];
86
- throw e;
87
- } else {
88
- delete this.inprogressUpdates[id];
89
- if (this.pendingUpdates[id]) delete this.pendingUpdates[id];
90
- logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
91
- throw e;
70
+ /** Writes the doc's queued updates, batch by batch, until none are left. */
71
+ async drain(id) {
72
+ this.draining.add(id);
73
+ try {
74
+ let batch;
75
+ while ((batch = this.pending.get(id)) && batch.length > 0) {
76
+ this.pending.delete(id);
77
+ try {
78
+ const doc = await this.write(id, batch.map((p) => p.update));
79
+ batch.forEach((p) => p.resolve(doc));
80
+ } catch (e) {
81
+ batch.forEach((p) => p.reject(e));
92
82
  }
93
83
  }
94
- throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
95
- } else throw new Error(`Empty Updates Queue Triggered`);
84
+ } finally {
85
+ this.draining.delete(id);
86
+ }
87
+ }
88
+ /** One read-apply-put of `updates`, retried on conflict against a fresh read. */
89
+ async write(id, updates) {
90
+ logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);
91
+ const MAX_RETRIES = 5;
92
+ for (let i = 0; i < MAX_RETRIES; i++) try {
93
+ let updatedDoc = { ...await this.readDB.get(id) };
94
+ for (const update of updates) updatedDoc = typeof update === "function" ? {
95
+ ...updatedDoc,
96
+ ...update(updatedDoc)
97
+ } : {
98
+ ...updatedDoc,
99
+ ...update
100
+ };
101
+ const res = await this.writeDB.put(updatedDoc);
102
+ return {
103
+ ...updatedDoc,
104
+ _rev: res.rev
105
+ };
106
+ } catch (e) {
107
+ if (e.name === "conflict" && i < MAX_RETRIES - 1) {
108
+ logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
109
+ await new Promise((res) => setTimeout(res, 50 * Math.random()));
110
+ } else if (e.name === "not_found" && i === 0) {
111
+ logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
112
+ throw e;
113
+ } else {
114
+ logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
115
+ throw e;
116
+ }
117
+ }
118
+ throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
96
119
  }
97
120
  };
98
121
  //#endregion
@@ -1 +1 @@
1
- {"version":3,"file":"updateQueue.mjs","names":[],"sources":["../../../src/impl/couch/updateQueue.ts"],"sourcesContent":["import { Loggable } from '../../util/Loggable';\nimport { logger } from '../../util/logger';\n\nexport type Update<T> = Partial<T> | ((x: T) => T);\n\nexport default class UpdateQueue extends Loggable {\n _className: string = 'UpdateQueue';\n private pendingUpdates: {\n [index: string]: Update<unknown>[];\n } = {};\n private inprogressUpdates: {\n [index: string]: boolean;\n } = {};\n\n private readDB: PouchDB.Database; // Database for read operations\n private writeDB: PouchDB.Database; // Database for write operations (local-first)\n\n /**\n * Queues an update for a document and applies it with conflict resolution.\n *\n * @param id - Document ID to update\n * @param update - Partial object or function that transforms the document\n * @returns Promise resolving to the updated document\n *\n * @throws {PouchError} with status 404 if document doesn't exist\n *\n * @remarks\n * **Error Handling Pattern:**\n * - This method does NOT create documents if they don't exist\n * - Callers are responsible for handling 404 errors and creating documents\n * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)\n *\n * @example\n * ```typescript\n * try {\n * await updateQueue.update(docId, (doc) => ({ ...doc, field: newValue }));\n * } catch (e) {\n * if ((e as PouchError).status === 404) {\n * // Create the document with initial values\n * await db.put({ _id: docId, field: newValue, ...initialFields });\n * }\n * }\n * ```\n */\n public update<T extends PouchDB.Core.Document<object>>(\n id: PouchDB.Core.DocumentId,\n update: Update<T>\n ) {\n logger.debug(`Update requested on doc: ${id}`);\n if (this.pendingUpdates[id]) {\n this.pendingUpdates[id].push(update);\n } else {\n this.pendingUpdates[id] = [update];\n }\n return this.applyUpdates<T>(id);\n }\n\n constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {\n super();\n // PouchDB.debug.enable('*');\n this.readDB = readDB;\n this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided\n logger.debug(`UpdateQ initialized...`);\n void this.readDB.info().then((i) => {\n logger.debug(`db info: ${JSON.stringify(i)}`);\n });\n }\n\n private async applyUpdates<T extends PouchDB.Core.Document<object>>(\n id: string\n ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {\n logger.debug(`Applying updates on doc: ${id}`);\n if (this.inprogressUpdates[id]) {\n // Poll instead of recursing to avoid infinite recursion\n while (this.inprogressUpdates[id]) {\n await new Promise(resolve => setTimeout(resolve, Math.random() * 50));\n }\n return this.applyUpdates<T>(id);\n } else {\n if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {\n this.inprogressUpdates[id] = true;\n\n const MAX_RETRIES = 5;\n for (let i = 0; i < MAX_RETRIES; i++) {\n try {\n const doc = await this.readDB.get<T>(id);\n\n // Create a new doc object to apply updates to for this attempt\n let updatedDoc = { ...doc };\n\n // Note: This loop is not fully safe if updates are functions that depend on a specific doc state\n // that might change between retries. But for simple object merges, it's okay.\n const updatesToApply = [...this.pendingUpdates[id]];\n for (const update of updatesToApply) {\n if (typeof update === 'function') {\n updatedDoc = { ...updatedDoc, ...update(updatedDoc) };\n } else {\n updatedDoc = {\n ...updatedDoc,\n ...update,\n };\n }\n }\n\n await this.writeDB.put<T>(updatedDoc);\n\n // Success! Remove the updates we just applied.\n this.pendingUpdates[id].splice(0, updatesToApply.length);\n\n if (this.pendingUpdates[id].length === 0) {\n this.inprogressUpdates[id] = false;\n delete this.inprogressUpdates[id];\n } else {\n // More updates came in, run again.\n return this.applyUpdates<T>(id);\n }\n return updatedDoc as any; // success, exit loop and function\n } catch (e: any) {\n if (e.name === 'conflict' && i < MAX_RETRIES - 1) {\n logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);\n await new Promise((res) => setTimeout(res, 50 * Math.random()));\n // continue to next iteration of the loop\n } else if (e.name === 'not_found' && i === 0) {\n // Document not present - throw to caller for initialization\n logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);\n delete this.inprogressUpdates[id];\n throw e; // Let caller handle\n } else {\n // Max retries reached or a non-conflict error\n delete this.inprogressUpdates[id];\n if (this.pendingUpdates[id]) {\n delete this.pendingUpdates[id];\n }\n logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);\n throw e; // Let caller handle\n }\n }\n }\n // This should be unreachable, but it satisfies the compiler that a value is always returned or an error thrown.\n throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);\n } else {\n throw new Error(`Empty Updates Queue Triggered`);\n }\n }\n }\n}\n"],"mappings":";;;;AAKA,IAAqB,cAArB,cAAyC,SAAS;CAChD,aAAqB;CACrB,iBAEI,EAAE;CACN,oBAEI,EAAE;CAEN;CACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BA,OACE,IACA,QACA;AACA,SAAO,MAAM,4BAA4B,KAAK;AAC9C,MAAI,KAAK,eAAe,IACtB,MAAK,eAAe,IAAI,KAAK,OAAO;MAEpC,MAAK,eAAe,MAAM,CAAC,OAAO;AAEpC,SAAO,KAAK,aAAgB,GAAG;;CAGjC,YAAY,QAA0B,SAA4B;AAChE,SAAO;AAEP,OAAK,SAAS;AACd,OAAK,UAAU,WAAW;AAC1B,SAAO,MAAM,yBAAyB;AACjC,OAAK,OAAO,MAAM,CAAC,MAAM,MAAM;AAClC,UAAO,MAAM,YAAY,KAAK,UAAU,EAAE,GAAG;IAC7C;;CAGJ,MAAc,aACZ,IACiE;AACjE,SAAO,MAAM,4BAA4B,KAAK;AAC9C,MAAI,KAAK,kBAAkB,KAAK;AAE9B,UAAO,KAAK,kBAAkB,IAC5B,OAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,KAAK,QAAQ,GAAG,GAAG,CAAC;AAEvE,UAAO,KAAK,aAAgB,GAAG;aAE3B,KAAK,eAAe,OAAO,KAAK,eAAe,IAAI,SAAS,GAAG;AACjE,QAAK,kBAAkB,MAAM;GAE7B,MAAM,cAAc;AACpB,QAAK,IAAI,IAAI,GAAG,IAAI,aAAa,IAC/B,KAAI;IAIF,IAAI,aAAa,EAAE,GAHP,MAAM,KAAK,OAAO,IAAO,GAAG,EAGb;IAI3B,MAAM,iBAAiB,CAAC,GAAG,KAAK,eAAe,IAAI;AACnD,SAAK,MAAM,UAAU,eACnB,KAAI,OAAO,WAAW,WACpB,cAAa;KAAE,GAAG;KAAY,GAAG,OAAO,WAAW;KAAE;QAErD,cAAa;KACX,GAAG;KACH,GAAG;KACJ;AAIL,UAAM,KAAK,QAAQ,IAAO,WAAW;AAGrC,SAAK,eAAe,IAAI,OAAO,GAAG,eAAe,OAAO;AAExD,QAAI,KAAK,eAAe,IAAI,WAAW,GAAG;AACxC,UAAK,kBAAkB,MAAM;AAC7B,YAAO,KAAK,kBAAkB;UAG9B,QAAO,KAAK,aAAgB,GAAG;AAEjC,WAAO;YACA,GAAQ;AACf,QAAI,EAAE,SAAS,cAAc,IAAI,cAAc,GAAG;AAChD,YAAO,KAAK,8BAA8B,GAAG,WAAW,IAAI,IAAI;AAChE,WAAM,IAAI,SAAS,QAAQ,WAAW,KAAK,KAAK,KAAK,QAAQ,CAAC,CAAC;eAEtD,EAAE,SAAS,eAAe,MAAM,GAAG;AAE5C,YAAO,KAAK,qBAAqB,GAAG,wCAAwC;AAC5E,YAAO,KAAK,kBAAkB;AAC9B,WAAM;WACD;AAEL,YAAO,KAAK,kBAAkB;AAC9B,SAAI,KAAK,eAAe,IACtB,QAAO,KAAK,eAAe;AAE7B,YAAO,MAAM,mCAAmC,EAAE,KAAK,KAAK,UAAU,EAAE,GAAG;AAC3E,WAAM;;;AAKZ,SAAM,IAAI,MAAM,8BAA8B,GAAG,SAAS,YAAY,WAAW;QAEjF,OAAM,IAAI,MAAM,gCAAgC"}
1
+ {"version":3,"file":"updateQueue.mjs","names":[],"sources":["../../../src/impl/couch/updateQueue.ts"],"sourcesContent":["import { Loggable } from '../../util/Loggable';\nimport { logger } from '../../util/logger';\n\nexport type Update<T> = Partial<T> | ((x: T) => T);\n\ntype Applied<T> = T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta;\n\n/** A queued update and the caller waiting on it. */\ninterface Pending {\n update: Update<unknown>;\n resolve: (doc: unknown) => void;\n reject: (e: unknown) => void;\n}\n\n/**\n * Serialises updates per document. Updates queued while a write is in flight\n * go out together in the next write; each one settles exactly once, with the\n * outcome of the write that carried it, and is never applied again.\n */\nexport default class UpdateQueue extends Loggable {\n _className: string = 'UpdateQueue';\n /** Updates not yet taken by a write, per doc. */\n private pending: Map<string, Pending[]> = new Map();\n /** Docs with a drain loop running. */\n private draining: Set<string> = new Set();\n\n private readDB: PouchDB.Database; // Database for read operations\n private writeDB: PouchDB.Database; // Database for write operations (local-first)\n\n /**\n * Queues an update for a document and applies it with conflict resolution.\n *\n * @param id - Document ID to update\n * @param update - Partial object or function that transforms the document\n * @returns Promise resolving to the updated document\n *\n * @throws {PouchError} with status 404 if document doesn't exist\n *\n * @remarks\n * **Error Handling Pattern:**\n * - This method does NOT create documents if they don't exist\n * - Callers are responsible for handling 404 errors and creating documents\n * - A rejected update is dropped from the queue: a caller that creates the\n * doc after a 404 has already applied its change and must not see it\n * re-applied by a later update to the same doc\n * - This design maintains separation of concerns (UpdateQueue handles conflicts, callers handle lifecycle)\n *\n * @example\n * ```typescript\n * try {\n * await updateQueue.update(docId, (doc) => ({ ...doc, field: newValue }));\n * } catch (e) {\n * if ((e as PouchError).status === 404) {\n * // Create the document with initial values\n * await db.put({ _id: docId, field: newValue, ...initialFields });\n * }\n * }\n * ```\n */\n public update<T extends PouchDB.Core.Document<object>>(\n id: PouchDB.Core.DocumentId,\n update: Update<T>\n ): Promise<Applied<T>> {\n logger.debug(`Update requested on doc: ${id}`);\n return new Promise<Applied<T>>((resolve, reject) => {\n const queue = this.pending.get(id) ?? [];\n queue.push({\n update: update as Update<unknown>,\n resolve: resolve as (doc: unknown) => void,\n reject,\n });\n this.pending.set(id, queue);\n if (!this.draining.has(id)) void this.drain(id);\n });\n }\n\n constructor(readDB: PouchDB.Database, writeDB?: PouchDB.Database) {\n super();\n // PouchDB.debug.enable('*');\n this.readDB = readDB;\n this.writeDB = writeDB || readDB; // Default to readDB if writeDB not provided\n logger.debug(`UpdateQ initialized...`);\n void this.readDB.info().then((i) => {\n logger.debug(`db info: ${JSON.stringify(i)}`);\n });\n }\n\n /** Writes the doc's queued updates, batch by batch, until none are left. */\n private async drain(id: string): Promise<void> {\n this.draining.add(id);\n try {\n let batch: Pending[] | undefined;\n while ((batch = this.pending.get(id)) && batch.length > 0) {\n // Take the batch: anything queued from here on goes in the next write.\n this.pending.delete(id);\n try {\n const doc = await this.write(\n id,\n batch.map((p) => p.update)\n );\n batch.forEach((p) => p.resolve(doc));\n } catch (e) {\n batch.forEach((p) => p.reject(e));\n }\n }\n } finally {\n this.draining.delete(id);\n }\n }\n\n /** One read-apply-put of `updates`, retried on conflict against a fresh read. */\n private async write(id: string, updates: Update<unknown>[]): Promise<unknown> {\n logger.debug(`Applying ${updates.length} update(s) on doc: ${id}`);\n const MAX_RETRIES = 5;\n for (let i = 0; i < MAX_RETRIES; i++) {\n try {\n const doc = await this.readDB.get<object>(id);\n\n // Applied to a fresh copy each attempt, so function updates see the\n // doc as read on this attempt.\n let updatedDoc: PouchDB.Core.Document<object> & Partial<PouchDB.Core.RevisionIdMeta> = {\n ...doc,\n };\n for (const update of updates) {\n updatedDoc =\n typeof update === 'function'\n ? { ...updatedDoc, ...(update as (x: unknown) => object)(updatedDoc) }\n : { ...updatedDoc, ...(update as object) };\n }\n\n const res = await this.writeDB.put(updatedDoc);\n return { ...updatedDoc, _rev: res.rev };\n } catch (e: any) {\n if (e.name === 'conflict' && i < MAX_RETRIES - 1) {\n logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);\n await new Promise((res) => setTimeout(res, 50 * Math.random()));\n } else if (e.name === 'not_found' && i === 0) {\n // Document not present - throw to caller for initialization\n logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);\n throw e;\n } else {\n logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);\n throw e;\n }\n }\n }\n // Unreachable: the last attempt returns or throws.\n throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);\n }\n}\n"],"mappings":";;;;;;;;;AAmBA,IAAqB,cAArB,cAAyC,SAAS;CAChD,aAAqB;;CAErB,0BAA0C,IAAI,KAAK;;CAEnD,2BAAgC,IAAI,KAAK;CAEzC;CACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCA,OACE,IACA,QACqB;AACrB,SAAO,MAAM,4BAA4B,KAAK;AAC9C,SAAO,IAAI,SAAqB,SAAS,WAAW;GAClD,MAAM,QAAQ,KAAK,QAAQ,IAAI,GAAG,IAAI,EAAE;AACxC,SAAM,KAAK;IACD;IACC;IACT;IACD,CAAC;AACF,QAAK,QAAQ,IAAI,IAAI,MAAM;AAC3B,OAAI,CAAC,KAAK,SAAS,IAAI,GAAG,CAAO,MAAK,MAAM,GAAG;IAC/C;;CAGJ,YAAY,QAA0B,SAA4B;AAChE,SAAO;AAEP,OAAK,SAAS;AACd,OAAK,UAAU,WAAW;AAC1B,SAAO,MAAM,yBAAyB;AACjC,OAAK,OAAO,MAAM,CAAC,MAAM,MAAM;AAClC,UAAO,MAAM,YAAY,KAAK,UAAU,EAAE,GAAG;IAC7C;;;CAIJ,MAAc,MAAM,IAA2B;AAC7C,OAAK,SAAS,IAAI,GAAG;AACrB,MAAI;GACF,IAAI;AACJ,WAAQ,QAAQ,KAAK,QAAQ,IAAI,GAAG,KAAK,MAAM,SAAS,GAAG;AAEzD,SAAK,QAAQ,OAAO,GAAG;AACvB,QAAI;KACF,MAAM,MAAM,MAAM,KAAK,MACrB,IACA,MAAM,KAAK,MAAM,EAAE,OAAO,CAC3B;AACD,WAAM,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;aAC7B,GAAG;AACV,WAAM,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC;;;YAG7B;AACR,QAAK,SAAS,OAAO,GAAG;;;;CAK5B,MAAc,MAAM,IAAY,SAA8C;AAC5E,SAAO,MAAM,YAAY,QAAQ,OAAO,qBAAqB,KAAK;EAClE,MAAM,cAAc;AACpB,OAAK,IAAI,IAAI,GAAG,IAAI,aAAa,IAC/B,KAAI;GAKF,IAAI,aAAmF,EACrF,GALU,MAAM,KAAK,OAAO,IAAY,GAAG,EAM5C;AACD,QAAK,MAAM,UAAU,QACnB,cACE,OAAO,WAAW,aACd;IAAE,GAAG;IAAY,GAAI,OAAkC,WAAW;IAAE,GACpE;IAAE,GAAG;IAAY,GAAI;IAAmB;GAGhD,MAAM,MAAM,MAAM,KAAK,QAAQ,IAAI,WAAW;AAC9C,UAAO;IAAE,GAAG;IAAY,MAAM,IAAI;IAAK;WAChC,GAAQ;AACf,OAAI,EAAE,SAAS,cAAc,IAAI,cAAc,GAAG;AAChD,WAAO,KAAK,8BAA8B,GAAG,WAAW,IAAI,IAAI;AAChE,UAAM,IAAI,SAAS,QAAQ,WAAW,KAAK,KAAK,KAAK,QAAQ,CAAC,CAAC;cACtD,EAAE,SAAS,eAAe,MAAM,GAAG;AAE5C,WAAO,KAAK,qBAAqB,GAAG,wCAAwC;AAC5E,UAAM;UACD;AACL,WAAO,MAAM,mCAAmC,EAAE,KAAK,KAAK,UAAU,EAAE,GAAG;AAC3E,UAAM;;;AAKZ,QAAM,IAAI,MAAM,8BAA8B,GAAG,SAAS,YAAY,WAAW"}