@vue-skuilder/db 0.1.1

package/src/factory.ts

@@ -0,0 +1,86 @@
+// db/src/factory.ts
+
+import { DataLayerProvider } from './core/interfaces';
+import { logger } from './util/logger';
+
+interface DBEnv {
+  COUCHDB_SERVER_URL: string; // URL of CouchDB server
+  COUCHDB_SERVER_PROTOCOL: string; // Protocol of CouchDB server (http or https)
+  COUCHDB_USERNAME?: string;
+  COUCHDB_PASSWORD?: string;
+}
+
+export const ENV: DBEnv = {
+  COUCHDB_SERVER_PROTOCOL: 'NOT_SET',
+  COUCHDB_SERVER_URL: 'NOT_SET',
+};
+
+// Configuration type for data layer initialization
+export interface DataLayerConfig {
+  type: 'pouch' | 'static';
+  options: {
+    staticContentPath?: string; // Path to static content JSON files
+    localStoragePrefix?: string; // Prefix for IndexedDB storage names
+    COUCHDB_SERVER_URL?: string;
+    COUCHDB_SERVER_PROTOCOL?: string;
+    COUCHDB_USERNAME?: string;
+    COUCHDB_PASSWORD?: string;
+
+    COURSE_IDS?: string[];
+  };
+}
+
+// Singleton instance
+let dataLayerInstance: DataLayerProvider | null = null;
+
+/**
+ * Initialize the data layer with the specified configuration
+ */
+export async function initializeDataLayer(config: DataLayerConfig): Promise<DataLayerProvider> {
+  if (dataLayerInstance) {
+    logger.warn('Data layer already initialized. Returning existing instance.');
+    return dataLayerInstance;
+  }
+
+  if (config.type === 'pouch') {
+    if (!config.options.COUCHDB_SERVER_URL || !config.options.COUCHDB_SERVER_PROTOCOL) {
+      throw new Error('Missing CouchDB server URL or protocol');
+    }
+    ENV.COUCHDB_SERVER_PROTOCOL = config.options.COUCHDB_SERVER_PROTOCOL;
+    ENV.COUCHDB_SERVER_URL = config.options.COUCHDB_SERVER_URL;
+    ENV.COUCHDB_USERNAME = config.options.COUCHDB_USERNAME;
+    ENV.COUCHDB_PASSWORD = config.options.COUCHDB_PASSWORD;
+
+    // Dynamic import to avoid loading both implementations when only one is needed
+    const { PouchDataLayerProvider } = await import('./impl/pouch/PouchDataLayerProvider');
+    dataLayerInstance = new PouchDataLayerProvider(config.options.COURSE_IDS);
+  } else {
+    throw new Error('static data layer not implemented');
+    // const { StaticDataLayerProvider } = await import('./impl/static/StaticDataLayerProvider');
+    // dataLayerInstance = new StaticDataLayerProvider(config.options);
+  }
+
+  await dataLayerInstance.initialize();
+  return dataLayerInstance;
+}
+
+/**
+ * Get the initialized data layer instance
+ * @throws Error if not initialized
+ */
+export function getDataLayer(): DataLayerProvider {
+  if (!dataLayerInstance) {
+    throw new Error('Data layer not initialized. Call initializeDataLayer first.');
+  }
+  return dataLayerInstance;
+}
+
+/**
+ * Reset the data layer (primarily for testing)
+ */
+export async function _resetDataLayer(): Promise<void> {
+  if (dataLayerInstance) {
+    await dataLayerInstance.teardown();
+  }
+  dataLayerInstance = null;
+}

package/src/impl/pouch/PouchDataLayerProvider.ts

