Add Temporal.now.dateTimeISO() and Temporal.now.dateISO()

Convenience methods that give the current date and datetime in the ISO
8601 calendar.

See: #292

docs/cookbook/getCurrentDate.mjs

@@ -5,8 +5,8 @@
  *
  */
 
-const date = Temporal.now.date(); // Gets the current date
+const date = Temporal.now.dateISO(); // Gets the current date
 date.toString(); // returns the date in ISO 8601 date format
 
 // If you additionally want the time:
-Temporal.now.dateTime().toString(); // date and time in ISO 8601 format
+Temporal.now.dateTimeISO().toString(); // date and time in ISO 8601 format

docs/now.md

@@ -9,20 +9,19 @@ The `Temporal.now` object has several methods which give information about the c
 
 ## Methods
 
-### Temporal.now.**zonedDateTime**(_timeZone_: object | string = Temporal.now.timeZone(), _calendar_: object | string = 'iso8601') : Temporal.DateTime
+### Temporal.now.**zonedDateTimeISO**(_timeZone_: object | string = Temporal.now.timeZone()) : Temporal.ZonedDateTime
 
 **Parameters:**
 
 - `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#protocol), or a string.
   If not given, the current system time zone will be used.
-- `calendar` (optional `Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in.
-  If not given, the ISO 8601 calendar 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.
-Optionally a time zone can be given in which the time is computed, and a calendar system in which the date is reckoned.
-Subsequent calculations using this object (e.g. adding days or changing the time) will retain the same time zone and calendar.
+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.
 
 Example usage:
 
@@ -32,9 +31,9 @@ financialCentres = {
   London: 'Europe/London',
   Tokyo: 'Asia/Tokyo'
 };
-console.log(`Here: ${Temporal.now.zonedDateTime()}`);
+console.log(`Here: ${Temporal.now.zonedDateTimeISO()}`);
 Object.entries(financialCentres).forEach(([name, timeZone]) => {
-  console.log(`${name}: ${Temporal.now.zonedDateTime(timeZone)}`);
+  console.log(`${name}: ${Temporal.now.zonedDateTimeISO(timeZone)}`);
 });
 // example output:
 // Here: 2020-09-18T01:17:48.431957915-07:00[America/Los_Angeles]
@@ -105,20 +104,21 @@ nextTransition.toDateTime(tz);
 // On 2020-03-08T03:00 the clock will change from UTC -08:00 to -07:00
 ```
 
-### Temporal.now.**dateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.now.timeZone()) : Temporal.DateTime
+### Temporal.now.**dateTimeISO**(_timeZone_: object | string = Temporal.now.timeZone()) : Temporal.DateTime
 
 **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#protocol), or a string.
   If not given, the current system time zone will be used.
 
-**Returns:** a `Temporal.DateTime` object representing the current system date and time in the reckoning of the given calendar system.
+**Returns:** a `Temporal.DateTime` object representing the current system date and time in the reckoning of the ISO 8601 calendar.
 
 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.dateTimeISO()`.
+This method is the same as `dateTime()`, but always uses the ISO 8601 calendar.
+
+Example usage:
 
 <!-- prettier-ignore-start -->
 ```js
@@ -127,9 +127,9 @@ financialCentres = {
   'London': 'Europe/London',
   'Tokyo': 'Asia/Tokyo',
 };
-console.log(`Here: ${Temporal.now.dateTime()}`);
+console.log(`Here: ${Temporal.now.dateTimeISO()}`);
 Object.entries(financialCentres).forEach(([name, timeZone]) => {
-  console.log(`${name}: ${Temporal.now.dateTime(timeZone)}`);
+  console.log(`${name}: ${Temporal.now.dateTimeISO(timeZone)}`);
 });
 // example output:
 // Here: 2020-01-24T21:51:02.142905166
@@ -139,6 +139,43 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => {
 ```
 <!-- prettier-ignore-end -->
 
+### Temporal.now.**dateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.now.timeZone()) : Temporal.DateTime
+
+**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#protocol), or a string.
+  If not given, the current system time zone will be used.
+
+**Returns:** a `Temporal.DateTime` 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.dateTimeISO()`.
+
+### Temporal.now.**dateISO**(_timeZone_: object | string = Temporal.now.timeZone()) : Temporal.Date
+
+**Parameters:**
+
+- `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#protocol), or a string.
+  If not given, the current system time zone will be used.
+
+**Returns:** a `Temporal.Date` object representing the current system date in the reckoning of the ISO 8601 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.
+
+This method is the same as `date()`, but always uses the ISO 8601 calendar.
+
+Example usage:
+
+```js
+// Is it New Year in the ISO 8601 calendar?
+date = Temporal.now.dateISO();
+if (date.month === 1 && date.day === 1) console.log('New year!');
+```
+
 ### Temporal.now.**date**(_calendar_: object | string, _timeZone_: object | string = Temporal.now.timeZone()) : Temporal.Date
 
 **Parameters:**

