feat: ✨ add previews for courses/instructors

apps/api/src/lib/utils.ts

@@ -1,5 +1,12 @@
 import { Course as PrismaCourse } from "@libs/db";
-import { Course, CourseLevel, GECategory, PrerequisiteTree } from "@peterportal-api/types";
+import {
+  Course,
+  CourseLevel,
+  CoursePreview,
+  GECategory,
+  InstructorPreview,
+  PrerequisiteTree,
+} from "@peterportal-api/types";
 
 const days = ["Su", "M", "Tu", "W", "Th", "F", "Sa"];
 
@@ -64,11 +71,14 @@ export function normalizeCourse(course: PrismaCourse): Course {
   return {
     ...course,
     courseLevel,
-    instructorHistory: course.instructorHistory as unknown as string[],
-    prerequisiteTree: course.prerequisiteTree as unknown as PrerequisiteTree,
-    prerequisiteList: course.prerequisiteList as unknown as string[],
-    prerequisiteFor: course.prerequisiteFor as unknown as string[],
+    instructorHistory: course.instructorHistory,
+    instructors: course.instructors as InstructorPreview[],
+    prerequisiteTree: course.prerequisiteTree as PrerequisiteTree,
+    prerequisiteList: course.prerequisiteList,
+    prerequisiteFor: course.prerequisiteFor,
+    prerequisites: course.prerequisites as CoursePreview[],
+    dependencies: course.dependencies as CoursePreview[],
     geList,
-    terms: course.terms as unknown as string[],
+    terms: course.terms,
   };
 }

apps/api/src/routes/v1/graphql/schema/courses.graphql

