Class LessonService

Service class for comprehensive lesson management operations within the WayrApp content system.

Provides complete CRUD functionality for lessons, exercise assignment management, and maintains data integrity across the content hierarchy. Handles complex business logic including validation of module relationships, order conflict resolution, and exercise reordering operations.

Index

Constructors

constructor

Methods

createLesson getLesson getLessonsByModule getLessons updateLesson deleteLesson assignExerciseToLesson unassignExerciseFromLesson getLessonExercises reorderLessonExercises reorderLessons

Constructors

constructor

new LessonService(prisma: PrismaClient): LessonService
Initializes the LessonService with required repository dependencies.
Parameters
- prisma: PrismaClient
  Prisma database client for repository initialization
Returns LessonService
- Defined in src/modules/content/services/LessonService.ts:89

Methods

createLesson

createLesson(data: CreateLessonDto): Promise<Lesson>
Creates a new lesson within a specified module with comprehensive validation.

Validates module existence, ensures lesson ID uniqueness, and prevents order conflicts within the parent module before creating the lesson record.
Parameters
- data: CreateLessonDto
  Lesson creation data including ID, module_id, experience_points, and order
Returns Promise<Lesson>
The newly created lesson object
Throws
When parent module doesn't exist

Throws
When lesson ID already exists

Throws
When lesson order conflicts with existing lessons in the module
Example
```
const lesson = await lessonService.createLesson({
  id: 'lesson-intro-greetings',
  module_id: 'module-basic-conversation',
  experience_points: 25,
  order: 1
});
```
- Defined in src/modules/content/services/LessonService.ts:115

getLesson

getLesson(id: string, moduleId: string): Promise<Lesson>
Retrieves a single lesson by its unique identifier and module ID. Uses composite key lookup to prevent horizontal access vulnerabilities.
Parameters
- id: string
  The unique lesson identifier
- moduleId: string
  The module identifier to ensure lesson belongs to the correct module
Returns Promise<Lesson>
The lesson object with all its properties
Throws
When lesson with the specified ID is not found or doesn't belong to the module
Example
```
const lesson = await lessonService.getLesson('lesson-intro-greetings', 'module-basic-conversation');
console.log(lesson.experience_points); // 25
```
- Defined in src/modules/content/services/LessonService.ts:162

getLessonsByModule

getLessonsByModule(
moduleId: string,
options?: QueryOptions,
): Promise<PaginatedResult<Lesson>>
Retrieves paginated lessons belonging to a specific module.

Validates module existence before fetching lessons with support for pagination, sorting, and filtering options.
Parameters
- moduleId: string
  The unique module identifier
- Optionaloptions: QueryOptions = {}
  Query options for pagination, sorting, and filtering
  - page
    Page number for pagination
  - limit
    Number of items per page
  - sortBy
    Field to sort by
  - sortOrder
    Sort direction
Returns Promise<PaginatedResult<Lesson>>
Paginated lesson results with metadata
Throws
When module with the specified ID is not found
Example
```
const result = await lessonService.getLessonsByModule('module-basic-conversation', {
  page: 1,
  limit: 5,
  sortBy: 'order',
  sortOrder: 'asc'
});
console.log(result.data.length); // Up to 5 lessons
console.log(result.pagination.total); // Total lesson count
```
- Defined in src/modules/content/services/LessonService.ts:199

getLessons

getLessons(options?: QueryOptions): Promise<PaginatedResult<Lesson>>
Retrieves paginated lessons across all modules in the system.
Parameters
- Optionaloptions: QueryOptions = {}
  Query options for pagination, sorting, and filtering
  - page
    Page number for pagination
  - limit
    Number of items per page
  - sortBy
    Field to sort by
  - sortOrder
    Sort direction
  - filters
    Additional filters to apply
Returns Promise<PaginatedResult<Lesson>>
Paginated lesson results with metadata
Example
```
const allLessons = await lessonService.getLessons({
  page: 1,
  limit: 20,
  sortBy: 'created_at',
  sortOrder: 'desc'
});
```
- Defined in src/modules/content/services/LessonService.ts:232

