course pathfinding (#688)

- **refactor: group contentNavigation items**
- **add NavigationStrategy base types**
- **make courseDB impl compliant w/ StrategyManager**
- **update w/ interface changes**
- **add `coursedbInterface` to ContentNavigator inputs**
- **add ELO contentNavigator ...**
- **add getter for courseIDs**
- **use refactored default ELO contentNavigator**
- **use enum switch for implementation picking**
- **remove hard-coded ELO getPendingReviews**

Author: NiloCK

packages/db/src/core/interfaces/courseDB.ts

@@ -3,6 +3,7 @@ import { StudySessionNewItem, StudySessionItem } from './contentSource';
 import { TagStub, Tag } from '../types/types-legacy';
 import { SkuilderCourseData } from '@vue-skuilder/common/dist/db';
 import { DataLayerResult } from '../types/db';
+import { NavigationStrategyManager } from './navigationStrategyManager';
 
 /**
  * Course content and management
@@ -26,12 +27,14 @@ export interface CourseInfo {
   registeredUsers: number;
 }
 
-export interface CourseDBInterface {
+export interface CourseDBInterface extends NavigationStrategyManager {
   /**
    * Get course config
    */
   getCourseConfig(): Promise<CourseConfig>;
 
+  getCourseID(): string;
+
   /**
    * Set course config
    */

packages/db/src/core/interfaces/navigationStrategyManager.ts

@@ -0,0 +1,46 @@
+import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+
+/**
+ * A NavigationStrategyManager is an entity which may contain multiple strategies.
+ *
+ * This interface defines strategy CRUD.
+ */
+export interface NavigationStrategyManager {
+  /**
+   * Get the navigation strategy for a given course
+   * @returns The navigation strategy for the course
+   */
+  getNavigationStrategy(id: string): Promise<ContentNavigationStrategyData>;
+
+  /**
+   * Get all available navigation strategies
+   * @returns An array of all available navigation strategies
+   */
+  getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]>;
+
+  /**
+   * Add a new navigation strategy
+   * @param data The data for the new navigation strategy
+   * @returns A promise that resolves when the strategy has been added
+   */
+  addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void>;
+
+  /**
+   * Update an existing navigation strategy
+   * @param id The ID of the navigation strategy to update
+   * @param data The new data for the navigation strategy
+   * @returns A promise that resolves when the update is complete
+   */
+  updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
+
+  /**
+   * @returns A content navigation strategy suitable to the current context.
+   */
+  surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData>;
+
+  // [ ] addons here like:
+  //     - determining Navigation Strategy from context of current user
+  //     - determining weighted averages of navigation strategies
+  //     - expressing A/B testing results of 'ecosystem of strategies'
+  //     - etc etc
+}

packages/db/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',
+      };
+    });
+  }
+}

packages/db/src/core/navigators/index.ts

@@ -0,0 +1,55 @@
+import {
+  StudyContentSource,
+  UserDBInterface,
+  CourseDBInterface,
+  StudySessionReviewItem,
+  StudySessionNewItem,
+} from '..';
+import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import { ScheduledCard } from '../types/user';
+
+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 create(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategyData: ContentNavigationStrategyData
+  ): ContentNavigator {
+    const implementingClass = strategyData.implementingClass;
+    let NavigatorImpl;
+
+    // Try different extension variations
+    const variations = ['', '.ts', '.js'];
+
+    for (const ext of variations) {
+      try {
+        NavigatorImpl = require(`./${implementingClass}${ext}`).default;
+        break; // Break the loop if loading succeeds
+      } catch (e) {
+        // Continue to next variation if this one fails
+        console.log(`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[]>;
+}

packages/db/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;
+}

packages/db/src/core/types/types-legacy.ts

@@ -17,6 +17,7 @@ export enum DocType {
   CARDRECORD = 'CARDRECORD',
   SCHEDULED_CARD = 'SCHEDULED_CARD',
   TAG = 'TAG',
+  NAVIGATION_STRATEGY = 'NAVIGATION_STRATEGY',
 }
 
 /**