Schedule events library

This library allows you to schedule recurring (multi day) events. For any given recurring event that conflicts with your wishes, you can provide an exception.

This library is providing the retreat schedule at Lambda Zen Temple on https://zen-temple.net.

Tests

Tests are written in Jest.

make test

Usage

populateSchedule({ nthDay, months, firstDay, secondDay, exceptions, numberOfResults })

Parameters:

• nthDay: The nth day of the event (0-indexed)
• months: An array of booleans representing the months in which the event should take place. The array should have 12 elements with the first element representing January and the last element representing December.
• firstDay: An object containing the day of the week of the first day of the event (0-indexed, with 0 being Sunday and 6 being Saturday)
• secondDay: An object containing the number of days later after the first day of the event
• exceptions: An array of objects containing special dates that override the regular start and end dates. Each exception object should contain a regularStart property (in the format of YYYY-MM-DD) and a startDay and endDay properties (in the format of YYYY-MM-DD).
• numberOfResults: Number of event results to be returned.

Both firstDay and secondDay take hours, minute and a locale option to configure at what time the event starts/stops and for what audience the result is intended. The locale follows the Intl.DateTimeFormat convention.

Examples

Schedule without overriding dates

populateSchedule({
      // Get the third Friday of the month - and the second day three days later.
      nthDay: 2,
      firstDay: { day: 5, hours: 10, minute: 0, locale: "en-US" },
      secondDay: { daysLater: 2, hours: 15, minute: 0, locale: "en-US" },
      // All twelve months are relevant
      months: [
        true,
        true,
        true,
        true,
        true,
        true,
        true,
        true,
        true,
        true,
        true,
        true,
      ],
      numberOfResults: 5
});

This will schedule recurring events for the 3rd Friday of the month until the following Sunday for every month of the year. The events will start on Friday at 10 am and end on Sunday at 3 pm. The format of the date will be in “en-US” style. Here’s the result:

• [“Fri, 1/20/2023, 10:00 AM”, “Sun, 1/22/2023, 3:00 PM”],
• [“Fri, 2/17/2023, 10:00 AM”, “Sun, 2/19/2023, 3:00 PM”],
• [“Fri, 3/17/2023, 10:00 AM”, “Sun, 3/19/2023, 3:00 PM”],
• [“Fri, 4/21/2023, 10:00 AM”, “Sun, 4/23/2023, 3:00 PM”],
• [“Fri, 5/19/2023, 10:00 AM”, “Sun, 5/21/2023, 3:00 PM”],

Example with overriding exceptional dates

populateSchedule({
      // Get the first Monday of the month - and the second day six days later.
      nthDay: 0,
      firstDay: { day: 1, hours: 19, minute: 0, locale: "en-US" },
      secondDay: { daysLater: 6, hours: 11, minute: 0, locale: "en-US" },
      // May and August are relevant
      months: [
        false,
        false,
        false,
        false,
        true,
        false,
        false,
        true,
        false,
        false,
        false,
        false,
      ],
      numberOfResults: 5,
      exceptions: [
        // The pilgrim retreat and the monthly retreat would
        // only be 5 days apart.
        {
          regularStart: "2023-08-07",
          startDay: "2023-07-31",
          endDay: "2023-08-06",
        },
      ],
})

This will schedule a 7-day event starting the first Monday of the month for May and August and return 5 results. But the event for the 1st Monday of August would start at “Mon, 8/7/2023, 7:00 PM”. Given that you don’t want to schedule at that time, you can override it and give it a different date, yielding this result:

• [“Mon, 5/1/2023, 7:00 PM”, “Sun, 5/7/2023, 11:00 AM”],
• [“Mon, 7/31/2023, 7:00 PM”, “Sun, 8/6/2023, 11:00 AM”],
• [“Mon, 5/6/2024, 7:00 PM”, “Sun, 5/12/2024, 11:00 AM”],
• [“Mon, 8/5/2024, 7:00 PM”, “Sun, 8/11/2024, 11:00 AM”],
• [“Mon, 5/5/2025, 7:00 PM”, “Sun, 5/11/2025, 11:00 AM”],