Overview The Reservations API manages table reservations with real-time availability checking, capacity planning, and conflict detection. It integrates with the Tables and Orders APIs to ensure accurate table status.
Reservation Management getReservationsFromCache Retrieves reservations from in-memory cache synchronously.
export const getReservationsFromCache = () : Reservation []
Array of reservations sorted by reservation time
fetchAndCacheReservations Fetches reservations from Firebase and updates caches.
export const fetchAndCacheReservations = async () : Promise < Reservation []>
addReservation Creates a new table reservation.
export const addReservation = async ( reservationData : Omit < Reservation , 'id' | 'status' | 'createdAt' | 'statusHistory' | 'finishedAt' > ): Promise < Reservation >
ISO timestamp for reservation (e.g., “2024-03-08T20:00:00.000Z”)
Array of table IDs to reserve
Special notes or requests
Associated order ID if order was placed
Created reservation with:
Generated ID (format: RES-{timestamp}-{random})
Initial status: ReservationStatus.PENDING
Status history initialized
import { addReservation , CreatedBy } from './services/reservationService' ; const reservation = await addReservation ({ customerName: "María González" , customerPhone: "+5491145678901" , guests: 4 , reservationTime: "2024-03-10T20:30:00.000Z" , tableIds: [ "T1" , "T2" ], notes: "Ventana si es posible" , createdBy: CreatedBy . WEB_ASSISTANT }); console . log ( 'Reservation created:' , reservation . id );
updateReservation Updates an existing reservation.
export const updateReservation = async ( updatedReservation : Reservation ) : Promise < Reservation >
Complete reservation object with all fields
updateReservationStatus Updates reservation status with optional cancellation reason.
export const updateReservationStatus = async ( reservationId : string , status : ReservationStatus , cancellationReason ?: ReservationCancellationReason ): Promise < Reservation >
status
ReservationStatus
required
New status
cancellationReason
ReservationCancellationReason
Required when status is CANCELLED
Behavior:
Cannot update finished reservations
Sets finishedAt timestamp for terminal statuses
Sends notification on status change
Adds status to history
import { updateReservationStatus , ReservationStatus , ReservationCancellationReason } from './services/reservationService' ; // Confirm reservation await updateReservationStatus ( "RES-1709876543210-xyz45" , ReservationStatus . CONFIRMED ); // Cancel reservation await updateReservationStatus ( "RES-1709876543210-xyz45" , ReservationStatus . CANCELLED , ReservationCancellationReason . USER );
deleteReservation Deletes a reservation by ID.
export const deleteReservation = async ( reservationId : string ) : Promise < void >
Availability & Capacity Planning findAvailableTables Finds suitable tables for a reservation based on guest count and time.
export const findAvailableTables = ( time : Date , guests : number , reservationToIgnoreId ?: string ): string [] | null
Reservation ID to exclude from availability check (useful when updating existing reservation)
Array of table IDs that can accommodate the guests
null if no suitable tables available Selection Logic:
Tries to find single table with sufficient capacity (prefers smallest fitting table)
If no single table fits, combines multiple tables
Returns null if capacity cannot be met
import { findAvailableTables } from './services/reservationService' ; const time = new Date ( '2024-03-10T20:30:00' ); const tableIds = findAvailableTables ( time , 6 ); if ( tableIds ) { console . log ( 'Available tables:' , tableIds ); } else { console . log ( 'No availability for 6 guests at that time' ); }
Conflict Detection:
Checks existing reservations for table conflicts
Checks active dine-in orders occupying tables
Uses reservation duration from settings
Filters out tables that don’t allow reservations
getAvailability Gets all available time slots for a date and party size.
export const getAvailability = ( date : Date , guests : number ) : string []
Target date for reservation
Array of available time slots in “HH:MM” format (e.g., [“19:00”, “19:30”, “20:00”])
Algorithm:
Gets business hours schedule for the day
Checks for schedule exceptions (holidays, special hours)
Generates time slots based on slotInterval setting (default: 30 minutes)
Filters out slots before minimum booking time
Checks table availability for each slot
Returns only slots where tables are available
import { getAvailability } from './services/reservationService' ; const date = new Date ( '2024-03-10' ); const slots = getAvailability ( date , 4 ); console . log ( 'Available slots:' , slots ); // ["19:00", "19:30", "20:00", "20:30", "21:00"]
This function respects:
Business hours and schedule exceptions
Minimum booking time (can’t book too close to current time)
Existing reservations and active orders
Tables that allow reservations
Reservation Settings getReservationSettings Gets current reservation settings from cache.
export const getReservationSettings = () : ReservationSettings
Current reservation configuration
fetchAndCacheReservationSettings Fetches settings from Firebase.
export const fetchAndCacheReservationSettings = async () : Promise < ReservationSettings >
saveReservationSettings Updates reservation settings.
export const saveReservationSettings = async ( settings : ReservationSettings ) : Promise < void >
settings
ReservationSettings
required
Reservation duration in minutes (default: 90)
Minimum advance booking time in minutes (default: 60)
Minutes before reservation to block table (default: 60)
Additional blocking time in minutes (default: 30)
Minutes before reservation when modifications are locked (default: 60)
Time slot interval in minutes (default: 30)
import { saveReservationSettings } from './services/reservationService' ; await saveReservationSettings ({ duration: 120 , minBookingTime: 90 , initialBlockTime: 60 , extensionBlockTime: 30 , modificationLockTime: 60 , slotInterval: 30 });
TypeScript Types ReservationStatus Enum enum ReservationStatus { PENDING = 'Pendiente' , CONFIRMED = 'Confirmada' , SEATED = 'Sentado' , COMPLETED = 'Completada' , CANCELLED = 'Cancelada' , NO_SHOW = 'No Se Presentó' }
ReservationCancellationReason Enum enum ReservationCancellationReason { USER = 'Cancelado por el cliente' , ADMIN = 'Cancelado por el local' , SYSTEM = 'Cancelado por el sistema' }
Reservation Interface interface Reservation { id : string ; customerName : string ; customerPhone ?: string ; guests : number ; reservationTime : string ; // ISO timestamp tableIds : string []; status : ReservationStatus ; statusHistory : StatusHistory []; finishedAt : string | null ; cancellationReason ?: ReservationCancellationReason ; notes ?: string ; createdAt : string ; orderId ?: string ; createdBy : CreatedBy ; }
ReservationSettings Interface interface ReservationSettings { duration : number ; // minutes minBookingTime : number ; // minutes initialBlockTime : number ; // minutes extensionBlockTime : number ; // minutes modificationLockTime : number ; // minutes slotInterval : number ; // minutes }
Workflow Example Complete Reservation Flow import { getAvailability , findAvailableTables , addReservation , updateReservationStatus , ReservationStatus , CreatedBy } from './services/reservationService' ; // 1. Check availability const date = new Date ( '2024-03-10' ); const guests = 4 ; const availableSlots = getAvailability ( date , guests ); if ( availableSlots . length === 0 ) { console . log ( 'No availability for that date' ); return ; } // 2. Find tables for chosen time const chosenTime = new Date ( `2024-03-10T ${ availableSlots [ 0 ] } :00` ); const tableIds = findAvailableTables ( chosenTime , guests ); if ( ! tableIds ) { console . log ( 'Tables no longer available' ); return ; } // 3. Create reservation const reservation = await addReservation ({ customerName: "Carlos Ruiz" , customerPhone: "+5491156789012" , guests , reservationTime: chosenTime . toISOString (), tableIds , createdBy: CreatedBy . WEB_ASSISTANT }); // 4. Confirm reservation await updateReservationStatus ( reservation . id , ReservationStatus . CONFIRMED ); console . log ( 'Reservation confirmed:' , reservation . id );
