What about the default calendar?

[sffc]

Calendar support has landed in Temporal. Now we need to decide on the default calendar.

Option 1 is for the API to always assume the ISO (Gregorian) calendar. The programmer can opt-in to an alternative calendar system, but the API doesn't nudge them to do the right thing when a non-Gregorian calendar should actually be used.

However, it is bad i18n practice to assume that dates should be represented in the Gregorian calendar by default.

I have presented several ways that we could improve the API to nudge developers to do the right thing when it comes to non-Gregorian calendars:

2. Require the programmer to explicitly specify the calendar.
3. Default to a partial ISO calendar (detailed in the explainer).
4. Default to Intl.defaultCalendar (a new symbol), or ISO if that field doesn't exist.
5. Add ZonedAbsolute, a new type between Absolute (timestamp) and DateTime (calendar-dependent wall clock time).
6. Split factory methods into ISO and non-ISO variants.
7. Use Intl.defaultCalendar in Temporal.now, and explicit elsewhere. See What about the default calendar? #292 (comment)

More details on these six options is documented in the explainer doc: https://github.com/tc39/proposal-temporal/blob/main/docs/calendar-draft.md#default-calendar

[littledan]

I want to suggest that, rather than a broad survey like @codehag created for the pipeline operator, we focus on some targeted outreach to developers who work with various non-ISO calendars and locales. This may be more in the form of interviews rather than a survey, since this information is pretty detailed. I met one such developer, and wrote about his feedback in #268 (comment) (sorry for posting on the wrong issue); my overall impression is that any of 1-4 would be acceptable for his needs, which span both Gregorian and Hijri (Islamic) calendars.

[codehag]

Sorry i totally missed this issue. Happy to help where I can though.

[pipobscure]

Yes I agree with @littledan in addition I'd ask people about their circumstance. I believe knowing whether respondents regularly deal with differing calendars will be a key input.

[sffc]

See also my PR in #309

[littledan]

We've been thinking about this for a while. Now that we have an extensive cookbook, and the polyfill for non-Gregorian calendars is coming along, I think we're coming to the understanding of the design space where we could really come to a decision, based on consulting with more people.

[sffc]

I've updated calendar-draft.md in #590 with relevant cookbook changes and some new material in the default calendar explainer, including a closer look at the different factory methods used for constructing Temporal types.

[ptomato]

@sffc requested specific feedback on each of the 6 options, considered individually, so here's mine. I'd like to preface it by saying that I do see disadvantages in each of the options, so to me the question is picking the one with the least serious disadvantage.

1. Full ISO: I agree that this is a potential source of bugs as detailed in calendar-draft.md. However, I believe there ought to be some other way to reduce the likelihood of those kinds of bugs, even if we choose this option. I believe that should be carefully considered, but I don't believe it's an insurmountable problem, and the fact that those mistakes may be possible to commit is not a disadvantage that I weight very highly.

2. Explicit calendar: For the reason I commented elsewhere, I feel strongly that the calendar doesn't need to be explicit in Temporal.X.from(fields), so I would consider this option only for now and inTimeZone. So, concretely, we are talking about removing default values from arguments in the following four API signatures:

   • Temporal.now.dateTime(timeZone = Temporal.now.timeZone(), calendar = 'iso8601') → Temporal.now.dateTime(calendar, timeZone = Temporal.now.timeZone())
   • Temporal.now.date(timeZone = Temporal.now.timeZone(), calendar = 'iso8601') → Temporal.now.date(calendar, timeZone = Temporal.now.timeZone())
   • timeZone.getDateTimeFor(absolute, calendar = 'iso8601') → timeZone.getDateTimeFor(absolute, calendar)
   • absolute.inTimeZone(timeZone, calendar = 'iso8601') → absolute.inTimeZone(timeZone, calendar)

   I don't prefer this, because I think in practice the vast majority of programmers will be using ISO anyway, so having to write 'iso8601' explicitly will be a minor annoyance. At worst, it will confuse JavaScript beginners because it's a required parameter that they won't understand. (I'm assuming that inexperienced JavaScript programmers are barely going to understand the Temporal types to begin with, let alone non-ISO calendars.) I weight that argument very highly.

   I think in practice, tutorials and StackOverflow will tell people "oh, you have to pass 'iso8601' for that parameter, it's too complicated to explain why" and so any benefit to making it explicit will be lost. Specifically, for that reason I don't agree that this forces a decision point on the programmer.

