@vue-skuilder/common 0.1.0

package/README.md

@@ -0,0 +1 @@
+# common

package/eslint.config.js

@@ -0,0 +1,16 @@
+import backendConfig from '../../eslint.config.backend.mjs';
+
+export default [
+  ...backendConfig,
+  {
+    ignores: ['node_modules/**', 'dist/**', 'dist-esm/**', 'eslint.config.js'],
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+];

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@vue-skuilder/common",
+    "private": false,
+    "publishConfig": {
+      "access": "public"
+    },
+    "version": "0.1.0",
+    "type": "module",
+    "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"
+        }
+    },
+    "scripts": {
+        "build": "rm -rf dist dist-esm && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && find dist-esm -name '*.js' -exec sed -i \"s/\\.js'/\\.mjs'/g; s/\\.js\\\"/\\.mjs\\\"/g\" {} \\; && find dist-esm -name '*.js' -exec sh -c 'mv \"$1\" \"${1%.js}.mjs\"' _ {} \\; && cp -r dist-esm/* dist/ && rm -rf dist-esm",
+        "dev": "tsc --watch",
+        "lint": "npx eslint .",
+        "lint:fix": "npx eslint . --fix",
+        "lint:check": "npx eslint . --max-warnings 0"
+    },
+    "packageManager": "yarn@4.6.0",
+    "devDependencies": {
+        "typescript": "~5.7.2"
+    },
+    "dependencies": {
+        "moment": "^2.30.1"
+    }
+}

package/src/bulkImport/cardParser.ts

@@ -0,0 +1,137 @@
+import { ParsedCard } from './types.js';
+
+/**
+ * Configuration for the bulk card parser
+ */
+export interface CardParserConfig {
+  /** Custom tag identifier (defaults to 'tags:') */
+  tagIdentifier?: string;
+  /** Custom ELO identifier (defaults to 'elo:') */
+  eloIdentifier?: string;
+}
+
+/**
+ * Default configuration for the card parser
+ */
+const DEFAULT_PARSER_CONFIG: CardParserConfig = {
+  tagIdentifier: 'tags:',
+  eloIdentifier: 'elo:',
+};
+
+/**
+ * Card delimiter used to separate cards in bulk input
+ */
+export const CARD_DELIMITER = '\n---\n---\n';
+
+/**
+ * Parses a single card string into a structured object
+ *
+ * @param cardString - Raw string containing card content
+ * @param config - Optional parser configuration
+ * @returns ParsedCard object or null if parsing fails
+ */
+export function parseCard(
+  cardString: string,
+  config: CardParserConfig = DEFAULT_PARSER_CONFIG
+): ParsedCard | null {
+  const trimmedCardString = cardString.trim();
+  if (!trimmedCardString) {
+    return null;
+  }
+
+  const lines = trimmedCardString.split('\n');
+  let tags: string[] = [];
+  let elo: number | undefined = undefined;
+  const markdownLines = [...lines];
+
+  // Process the lines from bottom to top to handle metadata
+  let metadataLines = 0;
+
+  // Get the configured identifiers
+  const tagId = config.tagIdentifier || DEFAULT_PARSER_CONFIG.tagIdentifier;
+  const eloId = config.eloIdentifier || DEFAULT_PARSER_CONFIG.eloIdentifier;
+
+  // Check the last few lines for metadata (tags and elo)
+  for (let i = lines.length - 1; i >= 0 && i >= lines.length - 2; i--) {
+    const line = lines[i].trim();
+
+    // Check for tags
+    if (line.toLowerCase().startsWith(tagId!.toLowerCase())) {
+      tags = line
+        .substring(tagId!.length)
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter((tag) => tag);
+      metadataLines++;
+    }
+    // Check for ELO
+    else if (line.toLowerCase().startsWith(eloId!.toLowerCase())) {
+      const eloValue = line.substring(eloId!.length).trim();
+      const parsedElo = parseInt(eloValue, 10);
+      if (!isNaN(parsedElo)) {
+        elo = parsedElo;
+      }
+      metadataLines++;
+    }
+  }
+
+  // Remove metadata lines from the end of the content
+  if (metadataLines > 0) {
+    markdownLines.splice(markdownLines.length - metadataLines);
+  }
+
+  const markdown = markdownLines.join('\n').trim();
+  if (!markdown) {
+    // Card must have some markdown content
+    return null;
+  }
+
+  return { markdown, tags, elo };
+}
+
+/**
+ * Splits a bulk text input into individual card strings
+ *
+ * @param bulkText - Raw string containing multiple cards
+ * @returns Array of card strings
+ */
+export function splitCardsText(bulkText: string): string[] {
+  return bulkText
+    .split(CARD_DELIMITER)
+    .map((card) => card.trim())
+    .filter((card) => card); // Filter out empty strings
+}
+
+/**
+ * Parses a bulk text input into an array of structured ParsedCard objects.
+ *
+ * @param bulkText - Raw string containing multiple cards.
+ * @param config - Optional parser configuration.
+ * @returns Array of ParsedCard objects. Filters out cards that fail to parse.
+ */
+export function parseBulkTextToCards(
+  bulkText: string,
+  config: CardParserConfig = DEFAULT_PARSER_CONFIG
+): ParsedCard[] {
+  const cardStrings = splitCardsText(bulkText);
+  const parsedCards: ParsedCard[] = [];
+
+  for (const cardString of cardStrings) {
+    const parsedCard = parseCard(cardString, config);
+    if (parsedCard) {
+      parsedCards.push(parsedCard);
+    }
+  }
+  return parsedCards;
+}
+
+/**
+ * Validates if a bulk text input has valid format
+ *
+ * @param bulkText - Raw string containing multiple cards
+ * @returns true if valid, false otherwise
+ */
+export function isValidBulkFormat(bulkText: string): boolean {
+  const cardStrings = splitCardsText(bulkText);
+  return cardStrings.length > 0 && cardStrings.some((card) => !!card.trim());
+}

