@vue-skuilder/db 0.1.1

package/src/core/interfaces/userDB.ts

@@ -0,0 +1,183 @@
+import {
+  ActivityRecord,
+  CourseRegistration,
+  CourseRegistrationDoc,
+  ScheduledCard,
+} from '@/core/types/user';
+import { CourseElo, Status } from '@vue-skuilder/common';
+import { Moment } from 'moment';
+import { CardHistory, CardRecord } from '../types/types-legacy';
+import { UserConfig } from '../types/user';
+import { DocumentUpdater } from '@/study';
+
+/**
+ * User data and authentication
+ */
+export interface UserDBInterface extends DocumentUpdater {
+  /**
+   * Create a new user account
+   */
+  createAccount(
+    username: string,
+    password: string
+  ): Promise<{
+    status: Status;
+    error: string;
+  }>;
+
+  /**
+   * Log in as a user
+   */
+  login(
+    username: string,
+    password: string
+  ): Promise<{
+    ok: boolean;
+    name?: string;
+    roles?: string[];
+  }>;
+
+  /**
+   * Log out the current user
+   */
+  logout(): Promise<{
+    ok: boolean;
+  }>;
+
+  getUsername(): string;
+
+  isLoggedIn(): boolean;
+
+  /**
+   * Get user configuration
+   */
+  getConfig(): Promise<UserConfig>;
+
+  /**
+   * Update user configuration
+   */
+  setConfig(config: Partial<UserConfig>): Promise<void>;
+
+  /**
+   * Record a user's interaction with a card
+   */
+  putCardRecord<T extends CardRecord>(record: T): Promise<CardHistory<CardRecord>>;
+
+  /**
+   * Get cards that the user has seen
+   */
+  getSeenCards(courseId?: string): Promise<string[]>;
+
+  /**
+   * Get cards that are actively scheduled for review
+   */
+  getActiveCards(): Promise<string[]>;
+
+  /**
+   * Register user for a course
+   */
+  registerForCourse(courseId: string, previewMode?: boolean): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Drop a course registration
+   */
+  dropCourse(courseId: string, dropStatus?: string): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get user's course registrations
+   */
+  getCourseRegistrationsDoc(): Promise<CourseRegistrationDoc>;
+
+  /**
+   * Get the registration doc for a specific course.
+   * @param courseId
+   */
+  getCourseRegDoc(courseId: string): Promise<CourseRegistration>;
+
+  /**
+   * Get user's active courses
+   */
+  getActiveCourses(): Promise<CourseRegistration[]>;
+
+  /**
+   * Get user's pending reviews
+   */
+  getPendingReviews(courseId?: string): Promise<ScheduledCard[]>;
+
+  getActivityRecords(): Promise<ActivityRecord[]>;
+
+  /**
+   * Schedule a card for review
+   */
+  scheduleCardReview(review: {
+    user: string;
+    course_id: string;
+    card_id: string;
+    time: Moment;
+    scheduledFor: 'course' | 'classroom';
+    schedulingAgentId: string;
+  }): Promise<void>;
+
+  /**
+   * Remove a scheduled card review
+   */
+  removeScheduledCardReview(reviewId: string): Promise<void>;
+
+  /**
+   * Register user for a classroom
+   */
+  registerForClassroom(
+    classId: string,
+    registerAs: 'student' | 'teacher' | 'aide' | 'admin'
+  ): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Drop user from classroom
+   */
+  dropFromClassroom(classId: string): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get user's classroom registrations
+   */
+  getUserClassrooms(): Promise<ClassroomRegistrationDoc>;
+
+  /**
+   * Get user's active classes
+   */
+  getActiveClasses(): Promise<string[]>;
+
+  /**
+   * Update user's ELO rating for a course
+   */
+  updateUserElo(courseId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
+
+  getCourseInterface(courseId: string): Promise<UsrCrsDataInterface>;
+}
+
+export interface UserCourseSettings {
+  [setting: string]: string | number | boolean;
+}
+
+export interface UserCourseSetting {
+  key: string;
+  value: string | number | boolean;
+}
+
+// [ ] reconsider here. Should maybe be generic type based on <T extends StudyContentSource> ?
+export interface UsrCrsDataInterface {
+  getScheduledReviewCount(): Promise<number>;
+  getCourseSettings(): Promise<UserCourseSettings>;
+  updateCourseSettings(updates: UserCourseSetting[]): void; // [ ] return a result of some sort?
+  // getRegistrationDoc(): Promise<CourseRegistration>;
+}
+
+export type ClassroomRegistrationDesignation = 'student' | 'teacher' | 'aide' | 'admin';
+
+export interface ClassroomRegistration {
+  classID: string;
+  registeredAs: ClassroomRegistrationDesignation;
+}
+
+export interface ClassroomRegistrationDoc {
+  registrations: ClassroomRegistration[];
+}

package/src/core/navigators/elo.ts

@@ -0,0 +1,76 @@
+import { ScheduledCard } from '../types/user';
+import { CourseDBInterface } from '../interfaces/courseDB';
+import { UserDBInterface } from '../interfaces/userDB';
+import { ContentNavigator } from './index';
+import { CourseElo } from '@vue-skuilder/common';
+import { StudySessionReviewItem, StudySessionNewItem } from '..';
+
+export default class ELONavigator extends ContentNavigator {
+  user: UserDBInterface;
+  course: CourseDBInterface;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface
+    // The ELO strategy is non-parameterized.
+    //
+    // It instead relies on existing meta data from the course and user with respect to
+    //
+    //
+    // strategy?: ContentNavigationStrategyData
+  ) {
+    super();
+    this.user = user;
+    this.course = course;
+  }
+
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    type ratedReview = ScheduledCard & CourseElo;
+
+    const reviews = await this.user.getPendingReviews(this.course.getCourseID()); // todo: this adds a db round trip - should be server side
+    const elo = await this.course.getCardEloData(reviews.map((r) => r.cardId));
+
+    const ratedReviews = reviews.map((r, i) => {
+      const ratedR: ratedReview = {
+        ...r,
+        ...elo[i],
+      };
+      return ratedR;
+    });
+
+    ratedReviews.sort((a, b) => {
+      return a.global.score - b.global.score;
+    });
+
+    return ratedReviews.map((r) => {
+      return {
+        ...r,
+        contentSourceType: 'course',
+        contentSourceID: this.course.getCourseID(),
+        cardID: r.cardId,
+        courseID: r.courseId,
+        qualifiedID: `${r.courseId}-${r.cardId}`,
+        reviewID: r._id,
+        status: 'review',
+      };
+    });
+  }
+
+  async getNewCards(limit: number = 99): Promise<StudySessionNewItem[]> {
+    const activeCards = await this.user.getActiveCards();
+    return (
+      await this.course.getCardsCenteredAtELO({ limit: limit, elo: 'user' }, (c: string) => {
+        if (activeCards.some((ac) => c.includes(ac))) {
+          return false;
+        } else {
+          return true;
+        }
+      })
+    ).map((c) => {
+      return {
+        ...c,
+        status: 'new',
+      };
+    });
+  }
+}

