date+: Javascript Temporal rules vs ISO 8601 rules Peter McGoron 14 Nov 2026 01:23 UTC

Currently, the SRFI uses ISO 8601’s rules (for my purposes I am
following CalConnect 18011-2019, which you don’t have to pay for[1]) for
the addition of dates. Javascript’s Temporal [2] uses a different
algorithm than ISO 8601.

In short, Javascript:

1. Adds years.
2. Adds months, adjusting the years up.
3. If the day number is greater than the number of days in the month,
set it to the maximum valid day number. Otherwise keep it the same for now.
4. Add the days, adjusting up the month and the year as necessary.

In short, ISO 8601:

1. Adds each of year/month/day component-wise to the date.
2. Subtract days, carrying over into months, until a valid day number is
found.
3. Subtract months, carrying over into years, until a valid month number
is found.
4. If the day number is greater than the number of days in the month,
set it to the maximum valid day number.

These two algorithms go in different directions. Javascript goes from
years to days (and back again), while ISO 8601 adds everything at once,
and then goes from days to years. In ISO 8601 parlance, the Javascript
algorithm makes all durations a precedence duration[3].

I personally like the Javascript algorithm more than the ISO 8601
algorithm. The Javascript algorithm is easier to understand, because the
upper year/month combination is already resolved to sufficient
information to calculate the correct number of days in the month.

The issue with choosing among all of these algorithms is that what is
meant by adding units of time to a date is not clear. For example: say I
want to add 1 year and 1 day to 2026-02-29 (leap day). The ISO algorithm
would do

     2026-2-29 + 1Y1D
     → 2027-02-30
     → 2027-03-02

While the Javascript algorithm would do

     2026-02-29 + 1Y1D
     → 2027-02-29
     → 2027-02-28 (clamp)
     → 2027-03-01 (add day, carry over)

Another example: add 1 month to 2026-01-31.

ISO: 2026-01-31 + 1M → 2026-02-31 → 2026-03-02
Javascript: 2026-01-31 + 1M → 2026-02-31 → 2026-02-28

I think Javascript gives the more reasonable answers here, but there is
no right answer.

So which one of these algorithms should the SRFI use? It’s possible to
implement either of these using (srfi 285 date), but having the built-in
ability to add dates sounds useful.

[1]: https://standards.calconnect.org/docs/cc-18011-2018.html#evaluation
[2]:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/add
[3]:
https://standards.calconnect.org/docs/cc-18011-2018.html#calculation-precedence

-- Peter McGoron