package/src/bulkImport/types.ts

@@ -0,0 +1,28 @@
+// We no longer need to import DataShape since we've moved the interfaces that used it
+// import { DataShape } from '@vue-skuilder/common';
+
+/**
+ * Interface representing a parsed card from bulk import
+ */
+export interface ParsedCard {
+  /** The markdown content of the card */
+  markdown: string;
+  /** Tags associated with the card */
+  tags: string[];
+  /** ELO rating for the card (optional) */
+  elo?: number;
+}
+
+/**
+ * Interface for card data ready to be stored in the database
+ */
+export interface BulkImportCardData {
+  /** Card markdown content */
+  Input: string;
+  /** Card media uploads */
+  Uploads: unknown[];
+  /** Any additional fields can be added as needed */
+  [key: string]: unknown;
+}
+
+// ImportResult and BulkCardProcessorConfig have been moved to @vue-skuilder/db

package/src/course-data.ts

@@ -0,0 +1,119 @@
+import { DisplayableData, DocType } from './db.js';
+import { NameSpacer } from './namespacer.js';
+import { DataShape } from './interfaces/DataShape.js';
+import { FieldDefinition } from './interfaces/FieldDefinition.js';
+
+import { FieldType } from './enums/FieldType.js';
+
+export function prepareNote55(
+  courseID: string,
+  codeCourse: string,
+  shape: DataShape,
+  // [ ] add typing
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data: any,
+  author: string,
+  _tags: string[],
+  uploads?: { [x: string]: PouchDB.Core.FullAttachment }
+): DisplayableData {
+  const dataShapeId = NameSpacer.getDataShapeString({
+    course: codeCourse,
+    dataShape: shape.name,
+  });
+
+  const attachmentFields = shape.fields
+    .map((field) => {
+      // make a copy, in order NOT to append to the datashape
+      const copy: FieldDefinition = {
+        name: field.name,
+        type: field.type,
+      };
+      return copy;
+    })
+    .filter((field) => {
+      return field.type === FieldType.IMAGE || field.type === FieldType.AUDIO;
+    })
+    .concat([
+      {
+        name: 'autoplayAudio',
+        type: FieldType.AUDIO,
+      },
+    ]);
+
+  for (let i = 1; i < 11; i++) {
+    if (data[`audio-${i}`]) {
+      attachmentFields.push({
+        name: `audio-${i}`,
+        type: FieldType.AUDIO,
+      });
+    }
+
+    if (data[`image-${i}`]) {
+      attachmentFields.push({
+        name: `image-${i}`,
+        type: FieldType.IMAGE,
+      });
+    }
+  }
+  if (data[`audio-11`]) {
+    throw new Error('Too many audio attachments');
+  }
+  if (data[`image-11`]) {
+    throw new Error('Too many image attachments');
+  }
+
+  const attachments: { [index: string]: PouchDB.Core.FullAttachment } = {};
+  const payload: DisplayableData = {
+    course: courseID,
+    data: [],
+    docType: DocType.DISPLAYABLE_DATA,
+    id_datashape: dataShapeId,
+  };
+
+  if (author) {
+    payload.author = author;
+  }
+
+  attachmentFields.forEach((attField) => {
+    attachments[attField.name] = data[attField.name];
+  });
+
+  //
+  if (uploads) {
+    Object.keys(uploads).forEach((k) => {
+      attachments[k] = uploads[k];
+    });
+  }
+
+  if (attachmentFields.length !== 0 || (uploads && Object.keys(uploads).length)) {
+    payload._attachments = attachments;
+  }
+
+  shape.fields
+    .filter((field) => {
+      return field.type !== FieldType.IMAGE && field.type !== FieldType.AUDIO;
+    })
+    .forEach((field) => {
+      payload.data.push({
+        name: field.name,
+        data: data[field.name],
+      });
+    });
+
+  return payload;
+}
+
+/**
+ * Question components
+ */
+
+export interface Evaluation {
+  isCorrect: boolean; // expand / contract the SRS
+  performance: Performance;
+}
+
+type Performance =
+  | number
+  | {
+      [dimension: string]: Performance;
+    };