updateLesson

updateLesson(
    id: string,
    moduleId: string,
    data: Partial<Omit<CreateLessonDto, "id" | "module_id">>,
): Promise<Lesson>
Updates an existing lesson with partial data and order conflict validation. Uses composite key lookup to prevent horizontal access vulnerabilities.

Validates lesson existence and prevents order conflicts within the same module when updating lesson properties. ID and module_id cannot be modified.
Parameters
- id: string
  The unique lesson identifier
- moduleId: string
  The module identifier to ensure lesson belongs to the correct module
- data: Partial<Omit<CreateLessonDto, "id" | "module_id">>
  Partial lesson data for update
  - experience_points
    Updated experience points value
  - order
    Updated lesson order within the module
Returns Promise<Lesson>
The updated lesson object
Throws
When lesson with the specified ID is not found or doesn't belong to the module

Throws
When new order conflicts with existing lessons in the module
Example
```
const updatedLesson = await lessonService.updateLesson('lesson-intro-greetings', 'module-basic-conversation', {
  experience_points: 30,
  order: 2
});
```
- Defined in src/modules/content/services/LessonService.ts:258

deleteLesson

deleteLesson(id: string, moduleId: string): Promise<void>
Permanently deletes a lesson and all its associated exercise assignments. Uses composite key lookup to prevent horizontal access vulnerabilities.

Validates lesson existence before deletion and ensures the operation completes successfully. This operation cascades to remove all lesson-exercise relationships.
Parameters
- id: string
  The unique lesson identifier
- moduleId: string
  The module identifier to ensure lesson belongs to the correct module
Returns Promise<void>
Resolves when deletion is complete
Throws
When lesson with the specified ID is not found or doesn't belong to the module

Throws
When deletion operation fails
Example
```
await lessonService.deleteLesson('lesson-intro-greetings', 'module-basic-conversation');
// Lesson and all its exercise assignments are now deleted
```
- Defined in src/modules/content/services/LessonService.ts:301

assignExerciseToLesson

assignExerciseToLesson(
lessonId: string,
data: AssignExerciseToLessonDto,
): Promise<LessonExercise>
Assigns an exercise to a lesson at a specific order position with comprehensive validation.

Validates both lesson and exercise existence, prevents duplicate assignments, and ensures order uniqueness within the lesson before creating the assignment relationship.
Parameters
- lessonId: string
  The unique lesson identifier
- data: AssignExerciseToLessonDto
  Exercise assignment data
  - exercise_id
    The unique exercise identifier to assign
  - order
    The order position of the exercise within the lesson
Returns Promise<LessonExercise>
The created lesson-exercise assignment relationship
Throws
When lesson with the specified ID is not found

Throws
When exercise with the specified ID is not found

Throws
When exercise is already assigned to the lesson

Throws
When order position is already occupied in the lesson
Example
```
const assignment = await lessonService.assignExerciseToLesson('lesson-intro-greetings', {
  exercise_id: 'exercise-translate-hello',
  order: 1
});
console.log(assignment.lesson_id); // 'lesson-intro-greetings'
console.log(assignment.exercise_id); // 'exercise-translate-hello'
```
- Defined in src/modules/content/services/LessonService.ts:346

unassignExerciseFromLesson

unassignExerciseFromLesson(lessonId: string, exerciseId: string): Promise<void>
Removes an exercise assignment from a lesson with validation.

Validates lesson and exercise existence, confirms the assignment relationship exists, and removes the lesson-exercise association.
Parameters
- lessonId: string
  The unique lesson identifier
- exerciseId: string
  The unique exercise identifier to unassign
Returns Promise<void>
Resolves when unassignment is complete
Throws
When lesson with the specified ID is not found

Throws
When exercise with the specified ID is not found

Throws
When exercise is not assigned to the lesson

Throws
When unassignment operation fails
Example
```
await lessonService.unassignExerciseFromLesson('lesson-intro-greetings', 'exercise-translate-hello');
// Exercise is now removed from the lesson
```
- Defined in src/modules/content/services/LessonService.ts:409

