AvailabilityService

Overview

AvailabilityService provides compound room availability searches with scoring and a forward-scanning slot finder. It checks overlapping bookings, blackout windows, and operating hours.

import { AvailabilityService } from '@roomkit/nestjs';

Methods

search

Search for available rooms matching a set of filters. Results are scored by capacity fit and equipment match, and returned with cursor-based pagination.

async search(
    filters: AvailabilityFilter,
    pagination: Pagination,
): Promise<AvailabilityResult>

Parameter	Type	Description
`filters`	`AvailabilityFilter`	Compound search filters
`pagination`	`Pagination`	Cursor-based pagination options

How it works:

Filters rooms by capacity (seated, exam, or standing), equipment, accessibility, and location scope
Checks each candidate for overlapping bookings and blackout windows in the requested time range
Scores results by capacity fit and equipment match
Returns paginated results sorted by score

const result = await availabilityService.search(
    {
        timeRange: {
            startsAt: new Date('2026-03-02T14:00:00'),
            endsAt: new Date('2026-03-02T16:00:00'),
        },
        minCapacity: 20,
        capacityType: 'seated',
        requiredEquipment: ['projector', 'whiteboard'],
        requiredAccessibility: ['wheelchair'],
        locationScope: 'building-north',
    },
    { cursor: null, limit: 10 },
);

for (const room of result.items) {
    console.log(room.id, room.score);
}

findNextAvailable

Scan forward from a given time to find the next available slots for a specific room. Checks bookings, blackout windows, and operating hours.

async findNextAvailable(
    roomId: string,
    after: Date,
    duration: number,
    limit: number,
): Promise<TimeSlot[]>

Parameter	Type	Description
`roomId`	`string`	Room ID to scan
`after`	`Date`	Start scanning from this time
`duration`	`number`	Required slot duration in minutes
`limit`	`number`	Maximum number of slots to return

Scans forward in 30-minute increments for up to 14 days. Returns an array of TimeSlot objects representing available windows.

const slots = await availabilityService.findNextAvailable(
    'room-a1',
    new Date('2026-03-02T09:00:00'),
    60, // 60-minute slot
    3,  // return up to 3 slots
);

for (const slot of slots) {
    console.log(`${slot.startsAt} – ${slot.endsAt}`);
}

Throws RoomNotFoundError if the room does not exist.

AvailabilityFilter

interface AvailabilityFilter {
    timeRange: TimeRange;
    minCapacity?: number;
    capacityType?: 'seated' | 'exam' | 'standing';
    requiredEquipment?: string[];
    requiredAccessibility?: string[];
    locationScope?: string;
    excludeRoomIds?: string[];
}

Field	Type	Description
`timeRange`	`TimeRange`	Required time range to check availability for
`minCapacity`	`number`	Minimum room capacity
`capacityType`	`'seated' \| 'exam' \| 'standing'`	Which capacity metric to filter by
`requiredEquipment`	`string[]`	Equipment the room must have
`requiredAccessibility`	`string[]`	Accessibility features the room must have
`locationScope`	`string`	Location node ID to scope the search within
`excludeRoomIds`	`string[]`	Room IDs to exclude from results