package/src/db.ts

@@ -0,0 +1,181 @@
+import { Evaluation } from './course-data.js';
+import { Answer } from './interfaces/AnswerInterfaces.js';
+import { CourseElo } from './elo.js';
+import { Moment } from 'moment';
+
+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',
+}
+
+/**
+ * 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[];
+}
+
+const cardHistoryPrefix = 'cardH';
+
+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);
+  }
+}
+
+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;
+}
+
+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;
+}

package/src/elo.ts

@@ -0,0 +1,193 @@
+export class EloRanker {
+  constructor(public k: number = 32) {}
+
+  setKFactor(k: number): void {
+    this.k = k;
+  }
+  getKFactor(): number {
+    return this.k;
+  }
+
+  getExpected(a: number, b: number): number {
+    return 1 / (1 + Math.pow(10, (b - a) / 400));
+  }
+  updateRating(expected: number, actual: number, current: number): number {
+    return Math.round(current + this.k * (actual - expected));
+  }
+}
+
+export type CourseElo = {
+  global: EloRank;
+  tags: {
+    [tagID: string]: EloRank;
+  };
+  misc: {
+    [eloID: string]: EloRank;
+  };
+};
+
+type EloRank = {
+  score: number;
+  count: number;
+};
+
+type Eloish = number | EloRank | CourseElo;
+
+export function blankCourseElo(): CourseElo {
+  return {
+    global: {
+      score: 990 + Math.round(Math.random() * 20),
+      count: 0,
+    },
+    tags: {},
+    misc: {},
+  };
+}
+
+export function EloToNumber(elo: Eloish): number {
+  if (typeof elo === 'number') {
+    return elo;
+  } else if (isCourseElo(elo)) {
+    return elo.global.score;
+  }
+  {
+    return elo.score;
+  }
+}
+export function toElo(elo: number | EloRank): EloRank {
+  if (typeof elo === 'number') {
+    return {
+      score: elo,
+      count: 0,
+    };
+  } else {
+    return elo;
+  }
+}
+export function toCourseElo(elo: Eloish | undefined): CourseElo {
+  if (typeof elo === 'string') {
+    throw new Error('unsuitiably typed input to toCourseElo');
+  }
+  if (typeof elo === 'number') {
+    return {
+      global: {
+        score: elo,
+        count: 0,
+      },
+      misc: {},
+      tags: {},
+    };
+  } else if (isCourseElo(elo)) {
+    return elo;
+  } else if (elo === undefined) {
+    return {
+      global: {
+        score: 995 + Math.random() * 10,
+        count: 0,
+      },
+      tags: {},
+      misc: {},
+    };
+  } else {
+    return {
+      global: elo,
+      tags: {},
+      misc: {},
+    };
+  }
+}
+
+export function isCourseElo(x: unknown): x is CourseElo {
+  if (!x || typeof x !== 'object') {
+    return false;
+  }
+
+  return 'global' in x && 'tags' in x;
+}
+
+/**
+ * Calculates updated ELO scores for users and content after they interact
+ *
+ * @param userElo current ELO score of the user
+ * @param cardElo current ELO score of the card
+ * @param userScore user performance against the card in range [0,1]
+ * @param k optional scaling factor. Higher values -> larger score adjustments. Default 32.
+ * @returns
+ */
+export function adjustCourseScores(
+  aElo: Eloish,
+  bElo: Eloish,
+  userScore: number,
+  options?: {
+    globalOnly: boolean;
+  }
+): {
+  userElo: CourseElo;
+  cardElo: CourseElo;
+} {
+  if (userScore < 0 || userScore > 1) {
+    throw new Error(`ELO performance rating must be between 0 and 1 - received ${userScore}`);
+  }
+
+  const userElo: CourseElo = toCourseElo(aElo);
+  const cardElo: CourseElo = toCourseElo(bElo);
+
+  if (options == undefined || !options.globalOnly) {
+    // grade on each tag present for the card
+    Object.keys(cardElo.tags).forEach((k) => {
+      const userTagElo: EloRank = userElo.tags[k]
+        ? userElo.tags[k]
+        : {
+            count: 0,
+            score: userElo.global.score, // todo: 1000?
+          };
+      const adjusted = adjustScores(userTagElo, cardElo.tags[k], userScore);
+      userElo.tags[k] = adjusted.userElo;
+      cardElo.tags[k] = adjusted.cardElo;
+    });
+  }
+
+  const adjusted = adjustScores(userElo.global, cardElo.global, userScore);
+  userElo.global = adjusted.userElo;
+  cardElo.global = adjusted.cardElo;
+
+  return {
+    userElo,
+    cardElo,
+  };
+}
+
+function adjustScores(
+  userElo: EloRank,
+  cardElo: EloRank,
+  userScore: number
+): {
+  userElo: EloRank;
+  cardElo: EloRank;
+} {
+  if (userScore < 0 || userScore > 1) {
+    throw new Error(`ELO performance rating must be between 0 and 1 - received ${userScore}`);
+  }
+
+  // todo: how to calculate here?
+  // todo: should / must these be equal?
+  // todo: 176 - these K values should be a fcn of `.count` values of userElo and cardElo
+  const userRanker = new EloRanker(16);
+  const cardRanker = new EloRanker(16);
+
+  const exp = userRanker.getExpected(userElo.score, cardElo.score);
+
+  const updatedUserElo = userRanker.updateRating(exp, userScore, userElo.score);
+  const updatedCardElo = cardRanker.updateRating(1 - exp, 1 - userScore, cardElo.score);
+
+  return {
+    userElo: {
+      score: updatedUserElo,
+      count: userElo.count + 1,
+    },
+    cardElo: {
+      score: updatedCardElo,
+      count: cardElo.count + 1,
+    },
+  };
+}