getLessonExercises

getLessonExercises(lessonId: string): Promise<LessonExercise[]>
Retrieves all exercises assigned to a specific lesson in their defined order.

Validates lesson existence and returns all lesson-exercise relationships sorted by their order position within the lesson.
Parameters
- lessonId: string
  The unique lesson identifier
Returns Promise<LessonExercise[]>
Array of lesson-exercise assignments ordered by position
Throws
When lesson with the specified ID is not found
Example
```
const exercises = await lessonService.getLessonExercises('lesson-intro-greetings');
exercises.forEach(ex => {
  console.log(`Exercise ${ex.exercise_id} at position ${ex.order}`);
});
```
- Defined in src/modules/content/services/LessonService.ts:467

reorderLessonExercises

reorderLessonExercises(lessonId: string, exerciseIds: string[]): Promise<void>
Reorders exercises within a lesson by updating their position sequence.

Validates lesson existence, ensures all provided exercise IDs are currently assigned to the lesson, validates completeness of the reorder list, and prevents duplicates before applying the new exercise order.
Parameters
- lessonId: string
  The unique lesson identifier
- exerciseIds: string[]
  Array of exercise IDs in their new desired order
Returns Promise<void>
Resolves when reordering is complete
Throws
When lesson with the specified ID is not found

Throws
When provided exercise IDs are not assigned to the lesson

Throws
When reorder list is incomplete (missing currently assigned exercises)

Throws
When duplicate exercise IDs are provided in the reorder list

Throws
When reordering operation fails
Example
```
// Reorder exercises in a lesson
await lessonService.reorderLessonExercises('lesson-intro-greetings', [
  'exercise-translate-hello',
  'exercise-fill-blank-greeting',
  'exercise-match-responses'
]);
// Exercises are now in the specified order
```
- Defined in src/modules/content/services/LessonService.ts:506

reorderLessons

reorderLessons(moduleId: string, lessonIds: string[]): Promise<void>
Reorders lessons within a module by updating their position sequence.

Validates module existence, ensures all provided lesson IDs are currently assigned to the module, validates completeness of the reorder list, and prevents duplicates before applying the new lesson order.
Parameters
- moduleId: string
  The unique module identifier
- lessonIds: string[]
  Array of lesson IDs in their new desired order
Returns Promise<void>
Resolves when reordering is complete
Throws
When module with the specified ID is not found

Throws
When provided lesson IDs are not assigned to the module

Throws
When reorder list is incomplete (missing currently assigned lessons)

Throws
When duplicate lesson IDs are provided in the reorder list

Throws
When reordering operation fails
Example
```
// Reorder lessons in a module
await lessonService.reorderLessons('module-basic-conversation', [
  'lesson-greetings',
  'lesson-introductions',
  'lesson-farewells'
]);
// Lessons are now in the specified order
```
- Defined in src/modules/content/services/LessonService.ts:586

Class LessonService

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns LessonService

Methods

createLesson

Parameters

Returns Promise<Lesson>

Throws

Throws

Throws

Example

getLesson

Parameters

Returns Promise<Lesson>

Throws

Example

getLessonsByModule

Parameters

page

limit

sortBy

sortOrder

Returns Promise<PaginatedResult<Lesson>>

Throws

Example

getLessons

Parameters

page

limit

sortBy

sortOrder

filters

Returns Promise<PaginatedResult<Lesson>>

Example

updateLesson

Parameters

experience_points

order

Returns Promise<Lesson>

Throws

Throws

Example

deleteLesson

Parameters

Returns Promise<void>

Throws

Throws

Example

assignExerciseToLesson

Parameters

exercise_id

order

Returns Promise<LessonExercise>

Throws

Throws

Throws

Throws

Example

unassignExerciseFromLesson

Parameters

Returns Promise<void>

Throws

Throws

Throws

Throws

Example

getLessonExercises

Parameters

Returns Promise<LessonExercise[]>

Throws

Example

reorderLessonExercises

Parameters

Returns Promise<void>

Throws