I only have time for a quick glance, but this catched my eye instantly:

  april+1M returns 2021-05-02

Well, months are the worst beasts of all of date parts. This tool doesn’t seem to handle them if not well then at least intuitive. Adding a month to april cannot result in may 2 in a sensible way.

Some text editors have a similar feature for text lines. If you put your cursor at some column (including last one), then when moving up and down they try to retain that column if possible. E.g.

  short lin<cursor>e</cursor>
  longer line
  shrt

When you move down, a cursor selects “n” and then “t”. When you move back up, it selects “n” again and “e” again.

But if you place it at the end of line with ‘End’ key, it goes to the last char on every line when you move up/down. This is done by maintaining additional isAtEnd flag, until it is reset by a horizontal movement.

Month-to-day calculations should not add average (or now-related?) values to do a sensible thing. If you add month to a date (which for “april” I believe is “april 1”), it should just jump to “next-month 1”. If you add month to “march 31”, it should detect that it’s an end of month, and jump to “april 30” retaining isAtEnd until it’s reset by non-month operation, so +1M again gives “may 31”, and then -3M gives “feb 28(29)”. OR there should be a way to turn off “sticky end of month” mode. In no case that can result in “may 2”. Unless I’m missing something.

(I’ve made a similar library around ten years ago but never published it. It was designed for leasing contracts which love to use “a thursday before or including the fifth last day of a month next to the month in which insurance was paid” statements for their terms.