feat(server): add programs and courses schemas and functions (#10)

Author: chenxin-yan

bun.lock

@@ -82,6 +82,7 @@
       "name": "@dev-team-fall-25/server",
       "dependencies": {
         "convex": "^1.27.3",
+        "convex-helpers": "^0.1.104",
       },
       "devDependencies": {
         "@biomejs/biome": "2.2.4",
@@ -487,6 +488,8 @@
 
     "convex": ["[email protected]", "", { "dependencies": { "esbuild": "0.25.4", "jwt-decode": "^4.0.0", "prettier": "^3.0.0" }, "peerDependencies": { "@auth0/auth0-react": "^2.0.1", "@clerk/clerk-react": "^4.12.8 || ^5.0.0", "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0" }, "optionalPeers": ["@auth0/auth0-react", "@clerk/clerk-react", "react"], "bin": { "convex": "bin/main.js" } }, "sha512-Ebr9lPgXkL7JO5IFr3bG+gYvHskyJjc96Fx0BBNkJUDXrR/bd9/uI4q8QszbglK75XfDu068vR0d/HK2T7tB9Q=="],
 
+    "convex-helpers": ["[email protected]", "", { "peerDependencies": { "@standard-schema/spec": "^1.0.0", "convex": "^1.24.0", "hono": "^4.0.5", "react": "^17.0.2 || ^18.0.0 || ^19.0.0", "typescript": "^5.5", "zod": "^3.22.4 || ^4.0.15" }, "optionalPeers": ["@standard-schema/spec", "hono", "react", "typescript", "zod"], "bin": { "convex-helpers": "bin.cjs" } }, "sha512-7CYvx7T3K6n+McDTK4ZQaQNNGBzq5aWezpjzsKbOxPXx7oNcTP9wrpef3JxeXWFzkByJv5hRCjseh9B7eNJ7Ig=="],
+
     "cookie": ["[email protected]", "", {}, "sha512-9Kr/j4O16ISv8zBBhJoi4bXOYNTkFLOqSL3UDB0njXxCXNezjeyVrJyGOWtgfs/q2km1gwBcfH8q1yEGoMYunA=="],
 
     "core-util-is": ["[email protected]", "", {}, "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="],
@@ -805,6 +808,8 @@
 
     "@cspotcode/source-map-support/@jridgewell/trace-mapping": ["@jridgewell/[email protected]", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.0.3", "@jridgewell/sourcemap-codec": "^1.4.10" } }, "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ=="],
 
+    "@dev-team-fall-25/server/@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.2.23" } }, "sha512-le8ueOY5b6VKYf19xT3McVbXqLqmxzPXHsQT/q9JHgikJ2X22wyTW3g3ohz2ZMnp7dod6aduIiq8A14Xyimm0A=="],
+
     "@rollup/pluginutils/picomatch": ["[email protected]", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
     "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/[email protected]", "", { "dependencies": { "@emnapi/wasi-threads": "1.1.0", "tslib": "^2.4.0" }, "bundled": true }, "sha512-sbP8GzB1WDzacS8fgNPpHlp6C9VZe+SJP3F90W9rLemaQj2PzIuTEl1qDOYQf58YIpyjViI24y9aPWCjEzY2cg=="],
@@ -849,6 +854,8 @@
 
     "web/@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-gfehUI8N1z92kygssiuWvLiwcbOB3IRktR6hTDgJlXMYh5OvkPSRmgfoBUmfZt+vhwJtX7v1Yw4KvvAf7c5QKQ=="],
 
+    "@dev-team-fall-25/server/@types/bun/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-R9f0hKAZXgFU3mlrA0YpE/fiDvwV0FT9rORApt2aQVWSuJDzZOyB5QLc0N/4HF57CS8IXJ6+L5E4W1bW6NS2Aw=="],
+
     "bun-types/@types/node/undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
     "miniflare/sharp/@img/sharp-darwin-arm64": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.0.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ=="],

packages/server/convex/_generated/api.d.ts

@@ -13,6 +13,12 @@ import type {
   FilterApi,
   FunctionReference,
 } from "convex/server";