@@ -0,0 +1,102 @@
+// db/src/impl/pouch/PouchDataLayerProvider.ts
+
+import {
+  AdminDBInterface,
+  ClassroomDBInterface,
+  CoursesDBInterface,
+  CourseDBInterface,
+  DataLayerProvider,
+  UserDBInterface,
+} from '../../core/interfaces';
+import { logger } from '../../util/logger';
+
+import { getLoggedInUsername } from './auth';
+
+import { AdminDB } from './adminDB';
+import { StudentClassroomDB, TeacherClassroomDB } from './classroomDB';
+import { CourseDB, CoursesDB } from './courseDB';
+
+import { User } from './userDB';
+
+export class PouchDataLayerProvider implements DataLayerProvider {
+  private initialized: boolean = false;
+  private userDB!: UserDBInterface;
+  private currentUsername: string = '';
+
+  // the scoped list of courseIDs for a UI focused on a specific course
+  // or group of courses
+  private _courseIDs: string[] = [];
+
+  constructor(coursIDs?: string[]) {
+    if (coursIDs) {
+      this._courseIDs = coursIDs;
+    }
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // Check if we are in a Node.js environment
+    const isNodeEnvironment =
+      typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+
+    if (isNodeEnvironment) {
+      logger.info(
+        'PouchDataLayerProvider: Running in Node.js environment, skipping user session check and user DB initialization.'
+      );
+    } else {
+      // Assume browser-like environment, proceed with user session logic
+      try {
+        // Get the current username from session
+        this.currentUsername = await getLoggedInUsername();
+        logger.debug(`Current username: ${this.currentUsername}`);
+
+        // Create the user db instance if a username was found
+        if (this.currentUsername) {
+          this.userDB = await User.instance(this.currentUsername);
+        } else {
+          logger.warn('PouchDataLayerProvider: No logged-in username found in session.');
+        }
+      } catch (error) {
+        logger.error(
+          'PouchDataLayerProvider: Error during user session check or user DB initialization:',
+          error
+        );
+      }
+    }
+
+    this.initialized = true;
+  }
+
+  async teardown(): Promise<void> {
+    // Close connections, etc.
+    this.initialized = false;
+  }
+
+  getUserDB(): UserDBInterface {
+    return this.userDB;
+  }
+
+  getCourseDB(courseId: string): CourseDBInterface {
+    return new CourseDB(courseId, async () => this.getUserDB());
+  }
+
+  getCoursesDB(): CoursesDBInterface {
+    return new CoursesDB(this._courseIDs);
+  }
+
+  async getClassroomDB(
+    classId: string,
+    type: 'student' | 'teacher'
+  ): Promise<ClassroomDBInterface> {
+    if (type === 'student') {
+      return await StudentClassroomDB.factory(classId, this.getUserDB());
+    } else {
+      return await TeacherClassroomDB.factory(classId);
+    }
+  }
+
+  getAdminDB(): AdminDBInterface {
+    return new AdminDB();
+  }
+}

package/src/impl/pouch/adminDB.ts

@@ -0,0 +1,91 @@
+import pouch from './pouchdb-setup';
+import { ENV } from '@/factory';
+import {
+  pouchDBincludeCredentialsConfig,
+  getStartAndEndKeys,
+  getCredentialledCourseConfig,
+  updateCredentialledCourseConfig,
+} from '.';
+import { TeacherClassroomDB, ClassroomLookupDB } from './classroomDB';
+import { PouchError } from './types';
+
+import { AdminDBInterface } from '@/core';
+import CourseLookup from './courseLookupDB';
+import { logger } from '@/util/logger';
+
+export class AdminDB implements AdminDBInterface {
+  private usersDB!: PouchDB.Database;
+
+  constructor() {
+    // [ ] execute a check here against credentials, and throw an error
+    //     if the user is not an admin
+    this.usersDB = new pouch(
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + '_users',
+      pouchDBincludeCredentialsConfig
+    );
+  }
+
+  public async getUsers() {
+    return (
+      await this.usersDB.allDocs({
+        include_docs: true,
+        ...getStartAndEndKeys('org.couchdb.user:'),
+      })
+    ).rows.map((r) => r.doc!);
+  }
+
+  public async getCourses() {
+    const list = await CourseLookup.allCourses();
+    return await Promise.all(
+      list.map((c) => {
+        return getCredentialledCourseConfig(c._id);
+      })
+    );
+  }
+  public async removeCourse(id: string) {
+    // remove the indexer
+    const delResp = await CourseLookup.delete(id);
+
+    // set the 'CourseConfig' to 'deleted'
+    const cfg = await getCredentialledCourseConfig(id);
+    cfg.deleted = true;
+    const isDeletedResp = await updateCredentialledCourseConfig(id, cfg);
+
+    return {
+      ok: delResp.ok && isDeletedResp.ok,
+      id: delResp.id,
+      rev: delResp.rev,
+    };
+  }
+
+  public async getClassrooms() {
+    // const joincodes =
+    const uuids = (
+      await ClassroomLookupDB().allDocs<{ uuid: string }>({
+        include_docs: true,
+      })
+    ).rows.map((r) => r.doc!.uuid);
+    logger.debug(uuids.join(', '));
+
+    const promisedCRDbs: TeacherClassroomDB[] = [];
+    for (let i = 0; i < uuids.length; i++) {
+      try {
+        const db = await TeacherClassroomDB.factory(uuids[i]);
+        promisedCRDbs.push(db);
+      } catch (e) {
+        const err = e as PouchError;
+        if (err.error && err.error === 'not_found') {
+          logger.warn(`db ${uuids[i]} not found`);
+        }
+      }
+    }
+
+    const dbs = await Promise.all(promisedCRDbs);
+    return dbs.map((db) => {
+      return {
+        ...db.getConfig(),
+        _id: db._id,
+      };
+    });
+  }
+}

