TravelTimeService

Overview

TravelTimeService validates that a person's schedule allows sufficient travel time between bookings on different campuses. It uses a configurable travel time matrix to determine required transit durations.

This service is optional. It is only registered when travelTimeMatrix is provided in the module options.

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

Methods

validatePersonSchedule

Validate that a proposed booking does not violate travel time constraints for a person. Gets all bookings for the person on the same day, inserts the proposed booking, and checks each adjacent pair. If two adjacent bookings are on different campuses, the gap between them must be greater than or equal to the required travel time.

async validatePersonSchedule(
    personId: string,
    proposedBooking: { roomId: string; startsAt: Date; endsAt: Date },
): Promise<TravelTimeValidationResult>

Parameter	Type	Description
`personId`	`string`	The person whose schedule to validate
`proposedBooking`	`{ roomId: string; startsAt: Date; endsAt: Date }`	The proposed booking to validate

const result = await travelTimeService.validatePersonSchedule('person-1', {
    roomId: 'room-b1',
    startsAt: new Date('2026-03-02T10:00:00'),
    endsAt: new Date('2026-03-02T11:00:00'),
});

if (!result.valid) {
    for (const violation of result.violations) {
        console.log(
            `Cannot travel from ${violation.fromCampus} to ${violation.toCampus}: ` +
            `need ${violation.requiredMinutes}min, only ${violation.availableMinutes}min available ` +
            `(conflicts with booking ${violation.conflictingBookingId})`
        );
    }
}

getTravelTime

Get the travel time between two locations. Resolves both locations to their campus ancestors and looks up the travel time in the matrix. Both orderings of the campus pair are checked.

async getTravelTime(fromLocationId: string, toLocationId: string): Promise<number | null>

Parameter	Type	Description
`fromLocationId`	`string`	Origin location node ID
`toLocationId`	`string`	Destination location node ID

Returns the travel time in minutes, or null if no data is available for the campus pair.

const minutes = await travelTimeService.getTravelTime('room-a1', 'room-b1');
if (minutes !== null) {
    console.log(`Travel time: ${minutes} minutes`);
}

TravelTimeValidationResult

interface TravelTimeValidationResult {
    valid: boolean;
    violations: TravelTimeViolation[];
}

TravelTimeViolation

interface TravelTimeViolation {
    fromCampus: string;
    toCampus: string;
    requiredMinutes: number;
    availableMinutes: number;
    conflictingBookingId: string;
}

Travel Time Matrix

The travel time matrix is provided via module options and uses a key format of "campusAId|campusBId". Both orderings are checked when looking up travel times, so you only need to define each pair once.

RoomKitModule.forRoot({
    travelTimeMatrix: {
        'campus-north|campus-south': 30,
        'campus-north|campus-downtown': 45,
        'campus-south|campus-downtown': 20,
    },
    // ...other options
});