payload-reserve 2.3.0 → 3.0.0

package/dist/services/AvailabilityService.js

@@ -1,3 +1,4 @@
+import { NOOP_RESERVE_DEBUG } from '../utilities/reserveDebug.js';
 import { resolveReservationItems } from '../utilities/resolveReservationItems.js';
 import { isExceptionDate, resolveScheduleForDate } from '../utilities/scheduleUtils.js';
 import { addMinutes, computeBlockedWindow, doRangesOverlap, intersectIntervals } from '../utilities/slotUtils.js';
@@ -148,12 +149,23 @@ export function buildOverlapQuery(params) {
     }
     return occupancies;
 }
-/** Occupancy a single fetched reservation imposes on `resourceId`. */ export async function reservationOccupancies(params) {
+/**
+ * Occupancy a single fetched reservation imposes on `resourceId`.
+ *
+ * Resolves `reservation` LENIENTLY: this is a stored document, which — unlike
+ * a write in progress — can carry an inverted top-level window from a
+ * `context.skipReservationHooks` write or data predating that check. Lenient
+ * mode skips parent synthesis instead of throwing, so a malformed top-level
+ * window never discards the real `items[]` occupancies also present on the
+ * same row (see the lenient-mode note in resolveReservationItems.ts).
+ */ export async function reservationOccupancies(params) {
     const { bufferFor, capacityMode, reservation, resourceId } = params;
     return itemsToOccupancies({
         bufferFor,
         capacityMode,
-        items: resolveReservationItems(reservation),
+        items: resolveReservationItems(reservation, {
+            lenient: true
+        }),
         resourceId
     });
 }
@@ -180,7 +192,8 @@ export function validateTransition(fromStatus, toStatus, statusMachine) {
 }
 // --- DB functions (use Payload Local API only) ---
 export async function checkAvailability(params) {
-    const { blockingStatuses, bufferAfter, bufferBefore, endTime, excludeReservationId, getExternalBusy, guestCount, payload, req, reservationSlug, resourceId, resourceSlug, servicesSlug, siblingItems, startTime } = params;
+    const { blockingStatuses, bufferAfter, bufferBefore, debug, endTime, excludeHoldToken, excludeReservationId, getExternalBusy, guestCount, holdsSlug, payload, req, reservationSlug, resourceId, resourceSlug, servicesSlug, siblingItems, startTime } = params;
+    const trace = debug ?? NOOP_RESERVE_DEBUG;
     // Fetch resource for quantity and capacity mode
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const resource = await payload.findByID({
@@ -194,19 +207,29 @@ export async function checkAvailability(params) {
     // Candidate window expanded by its own buffers
     const { effectiveEnd: candidateEnd, effectiveStart: candidateStart } = computeBlockedWindow(startTime, endTime, bufferBefore, bufferAfter);
     // Coarse superset fetch — precise per-item overlap is computed in memory below
+    const coarseWhere = buildCoarseOverlapQuery({
+        blockingStatuses,
+        candidateEnd,
+        candidateStart,
+        excludeReservationId,
+        resourceId
+    });
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const { docs } = await payload.find({
         collection: reservationSlug,
         depth: 0,
         limit: 0,
         req,
-        where: buildCoarseOverlapQuery({
-            blockingStatuses,
-            candidateEnd,
-            candidateStart,
-            excludeReservationId,
-            resourceId
-        })
+        where: coarseWhere
+    });
+    trace.dbg('check', {
+        blockingReservations: docs.length,
+        candidateEnd: candidateEnd.toISOString(),
+        candidateStart: candidateStart.toISOString(),
+        capacityMode,
+        coarseWhere,
+        quantity,
+        resourceId
     });
     // Per-call cache: fetch each distinct service's buffers at most once
     const bufferCache = new Map();
@@ -227,6 +250,9 @@ export async function checkAvailability(params) {
                     id: serviceId,
                     collection: servicesSlug,
                     depth: 0,
+                    // Skip the resources join — internal logic never reads it, and without this
+                    // every service read becomes an aggregation with a $lookup.
+                    joins: false,
                     req
                 });
                 if (service) {
@@ -235,19 +261,41 @@ export async function checkAvailability(params) {
                         before: service.bufferTimeBefore ?? 0
                     };
                 }
-            } catch  {
-            // service missing — no buffers
+            } catch (err) {
+                trace.dbg('error', {
+                    err,
+                    serviceId,
+                    where: 'bufferFor'
+                });
             }
         }
         bufferCache.set(key, result);
         return result;
     };
-    const fetchedOccupancies = (await Promise.all(docs.map((doc)=>reservationOccupancies({
+    // reservationOccupancies resolves each doc LENIENTLY (see its own doc
+    // comment) — an inverted top-level window on a stored row skips parent
+    // synthesis rather than throwing, so this never needs a try/catch: every
+    // real items[] occupancy on the row still comes back.
+    //
+    // SEQUENTIAL, not Promise.all, and that is load-bearing. Each iteration can
+    // reach `bufferFor` -> `payload.findByID` on the shared `req`, and this whole
+    // function runs inside the booking's own transaction on the write path. A
+    // MongoDB ClientSession cannot carry concurrent operations inside a
+    // transaction: when two do collide, the loser's `count`/`findByID` calls
+    // `killTransaction` from its own catch, which rolls back and clears the
+    // transaction the enclosing create/delete owns, and the survivor then reports
+    // `NoSuchTransaction` ("transaction number N does not match any in-progress
+    // transactions"). Buffers are per-service and cached, so the loop is at most
+    // one read per DISTINCT neighbouring service either way.
+    const fetchedOccupancies = [];
+    for (const doc of docs){
+        fetchedOccupancies.push(...await reservationOccupancies({
             bufferFor,
             capacityMode,
             reservation: doc,
             resourceId
-        })))).flat();
+        }));
+    }
     // Sibling items from the same booking (review A5) — expanded with the same
     // per-service buffers and capacity mode.
     const siblingOccupancies = siblingItems ? await itemsToOccupancies({
@@ -273,19 +321,102 @@ export async function checkAvailability(params) {
                     blockedStart: new Date(iv.start),
                     units: quantity
                 })).filter((o)=>!isNaN(o.blockedStart.getTime()) && !isNaN(o.blockedEnd.getTime()));
-        } catch  {
+        } catch (err) {
+            trace.dbg('error', {
+                err,
+                resourceId,
+                where: 'getExternalBusy'
+            });
             externalOccupancies = [];
         }
     }