package/src/impl/pouch/auth.ts

@@ -0,0 +1,48 @@
+import { ENV } from '@/factory';
+import { GuestUsername } from '../../core/types/types-legacy';
+import { logger } from '@/util/logger';
+
+interface SessionResponse {
+  info: unknown;
+  ok: boolean;
+  userCtx: {
+    name: string;
+    roles: string[];
+  };
+}
+
+export async function getCurrentSession(): Promise<SessionResponse> {
+  return new Promise((resolve, reject) => {
+    const authXML = new XMLHttpRequest();
+    authXML.withCredentials = true;
+
+    authXML.onerror = (e): void => {
+      reject(new Error('Session check failed:', e));
+    };
+
+    authXML.addEventListener('load', () => {
+      try {
+        const resp: SessionResponse = JSON.parse(authXML.responseText);
+        resolve(resp);
+      } catch (e) {
+        reject(e);
+      }
+    });
+
+    const url = `${ENV.COUCHDB_SERVER_PROTOCOL}://${ENV.COUCHDB_SERVER_URL}_session`;
+    authXML.open('GET', url);
+    authXML.send();
+  });
+}
+
+export async function getLoggedInUsername(): Promise<string> {
+  try {
+    const session = await getCurrentSession();
+    if (session.userCtx.name && session.userCtx.name !== '') {
+      return session.userCtx.name;
+    }
+  } catch (error) {
+    logger.error('Failed to get session:', error);
+  }
+  return GuestUsername;
+}

package/src/impl/pouch/classroomDB.ts