3. Partial ISO: I see this option as adding a flag to Temporal.Date and Temporal.DateTime saying "is this object broken Y/N" and the way you flip the flag is using a method named withCalendar(). If you write a function that takes a Temporal.Date or Temporal.DateTime, you have no way to know whether the object has its broken-flag set or not, so in practice your function will have to defensively call withCalendar('iso8601') on it anyway if you need to do one of the operations not supported by partial ISO. This violates predictability, which I weight highest of all, and for that reason this is a non-starter for me.

4. Locale-defined default (whether via Intl.defaultCalendar or something else): I think this option does prevent the bugs detailed in calendar-draft.md, but it makes your arithmetic operations have potentially different results depending on what locale you're in. This violates predictability, making this one also a non-starter for me.

5. Extra types: This one I haven't been able to fully study the advantages and disadvantages yet. But, I think just the fact that it's been several days and I haven't had time to wrap my head around it, is an indication that it's too complicated. If inexperienced JavaScript programmers are barely going to understand the existing Temporal types, then adding two more types is not going to improve things.

   What I do understand is that we'd need a new Date-type and DateTime-type without a calendar, to contrast Temporal.Date and Temporal.DateTime with a calendar. I think this will confuse inexperienced JavaScript programmers, and the advice on StackOverflow will be "oh, you have to do withCalendar('iso8601') to be able to subtract," and that advice will be applied indiscriminately.

6. Separate API: Again assuming that the ISO calendar can be the default in Temporal.X.from(fields), we are talking concretely about doing option 2, removing the default value from some calendar arguments that would otherwise default to ISO, while also adding new methods for the convenience of programmers who only want the ISO calendar:

   • add Temporal.now.isoDateTime(timeZone = Temporal.now.timeZone())
   • add Temporal.now.isoDate(timeZone = Temporal.now.timeZone())
   • add timeZone.getISODateTimeFor(absolute)
   • add absolute.inTimeZoneISO(timeZone)

   Since the vast majority of programmers will want ISO, I think this prioritizes the wrong use case. It will also confuse inexperienced JavaScript programmers. Reading the docs, or seeing what pops up in their IDEs, they will think "Do I want inTimeZone or inTimeZoneISO?" and code in the wild will end up with mixtures of the two.

   I'd have less of an objection to this option if we kept the existing methods as they are, and instead added differently-named methods, that mention "calendar" in the name, which require a calendar. That way, the obvious way would be to call e.g. Temporal.now.date() and absolute.inTimeZone(). Programmers would see Temporal.now.dateWithCalendar() and absolute.inTimeZoneWithCalendar() in the docs or in their IDEs, but the thought process would be clearer, since if they don't need calendars then they also don't need the calendar-named methods.

Here's approximately how I'd weight the various criteria that the proposals are validated by:

• API consistency & predictability
• Impact on Temporal call sites
  • (which I interpret more like "confusion caused for developers who don't know what calendars are")
• Impact on interoperability
• Impact on i18n correctness
• Logistics
  • (which I assume means "how difficult to get from here to there in the proposal-temporal repo", and if that's correct, then I'd weight this at basically zero)

I can make a pull request to calendar-draft.md showing how I'd change the emoji faces in the table if anyone wants that, but hopefully this illustrates my opinion.

[littledan]

I agree with all the points that @ptomato mentioned above, and his weighing of them. I want to mention a few more disadvantages of option 4, which I've mentioned in some calls but don't think I properly wrote down anywhere:

