Temporal edits

files/en-us/web/javascript/reference/global_objects/temporal/index.md

@@ -44,11 +44,11 @@ There are many other undesirable legacies about `Date`, such as all setters bein
     - As a timestamp: {{jsxref("Temporal.Instant")}}
     - As a date-time component combination paired with a time zone: {{jsxref("Temporal.ZonedDateTime")}}
   - Representing a time-zone-unaware date/time (which are all prefixed with "Plain"):
-    - Date (year, month, day) + time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainDateTime")}} (Note: `ZonedDateTime` is equivalent to `PlainDateTime` plus a time zone)
+    - Date (year, month, day) + time (hour, minute, second, millisecond, microsecond, nanosecond): {{jsxref("Temporal.PlainDateTime")}} (Note: `ZonedDateTime` is equivalent to `PlainDateTime` plus a time zone)
       - Date (year, month, day): {{jsxref("Temporal.PlainDate")}}
         - Year, month: {{jsxref("Temporal.PlainYearMonth")}}
         - Month, day: {{jsxref("Temporal.PlainMonthDay")}}
-      - Time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainTime")}}
+      - Time (hour, minute, second, millisecond, microsecond, nanosecond): {{jsxref("Temporal.PlainTime")}}
 
 Furthermore, there's also another utility namespace, {{jsxref("Temporal.Now")}}, which provides methods for getting the current time in various formats.
 
@@ -265,7 +265,7 @@ With these tables, you should have a basic idea of how to navigate the `Temporal
 
 ### Calendars
 
-A calendar is a way to organize days, typically into periods of weeks, months, years, and eras. Most of the world uses the Gregorian calendar, but there are many other calendars in use, especially in religious and cultural contexts. By default, all calendar-aware `Temporal` objects use the ISO 8601 calendar system, which is based on the Gregorian calendar and defines additional week-numbering rules. {{jsxref("Intl/Locale/getCalendars", "Intl.Locale.prototype.getCalendars()")}} lists most of the calendars likely to be supported by browsers. Here we provide a brief overview of how calendar systems are formed to help you internalize what factors may vary between calendars.
+A calendar is a way to organize days, typically into periods of weeks, months, years, and eras. Most of the world uses the Gregorian calendar, but there are many other calendars in use, especially in religious and cultural contexts. By default, all calendar-aware `Temporal` objects use the ISO 8601 calendar system, which is based on the Gregorian calendar and defines additional week-numbering rules. [`Intl.supportedValuesOf()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types) lists most of the calendars likely to be supported by browsers. Here we provide a brief overview of how calendar systems are formed to help you internalize what factors may vary between calendars.
 
 There are three prominent periodic events on Earth: its rotation around the sun (365.242 days for one revolution), the moon's rotation around the Earth (29.53 days from new moon to new moon), and its rotation around its axis (24 hours from sunrise to sunrise). Every culture has the same measure of a "day", which is 24 hours. Occasional changes such as daylight saving time are not part of the calendar, but are part of the [time zone](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets)'s information.
 
@@ -318,13 +318,28 @@ The concept of a "week" is not connected with any astronomical event, but is a c
 All `Temporal` classes can be serialized and deserialized using the format specified in [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557), which is based on [ISO 8601 / RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). The format, in its full form, is as follows (spaces are only for readability and should not be present in the actual string):
 
 ```plain
-YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm:ss.sssssssss [time_zone_id] [u-ca=calendar_id]
+YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm [time_zone_id] [u-ca=calendar_id]
 ```
 
 Different classes have different requirements for the presence of each component, so you will find a section titled "RFC 9557 format" in each class's documentation, which specifies the format recognized by that class.
 
 This is very similar to the [date time string format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format) used by {{jsxref("Date")}}, which is also based on ISO 8601. The main addition is the ability to specify micro- and nanosecond components, and the ability to specify the time zone and calendar system.
 