@@ -0,0 +1,306 @@
+import {
+  StudyContentSource,
+  StudySessionNewItem,
+  StudySessionReviewItem,
+} from '@/core/interfaces/contentSource';
+import { ClassroomConfig } from '@vue-skuilder/common';
+import { ENV } from '@/factory';
+import { logger } from '@/util/logger';
+import moment from 'moment';
+import pouch from './pouchdb-setup';
+import {
+  getCourseDB,
+  getStartAndEndKeys,
+  pouchDBincludeCredentialsConfig,
+  REVIEW_TIME_FORMAT,
+} from '.';
+import { CourseDB, getTag } from './courseDB';
+
+import { UserDBInterface } from '@/core';
+import {
+  AssignedContent,
+  AssignedCourse,
+  AssignedTag,
+  StudentClassroomDBInterface,
+  TeacherClassroomDBInterface,
+} from '@/core/interfaces/classroomDB';
+import { ScheduledCard } from '@/core/types/user';
+
+const classroomLookupDBTitle = 'classdb-lookup';
+export const CLASSROOM_CONFIG = 'ClassroomConfig';
+
+export type ClassroomMessage = object;
+
+abstract class ClassroomDBBase {
+  public _id!: string;
+  protected _db!: PouchDB.Database;
+  protected _cfg!: ClassroomConfig;
+  protected _initComplete: boolean = false;
+
+  protected readonly _content_prefix: string = 'content';
+  protected get _content_searchkeys() {
+    return getStartAndEndKeys(this._content_prefix);
+  }
+
+  protected abstract init(): Promise<void>;
+
+  public async getAssignedContent(): Promise<AssignedContent[]> {
+    logger.info(`Getting assigned content...`);
+    // see couchdb docs 6.2.2:
+    //   Guide to Views -> Views Collation -> String Ranges
+    const docRows = await this._db.allDocs<AssignedContent>({
+      startkey: this._content_prefix,
+      endkey: this._content_prefix + `\ufff0`,
+      include_docs: true,
+    });
+
+    const ret = docRows.rows.map((row) => {
+      return row.doc!;
+    });
+    // logger.info(`Assigned content: ${JSON.stringify(ret)}`);
+
+    return ret;
+  }
+
+  protected getContentId(content: AssignedContent): string {
+    if (content.type === 'tag') {
+      return `${this._content_prefix}-${content.courseID}-${content.tagID}`;
+    } else {
+      return `${this._content_prefix}-${content.courseID}`;
+    }
+  }
+
+  public get ready(): boolean {
+    return this._initComplete;
+  }
+  public getConfig(): ClassroomConfig {
+    return this._cfg;
+  }
+}
+
+export class StudentClassroomDB
+  extends ClassroomDBBase
+  implements StudyContentSource, StudentClassroomDBInterface
+{
+  // private readonly _prefix: string = 'content';
+  private userMessages!: PouchDB.Core.Changes<object>;
+  private _user: UserDBInterface;
+
+  private constructor(classID: string, user: UserDBInterface) {
+    super();
+    this._id = classID;
+    this._user = user;
+    // init() is called explicitly in factory method, not in constructor
+  }
+
+  async init(): Promise<void> {
+    const dbName = `classdb-student-${this._id}`;
+    this._db = new pouch(
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
+      pouchDBincludeCredentialsConfig
+    );
+    try {
+      const cfg = await this._db.get<ClassroomConfig>(CLASSROOM_CONFIG);
+      this._cfg = cfg;
+      this.userMessages = this._db.changes({
+        since: 'now',
+        live: true,
+        include_docs: true,
+      });
+      this._initComplete = true;
+      return;
+    } catch (e) {
+      throw new Error(`Error in StudentClassroomDB constructor: ${JSON.stringify(e)}`);
+    }
+  }
+
+  public static async factory(classID: string, user: UserDBInterface): Promise<StudentClassroomDB> {
+    const ret = new StudentClassroomDB(classID, user);
+    await ret.init();
+    return ret;
+  }
+
+  public setChangeFcn(f: (value: unknown) => object): void {
+    // todo: make this into a view request, w/ the user's name attached
+    // todo: requires creating the view doc on classroom create in /express
+    void this.userMessages.on('change', f);
+  }
+
+  public async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    const u = this._user;
+    return (await u.getPendingReviews())
+      .filter((r) => r.scheduledFor === 'classroom' && r.schedulingAgentId === this._id)
+      .map((r) => {
+        return {
+          ...r,
+          qualifiedID: `${r.courseId}-${r.cardId}`,
+          courseID: r.courseId,
+          cardID: r.cardId,
+          contentSourceType: 'classroom',
+          contentSourceID: this._id,
+          reviewID: r._id,
+          status: 'review',
+        };
+      });
+  }
+
+  public async getNewCards(): Promise<StudySessionNewItem[]> {
+    const activeCards = await this._user.getActiveCards();
+    const now = moment.utc();
+    const assigned = await this.getAssignedContent();
+    const due = assigned.filter((c) => now.isAfter(moment.utc(c.activeOn, REVIEW_TIME_FORMAT)));
+
+    logger.info(`Due content: ${JSON.stringify(due)}`);
+
+    let ret: StudySessionNewItem[] = [];
+
+    for (let i = 0; i < due.length; i++) {
+      const content = due[i];
+
+      if (content.type === 'course') {
+        const db = new CourseDB(content.courseID, async () => this._user);
+        ret = ret.concat(await db.getNewCards());
+      } else if (content.type === 'tag') {
+        const tagDoc = await getTag(content.courseID, content.tagID);
+
+        ret = ret.concat(
+          tagDoc.taggedCards.map((c) => {
+            return {
+              courseID: content.courseID,
+              cardID: c,
+              qualifiedID: `${content.courseID}-${c}`,
+              contentSourceType: 'classroom',
+              contentSourceID: this._id,
+              status: 'new',
+            };
+          })
+        );
+      } else if (content.type === 'card') {
+        // returning card docs - not IDs
+        ret.push(await getCourseDB(content.courseID).get(content.cardID));
+      }
+    }
+
+    logger.info(`New Cards from classroom ${this._cfg.name}: ${ret.map((c) => c.qualifiedID)}`);
+
+    return ret.filter((c) => {
+      if (activeCards.some((ac) => c.qualifiedID.includes(ac))) {
+        return false;
+      } else {
+        return true;
+      }
+    });
+  }
+}
+
+/**
+ * Interface for managing a classroom.
+ */
+export class TeacherClassroomDB extends ClassroomDBBase implements TeacherClassroomDBInterface {
+  private _stuDb!: PouchDB.Database;
+
+  private constructor(classID: string) {
+    super();
+    this._id = classID;
+  }
+
+  async init(): Promise<void> {
+    const dbName = `classdb-teacher-${this._id}`;
+    const stuDbName = `classdb-student-${this._id}`;
+    this._db = new pouch(
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
+      pouchDBincludeCredentialsConfig
+    );
+    this._stuDb = new pouch(
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + stuDbName,
+      pouchDBincludeCredentialsConfig
+    );
+    try {
+      return this._db
+        .get<ClassroomConfig>(CLASSROOM_CONFIG)
+        .then((cfg) => {
+          this._cfg = cfg;
+          this._initComplete = true;
+        })
+        .then(() => {
+          return;
+        });
+    } catch (e) {
+      throw new Error(`Error in TeacherClassroomDB constructor: ${JSON.stringify(e)}`);
+    }
+  }
+
+  public static async factory(classID: string): Promise<TeacherClassroomDB> {
+    const ret = new TeacherClassroomDB(classID);
+    await ret.init();
+    return ret;
+  }
+
+  public async removeContent(content: AssignedContent): Promise<void> {
+    const contentID = this.getContentId(content);
+
+    try {
+      const doc = await this._db.get(contentID);
+      await this._db.remove(doc);
+      void this._db.replicate.to(this._stuDb, {
+        doc_ids: [contentID],
+      });
+    } catch (error) {
+      logger.error('Failed to remove content:', contentID, error);
+    }
+  }
+
+  public async assignContent(content: AssignedContent): Promise<boolean> {
+    let put: PouchDB.Core.Response;
+    const id: string = this.getContentId(content);
+
+    if (content.type === 'tag') {
+      put = await this._db.put<AssignedTag>({
+        courseID: content.courseID,
+        tagID: content.tagID,
+        type: 'tag',
+        _id: id,
+        assignedBy: content.assignedBy,
+        assignedOn: moment.utc(),
+        activeOn: content.activeOn || moment.utc(),
+      });
+    } else {
+      put = await this._db.put<AssignedCourse>({
+        courseID: content.courseID,
+        type: 'course',
+        _id: id,
+        assignedBy: content.assignedBy,
+        assignedOn: moment.utc(),
+        activeOn: content.activeOn || moment.utc(),
+      });
+    }
+
+    if (put.ok) {
+      void this._db.replicate.to(this._stuDb, {
+        doc_ids: [id],
+      });
+      return true;
+    } else {
+      return false;
+    }
+  }
+}
+
+export const ClassroomLookupDB: () => PouchDB.Database = () =>
+  new pouch(ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + classroomLookupDBTitle, {
+    skip_setup: true,
+  });
+
+export function getClassroomDB(classID: string, version: 'student' | 'teacher'): PouchDB.Database {
+  const dbName = `classdb-${version}-${classID}`;
+  logger.info(`Retrieving classroom db: ${dbName}`);
+
+  return new pouch(
+    ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
+    pouchDBincludeCredentialsConfig
+  );
+}
+
+export async function getClassroomConfig(classID: string): Promise<ClassroomConfig> {
+  return await getClassroomDB(classID, 'student').get<ClassroomConfig>(CLASSROOM_CONFIG);
+}

package/src/impl/pouch/clientCache.ts

@@ -0,0 +1,19 @@
+// todo: something good here instead
+
+const CLIENT_CACHE: {
+  [k: string]: unknown;
+} = {};
+
+export async function GET_CACHED<K>(k: string, f?: (x: string) => Promise<K>): Promise<K> {
+  if (CLIENT_CACHE[k]) {
+    // console.log('returning a cached item');
+    return CLIENT_CACHE[k] as K;
+  }
+
+  CLIENT_CACHE[k] = f ? await f(k) : await GET_ITEM(k);
+  return GET_CACHED(k);
+}
+
+async function GET_ITEM(k: string): Promise<unknown> {
+  throw new Error(`No implementation found for GET_CACHED(${k})`);
+}