polyfill/lib/now.mjs

@@ -5,7 +5,9 @@ import { GetIntrinsic } from './intrinsicclass.mjs';
 export const now = {
   instant,
   dateTime,
+  dateTimeISO,
   date,
+  dateISO,
   timeISO,
   timeZone
 };
@@ -20,9 +22,18 @@ function dateTime(calendarLike, temporalTimeZoneLike = timeZone()) {
   const abs = instant();
   return ES.GetTemporalDateTimeFor(timeZone, abs, calendar);
 }
+function dateTimeISO(temporalTimeZoneLike = timeZone()) {
+  const timeZone = ES.ToTemporalTimeZone(temporalTimeZoneLike);
+  const calendar = GetDefaultCalendar();
+  const abs = instant();
+  return ES.GetTemporalDateTimeFor(timeZone, abs, calendar);
+}
 function date(calendarLike, temporalTimeZoneLike = timeZone()) {
   return ES.TemporalDateTimeToDate(dateTime(calendarLike, temporalTimeZoneLike));
 }
+function dateISO(temporalTimeZoneLike = timeZone()) {
+  return ES.TemporalDateTimeToDate(dateTimeISO(temporalTimeZoneLike));
+}
 function timeISO(temporalTimeZoneLike = timeZone()) {
   return ES.TemporalDateTimeToTime(dateTimeISO(temporalTimeZoneLike));
 }

polyfill/test/now.mjs