+import type * as courses from "../courses.js";
+import type * as prerequisites from "../prerequisites.js";
+import type * as programs from "../programs.js";
+import type * as requirements from "../requirements.js";
+import type * as schemas_courses from "../schemas/courses.js";
+import type * as schemas_programs from "../schemas/programs.js";
 
 /**
  * A utility for referencing Convex functions in your app's API.
@@ -22,7 +28,14 @@ import type {
  * const myFunctionReference = api.myModule.myFunction;
  * ```
  */
-declare const fullApi: ApiFromModules<{}>;
+declare const fullApi: ApiFromModules<{
+  courses: typeof courses;
+  prerequisites: typeof prerequisites;
+  programs: typeof programs;
+  requirements: typeof requirements;
+  "schemas/courses": typeof schemas_courses;
+  "schemas/programs": typeof schemas_programs;
+}>;
 export declare const api: FilterApi<
   typeof fullApi,
   FunctionReference<any, "public">

packages/server/convex/_generated/dataModel.d.ts

@@ -8,29 +8,29 @@
  * @module
  */
 
-import { AnyDataModel } from "convex/server";
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
 import type { GenericId } from "convex/values";
-
-/**
- * No `schema.ts` file found!
- *
- * This generated code has permissive types like `Doc = any` because
- * Convex doesn't know your schema. If you'd like more type safety, see
- * https://docs.convex.dev/using/schemas for instructions on how to add a
- * schema file.
- *
- * After you change a schema, rerun codegen with `npx convex dev`.
- */
+import schema from "../schema.js";
 
 /**
  * The names of all of your Convex tables.
  */
-export type TableNames = string;
+export type TableNames = TableNamesInDataModel<DataModel>;
 
 /**
  * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
  */
-export type Doc = any;
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
 
 /**
  * An identifier for a document in Convex.
@@ -42,8 +42,10 @@ export type Doc = any;
  *
  * IDs are just strings at runtime, but this type can be used to distinguish them from other
  * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
  */
-export type Id<TableName extends TableNames = TableNames> =
+export type Id<TableName extends TableNames | SystemTableNames> =
   GenericId<TableName>;
 
 /**
@@ -55,4 +57,4 @@ export type Id<TableName extends TableNames = TableNames> =
  * This type is used to parameterize methods like `queryGeneric` and
  * `mutationGeneric` to make them type-safe.
  */
-export type DataModel = AnyDataModel;
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

packages/server/convex/courses.ts

