feat(server)!: add course offerings corequisites (#44)

Author: chenxin-yan

apps/scraper/src/index.ts

@@ -1,7 +1,3 @@
-import type {
-  ZUpsertPrerequisites,
-  ZUpsertRequirements,
-} from "@dev-team-fall-25/server/convex/http";
 import { eq } from "drizzle-orm";
 import { Hono } from "hono";
 import * as z from "zod/mini";
@@ -185,47 +181,33 @@ export default {
               case "program": {
                 const res = await scrapeProgram(job.url, db, env);
 
-                const programId = await convex.upsertProgram(res.program);
+                const programId = await convex.upsertProgramWithRequirements({
+                  ...res.program,
+                  requirements: res.requirements,
+                });
 
                 if (!programId) {
                   throw new JobError(
                     "Failed to upsert program: no ID returned",
                     "validation",
                   );
                 }
-
-                // it is safe to assert the type here because the data will be validated before sending the request
-                const newRequirements = res.requirements.map((req) => ({
-                  ...req,
-                  programId: programId,
-                })) as z.infer<typeof ZUpsertRequirements>;
-
-                if (res.requirements.length > 0) {
-                  await convex.upsertRequirements(newRequirements);
-                }
                 break;
               }
               case "course": {
                 const res = await scrapeCourse(job.url, db, env);
 
-                const courseId = await convex.upsertCourse(res.course);
+                const courseId = await convex.upsertCourseWithPrerequisites({
+                  ...res.course,
+                  prerequisites: res.prerequisites,
+                });
 
                 if (!courseId) {
                   throw new JobError(
                     "Failed to upsert course: no ID returned",
                     "validation",
                   );
                 }
-
-                // it is safe to assert the type here because the data will be validated before sending the request
-                const newPrerequisites = res.prerequisites.map((prereq) => ({
-                  ...prereq,
-                  courseId: courseId,
-                })) as z.infer<typeof ZUpsertPrerequisites>;
-
-                if (res.prerequisites.length > 0) {
-                  await convex.upsertPrerequisites(newPrerequisites);
-                }
                 break;
               }
             }

apps/scraper/src/lib/convex.ts

@@ -2,11 +2,9 @@ import type { internal } from "@dev-team-fall-25/server/convex/_generated/api";
 import {
   ZGetAppConfig,
   type ZSetAppConfig,
-  ZUpsertCourse,
   ZUpsertCourseOffering,
-  ZUpsertPrerequisites,
-  ZUpsertProgram,
-  ZUpsertRequirements,
+  ZUpsertCourseWithPrerequisites,
+  ZUpsertProgramWithRequirements,
 } from "@dev-team-fall-25/server/convex/http";
 import type { FunctionReturnType } from "convex/server";
 import * as z from "zod/mini";
@@ -57,35 +55,21 @@ export class ConvexApi {
     return response.json();
   }
 
-  async upsertCourse(data: z.infer<typeof ZUpsertCourse>) {
+  async upsertCourseWithPrerequisites(
+    data: z.infer<typeof ZUpsertCourseWithPrerequisites>,
+  ) {
     const res = await this.request<
       FunctionReturnType<typeof internal.courses.upsertCourseInternal>
-    >("/api/courses/upsert", ZUpsertCourse, data);
+    >("/api/courses/upsert", ZUpsertCourseWithPrerequisites, data);
     return res.data;
   }
 
-  async upsertProgram(data: z.infer<typeof ZUpsertProgram>) {
+  async upsertProgramWithRequirements(
+    data: z.infer<typeof ZUpsertProgramWithRequirements>,
+  ) {
     const res = await this.request<
       FunctionReturnType<typeof internal.programs.upsertProgramInternal>
-    >("/api/programs/upsert", ZUpsertProgram, data);
-    return res.data;
-  }
-
-  async upsertRequirements(data: z.infer<typeof ZUpsertRequirements>) {
-    const res = await this.request<
-      FunctionReturnType<
-        typeof internal.requirements.createRequirementsInternal
-      >
-    >("/api/requirements/upsert", ZUpsertRequirements, data);
-    return res.data;
-  }
-
-  async upsertPrerequisites(data: z.infer<typeof ZUpsertPrerequisites>) {
-    const res = await this.request<
-      FunctionReturnType<
-        typeof internal.prerequisites.createPrerequisitesInternal
-      >
-    >("/api/prerequisites/upsert", ZUpsertPrerequisites, data);
+    >("/api/programs/upsert", ZUpsertProgramWithRequirements, data);
     return res.data;
   }
 

apps/scraper/src/modules/courses/index.ts

@@ -6,10 +6,12 @@ import type {
 import type { DrizzleD1Database } from "drizzle-orm/d1";
 import type * as z from "zod/mini";
 
-export type CoursePrerequisite = Omit<
-  z.infer<typeof ZUpsertPrerequisites>[number],
-  "courseId"
->;
+type PrerequisiteItem = z.infer<typeof ZUpsertPrerequisites>[number];
+
+export type CoursePrerequisite =
+  | Omit<Extract<PrerequisiteItem, { type: "required" }>, "courseId">
+  | Omit<Extract<PrerequisiteItem, { type: "alternative" }>, "courseId">
+  | Omit<Extract<PrerequisiteItem, { type: "options" }>, "courseId">;
 
 export async function discoverCourses(url: string): Promise<string[]> {
   // TODO: implement this function

packages/server/convex/courseOfferings.ts

@@ -1,3 +1,4 @@
+import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { internalMutation } from "./_generated/server";
 import { protectedQuery } from "./helpers/auth";
@@ -10,8 +11,39 @@ export const getCourseOfferingById = protectedQuery({
   },
 });
 
-export const getCourseOfferingsByTerm = protectedQuery({
+export const getCourseOfferingsByCourseTerm = protectedQuery({
+  args: {
+    courseCodes: v.array(v.string()),
+    term: v.union(
+      v.literal("spring"),
+      v.literal("summer"),
+      v.literal("fall"),
+      v.literal("j-term"),
+    ),
+    year: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const results = await Promise.all(
+      args.courseCodes.map((courseCode) =>
+        ctx.db
+          .query("courseOfferings")
+          .withIndex("by_course_term", (q) =>
+            q
+              .eq("courseCode", courseCode)
+              .eq("term", args.term)
+              .eq("year", args.year),
+          )
+          .collect(),
+      ),
+    );
+
+    return results.flat();
+  },
+});
+
+export const getCourseOfferingByClassNumber = protectedQuery({
   args: {
+    classNumber: v.number(),
     term: v.union(
       v.literal("spring"),
       v.literal("summer"),
@@ -23,16 +55,19 @@ export const getCourseOfferingsByTerm = protectedQuery({
   handler: async (ctx, args) => {
     return await ctx.db
       .query("courseOfferings")
-      .withIndex("by_term_year", (q) =>
-        q.eq("term", args.term).eq("year", args.year),
+      .withIndex("by_class_number", (q) =>
+        q
+          .eq("classNumber", args.classNumber)
+          .eq("term", args.term)
+          .eq("year", args.year),
       )
-      .collect();
+      .unique();
   },
 });
 
-export const getCourseOfferingsByCourseTerm = protectedQuery({
+export const getCorequisitesByCourseCode = protectedQuery({
   args: {
-    courseCode: v.string(),
+    classNumber: v.number(),
     term: v.union(
       v.literal("spring"),
       v.literal("summer"),
@@ -44,34 +79,94 @@ export const getCourseOfferingsByCourseTerm = protectedQuery({
   handler: async (ctx, args) => {
     return await ctx.db
       .query("courseOfferings")
-      .withIndex("by_course_term_section", (q) =>
+      .withIndex("by_corequisite_of", (q) =>
         q
-          .eq("courseCode", args.courseCode)
+          .eq("corequisiteOf", args.classNumber)
           .eq("term", args.term)
           .eq("year", args.year),
       )
       .collect();
   },
 });
 
+export const getCourseOfferings = protectedQuery({
+  args: {
+    query: v.optional(v.string()),
+    term: v.union(
+      v.literal("spring"),
+      v.literal("summer"),
+      v.literal("fall"),
+      v.literal("j-term"),
+    ),
+    year: v.number(),
+    paginationOpts: paginationOptsValidator,
+  },
+  handler: async (ctx, { query, paginationOpts, term, year }) => {
+    if (query) {
+      return await ctx.db
+        .query("courseOfferings")
+        .withSearchIndex("search_title", (q) =>
+          q
+            .search("title", query)
+            .eq("isCorequisite", false)
+            .eq("term", term)
+            .eq("year", year),
+        )
+        .paginate(paginationOpts);
+    }
+
+    return await ctx.db
+      .query("courseOfferings")
+      .withIndex("by_term_year", (q) =>
+        q.eq("isCorequisite", false).eq("term", term).eq("year", year),
+      )
+      .order("desc")
+      .paginate(paginationOpts);
+  },
+});
+
 export const upsertCourseOfferingInternal = internalMutation({
   args: courseOfferings,
   handler: async (ctx, args) => {
     const existing = await ctx.db
       .query("courseOfferings")
-      .withIndex("by_course_term_section", (q) =>
+      .withIndex("by_class_number", (q) =>
         q
-          .eq("courseCode", args.courseCode)
+          .eq("classNumber", args.classNumber)
           .eq("term", args.term)
-          .eq("year", args.year)
-          .eq("section", args.section),
+          .eq("year", args.year),
       )
       .unique();
 
     if (existing) {
       return await ctx.db.patch(existing._id, args);
-    } else {
-      return await ctx.db.insert("courseOfferings", args);
     }
+    return await ctx.db.insert("courseOfferings", args);
+  },
+});
+
+export const upsertCourseOfferingsInternal = internalMutation({
+  args: { courseOfferings: v.array(v.object(courseOfferings)) },
+  handler: async (ctx, args) => {
+    const results = await Promise.all(
+      args.courseOfferings.map(async (offering) => {
+        const existing = await ctx.db
+          .query("courseOfferings")
+          .withIndex("by_class_number", (q) =>
+            q
+              .eq("classNumber", offering.classNumber)
+              .eq("term", offering.term)
+              .eq("year", offering.year),
+          )
+          .unique();
+
+        if (existing) {
+          return await ctx.db.patch(existing._id, offering);
+        }
+        return await ctx.db.insert("courseOfferings", offering);
+      }),
+    );
+
+    return results;
   },
 });

packages/server/convex/courses.ts

@@ -1,3 +1,4 @@
+import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { internalMutation } from "./_generated/server";
 import { protectedQuery } from "./helpers/auth";
@@ -20,15 +21,27 @@ export const getCourseByCode = protectedQuery({
   },
 });
 
-export const getCourseByProgramLevel = protectedQuery({
-  args: { program: v.string(), level: v.number() },
+export const getCourses = protectedQuery({
+  args: {
+    level: v.number(),
+    query: v.optional(v.string()),
+    paginationOpts: paginationOptsValidator,
+  },
   handler: async (ctx, args) => {
+    if (args.query !== undefined) {
+      return await ctx.db
+        .query("courses")
+        .withSearchIndex("search_title", (q) =>
+          q.search("title", args.query as string).eq("level", args.level),
+        )
+        .paginate(args.paginationOpts);
+    }
+
     return await ctx.db
       .query("courses")
-      .withIndex("by_program_level", (q) =>
-        q.eq("program", args.program).eq("level", args.level),
-      )
-      .unique();
+      .withIndex("by_level", (q) => q.eq("level", args.level))
+      .order("desc")
+      .paginate(args.paginationOpts);
   },
 });
 
@@ -41,7 +54,8 @@ export const upsertCourseInternal = internalMutation({
       .unique();
 
     if (existing) {
-      return await ctx.db.patch(existing._id, args);
+      await ctx.db.patch(existing._id, args);
+      return existing._id;
     } else {
       return await ctx.db.insert("courses", args);
     }