Time Generator - Typescript

This is a library of generators and time description objects that can be used to create repeating calendar entries based on different repetition rules, along with ways to index into those entries absolutely.

This is primarily intended as a set of utilities for generating availability calendars or other repeating events that can be defined simply (ie. iCalendar RRules) and then reified into specific datetime ranges that can subsequently be compared to, intersected, or unioned with other repeating intervals.

Time Descriptions

A time description is an alternative to iCalendar RRules for specifying a repeating interval as a plain JSON object. It also does not make the assumption that the interval is a calendar event, rather they are more intended to be used to express availability periods that could become calendar events.

As a simple example, an individual might have availability "every day from 8am to 10am". Given a starting reference time of 2026-02-12T00:00 this description would generate the time intervals:

• [2026-02-12T08,2026-02-12T10:00)
• [2026-03-12T08,2026-03-12T10:00)
• [2026-04-12T08,2026-04-12T10:00)
• [2026-05-12T08,2026-05-12T10:00)
• ... and so on

Given another time description with a generated set of intervals those interval sets can be intersected, unioned, etc. to create more complex schedules and interval descriptions.

When working with reified times this library utilizes Luxon DateTime objects, but it also supports some more esoteric operations using generalized time descriptions, such as "08:00 on the third Sunday of every month until the first Tuesday of the following month". These can then be reified into an explicit DateTime interval based on a reference time to determine, for instance, what the first occurrence of that interval would be after March 3rd, 2023, PST.

This makes no attempt to save the user from specifying bizarre and potentially impossible time intervals, and makes no guarantee that every possible interval combination will generate something sensible.

Following are descriptions of each of the time objects and what they represent. All of them can be combined with the Walltime object to describe a specific time on a specific day.

Absolute Time Description

Absolute time descriptions specify a specific time that is only marginally related to the reference time insofar as it will be the first instance after or before the reference time. The first instance of July 10th will be the same if we ask for the first one after 2025-05-02 at 08:00, or after 2025-06-01 at 10:00.

Timestamp

The most absolute time unit that exists; it is a specific UTC timestamp.

This is the only time description that does not (and cannot) repeat, and only exists to permit an absolutely specified datetime to be used in conjunction with the rest of the time descriptions.

Walltime

This is a timezone-unaware hour and minute value, eg. "Every day at 11:34".

Day

A specific day in an indeterminate month and year. eg. "Every month on the fifth".

MonthDay

A specific day on a specific month in an indeterminate year. eg. "Every year on March 3rd".

MonthWeekday

A specific day of the week offset from the first of the month. eg. "The fourth Thursday in November every year".

Weekday

A specific day of the week. eg. "Every Wednesday".

Offset Time Objects

Offset time objects describe a time that is contingent on the reference time. "in two weeks" will be different if our reference time is 2025-05-02 at 08:00 or 2025-05-03 at 07:00. Offset times are typically used as the end for an interval in situations where the Absolute time is a bit more nebulous. For instance, if you want to express "Fourth Thursday in November to the following Sunday", you cannot necessarily specify both ends of that interval absolutely. "Fourth Thursday in November to the Fourth Sunday in November" is not necessarily the same time range. Take November 2025, for example. The fourth Thursday is the 28th, but the fourth Sunday is the 24th. In reality, we want the Sunday three days after the 28th. This is even further complicated by the fact that the Sunday in question is actually December 1st.

In comes an Offset time to save the day. By using a "WeekdayOffset", we can specify that we want the Sunday 0 weeks away from our start time. In this way we only have to use an absolute time for start, and then end can be based on that time.

WeekdayOffset

A particular weekday some number of weeks away from the reference time. eg. "Four Fridays from now."