package/src/core/navigators/index.ts

@@ -0,0 +1,57 @@
+import {
+  StudyContentSource,
+  UserDBInterface,
+  CourseDBInterface,
+  StudySessionReviewItem,
+  StudySessionNewItem,
+} from '..';
+import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import { ScheduledCard } from '../types/user';
+import { logger } from '../../util/logger';
+
+export enum Navigators {
+  ELO = 'elo',
+}
+
+/**
+ * A content-navigator provides runtime steering of study sessions.
+ */
+export abstract class ContentNavigator implements StudyContentSource {
+  /**
+   *
+   * @param user
+   * @param strategyData
+   * @returns the runtime object used to steer a study session.
+   */
+  static async create(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategyData: ContentNavigationStrategyData
+  ): Promise<ContentNavigator> {
+    const implementingClass = strategyData.implementingClass;
+    let NavigatorImpl;
+
+    // Try different extension variations
+    const variations = ['', '.js', '.ts'];
+
+    for (const ext of variations) {
+      try {
+        const module = await import(`./${implementingClass}${ext}`);
+        NavigatorImpl = module.default;
+        break; // Break the loop if loading succeeds
+      } catch (e) {
+        // Continue to next variation if this one fails
+        logger.debug(`Failed to load with extension ${ext}:`, e);
+      }
+    }
+
+    if (!NavigatorImpl) {
+      throw new Error(`Could not load navigator implementation for: ${implementingClass}`);
+    }
+
+    return new NavigatorImpl(user, course, strategyData);
+  }
+
+  abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+  abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+}

package/src/core/readme.md

@@ -0,0 +1,9 @@
+# `db/src/core`
+
+Implementation-agnostic type definitions for skuilder data layer.
+
+### Overview
+
+- `types` - structured data types
+- `interfaces` - behaviour contracts for reading and writing data
+- `utils` - generic helper functions for working with these data types and interfaces

