@vue-skuilder/db 0.1.1

package/src/impl/pouch/courseLookupDB.ts

@@ -0,0 +1,135 @@
+import pouch from './pouchdb-setup';
+import { ENV } from '@/factory';
+import { logger } from '../../util/logger';
+
+const courseLookupDBTitle = 'coursedb-lookup';
+
+interface CourseLookupDoc {
+  _id: string;
+  _rev: string;
+  name: string;
+  disambiguator?: string;
+}
+
+logger.debug(`COURSELOOKUP FILE RUNNING`);
+
+/**
+ * A Lookup table of existant courses. Each docID in this DB correspondes to a
+ * course database whose name is `coursedb-{docID}`
+ */
+export default class CourseLookup {
+  // [ ] this db should be read only for public, admin-only for write
+  // Cache for the PouchDB instance
+  private static _dbInstance: PouchDB.Database | null = null;
+
+  /**
+   * Static getter for the PouchDB database instance.
+   * Connects using ENV variables and caches the instance.
+   * Throws an error if required ENV variables are not set.
+   */
+  private static get _db(): PouchDB.Database {
+    // Return cached instance if available
+    if (this._dbInstance) {
+      return this._dbInstance;
+    }
+
+    // --- Check required environment variables ---
+    if (ENV.COUCHDB_SERVER_URL === 'NOT_SET' || !ENV.COUCHDB_SERVER_URL) {
+      throw new Error(
+        'CourseLookup.db: COUCHDB_SERVER_URL is not set. Ensure initializeDataLayer has been called with valid configuration.'
+      );
+    }
+    if (ENV.COUCHDB_SERVER_PROTOCOL === 'NOT_SET' || !ENV.COUCHDB_SERVER_PROTOCOL) {
+      throw new Error(
+        'CourseLookup.db: COUCHDB_SERVER_PROTOCOL is not set. Ensure initializeDataLayer has been called with valid configuration.'
+      );
+    }
+
+    // --- Construct connection options ---
+    const dbUrl = `${ENV.COUCHDB_SERVER_PROTOCOL}://${ENV.COUCHDB_SERVER_URL}/${courseLookupDBTitle}`;
+    const options: PouchDB.Configuration.RemoteDatabaseConfiguration = {
+      skip_setup: true, // Keep the original option
+      // fetch: (url, opts) => { // Optional: Add for debugging network requests
+      //   console.log('PouchDB fetch:', url, opts);
+      //   return pouch.fetch(url, opts);
+      // }
+    };
+
+    // Add authentication if both username and password are provided
+    if (ENV.COUCHDB_USERNAME && ENV.COUCHDB_PASSWORD) {
+      options.auth = {
+        username: ENV.COUCHDB_USERNAME,
+        password: ENV.COUCHDB_PASSWORD,
+      };
+      logger.info(`CourseLookup: Connecting to ${dbUrl} with authentication.`);
+    } else {
+      logger.info(`CourseLookup: Connecting to ${dbUrl} without authentication.`);
+    }
+
+    // --- Create and cache the PouchDB instance ---
+    try {
+      this._dbInstance = new pouch(dbUrl, options);
+      logger.info(`CourseLookup: Database instance created for ${courseLookupDBTitle}.`);
+      return this._dbInstance;
+    } catch (error) {
+      logger.error(`CourseLookup: Failed to create PouchDB instance for ${dbUrl}`, error);
+      // Reset cache attempt on failure
+      this._dbInstance = null;
+      // Re-throw the error to indicate connection failure
+      throw new Error(
+        `CourseLookup: Failed to initialize database connection: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  /**
+   * Adds a new course to the lookup database, and returns the courseID
+   * @param courseName
+   * @returns
+   */
+  static async add(courseName: string): Promise<string> {
+    const resp = await CourseLookup._db.post({
+      name: courseName,
+    });
+
+    return resp.id;
+  }
+
+  /**
+   * Removes a course from the index
+   * @param courseID
+   */
+  static async delete(courseID: string): Promise<PouchDB.Core.Response> {
+    const doc = await CourseLookup._db.get(courseID);
+    return await CourseLookup._db.remove(doc);
+  }
+
+  static async allCourses(): Promise<CourseLookupDoc[]> {
+    const resp = await CourseLookup._db.allDocs<CourseLookupDoc>({
+      include_docs: true,
+    });
+
+    return resp.rows.map((row) => row.doc!);
+  }
+
+  static async updateDisambiguator(
+    courseID: string,
+    disambiguator?: string
+  ): Promise<PouchDB.Core.Response> {
+    const doc = await CourseLookup._db.get<CourseLookupDoc>(courseID);
+    doc.disambiguator = disambiguator;
+    return await CourseLookup._db.put(doc);
+  }
+
+  static async isCourse(courseID: string): Promise<boolean> {
+    try {
+      await CourseLookup._db.get(courseID);
+      return true;
+    } catch (error) {
+      logger.info(`Courselookup failed:`, error);
+      return false;
+    }
+  }
+}

package/src/impl/pouch/index.ts

@@ -0,0 +1,235 @@
+import { ENV } from '@/factory';
+import { DocType, GuestUsername, log, SkuilderCourseData } from '../../core/types/types-legacy';
+// import { getCurrentUser } from '../../stores/useAuthStore';
+import moment, { Moment } from 'moment';
+import { logger } from '@/util/logger';
+
+import pouch from './pouchdb-setup';
+
+import { ScheduledCard } from '@/core/types/user';
+import process from 'process';
+import { getUserDB } from './userDB';
+
+const isBrowser = typeof window !== 'undefined';
+
+if (isBrowser) {
+  (window as any).process = process; // required as a fix for pouchdb - see #18
+}
+
+const expiryDocID: string = 'GuestAccountExpirationDate';
+
+const GUEST_LOCAL_DB = `userdb-${GuestUsername}`;
+export const localUserDB: PouchDB.Database = new pouch(GUEST_LOCAL_DB);
+
+export function hexEncode(str: string): string {
+  let hex: string;
+  let returnStr: string = '';
+
+  for (let i = 0; i < str.length; i++) {
+    hex = str.charCodeAt(i).toString(16);
+    returnStr += ('000' + hex).slice(3);
+  }
+
+  return returnStr;
+}
+export const pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDatabaseConfiguration = {
+  fetch(url: string | Request, opts: RequestInit): Promise<Response> {
+    opts.credentials = 'include';
+
+    return (pouch as any).fetch(url, opts);
+  },
+} as PouchDB.Configuration.RemoteDatabaseConfiguration;
+
+function getCouchDB(dbName: string): PouchDB.Database {
+  return new pouch(
+    ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
+    pouchDBincludeCredentialsConfig
+  );
+}
+
+export function getCourseDB(courseID: string): PouchDB.Database {
+  // todo: keep a cache of opened courseDBs? need to benchmark this somehow
+  return new pouch(
+    ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID,
+    pouchDBincludeCredentialsConfig
+  );
+}
+
+export async function getLatestVersion() {
+  try {
+    const docs = await getCouchDB('version').allDocs({
+      descending: true,
+      limit: 1,
+    });
+    if (docs && docs.rows && docs.rows[0]) {
+      return docs.rows[0].id;
+    } else {
+      return '0.0.0';
+    }
+  } catch {
+    return '-1';
+  }
+}
+
+/**
+ * Checks the remote couchdb to see if a given username is available
+ * @param username The username to be checked
+ */
+export async function usernameIsAvailable(username: string): Promise<boolean> {
+  log(`Checking availability of ${username}`);
+  const req = new XMLHttpRequest();
+  const url = ENV.COUCHDB_SERVER_URL + 'userdb-' + hexEncode(username);
+  req.open('HEAD', url, false);
+  req.send();
+  return req.status === 404;
+}
+
+export function updateGuestAccountExpirationDate(guestDB: PouchDB.Database<object>) {
+  const currentTime = moment.utc();
+  const expirationDate: string = currentTime.add(2, 'months').toISOString();
+
+  void guestDB
+    .get(expiryDocID)
+    .then((doc) => {
+      return guestDB.put({
+        _id: expiryDocID,
+        _rev: doc._rev,
+        date: expirationDate,
+      });
+    })
+    .catch(() => {
+      return guestDB.put({
+        _id: expiryDocID,
+        date: expirationDate,
+      });
+    });
+}
+
+export function getCourseDocs<T extends SkuilderCourseData>(
+  courseID: string,
+  docIDs: string[],
+  options: PouchDB.Core.AllDocsOptions = {}
+) {
+  return getCourseDB(courseID).allDocs<T>({
+    ...options,
+    keys: docIDs,
+  });
+}
+
+export function getCourseDoc<T extends SkuilderCourseData>(
+  courseID: string,
+  docID: PouchDB.Core.DocumentId,
+  options: PouchDB.Core.GetOptions = {}
+): Promise<T> {
+  return getCourseDB(courseID).get<T>(docID, options);
+}
+
+/**
+ * Returns *all* cards from the parameter courses, in
+ * 'qualified' card format ("courseid-cardid")
+ *
+ * @param courseIDs A list of all course_ids to get cards from
+ */
+export async function getRandomCards(courseIDs: string[]) {
+  if (courseIDs.length === 0) {
+    throw new Error(`getRandomCards:\n\tAttempted to get all cards from no courses!`);
+  } else {
+    const courseResults = await Promise.all(
+      courseIDs.map((course) => {
+        return getCourseDB(course).find({
+          selector: {
+            docType: DocType.CARD,
+          },
+          limit: 1000,
+        });
+      })
+    );
+
+    const ret: string[] = [];
+    courseResults.forEach((courseCards, index) => {
+      courseCards.docs.forEach((doc) => {
+        ret.push(`${courseIDs[index]}-${doc._id}`);
+      });
+    });
+
+    return ret;
+  }
+}
+
+export const REVIEW_PREFIX: string = 'card_review_';
+export const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';
+
+export function scheduleCardReview(review: {
+  user: string;
+  course_id: string;
+  card_id: PouchDB.Core.DocumentId;
+  time: Moment;
+  scheduledFor: ScheduledCard['scheduledFor'];
+  schedulingAgentId: ScheduledCard['schedulingAgentId'];
+}) {
+  const now = moment.utc();
+  logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);
+  void getUserDB(review.user).put<ScheduledCard>({
+    _id: REVIEW_PREFIX + review.time.format(REVIEW_TIME_FORMAT),
+    cardId: review.card_id,
+    reviewTime: review.time,
+    courseId: review.course_id,
+    scheduledAt: now,
+    scheduledFor: review.scheduledFor,
+    schedulingAgentId: review.schedulingAgentId,
+  });
+}
+
+export async function removeScheduledCardReview(user: string, reviewDocID: string) {
+  const db = getUserDB(user);
+  const reviewDoc = await db.get(reviewDocID);
+  db.remove(reviewDoc)
+    .then((res) => {
+      if (res.ok) {
+        log(`Removed Review Doc: ${reviewDocID}`);
+      }
+    })
+    .catch((err) => {
+      log(`Failed to remove Review Doc: ${reviewDocID},\n${JSON.stringify(err)}`);
+    });
+}
+
+export function filterAllDocsByPrefix<T>(
+  db: PouchDB.Database,
+  prefix: string,
+  opts?: PouchDB.Core.AllDocsOptions
+) {
+  // see couchdb docs 6.2.2:
+  //   Guide to Views -> Views Collation -> String Ranges
+  const options: PouchDB.Core.AllDocsWithinRangeOptions = {
+    startkey: prefix,
+    endkey: prefix + '\ufff0',
+    include_docs: true,
+  };
+
+  if (opts) {
+    Object.assign(options, opts);
+  }
+  return db.allDocs<T>(options);
+}
+
+export function getStartAndEndKeys(key: string): {
+  startkey: string;
+  endkey: string;
+} {
+  return {
+    startkey: key,
+    endkey: key + '\ufff0',
+  };
+}
+
+//////////////////////
+// Package exports
+//////////////////////
+
+export * from '../../core/interfaces/contentSource';
+export * from './adminDB';
+export * from './classroomDB';
+export * from './courseAPI';
+export * from './courseDB';
+export * from './userDB';

package/src/impl/pouch/pouchdb-setup.ts

@@ -0,0 +1,16 @@
+import PouchDB from 'pouchdb';
+import PouchDBFind from 'pouchdb-find';
+import PouchDBAuth from '@nilock2/pouchdb-authentication';
+
+// Register plugins
+PouchDB.plugin(PouchDBFind);
+PouchDB.plugin(PouchDBAuth);
+
+// Configure PouchDB globally
+PouchDB.defaults({
+  ajax: {
+    timeout: 60000,
+  },
+});
+
+export default PouchDB;

package/src/impl/pouch/types.ts

@@ -0,0 +1,7 @@
+export interface PouchError {
+  status?: number;
+  name?: string;
+  reason?: string;
+  message?: string;
+  error?: string;
+}

package/src/impl/pouch/updateQueue.ts

@@ -0,0 +1,89 @@
+import { Loggable } from '../../util/Loggable';
+import { logger } from '../../util/logger';
+
+export type Update<T> = Partial<T> | ((x: T) => T);
+
+export default class UpdateQueue extends Loggable {
+  _className: string = 'UpdateQueue';
+  private pendingUpdates: {
+    [index: string]: Update<unknown>[];
+  } = {};
+  private inprogressUpdates: {
+    [index: string]: boolean;
+  } = {};
+
+  private db: PouchDB.Database;
+
+  public update<T extends PouchDB.Core.Document<object>>(
+    id: PouchDB.Core.DocumentId,
+    update: Update<T>
+  ) {
+    logger.debug(`Update requested on doc: ${id}`);
+    if (this.pendingUpdates[id]) {
+      this.pendingUpdates[id].push(update);
+    } else {
+      this.pendingUpdates[id] = [update];
+    }
+    return this.applyUpdates<T>(id);
+  }
+
+  constructor(db: PouchDB.Database) {
+    super();
+    // PouchDB.debug.enable('*');
+    this.db = db;
+    logger.debug(`UpdateQ initialized...`);
+    void this.db.info().then((i) => {
+      logger.debug(`db info: ${JSON.stringify(i)}`);
+    });
+  }
+
+  private async applyUpdates<T extends PouchDB.Core.Document<object>>(id: string): Promise<T> {
+    logger.debug(`Applying updates on doc: ${id}`);
+    if (this.inprogressUpdates[id]) {
+      // console.log(`Updates in progress...`);
+      await this.db.info(); // stall for a round trip
+      // console.log(`Retrying...`);
+      return this.applyUpdates<T>(id);
+    } else {
+      if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
+        this.inprogressUpdates[id] = true;
+
+        try {
+          let doc = await this.db.get<T>(id);
+          logger.debug(`Retrieved doc: ${id}`);
+          while (this.pendingUpdates[id].length !== 0) {
+            const update = this.pendingUpdates[id].splice(0, 1)[0];
+            if (typeof update === 'function') {
+              doc = { ...doc, ...update(doc) };
+            } else {
+              doc = {
+                ...doc,
+                ...update,
+              };
+            }
+          }
+          // for (const k in doc) {
+          //   console.log(`${k}: ${typeof k}`);
+          // }
+          // console.log(`Applied updates to doc: ${JSON.stringify(doc)}`);
+          await this.db.put<T>(doc);
+          logger.debug(`Put doc: ${id}`);
+
+          if (this.pendingUpdates[id].length === 0) {
+            this.inprogressUpdates[id] = false;
+            delete this.inprogressUpdates[id];
+          } else {
+            return this.applyUpdates<T>(id);
+          }
+          return doc;
+        } catch (e) {
+          delete this.inprogressUpdates[id];
+          logger.error(`Error on attemped update: ${JSON.stringify(e)}`);
+          throw e;
+        }
+      } else {
+        throw new Error(`Empty Updates Queue Triggered`);
+      }
+    }
+  }
+}

package/src/impl/pouch/user-course-relDB.ts

@@ -0,0 +1,73 @@
+import { ScheduledCard, UserCourseSetting, UserCourseSettings, UsrCrsDataInterface } from '@/core';
+import moment, { Moment } from 'moment';
+import { getStartAndEndKeys, REVIEW_PREFIX, REVIEW_TIME_FORMAT } from '.';
+import { CourseDB } from './courseDB';
+import { User } from './userDB';
+import { logger } from '../../util/logger';
+
+export class UsrCrsData implements UsrCrsDataInterface {
+  private user: User;
+  private course: CourseDB;
+  private _courseId: string;
+
+  constructor(user: User, courseId: string) {
+    this.user = user;
+    this.course = new CourseDB(courseId, async () => this.user);
+    this._courseId = courseId;
+  }
+
+  public async getReviewsForcast(daysCount: number) {
+    const time = moment.utc().add(daysCount, 'days');
+    return this.getReviewstoDate(time);
+  }
+
+  public async getPendingReviews() {
+    const now = moment.utc();
+    return this.getReviewstoDate(now);
+  }
+
+  public async getScheduledReviewCount(): Promise<number> {
+    return (await this.getPendingReviews()).length;
+  }
+
+  public async getCourseSettings(): Promise<UserCourseSettings> {
+    const regDoc = await this.user.getCourseRegistrationsDoc();
+    const crsDoc = regDoc.courses.find((c) => c.courseID === this._courseId);
+
+    if (crsDoc && crsDoc.settings) {
+      return crsDoc.settings;
+    } else {
+      logger.warn(`no settings found during lookup on course ${this._courseId}`);
+      return {};
+    }
+  }
+  public updateCourseSettings(updates: UserCourseSetting[]): void {
+    void this.user.updateCourseSettings(this._courseId, updates);
+  }
+
+  private async getReviewstoDate(targetDate: Moment) {
+    const keys = getStartAndEndKeys(REVIEW_PREFIX);
+
+    const reviews = await this.user.remote().allDocs<ScheduledCard>({
+      startkey: keys.startkey,
+      endkey: keys.endkey,
+      include_docs: true,
+    });
+
+    logger.debug(
+      `Fetching ${this.user.getUsername()}'s scheduled reviews for course ${this._courseId}.`
+    );
+    return reviews.rows
+      .filter((r) => {
+        if (r.id.startsWith(REVIEW_PREFIX)) {
+          const date = moment.utc(r.id.substr(REVIEW_PREFIX.length), REVIEW_TIME_FORMAT);
+          if (targetDate.isAfter(date)) {
+            if (this._courseId === undefined || r.doc!.courseId === this._courseId) {
+              return true;
+            }
+          }
+        }
+      })
+      .map((r) => r.doc!);
+  }
+}