• Determining the default calendar: My understanding is that many regions of the world have a default calendar which is really more of an individual preference. CLDR sometimes lists, for these regions, that the default calendar is ISO, and other times another calendar, but the ground truth is more subtle. If the default calendar is chosen based on the region, we may not meet user expectations; application-level logic would lead to better results. (I don't really know how close we'll get to users' real calendar preferences if we pass up the "right" default calendar through navigator.locales; maybe that would be enough?) Application-level calendar determination would be best implemented on top of a simpler, more predictable base.
• Testing: Since most of the world uses an ISO calendar default, most testing would be executed in environments with an ISO calendar. This leads to the risk of code being shipped which works in most of the world and is broken when the "wrong" default calendar is selected by the environment.
• Separation of concerns: Without the inheritance of the default calendar from the environment, Temporal would operate consistently the same across different contexts/environments, modulo ECMA-402's implementation-defined-ness of calendars. I'd prefer to expose the user agent's default calendar through a separate navigator.locales API or similar, and ask developers to thread it through if it makes sense. Often, there will be application-level preferences which would override it. Also, not all environments have a meaningful user-agent-level default (e.g., servers). (Yes, Intl has a pervasive concept of a default locale; my claim is, that was an unfortunate design and we shouldn't extend it more broadly.)

Across options 2, 3, 5 and 6, there is a common API design principle that, if we ask developers to explicitly invoke the "iso" calendar in one way or another, then that will lead to a decision point from them. I share @ptomato 's skepticism about what this would mean in practice--I think the meaning of this would remain confusing to many programmers, and wouldn't constitute a choice point in practice. However, this is just a hypothesis, which we might investigate by talking to more programmers, distributing sample implementations/documentation for API alternatives, etc.

Among options 2, 3, 5 and 6, I prefer 6--I think it has the lowest syntactic overhead in practice, and it still meets the goal of "providing an explicit choice point", if that's taken to be a goal. The alternate naming that @ptomato proposes in option 6 seems interesting to me--this alternative option 6 would still create a situation where, in the documentation listing, tab completion for methods, etc, you see an option where there's an explicit calendar parameter, so this may still lead developers to invoke the right calendar-specific APIs. Option 6 seems to me like, at worst, a very minor source of slight ugliness compared to Option 1.

Overall, I prefer option 1, but the only option I am very strongly concerned about is option 4.

[justingrant]

I think the high-order bit for defaults is (as @littledan notes above) that calendar defaults are nuanced and can affect application logic more than other localization domains. By contrast, a "default locale" is simpler, e.g. Japanese user only wants to see Japanese text or number formats. In that case, a developer's job is mostly to pass the right locale parameter to the right APIs, but otherwise their application logic could be almost identical across locales.

I don't think calendars will ever work like that. In markets using non-ISO calendars, both developers and end-users must navigate the complexity of local and/or ISO calendars used depending on the user (e.g. young vs. old users) or the app (e.g. government websites vs. ecommerce). A "default calendar" at the user or app level may not really exist. It could be a toggle, like @littledan's Jordanian friend describes. Or could even be 2 calendars side-by-side in the same UI.

Also, I think it's important to think of defaults in context of which users will need them:

• A) Developers writing software that must work in every calendar. This is a small group, mostly at huge companies like Google/Facebook/Microsoft that build developer platforms and/or consumer-facing software for a global market, or developers who contribute to a relatively small set of globalized OSS projects. Defaults are probably irrelevant for this sophisticated group. Instead, they'll want flexible APIs that don't preclude the weird things they need (e.g. custom calendars, sophisticated math/conversion, etc.) but won't care as much about defaults. Also, it should be easy, or at least easier, to build multi-calendar test automation.
• B) Developers writing software for local markets in countries that use non-ISO calendars. This complexity means that non-ISO developers also work in ISO, so I'm not sure these developers would be upset by an ISO default. They'll probably care more about having APIs that are easy to learn (few concepts, few types), easy to use (e.g. don't require passing the same calendar parameter in a chain of method calls), and predictable in a context where flipping between ISO and other calendars is common.
• C) Everyone else. Probably 95%+ of JS developers. The most conscientious of these will use appropriate best practices if we provide clear documentation, e.g. to use Intl instead of toString() for formatting. Many won't even do that. These developers rely heavily on defaults and won't understand non-ISO calendars so asking them to choose 'iso' every time won't be helpful. This group will appreciate docs with common use cases like "display today's date in X calendar" so that conscientious developers who get bug reports from non-ISO markets can easily modify their code to fix those bugs. I think "it just works" date math in non-ISO calendars is too much to expect from this group, even with perfect APIs, because there's underlying domain knowledge they won't have e.g. year*12+month !== totalMonths, or "leap months".

