@vue-skuilder/db 0.1.1

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './core';
+
+export { default as CourseLookup } from './impl/pouch/courseLookupDB';
+
+export * from './study';
+
+export * from './util';
+export * from './factory';

package/src/study/SessionController.ts

@@ -0,0 +1,401 @@
+import {
+  isReview,
+  StudyContentSource,
+  StudySessionFailedItem,
+  StudySessionItem,
+  StudySessionNewItem,
+  StudySessionReviewItem,
+} from '@/impl/pouch';
+
+import { CardRecord } from '@/core';
+import { Loggable } from '@/util';
+import { ScheduledCard } from '@/core/types/user';
+
+function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export interface StudySessionRecord {
+  card: {
+    course_id: string;
+    card_id: string;
+    card_elo: number;
+  };
+  item: StudySessionItem;
+  records: CardRecord[];
+}
+
+class ItemQueue<T extends StudySessionItem> {
+  private q: T[] = [];
+  private seenCardIds: string[] = [];
+  private _dequeueCount: number = 0;
+  public get dequeueCount(): number {
+    return this._dequeueCount;
+  }
+
+  public add(item: T) {
+    if (this.seenCardIds.find((d) => d === item.cardID)) {
+      return; // do not re-add a card to the same queue
+    }
+
+    this.seenCardIds.push(item.cardID);
+    this.q.push(item);
+  }
+  public addAll(items: T[]) {
+    items.forEach((i) => this.add(i));
+  }
+  public get length() {
+    return this.q.length;
+  }
+  public peek(index: number): T {
+    return this.q[index];
+  }
+
+  public dequeue(): T | null {
+    if (this.q.length !== 0) {
+      this._dequeueCount++;
+      return this.q.splice(0, 1)[0];
+    } else {
+      return null;
+    }
+  }
+
+  public get toString(): string {
+    return (
+      `${typeof this.q[0]}:\n` + this.q.map((i) => `\t${i.qualifiedID}: ${i.status}`).join('\n')
+    );
+  }
+}
+
+export class SessionController extends Loggable {
+  _className = 'SessionController';
+  private sources: StudyContentSource[];
+  private _sessionRecord: StudySessionRecord[] = [];
+  public set sessionRecord(r: StudySessionRecord[]) {
+    this._sessionRecord = r;
+  }
+
+  private reviewQ: ItemQueue<StudySessionReviewItem> = new ItemQueue<StudySessionReviewItem>();
+  private newQ: ItemQueue<StudySessionNewItem> = new ItemQueue<StudySessionNewItem>();
+  private failedQ: ItemQueue<StudySessionFailedItem> = new ItemQueue<StudySessionFailedItem>();
+  private _currentCard: StudySessionItem | null = null;
+  /**
+   * Indicates whether the session has been initialized - eg, the
+   * queues have been populated.
+   */
+  private _isInitialized: boolean = false;
+
+  private startTime: Date;
+  private endTime: Date;
+  private _secondsRemaining: number;
+  public get secondsRemaining(): number {
+    return this._secondsRemaining;
+  }
+  public get report(): string {
+    return `${this.reviewQ.dequeueCount} reviews, ${this.newQ.dequeueCount} new cards`;
+  }
+  public get detailedReport(): string {
+    return this.newQ.toString + '\n' + this.reviewQ.toString + '\n' + this.failedQ.toString;
+  }
+  // @ts-expect-error NodeJS.Timeout type not available in browser context
+  private _intervalHandle: NodeJS.Timeout;
+
+  /**
+   *
+   */
+  constructor(sources: StudyContentSource[], time: number) {
+    super();
+
+    this.sources = sources;
+    this.startTime = new Date();
+    this._secondsRemaining = time;
+    this.endTime = new Date(this.startTime.valueOf() + 1000 * this._secondsRemaining);
+
+    this.log(`Session constructed:
+    startTime: ${this.startTime}
+    endTime: ${this.endTime}`);
+  }
+
+  private tick() {
+    this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1000);
+    // this.log(this.secondsRemaining);
+
+    if (this._secondsRemaining === 0) {
+      clearInterval(this._intervalHandle);
+    }
+  }
+
+  /**
+   * Returns a rough, erring toward conservative, guess at
+   * the amount of time the failed cards queue will require
+   * to clean up.
+   *
+   * (seconds)
+   */
+  private estimateCleanupTime(): number {
+    let time: number = 0;
+    for (let i = 0; i < this.failedQ.length; i++) {
+      const c = this.failedQ.peek(i);
+      // this.log(`Failed card ${c.qualifiedID} found`)
+
+      const record = this._sessionRecord.find((r) => r.item.cardID === c.cardID);
+      let cardTime = 0;
+
+      if (record) {
+        // this.log(`Card Record Found...`);
+        for (let j = 0; j < record.records.length; j++) {
+          cardTime += record.records[j].timeSpent;
+        }
+        cardTime = cardTime / record.records.length;
+        time += cardTime;
+      }
+    }
+
+    const ret: number = time / 1000;
+    this.log(`Failed card cleanup estimate: ${Math.round(ret)}`);
+    return ret;
+  }
+
+  /**
+   * Extremely rough, conservative, estimate of amound of time to complete
+   * all scheduled reviews
+   */
+  private estimateReviewTime(): number {
+    const ret = 5 * this.reviewQ.length;
+    this.log(`Review card time estimate: ${ret}`);
+    return ret;
+  }
+
+  public async prepareSession() {
+    try {
+      await Promise.all([this.getScheduledReviews(), this.getNewCards()]);
+    } catch (e) {
+      this.error('Error preparing study session:', e);
+    }
+
+    this._isInitialized = true;
+
+    this._intervalHandle = setInterval(() => {
+      this.tick();
+    }, 1000);
+  }
+
+  public addTime(seconds: number) {
+    this.endTime = new Date(this.endTime.valueOf() + 1000 * seconds);
+  }
+
+  public get failedCount(): number {
+    return this.failedQ.length;
+  }
+
+  public toString() {
+    return `Session: ${this.reviewQ.length} Reviews, ${this.newQ.length} New, ${this.failedQ.length} failed`;
+  }
+  public reportString() {
+    return `${this.reviewQ.dequeueCount} Reviews, ${this.newQ.dequeueCount} New, ${this.failedQ.dequeueCount} failed`;
+  }
+
+  private async getScheduledReviews() {
+    const reviews = await Promise.all(
+      this.sources.map((c) =>
+        c.getPendingReviews().catch((error) => {
+          this.error(`Failed to get reviews for source ${c}:`, error);
+          return [];
+        })
+      )
+    );
+
+    const dueCards: (StudySessionReviewItem & ScheduledCard)[] = [];
+
+    while (reviews.length != 0 && reviews.some((r) => r.length > 0)) {
+      // pick a random review source
+      const index = randomInt(0, reviews.length - 1);
+      const source = reviews[index];
+
+      if (source.length === 0) {
+        reviews.splice(index, 1);
+        continue;
+      } else {
+        dueCards.push(source.shift()!);
+      }
+    }
+
+    let report = 'Review session created with:\n';
+    for (let i = 0; i < dueCards.length; i++) {
+      const card = dueCards[i];
+      this.reviewQ.add(card);
+      report += `\t${card.qualifiedID}}\n`;
+    }
+    this.log(report);
+  }
+
+  private async getNewCards(n: number = 10) {
+    const perCourse = Math.ceil(n / this.sources.length);
+    const newContent = await Promise.all(this.sources.map((c) => c.getNewCards(perCourse)));
+
+    // [ ] is this a noop?
+    newContent.forEach((newContentFromSource) => {
+      newContentFromSource.filter((c) => {
+        return this._sessionRecord.find((record) => record.card.card_id === c.cardID) === undefined;
+      });
+    });
+
+    while (n > 0 && newContent.some((nc) => nc.length > 0)) {
+      for (let i = 0; i < newContent.length; i++) {
+        if (newContent[i].length > 0) {
+          const item = newContent[i].splice(0, 1)[0];
+          this.log(`Adding new card: ${item.qualifiedID}`);
+          this.newQ.add(item);
+          n--;
+        }
+      }
+    }
+  }
+
+  private nextNewCard(): StudySessionNewItem | null {
+    const item = this.newQ.dequeue();
+
+    // queue some more content if we are getting low
+    if (this._isInitialized && this.newQ.length < 5) {
+      void this.getNewCards();
+    }
+
+    return item;
+  }
+
+  public nextCard(
+    action:
+      | 'dismiss-success'
+      | 'dismiss-failed'
+      | 'marked-failed'
+      | 'dismiss-error' = 'dismiss-success'
+  ): StudySessionItem | null {
+    // dismiss (or sort to failedQ) the current card
+    this.dismissCurrentCard(action);
+
+    const choice = Math.random();
+    let newBound: number = 0.1;
+    let reviewBound: number = 0.75;
+
+    if (this.reviewQ.length === 0 && this.failedQ.length === 0 && this.newQ.length === 0) {
+      // all queues empty - session is over (and course is complete?)
+      this._currentCard = null;
+      return this._currentCard;
+    }
+
+    if (this._secondsRemaining < 2 && this.failedQ.length === 0) {
+      // session is over!
+      this._currentCard = null;
+      return this._currentCard;
+    }
+
+    // supply new cards at start of session
+    if (this.newQ.dequeueCount < this.sources.length && this.newQ.length) {
+      this._currentCard = this.nextNewCard();
+      return this._currentCard;
+    }
+
+    const cleanupTime = this.estimateCleanupTime();
+    const reviewTime = this.estimateReviewTime();
+    const availableTime = this._secondsRemaining - (cleanupTime + reviewTime);
+
+    // if time-remaing vs (reviewQ + failureQ) looks good,
+    // lean toward newQ
+    if (availableTime > 20) {
+      newBound = 0.5;
+      reviewBound = 0.9;
+    }
+    // else if time-remaining vs failureQ looks good,
+    // lean toward reviewQ
+    else if (this._secondsRemaining - cleanupTime > 20) {
+      newBound = 0.05;
+      reviewBound = 0.9;
+    }
+    // else (time-remaining vs failureQ looks bad!)
+    // lean heavily toward failureQ
+    else {
+      newBound = 0.01;
+      reviewBound = 0.1;
+    }
+
+    // prevent (unless no other option available) re-display of
+    // most recent card
+    if (this.failedQ.length === 1 && action === 'marked-failed') {
+      reviewBound = 1;
+    }
+
+    // exclude possibility of drawing from empty queues
+    if (this.failedQ.length === 0) {
+      reviewBound = 1;
+    }
+    if (this.reviewQ.length === 0) {
+      newBound = reviewBound;
+    }
+
+    if (choice < newBound && this.newQ.length) {
+      this._currentCard = this.nextNewCard();
+    } else if (choice < reviewBound && this.reviewQ.length) {
+      this._currentCard = this.reviewQ.dequeue();
+    } else if (this.failedQ.length) {
+      this._currentCard = this.failedQ.dequeue();
+    } else {
+      this.log(`No more cards available for the session!`);
+      this._currentCard = null;
+    }
+
+    return this._currentCard;
+  }
+
+  private dismissCurrentCard(
+    action:
+      | 'dismiss-success'
+      | 'dismiss-failed'
+      | 'marked-failed'
+      | 'dismiss-error' = 'dismiss-success'
+  ) {
+    if (this._currentCard) {
+      // this.log(`Running dismissCurrentCard on ${this._currentCard!.qualifiedID}`);
+      // if (action.includes('dismiss')) {
+      //   if (this._currentCard.status === 'review' ||
+      //     this._currentCard.status === 'failed-review') {
+      //     removeScheduledCardReview(this.user.getUsername(),
+      //       (this._currentCard as StudySessionReviewItem).reviewID);
+      //     this.log(`Dismissed review card: ${this._currentCard.qualifiedID}`)
+      //   }
+      // }
+
+      if (action === 'dismiss-success') {
+        // schedule a review - currently done in Study.vue
+      } else if (action === 'marked-failed') {
+        let failedItem: StudySessionFailedItem;
+
+        if (isReview(this._currentCard)) {
+          failedItem = {
+            cardID: this._currentCard.cardID,
+            courseID: this._currentCard.courseID,
+            qualifiedID: this._currentCard.qualifiedID,
+            contentSourceID: this._currentCard.contentSourceID,
+            contentSourceType: this._currentCard.contentSourceType,
+            status: 'failed-review',
+            reviewID: this._currentCard.reviewID,
+          };
+        } else {
+          failedItem = {
+            cardID: this._currentCard.cardID,
+            courseID: this._currentCard.courseID,
+            qualifiedID: this._currentCard.qualifiedID,
+            contentSourceID: this._currentCard.contentSourceID,
+            contentSourceType: this._currentCard.contentSourceType,
+            status: 'failed-new',
+          };
+        }
+
+        this.failedQ.add(failedItem);
+      } else if (action === 'dismiss-error') {
+        // some error logging?
+      } else if (action === 'dismiss-failed') {
+        // handled by Study.vue
+      }
+    }
+  }
+}