+    // Unexpired slot holds occupy the resource exactly as a blocking reservation
+    // does. Expiry is a read-time predicate rather than a TTL index so the
+    // behaviour is identical on Mongo, Postgres and SQLite. `excludeHoldToken`
+    // is the bearer converting their OWN hold into a booking — without it the
+    // hold would block the very booking it was taken to protect.
+    const holdOccupancies = [];
+    if (holdsSlug) {
+        const holdWhere = {
+            and: [
+                {
+                    resource: {
+                        equals: resourceId
+                    }
+                },
+                {
+                    expiresAt: {
+                        greater_than: new Date().toISOString()
+                    }
+                },
+                {
+                    startTime: {
+                        less_than: candidateEnd.toISOString()
+                    }
+                },
+                {
+                    endTime: {
+                        greater_than: candidateStart.toISOString()
+                    }
+                },
+                ...excludeHoldToken ? [
+                    {
+                        token: {
+                            not_equals: excludeHoldToken
+                        }
+                    }
+                ] : []
+            ]
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { docs: holdDocs } = await payload.find({
+            collection: holdsSlug,
+            depth: 0,
+            limit: 0,
+            req,
+            where: holdWhere
+        });
+        // Sequential for the same reason the reservation loop above is: `bufferFor`
+        // reads through the shared `req`, and concurrent operations on one MongoDB
+        // session inside a transaction abort it.
+        for (const hold of holdDocs){
+            // Expand by the held service's own buffers, so a hold reserves the same
+            // real-world window the resulting booking will.
+            const { after, before } = await bufferFor(hold.service);
+            const { effectiveEnd, effectiveStart } = computeBlockedWindow(new Date(hold.startTime), new Date(hold.endTime), before, after);
+            holdOccupancies.push({
+                blockedEnd: effectiveEnd,
+                blockedStart: effectiveStart,
+                units: capacityMode === 'per-guest' ? hold.guestCount ?? 1 : 1
+            });
+        }
+        trace.dbg('check_holds', {
+            activeHolds: holdOccupancies.length,
+            resourceId
+        });
+    }
     const occupancies = [
         ...fetchedOccupancies,
         ...siblingOccupancies,
-        ...externalOccupancies
+        ...externalOccupancies,
+        ...holdOccupancies
     ];
     // Sum the units of every occupancy whose buffered window overlaps the candidate
     const currentUnits = occupancies.reduce((sum, occ)=>doRangesOverlap(candidateStart, candidateEnd, occ.blockedStart, occ.blockedEnd) ? sum + occ.units : sum, 0);
     const candidateUnits = capacityMode === 'per-guest' ? guestCount : 1;
     const available = currentUnits + candidateUnits <= quantity;
+    trace.dbg('check_result', {
+        available,
+        candidateUnits,
+        currentUnits,
+        occupancySources: {
+            external: externalOccupancies.length,
+            fetched: fetchedOccupancies.length,
+            sibling: siblingOccupancies.length
+        },
+        quantity,
+        resourceId
+    });
     return {
         available,
         currentCount: currentUnits,
@@ -294,14 +425,29 @@ export async function checkAvailability(params) {
     };
 }
 export async function getAvailableSlots(params) {
-    const { blockingStatuses, date, getExternalBusy, guestCount, payload, req, reservationSlug, resourceId, resourceIds, resourceSlug, scheduleSlug, serviceId, serviceSlug, timeZone } = params;
+    const { blockingStatuses, date, debug, enforceActive, getExternalBusy, guestCount, holdsSlug, payload, req, reservationSlug, resourceId, resourceIds, resourceSlug, scheduleSlug, serviceId, serviceSlug, timeZone } = params;
     const tz = timeZone ?? 'UTC';
     // Resolve the set of resources to intersect (single-resource callers still work)
     const ids = resourceIds && resourceIds.length > 0 ? resourceIds : resourceId !== undefined ? [
         resourceId
     ] : [];
+    const trace = (debug ?? NOOP_RESERVE_DEBUG).child({
+        resourceIds: ids,
+        serviceId
+    });
+    trace.dbg('input', {
+        date: date instanceof Date ? date.toISOString() : date,
+        guestCount: guestCount ?? 1,
+        timeZone: tz
+    });
     if (ids.length === 0) {
-        return [];
+        trace.dbg('empty', {
+            reason: 'no_resource_ids'
+        });
+        return {
+            reason: 'no_resource_ids',
+            slots: []
+        };
     }
     // 1. Service for duration + buffer times (from the primary service)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -309,45 +455,119 @@ export async function getAvailableSlots(params) {
         id: serviceId,
         collection: serviceSlug,
         depth: 0,
+        // Skip the resources join — internal logic never reads it, and without this
+        // every service read becomes an aggregation with a $lookup.
+        joins: false,
         req
     });
