@vue-skuilder/db 0.1.1

package/eslint.config.mjs

@@ -0,0 +1,20 @@
+import backendConfig from '../../eslint.config.backend.mjs';
+
+export default [
+  ...backendConfig,
+  {
+    ignores: ['node_modules/**', 'dist/**', 'eslint.config.mjs', 'tsup.config.ts'],
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Database-specific rules
+      '@typescript-eslint/no-explicit-any': 'off', // PouchDB types often use any
+    },
+  },
+];

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@vue-skuilder/db",
+    "publishConfig": {
+        "access": "public"
+    },
+    "version": "0.1.1",
+    "description": "Database layer for vue-skuilder",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        },
+        "./core": {
+            "types": "./dist/core/index.d.ts",
+            "import": "./dist/core/index.mjs",
+            "require": "./dist/core/index.js"
+        },
+        "./pouch": {
+            "types": "./dist/pouch/index.d.ts",
+            "import": "./dist/pouch/index.mjs",
+            "require": "./dist/pouch/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "build:debug": "tsup --sourcemap inline",
+        "dev": "tsup --watch",
+        "lint": "npx eslint .",
+        "lint:fix": "npx eslint . --fix",
+        "lint:check": "npx eslint . --max-warnings 0"
+    },
+    "dependencies": {
+        "@nilock2/pouchdb-authentication": "^1.0.2",
+        "@vue-skuilder/common": "workspace:*",
+        "moment": "^2.29.4",
+        "pouchdb": "^9.0.0",
+        "pouchdb-find": "^9.0.0"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.2",
+        "typescript": "~5.7.2"
+    }
+}

package/src/core/bulkImport/cardProcessor.ts