package/src/study/SpacedRepetition.ts

@@ -0,0 +1,128 @@
+import { CardHistory, CardRecord, QuestionRecord } from '@/core/types/types-legacy';
+import { areQuestionRecords } from '@/core/util';
+import { Update } from '@/impl/pouch/updateQueue';
+import moment from 'moment';
+import { logger } from '../util/logger';
+
+type Moment = moment.Moment;
+const duration = moment.duration;
+
+export interface DocumentUpdater {
+  update<T extends PouchDB.Core.Document<object>>(id: string, update: Update<T>): Promise<T>;
+}
+
+/**
+ * Returns the minimum number of seconds that should pass before a
+ * card is redisplayed for review / practice.
+ *
+ * @param cardHistory The user's history working with the given card
+ */
+export function newInterval(user: DocumentUpdater, cardHistory: CardHistory<CardRecord>): number {
+  if (areQuestionRecords(cardHistory)) {
+    return newQuestionInterval(user, cardHistory);
+  } else {
+    return 100000; // random - replace
+  }
+}
+
+function newQuestionInterval(user: DocumentUpdater, cardHistory: CardHistory<QuestionRecord>) {
+  const records = cardHistory.records;
+  const currentAttempt = records[records.length - 1];
+  const lastInterval: number = lastSuccessfulInterval(records);
+
+  if (lastInterval > cardHistory.bestInterval) {
+    cardHistory.bestInterval = lastInterval;
+    // update bestInterval on cardHistory in db
+    void user.update<CardHistory<QuestionRecord>>(cardHistory._id, {
+      bestInterval: lastInterval,
+    });
+  }
+
+  if (currentAttempt.isCorrect) {
+    const skill = currentAttempt.performance as number;
+    logger.debug(`Demontrated skill: \t${skill}`);
+    const interval: number = lastInterval * (0.75 + skill);
+    cardHistory.lapses = getLapses(cardHistory.records);
+    cardHistory.streak = getStreak(cardHistory.records);
+
+    if (
+      cardHistory.lapses &&
+      cardHistory.streak &&
+      cardHistory.bestInterval &&
+      (cardHistory.lapses >= 0 || cardHistory.streak >= 0)
+    ) {
+      // weighted average of best-ever performance vs current performance, based
+      // on how often the card has been failed, and the current streak of success
+      const ret =
+        (cardHistory.lapses * interval + cardHistory.streak * cardHistory.bestInterval) /
+        (cardHistory.lapses + cardHistory.streak);
+      logger.debug(`Weighted average interval calculation:
+\t(${cardHistory.lapses} * ${interval} + ${cardHistory.streak} * ${cardHistory.bestInterval}) / (${cardHistory.lapses} + ${cardHistory.streak}) = ${ret}`);
+      return ret;
+    } else {
+      return interval;
+    }
+  } else {
+    return 0;
+  }
+}
+
+/**
+ * Returns the amount of time, in seconds, of the most recent successful
+ * interval for this card. An interval is successful if the user answers
+ * a question correctly on the first attempt.
+ *
+ * @param cardHistory The record of user attempts with the question
+ */
+function lastSuccessfulInterval(cardHistory: QuestionRecord[]): number {
+  for (let i = cardHistory.length - 1; i >= 1; i--) {
+    if (cardHistory[i].priorAttemps === 0 && cardHistory[i].isCorrect) {
+      const lastInterval = secondsBetween(cardHistory[i - 1].timeStamp, cardHistory[i].timeStamp);
+      const ret = Math.max(lastInterval, 20 * 60 * 60);
+      logger.debug(`Last interval w/ this card was: ${lastInterval}s, returning ${ret}s`);
+      return ret;
+    }
+  }
+
+  return getInitialInterval(cardHistory); // used as a magic number here - indicates no prior intervals
+}
+
+function getStreak(records: QuestionRecord[]): number {
+  let streak = 0;
+  let index = records.length - 1;
+
+  while (index >= 0 && records[index].isCorrect) {
+    index--;
+    streak++;
+  }
+
+  return streak;
+}
+function getLapses(records: QuestionRecord[]): number {
+  return records.filter((r) => r.isCorrect === false).length;
+}
+
+function getInitialInterval(cardHistory: QuestionRecord[]): number {
+  logger.warn(`history of length: ${cardHistory.length} ignored!`);
+
+  // todo make this a data-driven service, relying on:
+  //  - global experience w/ the card (ie, what interval
+  //      seems to be working well across the population)
+  //  - the individual user (how do they respond in general
+  //      when compared to the population)
+  return 60 * 60 * 24 * 3; // 3 days
+}
+
+/**
+ * Returns the time in seconds between two Moment objects
+ * @param start The first time
+ * @param end The second time
+ */
+function secondsBetween(start: Moment, end: Moment): number {
+  // assertion guard against mis-typed json from database
+  start = moment(start);
+  end = moment(end);
+  const ret = duration(end.diff(start)).asSeconds();
+  // console.log(`From start: ${start} to finish: ${end} is ${ret} seconds`);
+  return ret;
+}