package/src/enums/DataShapeNames.ts

@@ -0,0 +1,43 @@
+export enum DataShapeName {
+  BLANK = '',
+  // Shared base-course types
+  Basic = 'Basic',
+  Blanks = 'Blanks',
+  Default = 'Default',
+
+  // Math
+  MATH_SingleDigitAddition = 'SingleDigitAddition',
+  MATH_SingleDigitSubtraction = 'SingleDigitSubtraction',
+  MATH_SingleDigitDivision = 'SingleDigitDivision',
+  MATH_SingleDigitMultiplication = 'SingleDigitMultiplication',
+  MATH_EqualityTest = 'EqualityTest',
+  MATH_OneStepEquation = 'OneStepEquation',
+  MATH_AngleCategorize = 'AngleCategorize',
+  MATH_SupplimentaryAngles = 'SupplimentaryAngles',
+  MATH_CountBy = 'CountBy',
+
+  // French
+  FRENCH_AudioParse = 'AudioParse',
+  FRENCH_Vocab = 'Vocab',
+
+  // WordWork
+  WORDWORK_Spelling = 'WordWork_Spelling',
+
+  // Piano
+  PIANO_Echo = 'Piano_Echo',
+  PIANO_PlayNote = 'Piano_PlayNote',
+
+  // Pitch
+  PITCH_chroma = 'Pitch_chroma',
+
+  // SightSing
+  SIGHTSING_IdentifyKey = 'SightSing_IdentifyKey',
+
+  // Chess
+  CHESS_puzzle = 'CHESS_puzzle',
+  CHESS_forks = 'CHESS_forks',
+
+  // Typing
+  TYPING_singleLetter = 'TYPING_singleLetter',
+  TYPING_fallingLetters = 'TYPING_fallingLetters',
+}