+    if (enforceActive !== false && service?.active === false) {
+        trace.dbg('empty', {
+            reason: 'service_inactive',
+            serviceId
+        });
+        return {
+            reason: 'service_inactive',
+            slots: []
+        };
+    }
     const duration = service.duration ?? 60;
     const bufferBefore = service.bufferTimeBefore ?? 0;
     const bufferAfter = service.bufferTimeAfter ?? 0;
     const durationType = service.durationType ?? 'fixed';
+    trace.dbg('service', {
+        bufferAfter,
+        bufferBefore,
+        duration,
+        durationType
+    });
     // 2. Per resource: fetch schedules and resolve to windows. A resource with >=1
     //    schedule is "schedule-bearing" and constrains time; a resource with zero
     //    schedules is capacity-only and contributes no time windows.
     const scheduleBearingWindowLists = [];
     for (const rid of ids){
+        // This read exists solely to feed the active check below — skip it
+        // entirely when enforceActive is off so an opted-out consumer doesn't pay
+        // for a findByID whose result is never read.
+        if (enforceActive !== false) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const resourceDoc = await payload.findByID({
+                id: rid,
+                collection: resourceSlug,
+                depth: 0,
+                // Skip joins — internal logic never reads them, and without this every
+                // resource read becomes an aggregation with a $lookup.
+                joins: false,
+                req
+            }).catch(()=>null);
+            if (resourceDoc?.active === false) {
+                trace.dbg('empty', {
+                    reason: 'resource_inactive',
+                    resourceId: rid
+                });
+                return {
+                    reason: 'resource_inactive',
+                    slots: []
+                };
+            }
+        }
+        const scheduleWhere = {
+            and: [
+                {
+                    resource: {
+                        equals: rid
+                    }
+                },
+                {
+                    active: {
+                        equals: true
+                    }
+                }
+            ]
+        };
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const { docs: schedules } = await payload.find({
             collection: scheduleSlug,
             depth: 0,
             limit: 100,
             req,
-            where: {
-                and: [
-                    {
-                        resource: {
-                            equals: rid
-                        }
-                    },
-                    {
-                        active: {
-                            equals: true
-                        }
-                    }
-                ]
-            }
+            where: scheduleWhere
+        });
+        trace.dbg('schedules', {
+            activeFlags: schedules.map((s)=>s.active),
+            resourceId: rid,
+            rowsFound: schedules.length,
+            scheduleWhere
         });
         if (!schedules || schedules.length === 0) {
+            trace.dbg('skip', {
+                reason: 'no_active_schedules',
+                resourceId: rid,
+                rowsFound: 0
+            });
             continue;
         }
         // A11: an exception on ANY of the resource's schedules makes the whole
         // resource unavailable that day — not just the schedule it's recorded on.