package/src/study/getCardDataShape.ts

@@ -0,0 +1,34 @@
+import { allCourses } from '@vue-skuilder/courses';
+import { log, NameSpacer, CourseConfig, DataShape } from '@vue-skuilder/common';
+import { CardData, DisplayableData } from '@/core';
+import { getCourseDB } from '@/impl/pouch/courseAPI';
+
+export async function getCardDataShape(courseID: string, cardID: string) {
+  const dataShapes: DataShape[] = [];
+  allCourses.courses.forEach((course) => {
+    course.questions.forEach((question) => {
+      question.dataShapes.forEach((ds) => {
+        dataShapes.push(ds);
+      });
+    });
+  });
+
+  // log(`Datashapes: ${JSON.stringify(dataShapes)}`);
+  const db = getCourseDB(courseID);
+  const card = await db.get<CardData>(cardID);
+  const disp = await db.get<DisplayableData>(card.id_displayable_data[0]);
+  const cfg = await db.get<CourseConfig>('CourseConfig');
+
+  // log(`Config: ${JSON.stringify(cfg)}`);
+  // log(`DisplayableData: ${JSON.stringify(disp)}`);
+  const dataShape = cfg!.dataShapes.find((ds) => {
+    return ds.name === disp.id_datashape;
+  });
+
+  const ret = dataShapes.find((ds) => {
+    return ds.name === NameSpacer.getDataShapeDescriptor(dataShape!.name).dataShape;
+  })!;
+
+  log(`Returning ${JSON.stringify(ret)}`);
+  return ret;
+}