With those customer profiles in mind, here's some specific suggestions:

• Default to ISO (@sffc's Option 1) but have an easy opt-in for non-ISO calendars. I think this default would best meet the needs of all three groups.
• Make ISO calendar APIs shorter and more easily discoverable than the non-ISO variants, so Group C won't accidentally end up using the "wrong" variant. The other groups already know about calendar complexity so will know that they need to look harder to find what they need.
• Use the word "calendar" (not "iso"!) in class/method/field names, because "ISO" already has a different meaning for many mainstream JS devs: "that weird string format that ends in Z and has the wrong time that I don't really understand but I know it's used to store in databases or send to external APIs". Trying to add another meaning will confuse many developers.
• Try to avoid "method soup" where there's a "withCalendar" variant of every method call. Alternatives could be optional calendar parameters, nested types in a separate namespace (e.g. Temporal.WithCalendar.CalendarDateTime), or some other way to avoid polluting method autocomplete in the IDE.
• Ideally, persist calendar on Temporal objects so you wouldn't have to keep telling Temporal what calendar something is across multiple chained method calls.
• In a perfect world, calendar would also persist on types too. Not sure this is possible to implement with static properties, but if it is then programmer-defined aliases would probably be usable, like this:

const WesternTemporal = Temporal;
const HijriTemporal = Temporal.withCalendar('hijri');
const HijriDateTime = HijriTemporal.DateTime;

Overall I agree with @littledan's and @ptomato's prioritization so I won't rehash the pro/con arguments for each option, other than to be careful not to make an already-complex API even more complicated for the vast majority of developers who only use ISO.

[ptomato]

Meeting, May 28: We'll initially ship the polyfill with option 1 (default is full ISO) with the understanding that it is revisited for Stage 3 based on feedback. It would be helpful to think about how we can most effectively gather that feedback (talk to individual developers using these calendars?) and what sort of feedback would change our minds vs. what sort of feedback would not.

[ptomato]

(Moving to Stage 3 milestone since option 1, like 2 or 6, doesn't require writing any significant extra code, I'll just implement it that way in the calendar branch)

[justingrant]

Some ideas stemming from discussions in last Friday's meeting:

First, we decided to add (see #625) an equalsISO method on the Temporal.Date type to mirror the existing getISOFields method. Could this XxxISO pattern be useful in other calendar-related places? For example, should there be a Temporal.nowISO object which is optimized for servers or other environments where an ISO default is desired, leaving Temporal.now to pick up the environment's calendar?

Second, in Friday's meeting we discussed using an ESLint rule to catch cases where users specify string or object literals without specifying a calendar. The more I thought about this approach, the more I liked it, because ESLint rules are highly configurable. The developer could dial up or dial down the "strictness" of the rule, e.g. whether to require the a calendar to be explicitly specified for object bags vs. strings vs. now() vs. toLocalDateTime/toDateTime.

If we had such a lint rule, @sffc how would you feel about Absolute.prototype.toLocalDateTime accepting an optional calendar (defaulting to ISO) instead of a required calendar? I'm asking because the pattern that we both like in #889 gets a lot more ergonomic if the calendar were optional in that method.

// 2 required parameters, so object bag required
absolute.toLocalDateTime({timeZone: 'America/Los_Angeles', calendar: 'iso8601'});
// optional calendar, so can provide only a string
absolute.toLocalDateTime('America/Los_Angeles');

[sffc]

First, we decided to add (see #625) an equalsISO method on the Temporal.Date type to mirror the existing getISOFields method. Could this XxxISO pattern be useful in other calendar-related places? For example, should there be a Temporal.nowISO object which is optimized for servers or other environments where an ISO default is desired, leaving Temporal.now to pick up the environment's calendar?

Works for me.

Second, in Friday's meeting we discussed using an ESLint rule to catch cases where users specify string or object literals without specifying a calendar. The more I thought about this approach, the more I liked it, because ESLint rules are highly configurable. The developer could dial up or dial down the "strictness" of the rule, e.g. whether to require the a calendar to be explicitly specified for object bags vs. strings vs. now() vs. toLocalDateTime/toDateTime.

If we had such a lint rule, @sffc how would you feel about Absolute.prototype.toLocalDateTime accepting an optional calendar (defaulting to ISO) instead of a required calendar? I'm asking because the pattern that we both like in #889 gets a lot more ergonomic if the calendar were optional in that method.

I would rather not rely solely on ESLint rules to enforce best i18n practices. The comment I made about strings is intended as a general comment about strings in code. My hope is that as more platforms adopt our convention for expressing calendars in strings, issues involving strings will diminish over time.

I also acknowledge the brevity argument, since it is the number 1 complaint about Temporal overall. However, I do think that this particular case warrants the extra code. It's now the one and only place where we're still talking about making the calendar a required option, and I think it will go great lengths to help developers understand this crucial difference between Absolute and the rest of Temporal.

I would likely be happy with toISOLocalDateTime("America/Chicago") coexisting as a briefer alternative to toLocalDateTime({ timeZone: "America/Chicago", calendar: "iso8601" }).

[sffc]

Okay. Here is my latest proposal, based on a synthesis of suggestions from @justingrant, @macchiati, and @pipobscure. Thanks everyone for hanging with me over the last several months. I truly hope that this solution makes everyone happy.

Instant → LocalDateTime

Since this is the only transition that adds a calendar field to the Temporal data model, it is the one and only transition that needs to get a calendar from somewhere. My proposal is to have two methods:

1. Temporal.Instant.prototype.toLocalDateTime({ timeZone, calendar }) takes an option bag with two required fields (timeZone and calendar).
2. Temporal.Instant.prototype.toLocalDateTimeISO(timeZone) takes only one option, the timeZone (which may be specified in the option bag as per Consistent pattern for additive conversion method parameters #889).

Temporal.now

This is a situation where the current time and time zone already come from the environment, so it makes intuitive sense that the calendar system also come from the environment. However, @littledan feels strongly that the ecosystem for user preferences hasn't evolved far enough yet to make the environment calendar high quality. I therefore propose two separate pieces:

1. Add new functions with the "iso" suffix that return objects with the ISO-8601 calendar system:
   • Temporal.now.dateISO()
   • Temporal.now.dateTimeISO()
   • Temporal.now.localDateTimeISO()
   • Temporal.now.timeISO()
2. Either remove the existing functions in Temporal.now that take an implicit calendar (Daniel's preference if I understand correctly), or change them to use the environment's calendar. If we remove them, we could always add them in the future when the user preferences ecosystem is more fully developed.
   • Temporal.now.date()
   • Temporal.now.dateTime()
   • Temporal.now.localDateTime()
   • Temporal.now.time()

Temporal.*.from(string)

As discussed in #293, I am engaging the Calsify group in IETF to discuss an extension to RFC 3339 that adds support for IANA time zone identifiers as well as calendars. As more of the ecosystem adopts this convention, strings are more and more likely to contain the correct calendar information when that information is pertinent.

Therefore, I do not feel it is warranted to have a separate calendar argument in this method.

Temporal.*.from(fields)

@ptomato astutely observed that at the point when the field object is created, the calendar system was already considered. For example, if a developer wrote { year: 2020, month: 9, day: 18 }, they clearly intended that to be a date in the ISO-8601 calendar, even though the calendar is not a slot (if this was not their intention, the developer should find out quickly because the date will be wrong). Likewise, { year: 5780, /* ... */, calendar: "hebrew" } accurately expresses the author's intent that the fields are expressed in the Hebrew calendar.

Therefore, I do not feel it is warranted to have a separate calendar argument in this method.

[sffc]

2020-09-18: Consensus on #292 (comment), with the following amendment: keep Temporal.now.date() and friends, and they take an explicit calendar argument.

// Current date in the ISO calendar
Temporal.now.dateISO();
Temporal.now.date({ calendar: "iso8601" });
Temporal.now.date("iso8601");  // shortcut according to #889

// Current date in the Hebrew calendar
Temporal.now.date({ calendar: "hebrew" });
Temporal.now.date("hebrew");  // shortcut

// Current date in the environment calendar
Temporal.now.date({ calendar: new Intl.DateTimeFormat().resolvedOptions().calendar });
Temporal.now.date(new Intl.DateTimeFormat().resolvedOptions().calendar);  // shortcut

// Throws an exception: calendar must be provided
Temporal.now.date()