@@ -0,0 +1,165 @@
+import { CourseElo, Status, ParsedCard, BulkImportCardData } from '@vue-skuilder/common';
+import { CourseDBInterface } from '../../core/interfaces/courseDB';
+import { ImportResult, BulkCardProcessorConfig } from './types';
+import { logger } from '../../util/logger';
+
+/**
+ * Processes multiple cards from bulk text input
+ *
+ * @param parsedCards - Array of parsed cards to import
+ * @param courseDB - Course database interface
+ * @param config - Configuration for the card processor
+ * @returns Array of import results
+ */
+export async function importParsedCards(
+  parsedCards: ParsedCard[],
+  courseDB: CourseDBInterface,
+  config: BulkCardProcessorConfig
+): Promise<ImportResult[]> {
+  const results: ImportResult[] = [];
+
+  for (const parsedCard of parsedCards) {
+    try {
+      // processCard takes a ParsedCard and returns an ImportResult
+      const result = await processCard(parsedCard, courseDB, config);
+      results.push(result);
+    } catch (error) {
+      logger.error('Error processing card:', error);
+      // Reconstruct originalText from parsedCard for this specific catch block
+      // This is a fallback if processCard itself throws an unhandled error.
+      // Normally, processCard should return an ImportResult with status 'error'.
+      let errorOriginalText = parsedCard.markdown;
+      if (parsedCard.tags && parsedCard.tags.length > 0) {
+        errorOriginalText += `\ntags: ${parsedCard.tags.join(', ')}`;
+      }
+      if (parsedCard.elo !== undefined) {
+        errorOriginalText += `\nelo: ${parsedCard.elo}`;
+      }
+      results.push({
+        originalText: errorOriginalText,
+        status: 'error',
+        message: `Error processing card: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Processes a single parsed card
+ *
+ * @param parsedCard - Parsed card data
+ * @param courseDB - Course database interface
+ * @param config - Configuration for the card processor
+ * @returns Import result for the card
+ */
+async function processCard(
+  parsedCard: ParsedCard,
+  courseDB: CourseDBInterface,
+  config: BulkCardProcessorConfig
+): Promise<ImportResult> {
+  const { markdown, tags, elo } = parsedCard;
+
+  // Build the original text representation including metadata
+  let originalText = markdown;
+  if (tags.length > 0) {
+    originalText += `\ntags: ${tags.join(', ')}`;
+  }
+  if (elo !== undefined) {
+    originalText += `\nelo: ${elo}`;
+  }
+
+  // Create card data object
+  const cardData: BulkImportCardData = {
+    Input: markdown,
+    Uploads: [], // No uploads for bulk import
+  };
+
+  const tagsElo: CourseElo['tags'] = {};
+  for (const tag of tags) {
+    tagsElo[tag] = {
+      score: elo || 0,
+      count: 1,
+    };
+  }
+
+  try {
+    const result = await courseDB.addNote(
+      config.courseCode,
+      config.dataShape,
+      cardData,
+      config.userName,
+      tags,
+      undefined, // attachments
+      elo
+        ? {
+            global: {
+              score: elo,
+              count: 1,
+            },
+            tags: tagsElo,
+            misc: {},
+          }
+        : undefined
+    );
+
+    if (result.status === Status.ok) {
+      return {
+        originalText,
+        status: 'success',
+        message: 'Card added successfully.',
+        cardId: result.id ? result.id : '(unknown)',
+      };
+    } else {
+      return {
+        originalText,
+        status: 'error',
+        message: result.message || 'Failed to add card to database. Unknown error.',
+      };
+    }
+  } catch (error) {
+    logger.error('Error adding note:', error);
+    return {
+      originalText,
+      status: 'error',
+      message: `Error adding card: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * Validates the configuration for bulk card processing
+ *
+ * @param config - Configuration to validate
+ * @returns Object with validation result and error message if any
+ */
+export function validateProcessorConfig(config: Partial<BulkCardProcessorConfig>): {
+  isValid: boolean;
+  errorMessage?: string;
+} {
+  if (!config.dataShape) {
+    return {
+      isValid: false,
+      errorMessage: 'No data shape provided for card processing',
+    };
+  }
+
+  if (!config.courseCode) {
+    return {
+      isValid: false,
+      errorMessage: 'No course code provided for card processing',
+    };
+  }
+
+  if (!config.userName) {
+    return {
+      isValid: false,
+      errorMessage: 'No user name provided for card processing',
+    };
+  }
+
+  return { isValid: true };
+}

package/src/core/bulkImport/index.ts

@@ -0,0 +1,2 @@
+export * from './cardProcessor.js';
+export * from './types.js';

package/src/core/bulkImport/types.ts

@@ -0,0 +1,27 @@
+import { DataShape } from '@vue-skuilder/common';
+
+/**
+ * Interface representing the result of a bulk import operation for a single card
+ */
+export interface ImportResult {
+  /** The original text input for the card */
+  originalText: string;
+  /** Status of the import operation */
+  status: 'success' | 'error';
+  /** Message describing the result or error */
+  message: string;
+  /** ID of the newly created card (only for success) */
+  cardId?: string;
+}
+
+/**
+ * Configuration for the bulk card processor
+ */
+export interface BulkCardProcessorConfig {
+  /** The data shape to use for the cards */
+  dataShape: DataShape;
+  /** The course code used for adding notes */
+  courseCode: string;
+  /** The username of the current user */
+  userName: string;
+}

package/src/core/index.ts

@@ -0,0 +1,9 @@
+// Export all core interfaces and types
+
+export * from './interfaces';
+export * from './types/types-legacy';
+export * from './types/user';
+export * from '../util/Loggable';
+export * from './util';
+export * from './navigators';
+export * from './bulkImport';

package/src/core/interfaces/adminDB.ts

@@ -0,0 +1,27 @@
+import { ClassroomConfig, CourseConfig } from '@vue-skuilder/common';
+
+/**
+ * Admin functionality
+ */
+export interface AdminDBInterface {
+  /**
+   * Get all users
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  getUsers(): Promise<PouchDB.Core.Document<{}>[]>;
+
+  /**
+   * Get all courses
+   */
+  getCourses(): Promise<CourseConfig[]>;
+
+  /**
+   * Remove a course
+   */
+  removeCourse(id: string): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get all classrooms
+   */
+  getClassrooms(): Promise<(ClassroomConfig & { _id: string })[]>;
+}

package/src/core/interfaces/classroomDB.ts

@@ -0,0 +1,75 @@
+import { ClassroomConfig } from '@vue-skuilder/common';
+import { ScheduledCard } from '../types/user';
+import { StudySessionNewItem, StudySessionReviewItem } from './contentSource';
+
+/**
+ * Classroom management
+ */
+export interface ClassroomDBInterface {
+  /**
+   * Get classroom config
+   */
+  getConfig(): ClassroomConfig;
+
+  /**
+   * Get assigned content
+   */
+  getAssignedContent(): Promise<AssignedContent[]>;
+}
+
+export interface TeacherClassroomDBInterface extends ClassroomDBInterface {
+  /**
+   * For teacher interfaces: assign content
+   */
+  assignContent?(content: AssignedContent): Promise<boolean>;
+
+  /**
+   * For teacher interfaces: remove content
+   */
+  removeContent?(content: AssignedContent): Promise<void>;
+}
+
+export interface StudentClassroomDBInterface extends ClassroomDBInterface {
+  /**
+   * For student interfaces: get pending reviews
+   */
+  getPendingReviews?(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+
+  /**
+   * For student interfaces: get new cards
+   */
+  getNewCards?(limit?: number): Promise<StudySessionNewItem[]>;
+}
+
+export type AssignedContent = AssignedCourse | AssignedTag | AssignedCard;
+
+export interface AssignedTag extends ContentBase {
+  type: 'tag';
+  tagID: string;
+}
+export interface AssignedCourse extends ContentBase {
+  type: 'course';
+}
+export interface AssignedCard extends ContentBase {
+  type: 'card';
+  cardID: string;
+}
+
+interface ContentBase {
+  type: 'course' | 'tag' | 'card';
+  /**
+   * Username of the assigning teacher.
+   */
+  assignedBy: string;
+  /**
+   * Date the content was assigned.
+   */
+  assignedOn: moment.Moment;
+  /**
+   * A 'due' date for this assigned content, for scheduling content
+   * in advance. Content will not be actively pushed to students until
+   * this date.
+   */
+  activeOn: moment.Moment;
+  courseID: string;
+}

package/src/core/interfaces/contentSource.ts

@@ -0,0 +1,64 @@
+import { UserDBInterface } from '..';
+import { StudentClassroomDB } from '../../impl/pouch/classroomDB';
+import { CourseDB } from '../../impl/pouch/courseDB';
+import { ScheduledCard } from '@/core/types/user';
+
+export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
+
+export interface StudySessionFailedNewItem extends StudySessionItem {
+  status: 'failed-new';
+}
+export interface StudySessionFailedReviewItem extends StudySessionReviewItem {
+  status: 'failed-review';
+}
+
+export interface StudySessionNewItem extends StudySessionItem {
+  status: 'new';
+}
+
+export interface StudySessionReviewItem extends StudySessionItem {
+  reviewID: string;
+  status: 'review' | 'failed-review';
+}
+export function isReview(item: StudySessionItem): item is StudySessionReviewItem {
+  const ret = item.status === 'review' || item.status === 'failed-review' || 'reviewID' in item;
+
+  // console.log(`itemIsReview: ${ret}
+  // \t${JSON.stringify(item)}`);
+
+  return ret;
+}
+
+export interface StudySessionItem {
+  status: 'new' | 'review' | 'failed-new' | 'failed-review';
+  qualifiedID: `${string}-${string}` | `${string}-${string}-${number}`;
+  cardID: string;
+  contentSourceType: 'course' | 'classroom';
+  contentSourceID: string;
+  courseID: string;
+  // reviewID?: string;
+}
+
+export interface ContentSourceID {
+  type: 'course' | 'classroom';
+  id: string;
+}
+
+export interface StudyContentSource {
+  getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+  getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+}
+
+export async function getStudySource(
+  source: ContentSourceID,
+  user: UserDBInterface
+): Promise<StudyContentSource> {
+  if (source.type === 'classroom') {
+    return await StudentClassroomDB.factory(source.id, user);
+  } else {
+    // if (source.type === 'course') - removed so tsc is certain something returns
+    return new CourseDB(source.id, async () => {
+      return user;
+    });
+  }
+}

package/src/core/interfaces/courseDB.ts

@@ -0,0 +1,139 @@
+import { CourseConfig, CourseElo, DataShape, SkuilderCourseData } from '@vue-skuilder/common';
+import { StudySessionNewItem, StudySessionItem } from './contentSource';
+import { TagStub, Tag } from '../types/types-legacy';
+import { DataLayerResult } from '../types/db';
+import { NavigationStrategyManager } from './navigationStrategyManager';
+
+/**
+ * Course content and management
+ */
+export interface CoursesDBInterface {
+  /**
+   * Get course config
+   */
+  getCourseConfig(courseId: string): Promise<CourseConfig>;
+
+  /**
+   * Get a list of all courses
+   */
+  getCourseList(): Promise<CourseConfig[]>;
+
+  disambiguateCourse(courseId: string, disambiguator: string): Promise<void>;
+}
+
+export interface CourseInfo {
+  cardCount: number;
+  registeredUsers: number;
+}
+
+export interface CourseDBInterface extends NavigationStrategyManager {
+  /**
+   * Get course config
+   */
+  getCourseConfig(): Promise<CourseConfig>;
+
+  getCourseID(): string;
+
+  /**
+   * Set course config
+   */
+  updateCourseConfig(cfg: CourseConfig): Promise<PouchDB.Core.Response>;
+
+  getCourseInfo(): Promise<CourseInfo>;
+
+  getCourseDoc<T extends SkuilderCourseData>(
+    id: string,
+    options?: PouchDB.Core.GetOptions
+  ): Promise<T>;
+  getCourseDocs<T extends SkuilderCourseData>(
+    ids: string[],
+    options?: PouchDB.Core.AllDocsOptions
+  ): Promise<PouchDB.Core.AllDocsWithKeysResponse<{} & T>>;
+
+  /**
+   * Get cards sorted by ELO rating
+   */
+  getCardsByELO(elo: number, limit?: number): Promise<string[]>;
+
+  /**
+   * Get ELO data for specific cards
+   */
+  getCardEloData(cardIds: string[]): Promise<CourseElo[]>;
+
+  /**
+   * Update card ELO rating
+   */
+  updateCardElo(cardId: string, elo: CourseElo): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get new cards for study
+   */
+  getNewCards(limit?: number): Promise<StudySessionNewItem[]>;
+
+  /**
+   * Get cards centered at a particular ELO rating
+   */
+  getCardsCenteredAtELO(
+    options: { limit: number; elo: 'user' | 'random' | number },
+    filter?: (id: string) => boolean
+  ): Promise<StudySessionItem[]>;
+
+  /**
+   * Get tags for a card
+   */
+  getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
+
+  /**
+   * Add a tag to a card
+   */
+  addTagToCard(cardId: string, tagId: string, updateELO?: boolean): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Remove a tag from a card
+   */
+  removeTagFromCard(cardId: string, tagId: string): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Create a new tag
+   */
+  createTag(tagName: string): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get a tag by name
+   */
+  getTag(tagName: string): Promise<Tag>;
+
+  /**
+   * Update a tag
+   */
+  updateTag(tag: Tag): Promise<PouchDB.Core.Response>;
+
+  /**
+   * Get all tag stubs for a course
+   */
+  getCourseTagStubs(): Promise<PouchDB.Core.AllDocsResponse<Tag>>;
+
+  /**
+   * Add a note to the course
+   */
+  addNote(
+    codeCourse: string,
+    shape: DataShape,
+    data: unknown,
+    author: string,
+    tags: string[],
+    uploads?: { [key: string]: PouchDB.Core.FullAttachment },
+    elo?: CourseElo
+  ): Promise<DataLayerResult>;
+
+  removeCard(cardId: string): Promise<PouchDB.Core.Response>;
+
+  getInexperiencedCards(): Promise<
+    {
+      courseId: string;
+      cardId: string;
+      count: number;
+      elo: CourseElo;
+    }[]
+  >;
+}

package/src/core/interfaces/dataLayerProvider.ts

@@ -0,0 +1,46 @@
+// db/src/core/interfaces.ts
+
+import { UserDBInterface } from './userDB';
+import { CourseDBInterface, CoursesDBInterface } from './courseDB';
+import { ClassroomDBInterface } from './classroomDB';
+import { AdminDBInterface } from './adminDB';
+
+/**
+ * Main factory interface for data access
+ */
+export interface DataLayerProvider {
+  /**
+   * Get the user database interface
+   */
+  getUserDB(): UserDBInterface;
+
+  /**
+   * Get a course database interface
+   */
+  getCourseDB(courseId: string): CourseDBInterface;
+
+  /**
+   * Get the courses-lookup interface
+   */
+  getCoursesDB(): CoursesDBInterface;
+
+  /**
+   * Get a classroom database interface
+   */
+  getClassroomDB(classId: string, type: 'student' | 'teacher'): Promise<ClassroomDBInterface>;
+
+  /**
+   * Get the admin database interface
+   */
+  getAdminDB(): AdminDBInterface;
+
+  /**
+   * Initialize the data layer
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Teardown the data layer
+   */
+  teardown(): Promise<void>;
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,7 @@
+export * from './adminDB';
+export * from './classroomDB';
+export * from './contentSource';
+export * from './courseDB';
+export * from './dataLayerProvider';
+
+export * from './userDB';

package/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
+}