Normative: Remove calendars and time zones

This is a very large change, as it not only removes Temporal.Calendar and
Temporal.TimeZone, but also tries to eliminate any extra complexity due to
no longer having to deal with user code calls for calendar and time zone
calculations.

Some of the things that are removed or simplified include:

- No more Calendar Method Records and Time Zone Method Records

- In many places, no need to pass around the user's original options bag

- In many places, no need to pass around the user's original PlainDate or
  Instant; use epoch nanoseconds, ISO Date Records, and ISO Date-Time
  Records instead

- No more copying the own properties of options bags

- Most of the calendar and time zone operations are now infallible

- The set of extra calendar fields that used to be returned by
  Temporal.Calendar.prototype.fields() is now static; so no need to have
  the complicated PrepareTemporalFields operation that returns a null-
  prototype object with own data properties that correspond to arbitrary
  user fields. Dates in calendar space can be represented by a Calendar
  Fields Record with known fields.

- Much of the special-casing to avoid user calls that was added in #2519
  and similar PRs is now unobservable and is removed.

Closes: #2836
Closes: #2853
Closes: #2854

Author: ptomato

docs/README.md

@@ -53,7 +53,7 @@ See [Temporal.Now Documentation](./now.md) for detailed documentation.
 ### **Temporal.Instant**
 
 A `Temporal.Instant` represents a fixed point in time (called **"exact time"**), without regard to calendar or location, e.g. July 20, 1969, at 20:17 UTC.
-For a human-readable local calendar date or clock time, use a `Temporal.TimeZone` and `Temporal.Calendar` to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`.
+For a human-readable local calendar date or clock time, use a time zone and calendar identifier to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`.
 
 ```js
 const instant = Temporal.Instant.from('1969-07-20T20:17Z');
@@ -83,7 +83,7 @@ const zonedDateTime = Temporal.ZonedDateTime.from({
 }); // => 1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]
 ```
 
-As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.TimeZone`, `Temporal.Instant`, and `Temporal.PlainDateTime` (which includes `Temporal.Calendar`).
+As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.Instant` and `Temporal.PlainDateTime` with a time zone identifier.
 
 See [Temporal.ZonedDateTime Documentation](./zoneddatetime.md) for detailed documentation.
 
@@ -126,7 +126,7 @@ See [Temporal.PlainTime Documentation](./plaintime.md) for detailed documentatio
 
 A `Temporal.PlainDateTime` represents a calendar date and wall-clock time that does not carry time zone information, e.g. December 7th, 1995 at 3:00 PM (in the Gregorian calendar).
 