package/src/core/types/contentNavigationStrategy.ts

@@ -0,0 +1,21 @@
+import { DocType, SkuilderCourseData } from './types-legacy';
+
+/**
+ *
+ */
+export interface ContentNavigationStrategyData extends SkuilderCourseData {
+  id: string;
+  docType: DocType.NAVIGATION_STRATEGY;
+  name: string;
+  description: string;
+  /**
+   The name of the class that implements the navigation strategy at runtime.
+   */
+  implementingClass: string;
+
+  /**
+   A representation of the strategy's parameterization - to be deserialized
+   by the implementing class's constructor at runtime.
+  */
+  serializedData: string;
+}

package/src/core/types/db.ts

@@ -0,0 +1,7 @@
+import { Status } from '@vue-skuilder/common';
+
+export interface DataLayerResult {
+  status: Status;
+  message: string;
+  id?: string;
+}

package/src/core/types/types-legacy.ts

@@ -0,0 +1,155 @@
+import { CourseElo, Answer, Evaluation } from '@vue-skuilder/common';
+import { Moment } from 'moment';
+import { logger } from '../../util/logger';
+
+export const GuestUsername: string = 'Guest';
+
+export const log = (message: string): void => {
+  logger.log(message);
+};
+
+export enum DocType {
+  DISPLAYABLE_DATA = 'DISPLAYABLE_DATA',
+  CARD = 'CARD',
+  DATASHAPE = 'DATASHAPE',
+  QUESTIONTYPE = 'QUESTION',
+  VIEW = 'VIEW',
+  PEDAGOGY = 'PEDAGOGY',
+  CARDRECORD = 'CARDRECORD',
+  SCHEDULED_CARD = 'SCHEDULED_CARD',
+  TAG = 'TAG',
+  NAVIGATION_STRATEGY = 'NAVIGATION_STRATEGY',
+}
+
+/**
+ * Interface for all data on course content and pedagogy stored
+ * in the c/pouch database.
+ */
+export interface SkuilderCourseData {
+  course: string;
+  docType: DocType;
+}
+
+export interface Tag extends SkuilderCourseData {
+  docType: DocType.TAG;
+  name: string;
+  snippet: string; // 200 char description of the tag
+  wiki: string; // 3000 char md-friendly description
+  taggedCards: PouchDB.Core.DocumentId[];
+}
+export interface TagStub {
+  name: string;
+  snippet: string;
+  count: number; // the number of cards that have this tag applied
+}
+
+export interface CardData extends SkuilderCourseData {
+  docType: DocType.CARD;
+  id_displayable_data: PouchDB.Core.DocumentId[];
+  id_view: PouchDB.Core.DocumentId;
+  elo: CourseElo;
+}
+
+/** A list of populated courses in the DB */
+export interface CourseListData extends PouchDB.Core.Response {
+  courses: string[];
+}
+
+/**
+ * The data used to hydrate viewable components (questions, info, etc)
+ */
+export interface DisplayableData extends SkuilderCourseData {
+  docType: DocType.DISPLAYABLE_DATA;
+  author?: string;
+  id_datashape: PouchDB.Core.DocumentId;
+  data: Field[];
+  _attachments?: { [index: string]: PouchDB.Core.FullAttachment };
+}
+
+export interface Field {
+  data: unknown;
+  name: string;
+}
+
+export interface DataShapeData extends SkuilderCourseData {
+  docType: DocType.DATASHAPE;
+  _id: PouchDB.Core.DocumentId;
+  questionTypes: PouchDB.Core.DocumentId[];
+}
+
+export interface QuestionData extends SkuilderCourseData {
+  docType: DocType.QUESTIONTYPE;
+  _id: PouchDB.Core.DocumentId;
+  viewList: string[];
+  dataShapeList: PouchDB.Core.DocumentId[];
+}
+
+export const cardHistoryPrefix = 'cardH';
+
+export interface CardHistory<T extends CardRecord> {
+  _id: PouchDB.Core.DocumentId;
+  /**
+   * The CouchDB id of the card
+   */
+  cardID: PouchDB.Core.DocumentId;
+
+  /**
+   * The ID of the course
+   */
+  courseID: string;
+
+  /**
+   * The to-date largest interval between successful
+   * card reviews. `0` indicates no successful reviews.
+   */
+  bestInterval: number;
+
+  /**
+   * The number of times that a card has been
+   * failed in review
+   */
+  lapses: number;
+
+  /**
+   * The number of consecutive successful impressions
+   * on this card
+   */
+  streak: number;
+
+  records: T[];
+}
+
+export interface CardRecord {
+  /**
+   * The CouchDB id of the card
+   */
+  cardID: string;
+  /**
+   * The ID of the course
+   */
+  courseID: string;
+  /**
+   * Number of milliseconds that the user spent before dismissing
+   * the card (ie, "I've read this" or "here is my answer")
+   *
+   * //TODO: this (sometimes?) wants to be replaced with a rich
+   *         recording of user activity in working the question
+   */
+  timeSpent: number;
+  /**
+   * The date-time that the card was rendered. timeStamp + timeSpent will give the
+   * time of user submission.
+   */
+  timeStamp: Moment;
+}
+
+export interface QuestionRecord extends CardRecord, Evaluation {
+  userAnswer: Answer;
+  /**
+   * The number of incorrect user submissions prededing this submisstion.
+   *
+   * eg, if a user is asked 7*6=__, submitting 46, 48, 42 will result in three
+   * records being created having 0, 1, and 2 as their recorded 'priorAttempts' values
+   */
+  priorAttemps: number;
+}