-        const exceptedToday = schedules.some((s)=>isExceptionDate(date, s.exceptions ?? [], tz));
-        if (exceptedToday) {
+        let matched;
+        for (const s of schedules){
+            const exs = s.exceptions ?? [];
+            if (isExceptionDate(date, exs, tz)) {
+                matched = {
+                    exception: exs.find((e)=>isExceptionDate(date, [
+                            e
+                        ], tz)),
+                    scheduleId: s.id
+                };
+                break;
+            }
+        }
+        if (matched) {
+            trace.dbg('skip', {
+                matchedException: matched.exception,
+                reason: 'date_excepted',
+                resourceId: rid,
+                scheduleId: matched.scheduleId
+            });
             scheduleBearingWindowLists.push([]);
             continue;
         }
@@ -355,11 +575,26 @@ export async function getAvailableSlots(params) {
         for (const schedule of schedules){
             windows.push(...resolveScheduleForDate(schedule, date, tz));
         }
+        trace.dbg('windows', {
+            resourceId: rid,
+            windowCount: windows.length,
+            windows: windows.map((w)=>({
+                    end: w.end.toISOString(),
+                    start: w.start.toISOString()
+                })),
+            windowsEmpty: windows.length === 0
+        });
         scheduleBearingWindowLists.push(windows);
     }
     // No resource constrains time → no basis for generating slots
     if (scheduleBearingWindowLists.length === 0) {
-        return [];
+        trace.dbg('empty', {
+            reason: 'no_windows'
+        });
+        return {
+            reason: 'no_windows',
+            slots: []
+        };
     }
     // 3. Intersect all schedule-bearing window lists
     let timeRanges = scheduleBearingWindowLists[0];
@@ -367,7 +602,17 @@ export async function getAvailableSlots(params) {
         timeRanges = intersectIntervals(timeRanges, scheduleBearingWindowLists[i]);
     }
     if (timeRanges.length === 0) {
-        return [];
+        trace.dbg('empty', {
+            perResourceWindows: scheduleBearingWindowLists.map((list)=>list.map((w)=>({
+                        end: w.end.toISOString(),
+                        start: w.start.toISOString()
+                    }))),
+            reason: 'empty_intersection'
+        });
+        return {
+            reason: 'empty_intersection',
+            slots: []
+        };
     }
     // 4. Candidate slot sizing
     // NOTE: epoch-trick sizing is only meaningful for fixed/flexible durations.
@@ -381,6 +626,11 @@ export async function getAvailableSlots(params) {
     });
     const slotDuration = Math.round(slotEndOffset.getTime() / 60_000);
     const effectiveDuration = durationType === 'fixed' ? duration : slotDuration;