@@ -0,0 +1,44 @@
+import { v } from "convex/values";
+import { partial } from "convex-helpers/validators";
+import { mutation, query } from "./_generated/server";
+import { courses } from "./schemas/courses";
+
+export const getCourseById = query({
+  args: { id: v.id("courses") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const getCourseByCode = query({
+  args: { code: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("courses")
+      .withIndex("by_course_code", (q) => q.eq("code", args.code))
+      .unique();
+  },
+});
+
+export const deleteCourse = mutation({
+  args: { id: v.id("courses") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+  },
+});
+
+export const upsertCourse = mutation({
+  args: courses,
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("courses")
+      .withIndex("by_course_code", (q) => q.eq("code", args.code))
+      .unique();
+
+    if (existing) {
+      return await ctx.db.patch(existing._id, args);
+    } else {
+      return await ctx.db.insert("courses", args);
+    }
+  },
+});

packages/server/convex/prerequisites.ts

@@ -0,0 +1,73 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { prerequisites } from "./schemas/courses";
+
+export const getPrerequisite = query({
+  args: { id: v.id("prerequisites") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const getPrerequisitesByCourse = query({
+  args: { courseId: v.id("courses") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("prerequisites")
+      .withIndex("by_course", (q) => q.eq("courseId", args.courseId))
+      .collect();
+  },
+});
+
+export const createPrerequisite = mutation({
+  args: {
+    courseId: v.id("courses"),
+    type: v.union(
+      v.literal("required"),
+      v.literal("alternative"),
+      v.literal("options"),
+    ),
+    courses: v.array(v.string()),
+    creditsRequired: v.optional(v.int64()),
+  },
+  handler: async (ctx, args) => {
+    if (args.type === "options") {
+      if (args.creditsRequired === undefined) {
+        throw new Error("creditsRequired is required for options type");
+      }
+      return await ctx.db.insert("prerequisites", {
+        courseId: args.courseId,
+        type: args.type,
+        courses: args.courses,
+        creditsRequired: args.creditsRequired,
+      });
+    } else {
+      return await ctx.db.insert("prerequisites", {
+        courseId: args.courseId,
+        type: args.type,
+        courses: args.courses,
+      });
+    }
+  },
+});
+
+export const deletePrerequisite = mutation({
+  args: { id: v.id("prerequisites") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+  },
+});
+
+export const deletePrerequisitesByCourse = mutation({
+  args: { courseId: v.id("courses") },
+  handler: async (ctx, args) => {
+    const prerequisitesToDelete = await ctx.db
+      .query("prerequisites")
+      .withIndex("by_course", (q) => q.eq("courseId", args.courseId))
+      .collect();
+
+    for (const prerequisite of prerequisitesToDelete) {
+      await ctx.db.delete(prerequisite._id);
+    }
+  },
+});

packages/server/convex/programs.ts

@@ -0,0 +1,43 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { programs } from "./schemas/programs";
+
+export const getProgram = query({
+  args: { id: v.id("programs") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const getProgramByName = query({
+  args: { name: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("programs")
+      .withIndex("by_program_name", (q) => q.eq("name", args.name))
+      .unique();
+  },
+});
+
+export const deleteProgram = mutation({
+  args: { id: v.id("programs") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+  },
+});
+
+export const upsertProgram = mutation({
+  args: programs,
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("programs")
+      .withIndex("by_program_name", (q) => q.eq("name", args.name))
+      .unique();
+
+    if (existing) {
+      return await ctx.db.patch(existing._id, args);
+    } else {
+      return await ctx.db.insert("programs", args);
+    }
+  },
+});

packages/server/convex/requirements.ts

@@ -0,0 +1,75 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+
+export const getRequirement = query({
+  args: { id: v.id("requirements") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const getRequirementsByProgram = query({
+  args: { programId: v.id("programs") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("requirements")
+      .withIndex("by_program", (q) => q.eq("programId", args.programId))
+      .collect();
+  },
+});
+
+export const createRequirement = mutation({
+  args: {
+    programId: v.id("programs"),
+    isMajor: v.boolean(),
+    type: v.union(
+      v.literal("required"),
+      v.literal("alternative"),
+      v.literal("options"),
+    ),
+    courses: v.array(v.string()),
+    creditsRequired: v.optional(v.int64()),
+  },
+  handler: async (ctx, args) => {
+    if (args.type === "options") {
+      if (args.creditsRequired === undefined) {
+        throw new Error("creditsRequired is required for options type");
+      }
+      return await ctx.db.insert("requirements", {
+        programId: args.programId,
+        isMajor: args.isMajor,
+        type: args.type,
+        courses: args.courses,
+        creditsRequired: args.creditsRequired,
+      });
+    } else {
+      return await ctx.db.insert("requirements", {
+        programId: args.programId,
+        isMajor: args.isMajor,
+        type: args.type,
+        courses: args.courses,
+      });
+    }
+  },
+});
+
+export const deleteRequirement = mutation({
+  args: { id: v.id("requirements") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+  },
+});
+
+export const deleteRequirementsByProgram = mutation({
+  args: { programId: v.id("programs") },
+  handler: async (ctx, args) => {
+    const requirementsToDelete = await ctx.db
+      .query("requirements")
+      .withIndex("by_program", (q) => q.eq("programId", args.programId))
+      .collect();
+
+    for (const requirement of requirementsToDelete) {
+      await ctx.db.delete(requirement._id);
+    }
+  },
+});

packages/server/convex/schema.ts

@@ -0,0 +1,12 @@
+import { defineSchema, defineTable } from "convex/server";
+import { courses, prerequisites } from "./schemas/courses";
+import { programs, requirements } from "./schemas/programs";
+
+export default defineSchema({
+  programs: defineTable(programs).index("by_program_name", ["name"]),
+  requirements: defineTable(requirements)
+    .index("by_program", ["programId"])
+    .index("by_program_and_type", ["programId", "isMajor"]),
+  courses: defineTable(courses).index("by_course_code", ["code"]),
+  prerequisites: defineTable(prerequisites).index("by_course", ["courseId"]),
+});