@@ -19,16 +19,25 @@ import * as Temporal from 'proposal-temporal';
 describe('Temporal.now', () => {
   describe('Structure', () => {
     it('Temporal.now is an object', () => equal(typeof Temporal.now, 'object'));
-    it('Temporal.now has 5 properties', () => equal(Object.keys(Temporal.now).length, 5));
+    it('Temporal.now has 7 properties', () => equal(Object.keys(Temporal.now).length, 7));
     it('Temporal.now.instant is a function', () => equal(typeof Temporal.now.instant, 'function'));
     it('Temporal.now.dateTime is a function', () => equal(typeof Temporal.now.dateTime, 'function'));
+    it('Temporal.now.dateTimeISO is a function', () => equal(typeof Temporal.now.dateTimeISO, 'function'));
     it('Temporal.now.date is a function', () => equal(typeof Temporal.now.date, 'function'));
+    it('Temporal.now.dateISO is a function', () => equal(typeof Temporal.now.dateISO, 'function'));
     it('Temporal.now.timeISO is a function', () => equal(typeof Temporal.now.timeISO, 'function'));
     it('Temporal.now.timeZone is a function', () => equal(typeof Temporal.now.timeZone, 'function'));
   });
   describe('Temporal.now.absolute()', () => {
     it('Temporal.now.instant() returns an Instant', () => assert(Temporal.now.instant() instanceof Temporal.Instant));
   });
+  describe('Temporal.now.dateTimeISO()', () => {
+    it('returns a DateTime in the ISO calendar', () => {
+      const dt = Temporal.now.dateTimeISO();
+      assert(dt instanceof Temporal.DateTime);
+      equal(dt.calendar.id, 'iso8601');
+    });
+  });
   describe('Temporal.now.dateTime()', () => {
     it('returns a DateTime in the correct calendar', () => {
       const dt = Temporal.now.dateTime('gregory');
@@ -37,6 +46,12 @@ describe('Temporal.now', () => {
     });
     it('requires a calendar', () => throws(() => Temporal.now.dateTime(), RangeError));
   });
+  describe('Temporal.now.dateISO()', () => {
+    it('returns a Date in the ISO calendar', () => {
+      const d = Temporal.now.dateISO();
+      assert(d instanceof Temporal.Date);
+      equal(d.calendar.id, 'iso8601');
+    });
   });
   describe('Temporal.now.date()', () => {
     it('returns a Date in the correct calendar', () => {

polyfill/test/usertimezone.mjs

@@ -64,7 +64,9 @@ describe('Userland time zone', () => {
     it('has no next transitions', () => assert.equal(obj.getNextTransition(), null));
     it('has no previous transitions', () => assert.equal(obj.getPreviousTransition(), null));
     it('works in Temporal.now', () => {
+      assert(Temporal.now.dateTimeISO(obj) instanceof Temporal.DateTime);
       assert(Temporal.now.dateTime('gregory', obj) instanceof Temporal.DateTime);
+      assert(Temporal.now.dateISO(obj) instanceof Temporal.Date);
       assert(Temporal.now.date('gregory', obj) instanceof Temporal.Date);
       assert(Temporal.now.timeISO(obj) instanceof Temporal.Time);
     });
@@ -108,7 +110,9 @@ describe('Userland time zone', () => {
         equal(dt.toInstant('Etc/Custom_UTC_Subclass').getEpochSeconds(), 0);
       });
       it('works for Temporal.now', () => {
+        assert(Temporal.now.dateTimeISO('Etc/Custom_UTC_Subclass') instanceof Temporal.DateTime);
         assert(Temporal.now.dateTime('gregory', 'Etc/Custom_UTC_Subclass') instanceof Temporal.DateTime);
+        assert(Temporal.now.dateISO('Etc/Custom_UTC_Subclass') instanceof Temporal.Date);
         assert(Temporal.now.date('gregory', 'Etc/Custom_UTC_Subclass') instanceof Temporal.Date);
         assert(Temporal.now.timeISO('Etc/Custom_UTC_Subclass') instanceof Temporal.Time);
       });
@@ -150,7 +154,9 @@ describe('Userland time zone', () => {
     it('prints in absolute.toString', () =>
       equal(abs.toString(obj), '1970-01-01T00:00+00:00[Etc/Custom_UTC_Protocol]'));
     it('works in Temporal.now', () => {
+      assert(Temporal.now.dateTimeISO(obj) instanceof Temporal.DateTime);
       assert(Temporal.now.dateTime('gregory', obj) instanceof Temporal.DateTime);
+      assert(Temporal.now.dateISO(obj) instanceof Temporal.Date);
       assert(Temporal.now.date('gregory', obj) instanceof Temporal.Date);
       assert(Temporal.now.timeISO(obj) instanceof Temporal.Time);
     });
@@ -194,7 +200,9 @@ describe('Userland time zone', () => {
         equal(dt.toInstant('Etc/Custom_UTC_Protocol').getEpochSeconds(), 0);
       });
       it('works for Temporal.now', () => {
+        assert(Temporal.now.dateTimeISO('Etc/Custom_UTC_Protocol') instanceof Temporal.DateTime);
         assert(Temporal.now.dateTime('gregory', 'Etc/Custom_UTC_Protocol') instanceof Temporal.DateTime);
+        assert(Temporal.now.dateISO('Etc/Custom_UTC_Protocol') instanceof Temporal.Date);
         assert(Temporal.now.date('gregory', 'Etc/Custom_UTC_Protocol') instanceof Temporal.Date);
         assert(Temporal.now.timeISO('Etc/Custom_UTC_Protocol') instanceof Temporal.Time);
       });

spec/temporal.html

@@ -105,6 +105,17 @@ <h1>Temporal.now.dateTime ( _calendar_ [ , _temporalTimeZoneLike_ ] )</h1>
       </emu-alg>
     </emu-clause>
 
+    <emu-clause id="sec-temporal.now.datetimeiso">
+      <h1>Temporal.now.dateTimeISO ( [ _temporalTimeZoneLike_ ] )</h1>
+      <p>
+        The `dateTimeISO` method takes one argument _temporalTimeZoneLike_.
+        The following steps are taken:
+      </p>
+      <emu-alg>
+        1. Return ? SystemDateTime(_temporalTimeZoneLike_).
+      </emu-alg>
+    </emu-clause>
+
     <emu-clause id="sec-temporal.now.date">
       <h1>Temporal.now.date ( _calendar_ [ , _temporalTimeZoneLike_ ] )</h1>
       <p>
@@ -117,6 +128,18 @@ <h1>Temporal.now.date ( _calendar_ [ , _temporalTimeZoneLike_ ] )</h1>
       </emu-alg>
     </emu-clause>
 
+    <emu-clause id="sec-temporal.now.dateiso">
+      <h1>Temporal.now.dateISO ( [ _temporalTimeZoneLike_ ] )</h1>
+      <p>
+        The `dateISO` method takes one argument _temporalTimeZoneLike_.
+        The following steps are taken:
+      </p>
+      <emu-alg>
+        1. Let _dateTime_ be ? SystemDateTime(_temporalTimeZoneLike_).
+        1. Return ? CreateTemporalDate(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]]).
+      </emu-alg>
+    </emu-clause>
+
     <emu-clause id="sec-temporal.now.timeiso">
       <h1>Temporal.now.timeISO ( [ _temporalTimeZoneLike_ ] )</h1>
       <p>