How is data passed into the calendar methods?

[sffc]

With the conclusions from #290/#291 about the data model, it raises questions about how calendar methods receive and return data. The problem is illustrated by the following code, which, by the semantics in #290/#291, is an infinite loop:

const gregorian = {
  day: function(obj) {
    return obj.day;
  }
};

console.log(Temporal.Date.from({ calendar: gregorian }).day);

The calendar must have a way to get at the data in the isoYear/isoMonth/isoDay internal slots. We could do this by:

1. Adding public getters for those slots to Temporal.[Date][Time].prototype.
2. Passing raw objects to the calendar functions.
3. Adding Temporal.[Date][Time].prototype.raw, which is an immutable raw object containing the underlying data (isoYear, isoMonth, isoDay, etc).

With option 2, for example, the calendar methods would be passed an object with fields isoYear, isoMonth, isoDay, hour, minute, second, and so on. They would either return an option bag of the same format, or return a Temporal object created with the constructor. Returning the option bag has some ergonomic advantages, because the options bag can be mutated and then returned from the function. If we wanted to return a Temporal object, we should consider allowing the constructor to accept the option bag described above (with isoYear instead of year, etc).

Related: we need a .from() method in Temporal.Calendar in order to receive requests from the .from() method on the Temporal types. I suspect the implementation would be similar to the current toISO() function we have in there.

[ptomato]

Meeting, March 26: No general consensus yet, but we discussed some more details of option 2. In order to implement #391 the constructors of YearMonth and MonthDay would need to accept a third parameter as well as the calendar. If we chose option 2, then the consensus would be to make these parameters optional and place them after the calendar, e.g. new Temporal.MonthDay(isoMonth, isoDay, calendar = ..., refIsoYear = 2000) and new Temporal.YearMonth(isoYear, isoMonth, calendar = ..., refIsoDay = 1).

[ptomato]

To continue the discussion, I'm personally in favour of option 2 because I think it has the least effect on the API. My preference would be to change the API as little as possible so that non-calendar users of Temporal are not mystified by API parameters that are not relevant to them.

[sffc]

I have a preference for option 1.

• It's weird if you can set these slots in the constructor but then can't access them again later.
• Adding .isoYear/.isoMonth/.isoDay getters does not hurt ergonomics. It adds additional options that programmers will see in MDN.

No matter which option we choose, the correct MDN for the year/month/day getters should read,

.year returns the year portion of this date according the date's calendar system. This getter calls the .year function of the calendar field.

And similar for month and day. These are the semantics we already reached consensus on in previous issues such as #291. Not stating the calendar semantics of these getters in the MDN would be withholding key information, making it much more confusing to reason about the behavior when calendar systems are in play.

Option 1 in this thread would be adding new getters whose MDN is,

.isoYear returns the year portion of this date according to the ISO calendar system, as set in the constructor.

I find both of the getters perfectly clear and sensible.

[ptomato]

Meeting, Apr 2: The consensus is to go with option 3 as a middle ground between 1 and 2. It allows access to the information while at the same time is less likely to be misused by programmers who actually want the non-ISO getters. Instead of a date.raw getter we are making it a method date.getISOFields(), for consistency with date.getFields() (#403).

@sffc suggested after the meeting that unlike the object returned from getFields, we may want to allow this object to be immutable, for optimization purposes.

[littledan]

We've settled on getISOFields() as the mechanism here; the remaining task is to document in calendar-draft.md, which is nice to have.

[ptomato]

I forgot when discussing this the other day that we do actually have to implement the method as well, and it's a prerequisite for calendar support; so it's not just nice to have. Moving this into the Stable API milestone.