Normative: Remove methods with ISO-named pairs

Closes: #2846
tc39 · Jun 13, 2024 · 1d8f15a · 1d8f15a
1 parent e5919bd
commit 1d8f15a
Show file tree

Hide file tree

Showing 8 changed files with 13 additions and 237 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -37,12 +37,9 @@ Several important concepts are explained elsewhere: [exact time, wall-clock time
 
 - `Temporal.Now.instant()` - get the current system exact time
 - `Temporal.Now.timeZoneId()` - get the current system time zone
-- `Temporal.Now.zonedDateTime(calendar)` - get the current date and wall-clock time in the system time zone and specified calendar
 - `Temporal.Now.zonedDateTimeISO()` - get the current date and wall-clock time in the system time zone and ISO-8601 calendar
-- `Temporal.Now.plainDate(calendar)` - get the current date in the system time zone and specified calendar
 - `Temporal.Now.plainDateISO()` - get the current date in the system time zone and ISO-8601 calendar
 - `Temporal.Now.plainTimeISO()` - get the current wall-clock time in the system time zone and ISO-8601 calendar
-- `Temporal.Now.plainDateTime(calendar)` - get the current system date/time in the system time zone, but return an object that doesn't remember its time zone so should NOT be used to derive other values (e.g. 12 hours later) in time zones that use Daylight Saving Time (DST).
 - `Temporal.Now.plainDateTimeISO()` - same as above, but return the DateTime in the ISO-8601 calendar
 
 ```js

diff --git a/docs/instant.md b/docs/instant.md
@@ -264,9 +264,8 @@ epochMicros = ns / 1000n + ((ns % 1000n) < 0n ? -1n : 0n);
 For a list of IANA time zone names, see the current version of the [IANA time zone database](https://www.iana.org/time-zones).
 A convenient list is also available [on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), although it might not reflect the latest official status.
 
-This method is one way to convert a `Temporal.Instant` to a `Temporal.ZonedDateTime`.
-It is the same as `toZonedDateTime()`, but always uses the ISO 8601 calendar.
-Use this method if you are not doing computations in other calendars.
+This method always returns a `Temporal.ZonedDateTime` with the ISO 8601 calendar.
+Remember to use `withCalendar()` on the result if you need to do computations in other calendars.
 
 Example usage:
 
@@ -276,39 +275,14 @@ timestamp = Temporal.Instant.fromEpochMilliseconds(1553993100_000);
 timestamp.toZonedDateTimeISO('Europe/Berlin'); // => 2019-03-31T01:45:00+01:00[Europe/Berlin]
 timestamp.toZonedDateTimeISO('UTC'); // => 2019-03-31T00:45:00+00:00[UTC]
 timestamp.toZonedDateTimeISO('-08:00'); // => 2019-03-30T16:45:00-08:00[-08:00]
-```
-
-### instant.**toZonedDateTime**(_item_: object) : Temporal.ZonedDateTime
-
-**Parameters:**
 
-- `item` (object): an object with properties to be combined with `instant`. The following properties are recognized:
-  - `calendar` (required calendar identifier string, `Temporal.Calendar` object, or object implementing the calendar protocol): the calendar in which to interpret `instant`.
-  - `timeZone` (required time zone identifier string, `Temporal.TimeZone` object, or object implementing the [time zone protocol](./timezone.md#custom-time-zones)): the time zone in which to interpret `instant`.
-
-**Returns:** a `Temporal.ZonedDateTime` object representing the calendar date, wall-clock time, time zone offset, and `timeZone`, according to the reckoning of `calendar`, at the exact time indicated by `instant`.
-
-For a list of IANA time zone names, see the current version of the [IANA time zone database](https://www.iana.org/time-zones).
-A convenient list is also available [on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), although it might not reflect the latest official status.
-
-For a list of calendar identifiers, see the documentation for [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#Parameters).
-
-If you only want to use the ISO 8601 calendar, use `toZonedDateTimeISO()`.
-
-Example usage:
-
-<!-- prettier-ignore-start -->
-```js
 // What time was the Unix epoch (timestamp 0) in Bell Labs (Murray Hill, New Jersey, USA) in the Gregorian calendar?
 epoch = Temporal.Instant.fromEpochMilliseconds(0);
-timeZone = Temporal.TimeZone.from('America/New_York');
-epoch.toZonedDateTime({ timeZone, calendar: 'gregory' });
+epoch.toZonedDateTimeISO('America/New_York').withCalendar('gregory');
   // => 1969-12-31T19:00:00-05:00[America/New_York][u-ca=gregory]
 
 // What time was the Unix epoch in Tokyo in the Japanese calendar?
-timeZone = Temporal.TimeZone.from('Asia/Tokyo');
-calendar = Temporal.Calendar.from('japanese');
-zdt = epoch.toZonedDateTime({ timeZone, calendar });
+zdt = epoch.toZonedDateTimeISO('Asia/Tokyo').withCalendar('japanese');
   // => 1970-01-01T09:00:00+09:00[Asia/Tokyo][u-ca=japanese]
 console.log(zdt.eraYear, zdt.era);
   // => '45 showa'

diff --git a/docs/now.md b/docs/now.md
@@ -25,7 +25,8 @@ The `Temporal.Now` object has several methods which give information about the c
 This method gets the current date, time, time zone, and time zone offset according to the system settings, in the reckoning of the ISO 8601 calendar system.
 Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
 
-This method is the same as `zonedDateTime()`, but always uses the ISO 8601 calendar.
+This method always returns a `Temporal.ZonedDateTime` with the ISO 8601 calendar.
+Remember to use `withCalendar()` on the result if you need to do computations in other calendars.
 
 Example usage:
 
@@ -46,21 +47,6 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => {
 // Tokyo: 2020-09-18T17:17:48.441068438+09:00[Asia/Tokyo]
 ```
 
-### Temporal.Now.**zonedDateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.ZonedDateTime
-
-**Parameters:**
-
-- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in.
-- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string.
-  If not given, the current system time zone will be used.
-
-**Returns:** a `Temporal.ZonedDateTime` object representing the current system date, time, time zone, and time zone offset.
-
-This method gets the current date, time, time zone, and time zone offset according to the system settings, in the reckoning of the given calendar system.
-Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
-
-If you only want to use the ISO 8601 calendar, use `Temporal.Now.zonedDateTimeISO()`.
-
 ### Temporal.Now.**instant**() : Temporal.Instant
 
 **Returns:** a `Temporal.Instant` object representing the current system time.
@@ -120,7 +106,8 @@ console.log(`At ${nextTransition.toZonedDateTimeISO(id)} the offset will change
 This method gets the current calendar date and wall-clock time according to the system settings.
 Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
 
-This method is the same as `dateTime()`, but always uses the ISO 8601 calendar.
+This method always returns a `Temporal.PlainDateTime` with the ISO 8601 calendar.
+Remember to use `withCalendar()` on the result if you need to do computations in other calendars.
 
 Example usage:
 
@@ -143,21 +130,6 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => {
 ```
 <!-- prettier-ignore-end -->
 
-### Temporal.Now.**plainDateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDateTime
-
-**Parameters:**
-
-- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in.
-- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string.
-  If not given, the current system time zone will be used.
-
-**Returns:** a `Temporal.PlainDateTime` object representing the current system date and time in the reckoning of the given calendar system.
-
-This method gets the current calendar date and wall-clock time according to the system settings.
-Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
-
-If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateTimeISO()`.
-
 ### Temporal.Now.**plainDateISO**(_timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDate
 
 **Parameters:**
@@ -170,34 +142,18 @@ If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateTimeIS
 This method gets the current calendar date according to the system settings.
 Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
 
-This method is the same as `date()`, but always uses the ISO 8601 calendar.
+This method always returns a `Temporal.PlainDate` with the ISO 8601 calendar.
+Remember to use `withCalendar()` on the result if you need to do computations in other calendars.
 
 Example usage:
 
 ```js
 // Is it New Year in the ISO 8601 calendar?
 date = Temporal.Now.plainDateISO();
 if (date.month === 1 && date.day === 1) console.log('New year!');
-```
 
-### Temporal.Now.**plainDate**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDate
-
-**Parameters:**
-
-- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in.
-- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string.
-  If not given, the current system time zone will be used.
-
-**Returns:** a `Temporal.PlainDate` object representing the current system date in the reckoning of the given calendar.
-
-This method gets the current calendar date according to the system settings.
-Optionally a time zone can be given in which the time is computed, instead of the current system time zone.
-
-If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateISO()`.
-
-```js
 // Is it Nowruz (New Year in the Persian calendar)?
-date = Temporal.Now.plainDate('persian');
+date = Temporal.Now.plainDateISO().withCalendar('persian');
 if (date.month === 1 && date.day === 1) console.log('New year!');
 ```
 

diff --git a/polyfill/index.d.ts b/polyfill/index.d.ts
@@ -594,7 +594,6 @@ export namespace Temporal {
     round(
       roundTo: RoundTo<'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond'>
     ): Temporal.Instant;
-    toZonedDateTime(calendarAndTimeZone: { timeZone: TimeZoneLike; calendar: CalendarLike }): Temporal.ZonedDateTime;
     toZonedDateTimeISO(tzLike: TimeZoneLike): Temporal.ZonedDateTime;
     toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
     toJSON(): string;
@@ -1334,26 +1333,6 @@ export namespace Temporal {
      * */
     instant: () => Temporal.Instant;
 
-    /**
-     * Get the current calendar date and clock time in a specific calendar and
-     * time zone.
-     *
-     * The `calendar` parameter is required. When using the ISO 8601 calendar or
-     * if you don't understand the need for or implications of a calendar, then
-     * a more ergonomic alternative to this method is
-     * `Temporal.Now.zonedDateTimeISO()`.
-     *
-     * @param {CalendarLike} [calendar] - calendar identifier, or
-     * a `Temporal.Calendar` instance, or an object implementing the calendar
-     * protocol.
-     * @param {TimeZoneLike} [tzLike] -
-     * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
-     * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
-     * object implementing the time zone protocol. If omitted, the environment's
-     * current time zone will be used.
-     */
-    zonedDateTime: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.ZonedDateTime;
-
     /**
      * Get the current calendar date and clock time in a specific time zone,
      * using the ISO 8601 calendar.
@@ -1366,31 +1345,6 @@ export namespace Temporal {
      */
     zonedDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.ZonedDateTime;
 
-    /**
-     * Get the current calendar date and clock time in a specific calendar and
-     * time zone.
-     *
-     * The calendar is required. When using the ISO 8601 calendar or if you
-     * don't understand the need for or implications of a calendar, then a more
-     * ergonomic alternative to this method is `Temporal.Now.plainDateTimeISO`.
-     *
-     * Note that the `Temporal.PlainDateTime` type does not persist the time zone,
-     * but retaining the time zone is required for most time-zone-related use
-     * cases. Therefore, it's usually recommended to use
-     * `Temporal.Now.zonedDateTimeISO` or `Temporal.Now.zonedDateTime` instead
-     * of this function.
-     *
-     * @param {CalendarLike} [calendar] - calendar identifier, or
-     * a `Temporal.Calendar` instance, or an object implementing the calendar
-     * protocol.
-     * @param {TimeZoneLike} [tzLike] -
-     * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
-     * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
-     * object implementing the time zone protocol. If omitted,
-     * the environment's current time zone will be used.
-     */
-    plainDateTime: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.PlainDateTime;
-
     /**
      * Get the current date and clock time in a specific time zone, using the
      * ISO 8601 calendar.
@@ -1408,24 +1362,6 @@ export namespace Temporal {
      */
     plainDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainDateTime;
 
-    /**
-     * Get the current calendar date in a specific calendar and time zone.
-     *
-     * The calendar is required. When using the ISO 8601 calendar or if you
-     * don't understand the need for or implications of a calendar, then a more
-     * ergonomic alternative to this method is `Temporal.Now.plainDateISO`.
-     *
-     * @param {CalendarLike} [calendar] - calendar identifier, or
-     * a `Temporal.Calendar` instance, or an object implementing the calendar
-     * protocol.
-     * @param {TimeZoneLike} [tzLike] -
-     * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
-     * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
-     * object implementing the time zone protocol. If omitted,
-     * the environment's current time zone will be used.
-     */
-    plainDate: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.PlainDate;
-
     /**
      * Get the current date in a specific time zone, using the ISO 8601
      * calendar.

diff --git a/polyfill/lib/instant.mjs b/polyfill/lib/instant.mjs
@@ -119,23 +119,6 @@ export class Instant {
   valueOf() {
     ES.ValueOfThrows('Instant');
   }
-  toZonedDateTime(item) {
-    if (!ES.IsTemporalInstant(this)) throw new TypeError('invalid receiver');
-    if (ES.Type(item) !== 'Object') {
-      throw new TypeError('invalid argument in toZonedDateTime');
-    }
-    const calendarLike = item.calendar;
-    if (calendarLike === undefined) {
-      throw new TypeError('missing calendar property in toZonedDateTime');
-    }
-    const calendar = ES.ToTemporalCalendarSlotValue(calendarLike);
-    const temporalTimeZoneLike = item.timeZone;
-    if (temporalTimeZoneLike === undefined) {
-      throw new TypeError('missing timeZone property in toZonedDateTime');
-    }
-    const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike);
-    return ES.CreateTemporalZonedDateTime(GetSlot(this, EPOCHNANOSECONDS), timeZone, calendar);
-  }
   toZonedDateTimeISO(timeZone) {
     if (!ES.IsTemporalInstant(this)) throw new TypeError('invalid receiver');
     timeZone = ES.ToTemporalTimeZoneSlotValue(timeZone);

diff --git a/polyfill/lib/now.mjs b/polyfill/lib/now.mjs
@@ -6,29 +6,15 @@ const instant = () => {
   const Instant = GetIntrinsic('%Temporal.Instant%');
   return new Instant(ES.SystemUTCEpochNanoSeconds());
 };
-const plainDateTime = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => {
-  const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike);
-  const calendar = ES.ToTemporalCalendarSlotValue(calendarLike);
-  const inst = instant();
-  const timeZoneRec = new TimeZoneMethodRecord(timeZone, ['getOffsetNanosecondsFor']);
-  return ES.GetPlainDateTimeFor(timeZoneRec, inst, calendar);
-};
 const plainDateTimeISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => {
   const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike);
   const inst = instant();
   const timeZoneRec = new TimeZoneMethodRecord(timeZone, ['getOffsetNanosecondsFor']);
   return ES.GetPlainDateTimeFor(timeZoneRec, inst, 'iso8601');
 };
-const zonedDateTime = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => {
-  const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike);
-  const calendar = ES.ToTemporalCalendarSlotValue(calendarLike);
-  return ES.CreateTemporalZonedDateTime(ES.SystemUTCEpochNanoSeconds(), timeZone, calendar);
-};
 const zonedDateTimeISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => {
-  return zonedDateTime('iso8601', temporalTimeZoneLike);
-};
-const plainDate = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => {
-  return ES.TemporalDateTimeToDate(plainDateTime(calendarLike, temporalTimeZoneLike));
+  const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike);
+  return ES.CreateTemporalZonedDateTime(ES.SystemUTCEpochNanoSeconds(), timeZone, 'iso8601');
 };
 const plainDateISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => {
   return ES.TemporalDateTimeToDate(plainDateTimeISO(temporalTimeZoneLike));
@@ -42,13 +28,10 @@ const timeZoneId = () => {
 
 export const Now = {
   instant,
-  plainDateTime,
   plainDateTimeISO,
-  plainDate,
   plainDateISO,
   plainTimeISO,
   timeZoneId,
-  zonedDateTime,
   zonedDateTimeISO
 };
 Object.defineProperty(Now, Symbol.toStringTag, {

diff --git a/spec/instant.html b/spec/instant.html
@@ -327,28 +327,6 @@ <h1>Temporal.Instant.prototype.valueOf ( )</h1>
       </emu-note>
     </emu-clause>
 
-    <emu-clause id="sec-temporal.instant.prototype.tozoneddatetime">
-      <h1>Temporal.Instant.prototype.toZonedDateTime ( _item_ )</h1>
-      <p>
-        This method performs the following steps when called:
-      </p>
-      <emu-alg>
-        1. Let _instant_ be the *this* value.
-        1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]).
-        1. If _item_ is not an Object, then
-          1. Throw a *TypeError* exception.
-        1. Let _calendarLike_ be ? Get(_item_, *"calendar"*).
-        1. If _calendarLike_ is *undefined*, then
-          1. Throw a *TypeError* exception.
-        1. Let _calendar_ be ? ToTemporalCalendarSlotValue(_calendarLike_).
-        1. Let _temporalTimeZoneLike_ be ? Get(_item_, *"timeZone"*).
-        1. If _temporalTimeZoneLike_ is *undefined*, then
-          1. Throw a *TypeError* exception.
-        1. Let _timeZone_ be ? ToTemporalTimeZoneSlotValue(_temporalTimeZoneLike_).
-        1. Return ! CreateTemporalZonedDateTime(_instant_.[[Nanoseconds]], _timeZone_, _calendar_).
-      </emu-alg>
-    </emu-clause>
-
     <emu-clause id="sec-temporal.instant.prototype.tozoneddatetimeiso">
       <h1>Temporal.Instant.prototype.toZonedDateTimeISO ( _timeZone_ )</h1>
       <p>