Calendar Availability Service

Project roadmap

1. 01

   Define the request and response

   ~1.5h

   Write API.md: POST /availability takes participants (each with a time zone, working hours per weekday and a list of busy intervals as ISO timestamps), a search window, the meeting length, a slot step (such as 15 minutes), an optional buffer between meetings and a maximum number of results; it returns candidate slots sorted by start time, with a short reason when none exist. Write the Zod schemas for these, with refinements (end after start, lengths within limits). Done when: API.md and the schemas describe the whole contract.

2. 02

   Merge busy intervals

   ~1.5h

   Write pure functions: normalize intervals to UTC milliseconds, sort them and merge overlapping or touching intervals, and add the buffer around each busy interval. Done when: unit tests cover overlapping, touching, nested and unsorted intervals.

3. 03

   Apply working hours and time zones

   ~2.5h

   Turn each participant's working hours into intervals for every day in the search window in their own time zone (using a library such as Luxon or date-fns-tz, or the Temporal API when available), treating time outside working hours as busy. Handle daylight saving changes (a 09:00 start is still 09:00 local time after the clocks change). Done when: tests show working hours are correct across a daylight saving change for two different time zones.

4. 04

   Find the free slots

   ~2h

   Combine everyone's busy intervals, compute the gaps inside the search window, and cut each gap into candidate slots of the meeting length, aligned to the slot step. Sort by start time and return the first N. The same input must always produce exactly the same output. Done when: tests with several participants return the expected slots, and repeated calls give identical results.

5. 05

   Build the HTTP API

   ~1.5h

   Serve POST /availability with a small Node.js HTTP server (or a framework such as Fastify), validating the body with Zod and returning 400 with the field errors when it's invalid. Limit the search window (for example to 31 days) and the number of participants and busy intervals, so one request can't use too much CPU. Done when: valid requests return slots, and invalid ones return clear 400 errors.

6. 06

   Build a React preview page

   ~2h

   Build a small React page where you can enter participants and their busy times (or load an example), call the API, and see a timeline for each day with busy blocks per person and the suggested slots highlighted, shown in the viewer's time zone. Done when: the page shows the slots visually and matches the API's answer.

7. 07

   Test edge cases

   ~2h

   Write Vitest tests for: no free time at all, a slot exactly the meeting length, buffers, participants in time zones on different days, daylight saving transitions, a search window starting mid-slot, and validation errors. Add a property-based test (with fast-check) checking that no returned slot ever overlaps anyone's busy time. Done when: npm test passes.

Resources

• DocsZod documentation
• DocsLuxon: time zones
• ArticleMerge intervals problem explained
• Docsfast-check documentation
• DocsVitest: getting started