Custom Priority Configuration

Overview

RoomKit's priority system determines which booking wins when a conflict occurs. Each booking is assigned a priority weight based on its purposeType, and higher weights take precedence during conflict resolution.

Default Priority Tiers

RoomKit ships with four default tiers, seeded automatically when you configure priorities in the module options:

The fallback weight is 25 — any unrecognized purposeType resolves to this value.

Configuring Custom Tiers

At Module Registration

RoomKitModule.register({
    storage: adapter,
    priorities: [
        { name: 'EXAM', weight: 200 },
        { name: 'LECTURE', weight: 100 },
        { name: 'SEMINAR', weight: 75 },
        { name: 'LAB', weight: 60 },
        { name: 'STUDY_GROUP', weight: 50 },
        { name: 'OFFICE_HOURS', weight: 40 },
        { name: 'OPEN', weight: 25 },
    ],
});

At Runtime

Use the PriorityService to add or update tiers:

import { PriorityService } from '@hfu.digital/roomkit-nestjs';

@Controller('admin')
export class AdminController {
    constructor(private readonly priorityService: PriorityService) {}

    @Post('priorities')
    async upsertTier(@Body() body: { name: string; weight: number }) {
        return this.priorityService.upsert(body);
    }

    @Get('priorities')
    async listTiers() {
        return this.priorityService.getAll();
    }
}

How Priority Resolution Works

1. When BookingService.create() is called, it checks if an explicit priority was provided in the DTO
2. If not, it calls PriorityService.resolve(purposeType) to look up the weight by name (case-insensitive)
3. If no matching tier is found, the fallback weight of 25 is used
4. The resolved weight is stored on the booking

Conflict Resolution by Priority

When ConflictService.resolveByPriority() is called:

1. The priority weights of both bookings are compared
2. The booking with the higher weight wins
3. If weights are equal, the existing booking wins (first-come-first-served)
4. The loser is either rejected (if new) or displaced (if existing)

const resolution = conflictService.resolveByPriority(existingBooking, newBooking);

// resolution.winner: "existing" | "new"
// resolution.action: "reject_new" | "displace_existing"
// resolution.alternatives: AlternativeSuggestion[]

Best Practices

• Keep weights spaced apart (multiples of 25) to leave room for new tiers
• Use meaningful names that map to your institution's booking categories
• Exam-related bookings should have the highest weight to prevent displacement
• Consider your institution's policies when deciding tie-breaking behavior