package/src/enums/FieldType.ts

@@ -0,0 +1,17 @@
+/**
+ * These are the defined types of user input that can hydrate a configured
+ * dataShape.
+ *
+ * These field types map to input elements and specific validation and processing functions.
+ */
+export enum FieldType {
+  STRING = 'string',
+  NUMBER = 'number',
+  INT = 'int',
+  IMAGE = 'image',
+  MARKDOWN = 'markdown',
+  AUDIO = 'audio',
+  MIDI = 'midi',
+  MEDIA_UPLOADS = 'uploads',
+  CHESS_PUZZLE = 'chess_puzzle',
+}

package/src/enums/index.ts

@@ -0,0 +1,2 @@
+export * from './DataShapeNames.js';
+export * from './FieldType.js';

package/src/fieldConverters.ts

@@ -0,0 +1,74 @@
+import { FieldType } from './enums/FieldType.js';
+
+const numberConverter: Converter = (value: string) => {
+  return parseFloat(value);
+};
+const intConverter: Converter = (value: string) => {
+  return parseInt(value, 10);
+};
+
+export const fieldConverters: { [index in FieldType]: FieldConverter } = {
+  string: {
+    databaseConverter: (value: string) => value,
+    previewConverter: (value: string) => value,
+  },
+  chess_puzzle: {
+    databaseConverter: (value: string) => value,
+    previewConverter: (value: string) => value,
+  },
+  number: {
+    databaseConverter: numberConverter,
+    previewConverter: numberConverter,
+  },
+  int: {
+    databaseConverter: intConverter,
+    previewConverter: intConverter,
+  },
+  image: {
+    databaseConverter: (value) => value,
+    previewConverter: (value: { content_type: string; data: Blob }) => {
+      if (value) {
+        return value.data;
+      } else {
+        return new Blob();
+      }
+    },
+  },
+  audio: {
+    databaseConverter: (value) => value,
+    previewConverter: (value: { content_type: string; data: Blob }) => {
+      if (value) {
+        return value.data;
+      } else {
+        return new Blob();
+      }
+      // return '(audio)';
+    },
+  },
+  midi: {
+    databaseConverter: (value) => value,
+    previewConverter: (value) => value,
+  },
+  markdown: {
+    databaseConverter: (value) => value,
+    previewConverter: (value) => value,
+  },
+  uploads: {
+    databaseConverter: (value) => value,
+    previewConverter: (value) => value,
+  },
+};
+
+/**
+ * FieldConverter contains functions to process raw user input
+ * from a DataInputForm into
+ *  - database-ready format (databseConverter)
+ *  - render-ready format (previewConverter)
+ */
+interface FieldConverter {
+  databaseConverter: Converter;
+  previewConverter: Converter;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Converter = (value: any) => string | number | boolean | Blob;

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './wire-format.js';
+export * from './course-data.js';
+export * from './elo.js';
+export * from './namespacer.js';
+export * from './logshim.js';
+export * from './validators.js';
+export * from './fieldConverters.js';
+export * from './db.js';
+
+export * from './bulkImport/cardParser.js';
+export * from './bulkImport/types.js';
+
+// interfaces
+export * from './interfaces/index.js';
+
+// enums
+export * from './enums/index.js';

package/src/interfaces/AnswerInterfaces.ts

@@ -0,0 +1,7 @@
+// eslint-disable-next-line
+export interface Answer {}
+
+export interface RadioMultipleChoiceAnswer extends Answer {
+  choiceList: string[];
+  selection: number;
+}

package/src/interfaces/DataShape.ts

@@ -0,0 +1,9 @@
+// [ ] remove this file - duplicated in `common` package
+
+import { FieldDefinition } from './FieldDefinition.js';
+import { DataShapeName } from '../enums/DataShapeNames.js';
+
+export interface DataShape {
+  name: DataShapeName;
+  fields: FieldDefinition[];
+}

package/src/interfaces/FieldDefinition.ts

@@ -0,0 +1,12 @@
+import { Validator } from './Validator.js';
+import { Tagger } from './Tagger.js';
+import { FieldType } from '../enums/FieldType.js';
+import { CourseElo } from '../elo.js';
+
+export interface FieldDefinition {
+  name: string;
+  type: FieldType;
+  validator?: Validator;
+  tagger?: Tagger;
+  generateELO?: (x: unknown) => CourseElo;
+}

package/src/interfaces/Tagger.ts

@@ -0,0 +1,6 @@
+/**
+ * A tagger is *some function* that produces a list of tags - ie, strings.
+ */
+export interface Tagger {
+  (x: unknown): string[];
+}

package/src/interfaces/Validator.ts

@@ -0,0 +1,27 @@
+import { Status } from '../wire-format.js';
+
+export type ValidatingFunction = (value: string) => ValidationResult;
+export type VuetifyRule = (value: string) => true | string;
+
+export interface ValidationResult {
+  status: Status;
+  msg: string;
+}
+
+export function validationFunctionToVuetifyRule(f: ValidatingFunction): VuetifyRule {
+  return (value: string) => {
+    const result = f(value);
+
+    if (result.status === Status.ok) {
+      return true;
+    } else {
+      return result.msg;
+    }
+  };
+}
+
+export interface Validator {
+  instructions?: string;
+  placeholder?: string;
+  test: ValidatingFunction;
+}

package/src/interfaces/ViewData.ts

@@ -0,0 +1,21 @@
+import { DisplayableData } from '../db.js';
+
+export interface ViewData {
+  [index: string]: string | number | Blob | boolean;
+}
+
+export function displayableDataToViewData(data: DisplayableData): ViewData {
+  const ret: ViewData = {};
+  data.data.forEach((field) => {
+    ret[field.name] = field.data as string | number | boolean;
+  });
+  if (data._attachments) {
+    Object.getOwnPropertyNames(data._attachments).forEach((attachment) => {
+      // this 2nd check shouldn't be necessary, but TS is insisting
+      if (data._attachments) {
+        ret[attachment] = data._attachments[attachment].data as Blob;
+      }
+    });
+  }
+  return ret;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,6 @@
+export * from './AnswerInterfaces.js';
+export * from './DataShape.js';
+export * from './FieldDefinition.js';
+export * from './Tagger.js';
+export * from './Validator.js';
+export * from './ViewData.js';

package/src/logshim.ts

@@ -0,0 +1,4 @@
+export const log = (...args: unknown[]): void => {
+  // eslint-disable-next-line no-console
+  console.log(...args);
+};

package/src/namespacer.ts

@@ -0,0 +1,71 @@
+export class NameSpacer {
+  public static getDataShapeDescriptor(shapeStr: string): ShapeDescriptor {
+    const splitArray = shapeStr.split('.');
+
+    if (splitArray.length !== 3) {
+      throw new Error('shapeStr not valid');
+    } else {
+      return {
+        course: splitArray[0],
+        dataShape: splitArray[2],
+      };
+    }
+  }
+  public static getDataShapeString(shapeDescription: ShapeDescriptor): string {
+    return `${shapeDescription.course}.datashape.${shapeDescription.dataShape}`;
+  }
+
+  public static getViewDescriptor(viewStr: string): ViewDescriptor {
+    const splitArray = viewStr.split('.');
+
+    if (splitArray.length !== 4) {
+      throw new Error('viewStr not valid');
+    } else {
+      return {
+        course: splitArray[0],
+        questionType: splitArray[2],
+        view: splitArray[3],
+      };
+    }
+  }
+
+  public static getViewString(viewDescription: ViewDescriptor): string {
+    return (
+      `${viewDescription.course}.question.` +
+      `${viewDescription.questionType}.${viewDescription.view}`
+    );
+  }
+
+  public static getQuestionDescriptor(questionStr: string): QuestionDescriptor {
+    const splitArray = questionStr.split('.');
+
+    if (splitArray.length !== 3) {
+      throw new Error('questionStr not valid');
+    } else {
+      return {
+        course: splitArray[0],
+        questionType: splitArray[2],
+      };
+    }
+  }
+
+  public static getQuestionString(questionDescription: QuestionDescriptor): string {
+    return `${questionDescription.course}.question.${questionDescription.questionType}`;
+  }
+}
+
+export interface ShapeDescriptor {
+  course: string;
+  dataShape: string;
+}
+
+export interface QuestionDescriptor {
+  course: string;
+  questionType: string;
+}
+
+export interface ViewDescriptor {
+  course: string;
+  questionType: string;
+  view: string;
+}

package/src/validators.ts

@@ -0,0 +1,25 @@
+import { Validator } from './interfaces/Validator.js';
+import { Status } from './wire-format.js';
+
+interface ValidatorIndex {
+  [x: string]: Validator;
+}
+
+export const Validators: ValidatorIndex = {
+  NonEmptyString: {
+    instructions: '',
+    test: (input: string) => {
+      if (input.length !== 0) {
+        return {
+          status: Status.ok,
+          msg: '',
+        };
+      } else {
+        return {
+          status: Status.error,
+          msg: 'Input cannot be empty',
+        };
+      }
+    },
+  },
+};

package/src/wire-format.ts

@@ -0,0 +1,159 @@
+import { DataShape } from './interfaces/DataShape.js';
+
+export enum Status {
+  awaitingResponse = 'awaiting',
+  ok = 'ok',
+  warning = 'warning',
+  error = 'error',
+}
+
+export interface IServerResponse {
+  errorText?: string;
+  status: Status;
+  ok: boolean;
+}
+
+export interface IServerRequest {
+  type: ServerRequestType;
+  user: string;
+  response: IServerResponse | null;
+  /**
+   * milliseconds to wait for a request to complete before timing out
+   */
+  timeout?: number;
+}
+
+export interface CreateClassroom extends IServerRequest {
+  type: ServerRequestType.CREATE_CLASSROOM;
+  data: ClassroomConfig;
+  response: {
+    status: Status;
+    ok: boolean;
+    joincode: string;
+    uuid: string;
+  } | null;
+}
+export interface DeleteClassroom extends IServerRequest {
+  type: ServerRequestType.DELETE_CLASSROOM;
+  classID: string;
+}
+export interface JoinClassroom extends IServerRequest {
+  type: ServerRequestType.JOIN_CLASSROOM;
+  user: string;
+  data: {
+    joinCode: string;
+    registerAs: 'student' | 'teacher' | 'aide' | 'admin';
+    user: string;
+  };
+  response: {
+    errorText?: string;
+    status: Status;
+    ok: boolean;
+    id_course: string;
+    course_name: string;
+  } | null;
+}
+export interface LeaveClassroom extends IServerRequest {
+  type: ServerRequestType.LEAVE_CLASSROOM;
+  data: {
+    classID: string;
+  };
+}
+
+type NamespacedDatashape = string; // ${course}.datashape.${datashape}
+
+export interface DataShape55 {
+  // [ ] rename this to something else - disambiguate from DataShape in base-course
+  name: NamespacedDatashape;
+  questionTypes: PouchDB.Core.DocumentId[];
+}
+
+type NamespacedQuestion = string; // ${course}.question.${question}
+export interface QuestionType55 {
+  name: NamespacedQuestion;
+  viewList: string[];
+  dataShapeList: string[];
+}
+
+export interface ClassroomConfig {
+  students: string[];
+  teachers: string[];
+  name: string;
+  birthYear?: number;
+  classMeetingSchedule: string;
+  peerAssist: boolean;
+  joinCode: string;
+}
+
+/**
+ * metadata about a defined course
+ *
+ * Note: `courseID` is generated server-side. It is not present on
+ * new courses at the time of writing, client-side, but always
+ * present (!) when a CourseConfig is retrieved from the database
+ */
+export interface CourseConfig {
+  courseID?: string;
+  name: string;
+  description: string;
+  public: boolean;
+  deleted: boolean;
+  creator: string;
+  admins: string[];
+  moderators: string[];
+  dataShapes: DataShape55[];
+  questionTypes: QuestionType55[];
+  disambiguator?: string;
+}
+
+export interface CreateCourse extends IServerRequest {
+  type: ServerRequestType.CREATE_COURSE;
+  data: CourseConfig;
+  response: {
+    status: Status;
+    ok: boolean;
+    courseID: string;
+  } | null;
+}
+export interface DeleteCourse extends IServerRequest {
+  type: ServerRequestType.DELETE_COURSE;
+  courseID: string;
+}
+
+export interface AddCourseDataPayload {
+  courseID: string;
+  codeCourse: string;
+  shape: DataShape;
+  data: unknown;
+  author: string;
+  tags: string[];
+  uploads?: { [x: string]: PouchDB.Core.FullAttachment };
+}
+
+export interface AddCourseData extends IServerRequest {
+  type: ServerRequestType.ADD_COURSE_DATA;
+  data: AddCourseDataPayload;
+  response: {
+    status: Status;
+    ok: boolean;
+  };
+}
+
+export type ServerRequest =
+  | CreateClassroom
+  | DeleteClassroom
+  | JoinClassroom
+  | LeaveClassroom
+  | CreateCourse
+  | DeleteCourse
+  | AddCourseData;
+
+export enum ServerRequestType {
+  CREATE_CLASSROOM = 'CREATE_CLASSROOM',
+  DELETE_CLASSROOM = 'DELETE_CLASSROOM',
+  JOIN_CLASSROOM = 'JOIN_CLASSROOM',
+  LEAVE_CLASSROOM = 'LEAVE_CLASSROOM',
+  CREATE_COURSE = 'CREATE_COURSE',
+  DELETE_COURSE = 'DELETE_COURSE',
+  ADD_COURSE_DATA = 'ADD_COURSE_DATA',
+}

package/tsconfig.cjs.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.esm.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist-esm",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "dist-esm"]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}