+    trace.dbg('sizing', {
+        effectiveDuration,
+        slotDuration,
+        stepSize: Math.min(effectiveDuration, 15)
+    });
     // Helper: a window is available only if EVERY required resource is free
     const allAvailable = async (start, end, bBefore, bAfter)=>{
         for (const rid of ids){
@@ -388,9 +638,11 @@ export async function getAvailableSlots(params) {
                 blockingStatuses,
                 bufferAfter: bAfter,
                 bufferBefore: bBefore,
+                debug: trace,
                 endTime: end,
                 getExternalBusy,
                 guestCount: guestCount ?? 1,
+                holdsSlug,
                 payload,
                 req,
                 reservationSlug,
@@ -408,7 +660,9 @@ export async function getAvailableSlots(params) {
     const availableSlots = [];
     // Full-day: offer each range as a single slot if all resources are free
     if (durationType === 'full-day') {
+        let candidatesGenerated = 0;
         for (const range of timeRanges){
+            candidatesGenerated++;
             if (await allAvailable(range.start, range.end, 0, 0)) {
                 availableSlots.push({
                     end: range.end,
@@ -416,9 +670,21 @@ export async function getAvailableSlots(params) {
                 });
             }
         }
-        return availableSlots;
+        trace.dbg('result', {
+            candidatesAvailable: availableSlots.length,
+            candidatesGenerated,
+            durationType: 'full-day',
+            returnedCount: availableSlots.length
+        });
+        return {
+            ...availableSlots.length === 0 ? {
+                reason: 'all_slots_taken'
+            } : {},
+            slots: availableSlots
+        };
     }
     const stepSize = Math.min(effectiveDuration, 15);
+    let candidatesGenerated = 0;
     for (const range of timeRanges){
         let candidateStart = new Date(range.start);
         while(true){
@@ -426,6 +692,7 @@ export async function getAvailableSlots(params) {
             if (candidateEnd > range.end) {
                 break;
             }
+            candidatesGenerated++;
             if (await allAvailable(candidateStart, candidateEnd, bufferBefore, bufferAfter)) {
                 availableSlots.push({
                     end: candidateEnd,
@@ -435,7 +702,17 @@ export async function getAvailableSlots(params) {
             candidateStart = addMinutes(candidateStart, stepSize);
         }
     }
-    return availableSlots;
+    trace.dbg('result', {
+        candidatesAvailable: availableSlots.length,
+        candidatesGenerated,
+        returnedCount: availableSlots.length
+    });
+    return {
+        ...availableSlots.length === 0 ? {
+            reason: candidatesGenerated === 0 ? 'window_too_short' : 'all_slots_taken'
+        } : {},
+        slots: availableSlots
+    };
 }
 
 //# sourceMappingURL=AvailabilityService.js.map