-It can be converted to a `Temporal.ZonedDateTime` using a `Temporal.TimeZone`.
+It can be converted to a `Temporal.ZonedDateTime` using time zone identifier.
 For use cases that require a time zone, especially using arithmetic or other derived values, consider using `Temporal.ZonedDateTime` instead because that type automatically adjusts for Daylight Saving Time.
 
 ```js
@@ -192,43 +192,26 @@ Unlike the other Temporal types, the units in `Temporal.Duration` don't naturall
 
 See [Duration balancing](./balancing.md) for more on this topic.
 
-### **Temporal.TimeZone**
+### Time Zones
 
-A `Temporal.TimeZone` represents an IANA time zone, a specific UTC offset, or UTC itself.
-Time zones translate from a date/time in UTC to a local date/time.
-Because of this `Temporal.TimeZone` can be used to convert between `Temporal.Instant` and `Temporal.PlainDateTime` as well as finding out the offset at a specific `Temporal.Instant`.
+A time zone in ECMAScript is usually represented by an IANA Time Zone Database identifier such as `'America/Los_Angeles'`, `'Asia/Tokyo'`, or `'UTC'`.
+Fixed-offset time zone identifiers like `'+05:30'` may also be used, although this usage is discouraged because offsets for a particular location may change in response to political changes.
 
-It is also possible to implement your own time zones.
+Time zones translate between a date/time in UTC to a local calendar date and wall clock time.
+`Temporal.ZonedDateTime` provides built-in support for time-zone-aware applications.
+A time zone is required to convert from `Temporal.Instant` or `Temporal.PlainDateTime` to `Temporal.ZonedDateTime`.
 
-```js
-const timeZone = Temporal.TimeZone.from('Africa/Cairo');
-timeZone.getInstantFor('2000-01-01T00:00'); // => 1999-12-31T22:00:00Z
-timeZone.getPlainDateTimeFor('2000-01-01T00:00Z'); // => 2000-01-01T02:00:00
-timeZone.getPreviousTransition(Temporal.Now.instant()); // => 2014-09-25T21:00:00Z
-timeZone.getNextTransition(Temporal.Now.instant()); // => null
-```
-
-See [Temporal.TimeZone Documentation](./timezone.md) for detailed documentation.
+See [`Temporal.ZonedDateTime` Documentation](./zoneddatetime.md) for more information.
 A conceptual explanation of handling [time zones, DST, and ambiguity in Temporal](./ambiguity.md) is also available.
 
-### **Temporal.Calendar**
+### Calendars
 
-A `Temporal.Calendar` represents a calendar system.
+Temporal supports multiple calendar systems.
 Most code will use the ISO 8601 calendar, but other calendar systems are available.
 
-Dates have associated `Temporal.Calendar` objects, to perform calendar-related math.
-Under the hood, this math is done by methods on the calendars.
-
-It is also possible to implement your own calendars.
-
-```js
-const cal = Temporal.Calendar.from('iso8601');
-const date = cal.dateFromFields({ year: 1999, month: 12, day: 31 }, {});
-date.monthsInYear; // => 12
-date.daysInYear; // => 365
-```
+Dates have associated calendar IDs, to perform calendar-related math.
 
-See [Temporal.Calendar Documentation](./calendar.md) for detailed documentation.
+See [Calendars in Temporal](./calendars.md) for detailed documentation.
 
 ## Object relationship
 

docs/ambiguity.md

@@ -54,10 +54,9 @@ In Temporal:
 
 - The [`Temporal.Instant`](./instant.md) type represents exact time only.
 - The [`Temporal.PlainDateTime`](./plaindatetime.md) type represents calendar date and wall-clock time, as do other narrower types: [`Temporal.PlainDate`](./plaindate.md), [`Temporal.PlainTime`](./plaintime.md), [`Temporal.PlainYearMonth`](./plainyearmonth.md), and [`Temporal.PlainMonthDay`](./plainmonthday.md).
-  These types all carry a calendar system, which by default is `'iso8601'` (the ISO 8601 calendar) but can be overridden for other [calendars](./calendar.md) like `'islamic'` or `'japanese'`.
-- The [`Temporal.TimeZone`](./timezone.md) represents a time zone function that converts between exact time and wall-clock time and vice-versa.
-  It also includes helper functions, e.g. to fetch the current time zone offset for a particular exact time.
-- The [`Temporal.ZonedDateTime`](./zoneddatetime.md) type encapsulates all of the types above: an exact time (like a [`Temporal.Instant`](./instant.md)), its wall-clock equivalent (like a [`Temporal.PlainDateTime`](./plaindatetime.md)), and the time zone that links the two (like a [`Temporal.TimeZone`](./timezone.md)).
+  These types all carry a calendar system, which by default is `'iso8601'` (the ISO 8601 calendar) but can be overridden for other calendars like `'islamic'` or `'japanese'`.
+- The time zone identifier represents a time zone function that converts between exact time and wall-clock time and vice-versa.
+- The [`Temporal.ZonedDateTime`](./zoneddatetime.md) type encapsulates all of the types above: an exact time (like a [`Temporal.Instant`](./instant.md)), its wall-clock equivalent (like a [`Temporal.PlainDateTime`](./plaindatetime.md)), and the time zone that links the two.
 
 There are two ways to get a human-readable calendar date and clock time from a `Temporal` type that stores exact time.
 
@@ -83,10 +82,10 @@ zdt.toLocaleString('en-us', { ...formatOptions, calendar: zdt.calendar });
   // => 'Sep 3, 2019 AD, 5:34:05 PM'
 zdt.year;
   // => 2019
-zdt = instant.toZonedDateTime({timeZone: 'Asia/Tokyo', calendar: 'iso8601'}).toLocaleString('ja-jp', formatOptions);
+zdt.toLocaleString('ja-jp', formatOptions);
   // => '西暦2019年9月3日 17:34:05'
 
-zdt = instant.toZonedDateTime({timeZone: 'Asia/Tokyo', calendar: 'japanese'});
+zdt = zdt.withCalendar('japanese');
   // => 2019-09-03T17:34:05+09:00[Asia/Tokyo][u-ca=japanese]
 zdt.toLocaleString('en-us', { ...formatOptions, calendar: zdt.calendar });
   // => 'Sep 3, 1 Reiwa, 5:34:05 PM'
@@ -202,7 +201,6 @@ Methods where this option is present include:
 - [`Temporal.ZonedDateTime.from` with object argument](./zoneddatetime.md#from)
 - [`Temporal.ZonedDateTime.prototype.with`](./zoneddatetime.md#with)
 - [`Temporal.PlainDateTime.prototype.toZonedDateTime`](./plaindatetime.md#toZonedDateTime)
-- [`Temporal.TimeZone.prototype.getInstantFor`](./timezone.md#getInstantFor).
 
 ## Examples: DST Disambiguation
 

docs/calendar-draft.md

@@ -2,7 +2,9 @@
 
 This doc describes a design for first-class support for non-Gregorian [calendars](https://en.wikipedia.org/wiki/Calendar) in Temporal. Although most of this document is based on Temporal.PlainDate, most of this applies to Temporal.PlainDateTime, Temporal.PlainYearMonth, Temporal.PlainMonthDay, and Temporal.PlainTime as well.
 
-The approach described in this document was largely adopted, so this document has been superseded by the [`Temporal.Calendar` documentation](./calendar.md).
+The approach described in this document was largely adopted, but most of
+this document's information is nonetheless obsolete, due to removing the
+Temporal.Calendar interface.
 
 ## Data Model
 

docs/calendar-subclass.md

@@ -1,6 +1,6 @@
 # Subclass-based Temporal Calendar API
 
-[calendar-draft.md](calendar.md) documents the design for calendar support in Temporal based on a single shared Temporal.PlainDate type with a Temporal.Calendar. This document discusses an alternative approach based on subclassing of Temporal.PlainDate types. This idea was not pursued further due to the drawbacks discussed in this document.
+[calendar-draft.md](calendar-draft.md) documents the design for calendar support in Temporal based on a single shared Temporal.PlainDate type with a Temporal.Calendar. This document discusses an alternative approach based on subclassing of Temporal.PlainDate types. This idea was not pursued further due to the drawbacks discussed in this document.
 
 In this document, the _Temporal.Calendar Approach_ refers to the solution proposed in [calendar-draft.md](calendar-draft.md), and the _Temporal.PlainDate Subclassing Approach_ refers to the alternative, but eliminated, solution proposed in this document.