+### Representable dates
+
+All `Temporal` objects that represent a specific calendar date impose a similar limit on the range of representable dates, which is ±10<sup>8</sup> days (inclusive) from the Unix epoch, or the range of instants from `-271821-04-20T00:00:00` to `+275760-09-13T00:00:00`. This is the same range as [valid dates](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date). More specifically:
+
+- {{jsxref("Temporal.Instant")}} and {{jsxref("Temporal.ZonedDateTime")}} apply this limit directly on its `epochNanoseconds` value.
+- {{jsxref("Temporal.PlainDateTime")}} interprets the date-time in the UTC time zone and requires it to be ±(10<sup>8</sup> + 1) days (exclusive) from the Unix epoch, so its valid range is `-271821-04-19T00:00:00` to `+275760-09-14T00:00:00`, exclusive. This allows any `ZonedDateTime` to be converted to a `PlainDateTime` regardless of its offset.
+- {{jsxref("Temporal.PlainDate")}} applies the same check as `PlainDateTime` to the noon (`12:00:00`) of that date, so its valid range is `-271821-04-19` to `+275760-09-13`. This allows any `PlainDateTime` to be converted to a `PlainDate` regardless of its time, and vice versa.
+- {{jsxref("Temporal.PlainYearMonth")}} has the valid range of `-271821-04` to `+275760-09`. This allows any `PlainDate` to be converted to a `PlainYearMonth` regardless of its date (except if a non-ISO month's first day falls in the ISO month `-271821-03`).
+
+The `Temporal` objects will refuse to construct an instance representing a date/time beyond this limit. This includes:
+
+- Using the constructor or `from()` static method.
+- Using the `with()` method to update calendar fields.
+- Using `add()`, `subtract()`, `round()`, or any other method to derive new instances.
+
 ## Static properties
 
 - {{jsxref("Temporal.Duration")}} {{experimental_inline}}

files/en-us/web/javascript/reference/global_objects/temporal/instant/add/index.md

@@ -31,7 +31,7 @@ A new {{jsxref("Temporal.Instant")}} object representing adding `duration` to th
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
     - `duration` is a [calendar duration](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) (it has a non-zero `years`, `months`, or `weeks`), or has a non-zero `days`, because calendar durations are ambiguous without a calendar and time reference.
-    - The sum of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±10<sup>8</sup> days (about ±273,972.6 years).
+    - The result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Description
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/from/index.md

@@ -33,7 +33,9 @@ A new `Temporal.Instant` object representing the instant in time specified by `i
 - {{jsxref("TypeError")}}
   - : Thrown if `info` is not a `Temporal.Instant` instance or a string.
 - {{jsxref("RangeError")}}
-  - : Thrown if the string is not a valid RFC 9557 string, or if the date and time are outside the range of representable instants (±10<sup>8</sup> days, or about ±273,972.6 years).
+  - : Thrown in one of the folowing cases:
+    - The string is not a valid RFC 9557 string.
+    - The info is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md

@@ -31,7 +31,9 @@ A new `Temporal.Instant` object representing the instant in time specified by `e
 ### Exceptions
 
 - {{jsxref("RangeError")}}
-  - : Thrown if `epochMilliseconds` is outside the range of a representable instant, which is ±10<sup>8</sup> days (±8.64e15 milliseconds, or about ±273,972.6 years), or if it cannot be converted to a BigInt (e.g., not an integer).
+  - : Thrown in one of the folowing cases:
+    - `epochMilliseconds` cannot be converted to a BigInt (e.g., not an integer).
+    - `epochMilliseconds` is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md

@@ -31,7 +31,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `e
 ### Exceptions
 
 - {{jsxref("RangeError")}}
-  - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±10<sup>8</sup> days (±8.64e21 nanoseconds, or about ±273,972.6 years).
+  - : Thrown if `epochNanoseconds` is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md

@@ -15,14 +15,14 @@ The **`Temporal.Instant`** object represents a unique point in history, with nan
 
 `Temporal.Instant` is semantically the same as {{jsxref("Date")}}. They both encapsulate a single point in time, but `Temporal.Instant` is more precise because it stores nanoseconds rather than milliseconds. `Temporal.Instant` also avoids pitfalls of `Date` because it does not assume any calendar or time zone information—if you want to read any date or time information such as year or month, you need to convert it to a {{jsxref("Temporal.ZonedDateTime")}} first, using {{jsxref("Temporal/Instant/toZonedDateTimeISO()", "toZonedDateTimeISO()")}}.
 
-You can convert from `Date` to `Temporal.Instant` using the {{jsxref("Date.prototype.toTemporalInstant()")}} method, which should be preferred over other methods such as `Temporal.Instant.fromEpochMilliseconds()` because the former involves less user code and may be more optimized. You can also convert from `Temporal.Instant` to `Date` using its epoch milliseconds, such as `new Date(instant.epochMilliseconds)`.
+You can convert from `Date` to `Temporal.Instant` using the {{jsxref("Date.prototype.toTemporalInstant()")}} method, which should be preferred over other methods such as {{jsxref("Temporal/Instant/fromEpochMilliseconds", "Temporal.Instant.fromEpochMilliseconds()")}} because the former involves less user code and may be more optimized. You can also convert from `Temporal.Instant` to `Date` using its epoch milliseconds, such as `new Date(instant.epochMilliseconds)`.
 
 ### RFC 9557 format
 
 `Instant` objects can be serialized and parsed using the [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557) format, an extension to the [ISO 8601 / RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. The string has the following form (spaces are only for readability and should not be present in the actual string):
 
 ```plain
-YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm:ss.sssssssss
+YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm
 ```
 
 - `YYYY`
@@ -39,8 +39,8 @@ YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm:ss.sssssssss
   - : A two-digit number from `00` to `59`. Defaults to `00`.
 - `ss.sssssssss` {{optional_inline}}
   - : A two-digit number from `00` to `59`. May optionally be followed by a `.` or `,` and one to nine digits. Defaults to `00`. The `HH`, `mm`, and `ss` components can be separated by `:` or nothing. You can omit either just `ss` or both `ss` and `mm`, so the time can be one of three forms: `HH`, `HH:mm`, or `HH:mm:ss.sssssssss`.
-- `Z/±HH:mm:ss.sssssssss`
-  - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the time component. Note that subminute precision may be unsupported by other systems. If an offset is provided, the time is interpreted in the specified offset.
+- `Z/±HH:mm`
+  - : Either the UTC designator `Z` or `z`, or an offset from UTC in the form `+` or `-` followed by the same format as the time component. Note that subminute precision (`:ss.sssssssss`) may be unsupported by other systems, and is accepted but never output. If an offset is provided, the time is interpreted in the specified offset.
 
 As an input, you may optionally include the time zone identifier and calendar, in the same format as [`ZonedDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#rfc_9557_format), but they will be ignored. Other annotations in the `[key=value]` format are also ignored, and they must not have the critical flag.
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md

@@ -33,7 +33,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `e
 ### Exceptions
 
 - {{jsxref("RangeError")}}
-  - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±10<sup>8</sup> days (±8.64e21 nanoseconds, or about ±273,972.6 years).
+  - : Thrown if `epochNanoseconds` represents an instant outside the range of representable instants, which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md

@@ -33,7 +33,7 @@ A new {{jsxref("Temporal.Instant")}} object representing subtracting `duration`
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
     - `duration` is a [calendar duration](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) (it has a non-zero `years`, `months`, or `weeks`), or has a non-zero `days`, because calendar durations are ambiguous without a calendar and time reference.
-    - The difference of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±10<sup>8</sup> days (about ±273,972.6 years).
+    - The result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±10<sup>8</sup> days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Description
 

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/add/index.md

@@ -35,6 +35,11 @@ add(duration, options)
 
 A new `Temporal.PlainDate` object representing the date specified by the original `PlainDate`, plus the duration.
 
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
+
 ## Description
 
 The `duration` is handled in this way:

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md

@@ -70,6 +70,7 @@ A new `Temporal.PlainDate` object, representing the date specified by `info` in
     - The provided properties that specify the same component are inconsistent.
     - The provided non-numerical properties are not valid; for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
+    - The info is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md

@@ -43,7 +43,8 @@ A new `Temporal.PlainDate` object, representing the date specified by `year`, `m
   - : Thrown if `calendar` is not a string or `undefined`.
 - {{jsxref("RangeError")}}
   - : Thrown in one of the following cases:
-    - `year`, `month`, or `day` is not a finite number, or do not represent a valid date in the ISO calendar system.
+    - `year`, `month`, or `day` is not a finite number.
+    - The `year`, `month`, and `day` combination does not represent a valid date in the ISO calendar system, or is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
     - `calendar` is not a valid calendar identifier.
 
 ## Examples

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/subtract/index.md

@@ -41,6 +41,11 @@ A new `Temporal.PlainDate` object representing the date specified by the origina
 
 Subtracting a duration is equivalent to [adding](Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/add) its [negation](Web/JavaScript/Reference/Global_Objects/Temporal/Duration/negated), so all the same considerations apply.
 
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
+
 ## Examples
 
 ### Subtracting a duration

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md

@@ -48,6 +48,7 @@ A new `Temporal.PlainDate` object, where the fields specified in `info` that are
     - The provided properties that specify the same component are inconsistent.
     - The provided non-numerical properties are not valid; for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
+    - The result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/add/index.md

@@ -35,6 +35,11 @@ add(duration, options)
 
 A new `Temporal.PlainDateTime` object representing the date-time specified by the original `PlainDateTime`, plus the duration.
 
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the result is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
+
 ## Description
 
 For how [calendar durations](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) are added, see {{jsxref("Temporal/PlainDate/add", "Temporal.PlainDate.prototype.add()")}}.

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/from/index.md

@@ -50,6 +50,7 @@ A new `Temporal.PlainDateTime` object, representing the date and time specified
     - The provided properties that specify the same component are inconsistent.
     - The provided non-numerical properties are not valid; for example, if `monthCode` is never a valid month code in this calendar.
     - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`.
+    - The info is not in the [representable range](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#representable_dates), which is ±(10<sup>8</sup> + 1) days, or about ±273,972.6 years, from the Unix epoch.
 
 ## Examples