package/src/study/index.ts

@@ -0,0 +1,2 @@
+export * from './SessionController';
+export * from './SpacedRepetition';

package/src/util/Loggable.ts

@@ -0,0 +1,11 @@
+export abstract class Loggable {
+  protected abstract readonly _className: string;
+  protected log(...args: unknown[]): void {
+    // eslint-disable-next-line no-console
+    console.log(`LOG-${this._className}@${new Date()}:`, ...args);
+  }
+  protected error(...args: unknown[]): void {
+    // eslint-disable-next-line no-console
+    console.error(`ERROR-${this._className}@${new Date()}:`, ...args);
+  }
+}

package/src/util/index.ts

@@ -0,0 +1 @@
+export * from './Loggable';

package/src/util/logger.ts

@@ -0,0 +1,55 @@
+/**
+ * Simple logging utility for @vue-skuilder/db package
+ *
+ * This utility provides environment-aware logging with ESLint suppressions
+ * to resolve console statement violations while maintaining logging functionality.
+ */
+
+const isDevelopment = typeof process !== 'undefined' && process.env.NODE_ENV === 'development';
+const _isBrowser = typeof window !== 'undefined';
+
+export const logger = {
+  /**
+   * Debug-level logging - only shown in development
+   */
+  debug: (message: string, ...args: any[]): void => {
+    if (isDevelopment) {
+      // eslint-disable-next-line no-console
+      console.debug(`[DB:DEBUG] ${message}`, ...args);
+    }
+  },
+
+  /**
+   * Info-level logging - general information
+   */
+  info: (message: string, ...args: any[]): void => {
+    // eslint-disable-next-line no-console
+    console.info(`[DB:INFO] ${message}`, ...args);
+  },
+
+  /**
+   * Warning-level logging - potential issues
+   */
+  warn: (message: string, ...args: any[]): void => {
+    // eslint-disable-next-line no-console
+    console.warn(`[DB:WARN] ${message}`, ...args);
+  },
+
+  /**
+   * Error-level logging - serious problems
+   */
+  error: (message: string, ...args: any[]): void => {
+    // eslint-disable-next-line no-console
+    console.error(`[DB:ERROR] ${message}`, ...args);
+  },
+
+  /**
+   * Log function for backward compatibility with existing log() usage
+   */
+  log: (message: string, ...args: any[]): void => {
+    if (isDevelopment) {
+      // eslint-disable-next-line no-console
+      console.log(`[DB:LOG] ${message}`, ...args);
+    }
+  },
+};

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: [
+    'src/index.ts',
+    'src/core/index.ts',
+    'src/pouch/index.ts'
+  ],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  outExtension: ({ format }) => ({
+    js: format === 'esm' ? '.mjs' : '.js'
+  })
+});