@@ -1,3 +1,15 @@
+"An object that contains a subset of a course's metadata, for preview purposes."
+type CoursePreview {
+  "The course ID."
+  id: String!
+  "The department code that the course belongs to."
+  department: String!
+  "The course number of the course."
+  courseNumber: String!
+  "The title of the course."
+  title: String!
+}
+
 "An object that represents a course."
 type Course {
   "The course ID."
@@ -52,6 +64,12 @@ type Course {
   geText: String!
   "The list of terms in which this course was offered."
   terms: [String!]!
+  "The previews for the instructors that have taught this course in the past."
+  instructors: [InstructorPreview!]!
+  "The previews for the courses that are required to take this course."
+  prerequisites: [CoursePreview!]!
+  "The previews for the courses that require this course."
+  dependencies: [CoursePreview!]!
 }
 
 extend type Query {

apps/api/src/routes/v1/graphql/schema/instructors.graphql

@@ -1,3 +1,13 @@
+"An object that contains a subset of an instructor's metadata, for preview purposes."
+type InstructorPreview {
+  "The instructor's UCINetID."
+  ucinetid: String!
+  "The full name of the instructor."
+  name: String!
+  "The shortened name (or WebSoc name; e.g. ``SHINDLER, M.``) of the instructor."
+  shortenedName: String!
+}
+
 "An object representing an instructor."
 type Instructor {
   "The instructor's UCINetID."

apps/api/src/routes/v1/rest/courses/lib.ts

@@ -37,16 +37,16 @@ export function constructPrismaQuery(parsedQuery: Query): Prisma.CourseWhereInpu
   if (parsedQuery.taughtByInstructors)
     AND.push({
       OR: parsedQuery.taughtByInstructors.map((instructor) => ({
-        instructorHistory: { array_contains: [instructor.toLowerCase()] },
+        instructorHistory: { has: instructor.toLowerCase() },
       })),
     });
 
   if (parsedQuery.geCategory && parsedQuery.geCategory !== "ANY")
-    AND.push({ geList: { array_contains: [parsedQuery.geCategory] } });
+    AND.push({ geList: { has: parsedQuery.geCategory } });
 
   if (parsedQuery.taughtInTerms)
     AND.push({
-      OR: parsedQuery.taughtInTerms.map((term) => ({ terms: { array_contains: [term] } })),
+      OR: parsedQuery.taughtInTerms.map((term) => ({ terms: { has: term } })),
     });
 
   return { AND: AND.length ? AND : undefined };

apps/api/src/routes/v1/rest/instructors/lib.ts

@@ -23,13 +23,13 @@ export function constructPrismaQuery(parsedQuery: Query): Prisma.InstructorWhere
 
   if (parsedQuery.schoolsContains)
     AND.push({
-      OR: parsedQuery.schoolsContains.map((school) => ({ schools: { array_contains: [school] } })),
+      OR: parsedQuery.schoolsContains.map((school) => ({ schools: { has: school } })),
     });
 
   if (parsedQuery.relatedDepartmentsContains)
     AND.push({
       OR: parsedQuery.relatedDepartmentsContains.map((dept) => ({
-        relatedDepartments: { array_contains: [dept.toUpperCase()] },
+        relatedDepartments: { has: dept.toUpperCase() },
       })),
     });
 

libs/db/prisma/schema.prisma

@@ -70,33 +70,37 @@ model Course {
   maxUnits          Float
   description       String      @db.Text
   departmentName    String
-  instructorHistory Json
+  instructorHistory String[]
+  instructors       Json        @default("[]")
   prerequisiteTree  Json
-  prerequisiteList  Json
+  prerequisiteList  String[]
   prerequisiteText  String      @db.Text
-  prerequisiteFor   Json
+  prerequisiteFor   String[]
+  prerequisites     Json        @default("[]")
+  dependencies      Json        @default("[]")
   repeatability     String
   gradingOption     String
   concurrent        String
   sameAs            String
   restriction       String      @db.Text
   overlap           String
   corequisites      String
-  geList            Json
+  geList            String[]
   geText            String
-  terms             Json
+  terms             String[]
 }
 
 model Instructor {
-  ucinetid           String @id
+  ucinetid           String   @id
   name               String
   shortenedName      String
   title              String
   email              String
   department         String
-  schools            Json
-  relatedDepartments Json
+  schools            String[]
+  relatedDepartments String[]
   courseHistory      Json
+  courses            Json     @default("[]")
 }
 
 model GradesInstructor {

packages/types/types/courses.ts

@@ -1,4 +1,5 @@
 import { CourseLevel, GECategory } from "./constants";
+import { InstructorPreview } from "./instructor";
 
 /**
  * An object representing a prerequisite.
@@ -44,6 +45,11 @@ export type PrerequisiteTree = {
   NOT?: Array<Prerequisite | PrerequisiteTree>;
 };
 
+/**
+ * An object that contains a subset of a course's metadata, for preview purposes.
+ */
+export type CoursePreview = Pick<Course, "id" | "department" | "courseNumber" | "title">;
+
 /**
  * An object that represents a course.
  * The type of the payload returned on a successful response from querying
@@ -103,15 +109,15 @@ export type Course = {
    */
   prerequisiteTree: PrerequisiteTree;
   /**
-   * The list of prerequisites for the course.
+   * The list of prerequisites' IDs for the course.
    */
   prerequisiteList: string[];
   /**
    * The catalogue's prerequisite text for the course.
    */
   prerequisiteText: string;
   /**
-   * The courses for which this course is a prerequisite.
+   * The IDs of the courses for which this course is a prerequisite.
    */
   prerequisiteFor: string[];
   /**
@@ -154,6 +160,18 @@ export type Course = {
    * The list of terms in which this course was offered.
    */
   terms: string[];
+  /**
+   * The previews for the instructors that have taught this course in the past.
+   */
+  instructors: InstructorPreview[];
+  /**
+   * The previews for the courses that are required to take this course.
+   */
+  prerequisites: CoursePreview[];
+  /**
+   * The previews for the courses that require this course.
+   */
+  dependencies: CoursePreview[];
 };
 
 /**

packages/types/types/instructor.ts

@@ -1,3 +1,5 @@
+import { CoursePreview } from "./courses";
+
 /**
  * An object representing an instructor.
  * The type of the payload returned on a successful response from querying
@@ -42,10 +44,19 @@ export type Instructor = {
    * the instructor taught the corresponding course.
    */
   courseHistory: Record<string, string[]>;
+  /**
+   * The previews for the course(s) this instructor has taught in the past.
+   */
+  courses: CoursePreview[];
 };
 
 /**
  * The type of the payload returned on a successful response from querying
  * ``/v1/rest/instructors/all``.
  */
 export type Instructors = Instructor[];
+
+/**
+ * An object that contains a subset of an instructor's metadata, for preview purposes.
+ */
+export type InstructorPreview = Pick<Instructor, "ucinetid" | "name" | "shortenedName">;

tools/registrar-scraper/src/index.ts

@@ -52,6 +52,61 @@ async function main() {
       data: Object.values(instructorInfo),
     }),
   ]);
