Students

The students module holds the people a teacher teaches. A student belongs to one teacher account and can be placed in several groups. The teacher app lists, creates and archives students; the API exposes the same operations.

Import from @workspace/training/domain/students and @workspace/training/application/students.

Domain

Student ids are numbers, unlike most ids in the package. userId is the owning teacher account.

StudentWithGroupCount is the list projection: Student & { groupCount: number }.

The module has no constants, guards or pure functions.

Application

StudentsService

createStudentsService(deps: StudentsServiceDeps): StudentsService, where StudentsServiceDeps is { students: StudentsRepository; studentsRead: StudentsReadRepository; groupStudents: GroupStudentsRepository; groupsRead: GroupsReadRepository; entitlements: EntitlementsGate }.

Every method takes the ServiceContext last. List and create are scoped to ctx.userId. The id-scoped methods check ownership first: they count the caller's student (or group, for listByGroup), throw AccessDeniedError when the caller has no such row, whether it belongs to another account or does not exist, so sequential ids reveal nothing, and only then read or write it. Each method composes a query object, a criteria or a projection and calls one primitive of the ports below.

export function listActiveStudents(
  deps: StudentsServiceDeps,
  ctx: ServiceContext
): Promise<StudentWithGroupCount[]> {
  const students = createStudentsService(deps);
  return students.list(false, ctx); // owned by ctx.userId, archived excluded
}

export async function enrol(
  deps: StudentsServiceDeps,
  ctx: ServiceContext
): Promise<Student> {
  const students = createStudentsService(deps);
  const created = await students.create(
    { firstName: "Ada", lastName: "Lovelace", email: "ada@example.com" },
    ctx
  );
  // Throws NotFoundError(NOT_FOUND) when the id is unknown.
  return students.update(created.id, { phone: "+33 6 00 00 00 00" }, ctx);
}

DTOs

Archiving is an update with isArchived: true; there is no dedicated method.

Query objects

The generics are described on Queries. The student family binds them with numeric ids.

StudentQuery (read side), over QueryParams<StudentWhere, StudentSort>.

StudentCriteria (write side and aggregates): byId, byIds, byOwner, where and .and(where). Refuses an empty where.

StudentWhere: id (Equality<number>), ownerId (Equality<string>) and isArchived (Equality<boolean>).

StudentProjections: entity() returns Student; withGroupCount() returns StudentWithGroupCount, counting the student's group links.

StudentAggregations: count(criteria?). StudentSort: { column: "lastName" \| "createdAt"; desc: boolean }, whitelisted by STUDENT_SORT_COLUMNS. StudentPatch: the mutable columns of UpdateStudentDTO.

// Inside a service: numeric ids, archived students left out.
export function activeStudentsAmong(
  studentsRead: StudentsReadRepository,
  studentIds: number[]
): Promise<Student[]> {
  return studentsRead.findMany(
    StudentQuery.empty().withIds(studentIds).withArchived(false),
    StudentProjections.entity()
  );
}

Ports

StudentsReadRepository is ReadRepository<StudentQuery, undefined, number>: the third type argument keys getById by the serial student id. getById throws NotFoundError(NOT_FOUND) when no row matches.

StudentsRepository is WriteRepository<StudentCriteria, StudentPatch, PersistableStudentWrite, undefined, StudentUpdateResult, StudentDeleteResult> plus writeOne(input: PersistableStudentWrite) => Promise<{ studentId: number }>. The two results carry numeric ids: { updatedIds: number[] } and { deletedIds: number[] }.

Group membership is not on these ports: it lives on GroupStudentsRepository, documented with groups.

Errors

Test data: makeStudent and makeStudentWithGroupCount in Factories. In-memory fakes in Testing: createFakeStudentsRepositories, fed by createFakeGroupStudentsRepository for group counts.

export function studentFixture(faker: Faker): Student {
  return makeStudent(faker, { isArchived: false });
}