Design Decisions

How can we represent time in these tools?

Much of the code written for these study tools relies on having a consistent representation of time. What data type should we use? Here are a few options that were considered:

• Javascript Date objects: Initially, date objects sounded appealing because we are working with dates after all, and they are well supported in the library we are using for our plots. However, Javascript dates are a pain to work with. They are influenced by timezones and do not have much support for ancient dates (e.g. B.C.E.). Obviously, we'd like to display time using the Gregorian calendar but it doesn't seem like the best choice for the underlying data type.

• Year: In the early stages of developing these tools, we started using the year as the plotted value to get something up and running. This worked fine since we were just plotting an integer. However, we need more than year granularity.

• Julian Day Number (JDN): Plotting a number much simpler than a Date object. It also gives us more flexibility if we ever want to change to a charting library that does not have good support for dates. Any charting library will support numbers. It turns out that there is a standard representation called Julian Day Number. The Julian Day Number (JDN) starts at noon on November 24, 4714 BCE on the Gregorian calendar (JDN 0), which is convenient for our purposes because the dates we are working with will typically be after that. Each day forward in time simply increments the JDN by 1, making time calculations straightforward. Time of day is represented as the fractional portion of the number. JDN is frequently used in astronomy. So, there are libraries that use JDN to calculate astronomical events like equinoxes and solstices, which will come in handy for calculating dates on the Hebrew calendar.

So based on these options, we went with JDN as the standard time representation.