package/src/core/types/user.ts

@@ -0,0 +1,70 @@
+import { CourseElo } from '@vue-skuilder/common';
+import { Moment } from 'moment';
+
+export interface UserConfig {
+  darkMode: boolean;
+  likesConfetti: boolean;
+}
+
+export interface ActivityRecord {
+  timeStamp: number | string;
+  [key: string]: any;
+}
+
+export interface CourseRegistration {
+  status?: 'active' | 'dropped' | 'maintenance-mode' | 'preview';
+  courseID: string;
+  admin: boolean;
+  moderator: boolean;
+  user: boolean;
+  settings?: {
+    [setting: string]: string | number | boolean;
+  };
+  elo: number | CourseElo;
+}
+
+interface StudyWeights {
+  [courseID: string]: number;
+}
+
+export interface CourseRegistrationDoc {
+  courses: CourseRegistration[];
+  studyWeight: StudyWeights;
+}
+
+export interface ScheduledCard {
+  _id: PouchDB.Core.DocumentId;
+
+  /**
+   * The docID of the card to be reviewed
+   */
+  cardId: PouchDB.Core.DocumentId;
+  /**
+   * The ID of the course
+   */
+  courseId: string;
+  /**
+   * The time at which the card becomes eligible for review.
+   *
+   * (Should probably be UTC adjusted so that performance is
+   * not wonky across time zones)
+   */
+  reviewTime: Moment;
+
+  /**
+   * The time at which this scheduled event was created.
+   */
+  scheduledAt: Moment;
+
+  /**
+   * Classifying whether this card is scheduled on behalf of a
+   * user-registered course or by as assigned content from a
+   * user-registered classroom
+   */
+  scheduledFor: 'course' | 'classroom';
+
+  /**
+   * The ID of the course or classroom that requested this card
+   */
+  schedulingAgentId: string;
+}

package/src/core/util/index.ts

@@ -0,0 +1,42 @@
+import { cardHistoryPrefix, CardHistory, CardRecord, QuestionRecord } from '../types/types-legacy';
+
+export function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord> {
+  return isQuestionRecord(h.records[0]);
+}
+
+export function isQuestionRecord(c: CardRecord): c is QuestionRecord {
+  return (c as QuestionRecord).userAnswer !== undefined;
+}
+
+export function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId {
+  return `${cardHistoryPrefix}-${courseID}-${cardID}`;
+}
+
+export function parseCardHistoryID(id: string): {
+  courseID: string;
+  cardID: string;
+} {
+  const split = id.split('-');
+  let error: string = '';
+  error += split.length === 3 ? '' : `\n\tgiven ID has incorrect number of '-' characters`;
+  error +=
+    split[0] === cardHistoryPrefix ? '' : `\n\tgiven ID does not start with ${cardHistoryPrefix}`;
+
+  if (split.length === 3 && split[0] === cardHistoryPrefix) {
+    return {
+      courseID: split[1],
+      cardID: split[2],
+    };
+  } else {
+    throw new Error('parseCardHistory Error:' + error);
+  }
+}
+
+interface PouchDBError extends Error {
+  error?: string;
+  reason?: string;
+}
+
+export function docIsDeleted(e: PouchDBError): boolean {
+  return Boolean(e?.error === 'not_found' && e?.reason === 'deleted');
+}