+  const courses = Object.fromEntries((await prisma.course.findMany()).map((x) => [x.id, x]));
+  const instructors = Object.fromEntries(
+    (await prisma.instructor.findMany()).map((x) => [x.ucinetid, x]),
+  );
+  const newCourses = Object.values(courses).map((course) => ({
+    ...course,
+    prerequisiteTree: course.prerequisiteTree as object,
+    instructors: course.instructorHistory
+      .map((x) => instructors[x])
+      .filter((x) => x)
+      .map(({ ucinetid, name, shortenedName }) => ({ ucinetid, name, shortenedName })),
+    prerequisites: course.prerequisiteList
+      .map((x) => courses[x.replace(/ /g, "")])
+      .filter((x) => x)
+      .map(({ id, title, department, courseNumber }) => ({
+        id,
+        title,
+        department,
+        courseNumber,
+      })),
+    dependencies: course.prerequisiteFor
+      .map((x) => courses[x.replace(/ /g, "")])
+      .filter((x) => x)
+      .map(({ id, title, department, courseNumber }) => ({
+        id,
+        title,
+        department,
+        courseNumber,
+      })),
+  }));
+  const newInstructors = Object.values(instructors).map((instructor) => ({
+    ...instructor,
+    courseHistory: instructor.courseHistory as object,
+    courses: Object.keys(instructor.courseHistory!)
+      .map((x) => courses[x.replace(/ /g, "")])
+      .filter((x) => x)
+      .map(({ id, title, department, courseNumber }) => ({
+        id,
+        title,
+        department,
+        courseNumber,
+      })),
+  }));
+  await prisma.$transaction([
+    prisma.course.deleteMany({ where: { id: { in: Object.keys(courses) } } }),
+    prisma.instructor.deleteMany({ where: { ucinetid: { in: Object.keys(instructors) } } }),
+    prisma.course.createMany({
+      data: newCourses,
+      skipDuplicates: true,
+    }),
+    prisma.instructor.createMany({
+      data: newInstructors,
+      skipDuplicates: true,
+    }),
+  ]);
 }
 
 main().then();

tools/registrar-scraper/src/instructor-scraper/index.ts

@@ -25,9 +25,9 @@ type InstructorsData = {
   log: InstructorsLog;
 };
 
-type InstructorsInfo = {
-  [ucinetid: string]: Instructor;
-};
+type ScrapedInstructor = Omit<Instructor, "courses">;
+
+type InstructorsInfo = Record<string, ScrapedInstructor>;
 
 type InstructorsLog = {
   [key: string]:
@@ -139,7 +139,7 @@ export async function getInstructors(
       }
     });
   });
-  const instructorPromises: Promise<[string, Instructor]>[] = [];
+  const instructorPromises: Promise<[string, ScrapedInstructor]>[] = [];
   Object.keys(instructorsDict).forEach((name) => {
     const schools = instructorsDict[name].schools;
     const related_departments = Array.from(instructorsDict[name].courses);
@@ -214,9 +214,9 @@ async function getInstructor(
   relatedDepartments: string[],
   attempts: number,
   year_threshold: number,
-): Promise<[string, Instructor]> {
+): Promise<[string, ScrapedInstructor]> {
   logger.info(`Scraping data for ${instructorName}`);
-  const instructorObject: Instructor = {
+  const instructorObject: ScrapedInstructor = {
     name: instructorName,
     ucinetid: "",
     title: "",