feat(2024): Add subclasses (#1043)

## What does this do?

Adds the 2024 subclasses

## Here's a fun image for your troubles

<img width="982" height="1155" alt="image"
src="https://github.com/user-attachments/assets/4c123535-3d5b-487b-8bc2-08b120fc88b3"
/>

Author: bagelbits

src/controllers/api/2024/subclassController.ts

@@ -0,0 +1,4 @@
+import SimpleController from '@/controllers/simpleController'
+import SubclassModel from '@/models/2024/subclass'
+
+export default new SimpleController(SubclassModel)

src/graphql/2024/resolvers/index.ts

@@ -13,6 +13,7 @@ import { MagicSchoolResolver } from './magicSchool/resolver'
 import { ProficiencyResolver } from './proficiency/resolver'
 import { SkillResolver } from './skill/resolver'
 import { SpeciesResolver } from './species/resolver'
+import { SubclassResolver } from './subclass/resolver'
 import { SubspeciesResolver } from './subspecies/resolver'
 import { TraitResolver } from './trait/resolver'
 import { WeaponMasteryPropertyResolver } from './weaponMasteryProperty/resolver'
@@ -33,6 +34,7 @@ const collectionResolvers = [
   ProficiencyResolver,
   SkillResolver,
   SpeciesResolver,
+  SubclassResolver,
   SubspeciesResolver,
   TraitResolver,
   WeaponMasteryPropertyResolver,

src/graphql/2024/resolvers/subclass/args.ts

@@ -0,0 +1,59 @@
+import { ArgsType, Field, InputType, registerEnumType } from 'type-graphql'
+import { z } from 'zod'
+
+import {
+  BaseFilterArgs,
+  BaseFilterArgsSchema,
+  BaseIndexArgsSchema,
+  BaseOrderInterface
+} from '@/graphql/common/args'
+import { OrderByDirection } from '@/graphql/common/enums'
+
+export enum SubclassOrderField {
+  NAME = 'name'
+}
+
+export const SUBCLASS_SORT_FIELD_MAP: Record<SubclassOrderField, string> = {
+  [SubclassOrderField.NAME]: 'name'
+}
+
+registerEnumType(SubclassOrderField, {
+  name: 'SubclassOrderField',
+  description: 'Fields to sort Subclasses by'
+})
+
+@InputType()
+export class SubclassOrder implements BaseOrderInterface<SubclassOrderField> {
+  @Field(() => SubclassOrderField)
+  by!: SubclassOrderField
+
+  @Field(() => OrderByDirection)
+  direction!: OrderByDirection
+
+  @Field(() => SubclassOrder, { nullable: true })
+  then_by?: SubclassOrder
+}
+
+export const SubclassOrderSchema: z.ZodType<SubclassOrder> = z.lazy(() =>
+  z.object({
+    by: z.nativeEnum(SubclassOrderField),
+    direction: z.nativeEnum(OrderByDirection),
+    then_by: SubclassOrderSchema.optional()
+  })
+)
+
+export const SubclassArgsSchema = z.object({
+  ...BaseFilterArgsSchema.shape,
+  order: SubclassOrderSchema.optional()
+})
+
+export const SubclassIndexArgsSchema = BaseIndexArgsSchema
+
+@ArgsType()
+export class SubclassArgs extends BaseFilterArgs {
+  @Field(() => SubclassOrder, {
+    nullable: true,
+    description: 'Specify sorting order for subclasses.'
+  })
+  order?: SubclassOrder
+}

src/graphql/2024/resolvers/subclass/resolver.ts

@@ -0,0 +1,56 @@
+import { Arg, Args, Query, Resolver } from 'type-graphql'
+
+import { buildSortPipeline } from '@/graphql/common/args'
+import SubclassModel, { Subclass2024 } from '@/models/2024/subclass'
+import { escapeRegExp } from '@/util'
+
+import {
+  SUBCLASS_SORT_FIELD_MAP,
+  SubclassArgs,
+  SubclassArgsSchema,
+  SubclassIndexArgsSchema,
+  SubclassOrderField
+} from './args'
+
+@Resolver(Subclass2024)
+export class SubclassResolver {
+  @Query(() => [Subclass2024], {
+    description: 'Gets all subclasses, optionally filtered by name.'
+  })
+  async subclasses(@Args(() => SubclassArgs) args: SubclassArgs): Promise<Subclass2024[]> {
+    const validatedArgs = SubclassArgsSchema.parse(args)
+    const query = SubclassModel.find()
+
+    if (validatedArgs.name != null && validatedArgs.name !== '') {
+      query.where({ name: { $regex: new RegExp(escapeRegExp(validatedArgs.name), 'i') } })
+    }
+
+    const sortQuery = buildSortPipeline<SubclassOrderField>({
+      order: validatedArgs.order,
+      sortFieldMap: SUBCLASS_SORT_FIELD_MAP,
+      defaultSortField: SubclassOrderField.NAME
+    })
+
+    if (Object.keys(sortQuery).length > 0) {
+      query.sort(sortQuery)
+    }
+
+    if (validatedArgs.skip) {
+      query.skip(validatedArgs.skip)
+    }
+    if (validatedArgs.limit) {
+      query.limit(validatedArgs.limit)
+    }
+
+    return query.lean()
+  }
+
+  @Query(() => Subclass2024, {
+    nullable: true,
+    description: 'Gets a single subclass by index.'
+  })
+  async subclass(@Arg('index', () => String) indexInput: string): Promise<Subclass2024 | null> {
+    const { index } = SubclassIndexArgsSchema.parse({ index: indexInput })
+    return SubclassModel.findOne({ index }).lean()
+  }
+}

src/models/2024/subclass.ts

@@ -0,0 +1,56 @@
+import { getModelForClass, prop } from '@typegoose/typegoose'
+import { DocumentType } from '@typegoose/typegoose/lib/types'
+import { Field, Int, ObjectType } from 'type-graphql'
+
+import { srdModelOptions } from '@/util/modelOptions'
+
+@ObjectType({ description: 'A feature granted by a 2024 subclass at a specific level.' })
+export class SubclassFeature2024 {
+  @Field(() => String, { description: 'The name of the subclass feature.' })
+  @prop({ required: true, type: () => String })
+  public name!: string
+
+  @Field(() => Int, { description: 'The character level at which this feature is gained.' })
+  @prop({ required: true, type: () => Number })
+  public level!: number
+
+  @Field(() => String, { description: 'A description of the subclass feature.' })
+  @prop({ required: true, type: () => String })
+  public description!: string
+}
+
+@ObjectType({ description: 'A subclass representing a specialization of a class in D&D 5e 2024.' })
+@srdModelOptions('2024-subclasses')
+export class Subclass2024 {
+  @Field(() => String, { description: 'The unique identifier for this subclass.' })
+  @prop({ required: true, index: true, type: () => String })
+  public index!: string
+
+  @Field(() => String, { description: 'The name of the subclass.' })
+  @prop({ required: true, index: true, type: () => String })
+  public name!: string
+
+  @Field(() => String, { description: 'A brief summary of the subclass.' })
+  @prop({ required: true, type: () => String })
+  public summary!: string
+
+  @Field(() => String, { description: 'A full description of the subclass.' })
+  @prop({ required: true, type: () => String })
+  public description!: string
+
+  @Field(() => [SubclassFeature2024], { description: 'Features granted by this subclass.' })
+  @prop({ required: true, type: () => [SubclassFeature2024] })
+  public features!: SubclassFeature2024[]
+
+  @prop({ required: true, index: true, type: () => String })
+  public url!: string
+
+  @Field(() => String, { description: 'Timestamp of the last update.' })
+  @prop({ required: true, index: true, type: () => String })
+  public updated_at!: string
+}
+
+export type SubclassDocument = DocumentType<Subclass2024>
+const SubclassModel = getModelForClass(Subclass2024)
+
+export default SubclassModel

src/routes/api/2024.ts

@@ -16,6 +16,7 @@ import MagicSchoolsHandler from './2024/magicSchools'
 import ProficienciesHandler from './2024/proficiencies'
 import SkillsHandler from './2024/skills'
 import SpeciesHandler from './2024/species'
+import SubclassesHandler from './2024/subclasses'
 import SubspeciesHandler from './2024/subspecies'
 import TraitsHandler from './2024/traits'
 import WeaponMasteryPropertiesHandler from './2024/weaponMasteryProperties'
@@ -41,6 +42,7 @@ router.use('/magic-schools', MagicSchoolsHandler)
 router.use('/proficiencies', ProficienciesHandler)
 router.use('/skills', SkillsHandler)
 router.use('/species', SpeciesHandler)
+router.use('/subclasses', SubclassesHandler)
 router.use('/subspecies', SubspeciesHandler)
 router.use('/traits', TraitsHandler)
 router.use('/weapon-mastery-properties', WeaponMasteryPropertiesHandler)

src/routes/api/2024/subclasses.ts

@@ -0,0 +1,15 @@
+import * as express from 'express'
+
+import SubclassController from '@/controllers/api/2024/subclassController'
+
+const router = express.Router()
+
+router.get('/', function (req, res, next) {
+  SubclassController.index(req, res, next)
+})
+
+router.get('/:index', function (req, res, next) {
+  SubclassController.show(req, res, next)
+})
+
+export default router

src/tests/controllers/api/2024/SubclassController.test.ts

@@ -0,0 +1,91 @@
+import { createRequest, createResponse } from 'node-mocks-http'
+import { describe, expect, it, vi } from 'vitest'
+
+import SubclassController from '@/controllers/api/2024/subclassController'
+import SubclassModel from '@/models/2024/subclass'
+import { subclassFactory } from '@/tests/factories/2024/subclass.factory'
+import { mockNext as defaultMockNext } from '@/tests/support'
+import {
+  generateUniqueDbUri,
+  setupIsolatedDatabase,
+  setupModelCleanup,
+  teardownIsolatedDatabase
+} from '@/tests/support/db'
+
+const mockNext = vi.fn(defaultMockNext)
+
+const dbUri = generateUniqueDbUri('subclass')
+
+setupIsolatedDatabase(dbUri)
+teardownIsolatedDatabase()
+setupModelCleanup(SubclassModel)
+
+describe('SubclassController', () => {
+  describe('index', () => {
+    it('returns a list of subclasses', async () => {
+      const subclassesData = subclassFactory.buildList(3)
+      await SubclassModel.insertMany(subclassesData)
+
+      const request = createRequest({ query: {} })
+      const response = createResponse()
+
+      await SubclassController.index(request, response, mockNext)
+
+      expect(response.statusCode).toBe(200)
+      const responseData = JSON.parse(response._getData())
+      expect(responseData.count).toBe(3)
+      expect(responseData.results).toHaveLength(3)
+      expect(mockNext).not.toHaveBeenCalled()
+    })
+
+    it('filters by name', async () => {
+      const subclassesData = [
+        subclassFactory.build({ name: 'Path of the Berserker' }),
+        subclassFactory.build({ name: 'Path of the Totem Warrior' })
+      ]
+      await SubclassModel.insertMany(subclassesData)
+
+      const request = createRequest({ query: { name: 'Berserker' } })
+      const response = createResponse()
+
+      await SubclassController.index(request, response, mockNext)
+
+      expect(response.statusCode).toBe(200)
+      const responseData = JSON.parse(response._getData())
+      expect(responseData.count).toBe(1)
+      expect(responseData.results[0].name).toBe('Path of the Berserker')
+    })
+  })
+
+  describe('show', () => {
+    it('returns a single subclass when found', async () => {
+      const subclassData = subclassFactory.build({
+        index: 'berserker',
+        name: 'Path of the Berserker'
+      })
+      await SubclassModel.insertMany([subclassData])
+
+      const request = createRequest({ params: { index: 'berserker' } })
+      const response = createResponse()
+
+      await SubclassController.show(request, response, mockNext)
+
+      expect(response.statusCode).toBe(200)
+      const responseData = JSON.parse(response._getData())
+      expect(responseData.index).toBe('berserker')
+      expect(responseData.name).toBe('Path of the Berserker')
+      expect(responseData.features).toHaveLength(2)
+      expect(mockNext).not.toHaveBeenCalled()
+    })
+
+    it('calls next() when the subclass is not found', async () => {
+      const request = createRequest({ params: { index: 'nonexistent' } })
+      const response = createResponse()
+
+      await SubclassController.show(request, response, mockNext)
+
+      expect(response._getData()).toBe('')
+      expect(mockNext).toHaveBeenCalledOnce()
+    })
+  })
+})

src/tests/factories/2024/subclass.factory.ts

@@ -0,0 +1,28 @@
+import { faker } from '@faker-js/faker'
+import { Factory } from 'fishery'
+
+import { Subclass2024, SubclassFeature2024 } from '@/models/2024/subclass'
+
+export const subclassFeatureFactory = Factory.define<SubclassFeature2024>(() => ({
+  name: faker.lorem.words(3),
+  level: faker.number.int({ min: 1, max: 20 }),
+  description: faker.lorem.paragraph()
+}))
+
+export const subclassFactory = Factory.define<Subclass2024>(({ sequence }) => {
+  const name = `Subclass ${sequence} - ${faker.lorem.words(2)}`
+  const index = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+
+  return {
+    index,
+    name,
+    summary: faker.lorem.sentence(),
+    description: faker.lorem.paragraph(),
+    features: subclassFeatureFactory.buildList(2),
+    url: `/api/2024/subclasses/${index}`,
+    updated_at: faker.date.recent().toISOString()
+  }
+})