Add getISOCalendarFields() method to calendar-dependent types

This is in order to be able to get the underlying fields from the data
model, which are stored in the ISO 8601 calendar.

It's not expected to be used in normal Temporal usage, it really exists
only for calendar implementors.

Closes: #354

docs/date.md

@@ -496,3 +496,17 @@ date = Temporal.Date.from('2006-08-24');
 Object.assign({}, date).day  // => undefined
 Object.assign({}, date.getFields()).day  // => 24
 ```
+
+### date.**getISOCalendarFields()**(): { year: number, month: number, day: number }
+
+**Returns:** a plain object with properties expressing `date` in the ISO 8601 calendar.
+
+This method is mainly useful if you are implementing a custom calendar.
+Most code will not need to use it.
+Use `date.getFields()` instead.
+
+Usage example:
+```javascript
+date = Temporal.Date.from('2006-08-24');
+date.getISOCalendarFields().day  // => 24
+```

docs/datetime.md

@@ -573,3 +573,17 @@ dt = Temporal.DateTime.from('1995-12-07T03:24:30.000003500');
 Object.assign({}, dt).day  // => undefined
 Object.assign({}, dt.getFields()).day  // => 7
 ```
+
+### datetime.**getISOCalendarFields()**(): { year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number, microsecond: number, nanosecond: number }
+
+**Returns:** a plain object with properties expressing `datetime` in the ISO 8601 calendar.
+
+This method is mainly useful if you are implementing a custom calendar.
+Most code will not need to use it.
+Use `datetime.getFields()` instead.
+
+Usage example:
+```javascript
+dt = Temporal.Date.from('1995-12-07T03:24:30.000003500');
+date.getISOCalendarFields().day  // => 7
+```

docs/monthday.md

@@ -283,3 +283,17 @@ md = Temporal.MonthDay.from('08-24');
 Object.assign({}, md).day  // => undefined
 Object.assign({}, md.getFields()).day  // => 24
 ```
+
+### monthDay.**getISOCalendarFields()**(): { month: number, day: number }
+
+**Returns:** a plain object with properties expressing `monthDay` in the ISO 8601 calendar.
+
+This method is mainly useful if you are implementing a custom calendar.
+Most code will not need to use it.
+Use `monthDay.getFields()` instead.
+
+Usage example:
+```javascript
+md = Temporal.MonthDay.from('08-24');
+md.getISOCalendarFields().day  // => 24
+```

docs/yearmonth.md

@@ -423,3 +423,17 @@ ym = Temporal.DateTime.from('2019-06');
 Object.assign({}, ym).year  // => undefined
 Object.assign({}, ym.getFields()).year  // => 2019
 ```
+
+### yearMonth.**getISOCalendarFields()**(): { year: number, month: number }
+
+**Returns:** a plain object with properties expressing `yearMonth` in the ISO 8601 calendar.
+
+This method is mainly useful if you are implementing a custom calendar.
+Most code will not need to use it.
+Use `yearMonth.getFields()` instead.
+
+Usage example:
+```javascript
+ym = Temporal.YearMonth.from('2019-06');
+ym.getISOCalendarFields().year  // => 2019
+```

polyfill/lib/date.mjs

@@ -173,6 +173,14 @@ export class Date {
     if (!fields) throw new TypeError('invalid receiver');
     return fields;
   }
+  getISOCalendarFields() {
+    if (!ES.IsTemporalDate(this)) throw new TypeError('invalid receiver');
+    return {
+      year: GetSlot(this, ISO_YEAR),
+      month: GetSlot(this, ISO_MONTH),
+      day: GetSlot(this, ISO_DAY)
+    };
+  }
   static from(item, options = undefined) {
     const disambiguation = ES.ToTemporalDisambiguation(options);
     let year, month, day;

polyfill/lib/datetime.mjs

@@ -338,6 +338,20 @@ export class DateTime {
     if (!fields) throw new TypeError('invalid receiver');
     return fields;
   }
+  getISOCalendarFields() {
+    if (!ES.IsTemporalDateTime(this)) throw new TypeError('invalid receiver');
+    return {
+      year: GetSlot(this, ISO_YEAR),
+      month: GetSlot(this, ISO_MONTH),
+      day: GetSlot(this, ISO_DAY),
+      hour: GetSlot(this, HOUR),
+      minute: GetSlot(this, MINUTE),
+      second: GetSlot(this, SECOND),
+      millisecond: GetSlot(this, MILLISECOND),
+      microsecond: GetSlot(this, MICROSECOND),
+      nanosecond: GetSlot(this, NANOSECOND)
+    };
+  }
 
   static from(item, options = undefined) {
     const disambiguation = ES.ToTemporalDisambiguation(options);

polyfill/lib/monthday.mjs

@@ -66,6 +66,13 @@ export class MonthDay {
     if (!fields) throw new TypeError('invalid receiver');
     return fields;
   }
+  getISOCalendarFields() {
+    if (!ES.IsTemporalMonthDay(this)) throw new TypeError('invalid receiver');
+    return {
+      month: GetSlot(this, ISO_MONTH),
+      day: GetSlot(this, ISO_DAY)
+    };
+  }
   static from(item, options = undefined) {
     const disambiguation = ES.ToTemporalDisambiguation(options);
     let month, day;

polyfill/lib/yearmonth.mjs

@@ -135,6 +135,13 @@ export class YearMonth {
     if (!fields) throw new TypeError('invalid receiver');
     return fields;
   }
+  getISOCalendarFields() {
+    if (!ES.IsTemporalYearMonth(this)) throw new TypeError('invalid receiver');
+    return {
+      year: GetSlot(this, ISO_YEAR),
+      month: GetSlot(this, ISO_MONTH)
+    };
+  }
   static from(item, options = undefined) {
     const disambiguation = ES.ToTemporalDisambiguation(options);
     let year, month;

polyfill/test/Date/prototype/getISOCalendarFields/branding.js

@@ -0,0 +1,16 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+const getISOCalendarFields = Temporal.Date.prototype.getISOCalendarFields;
+
+assert.sameValue(typeof getISOCalendarFields, "function");
+
+assert.throws(TypeError, () => getISOCalendarFields.call(undefined), "undefined");
+assert.throws(TypeError, () => getISOCalendarFields.call(null), "null");
+assert.throws(TypeError, () => getISOCalendarFields.call(true), "true");
+assert.throws(TypeError, () => getISOCalendarFields.call(""), "empty string");
+assert.throws(TypeError, () => getISOCalendarFields.call(Symbol()), "symbol");
+assert.throws(TypeError, () => getISOCalendarFields.call(1), "1");
+assert.throws(TypeError, () => getISOCalendarFields.call({}), "plain object");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.Date), "Temporal.Date");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.Date.prototype), "Temporal.Date.prototype");

polyfill/test/Date/prototype/getISOCalendarFields/prop-desc.js

@@ -0,0 +1,18 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+includes: [propertyHelper.js]
+---*/
+
+assert.sameValue(
+  typeof Temporal.Date.prototype.getISOCalendarFields,
+  "function",
+  "`typeof Date.prototype.getISOCalendarFields` is `function`"
+);
+
+verifyProperty(Temporal.Date.prototype, "getISOCalendarFields", {
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

polyfill/test/Date/prototype/getISOCalendarFields/subclass.js

@@ -0,0 +1,31 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+esid: sec-temporal.date.prototype.getisocalendarfields
+includes: [compareArray.js]
+---*/
+
+let called = 0;
+
+const constructorArguments = [
+  [2000, 5, 2]
+];
+
+class MyDate extends Temporal.Date {
+  constructor(year, month, day) {
+    assert.compareArray([year, month, day], constructorArguments.shift(), "constructor arguments");
+    ++called;
+    super(year, month, day);
+  }
+}
+
+const instance = MyDate.from("2000-05-02");
+assert.sameValue(called, 1);
+
+const result = instance.getISOCalendarFields();
+assert.sameValue(result.year, 2000, "year result");
+assert.sameValue(result.month, 5, "month result");
+assert.sameValue(result.day, 2, "day result");
+assert.sameValue(called, 1);
+assert.sameValue(Object.getPrototypeOf(result), Object.prototype);

polyfill/test/DateTime/prototype/getISOCalendarFields/branding.js

@@ -0,0 +1,16 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+const getISOCalendarFields = Temporal.DateTime.prototype.getISOCalendarFields;
+
+assert.sameValue(typeof getISOCalendarFields, "function");
+
+assert.throws(TypeError, () => getISOCalendarFields.call(undefined), "undefined");
+assert.throws(TypeError, () => getISOCalendarFields.call(null), "null");
+assert.throws(TypeError, () => getISOCalendarFields.call(true), "true");
+assert.throws(TypeError, () => getISOCalendarFields.call(""), "empty string");
+assert.throws(TypeError, () => getISOCalendarFields.call(Symbol()), "symbol");
+assert.throws(TypeError, () => getISOCalendarFields.call(1), "1");
+assert.throws(TypeError, () => getISOCalendarFields.call({}), "plain object");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.DateTime), "Temporal.DateTime");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.DateTime.prototype), "Temporal.DateTime.prototype");

polyfill/test/DateTime/prototype/getISOCalendarFields/prop-desc.js

@@ -0,0 +1,18 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+includes: [propertyHelper.js]
+---*/
+
+assert.sameValue(
+  typeof Temporal.DateTime.prototype.getISOCalendarFields,
+  "function",
+  "`typeof DateTime.prototype.getISOCalendarFields` is `function`"
+);
+
+verifyProperty(Temporal.DateTime.prototype, "getISOCalendarFields", {
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

polyfill/test/DateTime/prototype/getISOCalendarFields/subclass.js

@@ -0,0 +1,37 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+esid: sec-temporal.datetime.prototype.getisocalendarfields
+includes: [compareArray.js]
+---*/
+
+let called = 0;
+
+const constructorArguments = [
+  [2000, 5, 2, 12, 34, 56, 987, 654, 321]
+];
+
+class MyDateTime extends Temporal.DateTime {
+  constructor(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) {
+    assert.compareArray([year, month, day, hour, minute, second, millisecond, microsecond, nanosecond], constructorArguments.shift(), "constructor arguments");
+    ++called;
+    super(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
+  }
+}
+
+const instance = MyDateTime.from("2000-05-02T12:34:56.987654321");
+assert.sameValue(called, 1);
+
+const result = instance.getISOCalendarFields();
+assert.sameValue(result.year, 2000, "year result");
+assert.sameValue(result.month, 5, "month result");
+assert.sameValue(result.day, 2, "day result");
+assert.sameValue(result.hour, 12, "hour result");
+assert.sameValue(result.minute, 34, "minute result");
+assert.sameValue(result.second, 56, "second result");
+assert.sameValue(result.millisecond, 987, "millisecond result");
+assert.sameValue(result.microsecond, 654, "microsecond result");
+assert.sameValue(result.nanosecond, 321, "nanosecond result");
+assert.sameValue(called, 1);
+assert.sameValue(Object.getPrototypeOf(result), Object.prototype);

polyfill/test/MonthDay/prototype/getISOCalendarFields/branding.js

@@ -0,0 +1,16 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+const getISOCalendarFields = Temporal.MonthDay.prototype.getISOCalendarFields;
+
+assert.sameValue(typeof getISOCalendarFields, "function");
+
+assert.throws(TypeError, () => getISOCalendarFields.call(undefined), "undefined");
+assert.throws(TypeError, () => getISOCalendarFields.call(null), "null");
+assert.throws(TypeError, () => getISOCalendarFields.call(true), "true");
+assert.throws(TypeError, () => getISOCalendarFields.call(""), "empty string");
+assert.throws(TypeError, () => getISOCalendarFields.call(Symbol()), "symbol");
+assert.throws(TypeError, () => getISOCalendarFields.call(1), "1");
+assert.throws(TypeError, () => getISOCalendarFields.call({}), "plain object");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.MonthDay), "Temporal.MonthDay");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.MonthDay.prototype), "Temporal.MonthDay.prototype");

polyfill/test/MonthDay/prototype/getISOCalendarFields/prop-desc.js

@@ -0,0 +1,18 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+includes: [propertyHelper.js]
+---*/
+
+assert.sameValue(
+  typeof Temporal.MonthDay.prototype.getISOCalendarFields,
+  "function",
+  "`typeof MonthDay.prototype.getISOCalendarFields` is `function`"
+);
+
+verifyProperty(Temporal.MonthDay.prototype, "getISOCalendarFields", {
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

polyfill/test/MonthDay/prototype/getISOCalendarFields/subclass.js

@@ -0,0 +1,30 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+esid: sec-temporal.monthday.prototype.getisocalendarfields
+includes: [compareArray.js]
+---*/
+
+let called = 0;
+
+const constructorArguments = [
+  [5, 2]
+];
+
+class MyMonthDay extends Temporal.MonthDay {
+  constructor(month, day) {
+    assert.compareArray([month, day], constructorArguments.shift(), "constructor arguments");
+    ++called;
+    super(month, day);
+  }
+}
+
+const instance = MyMonthDay.from("05-02");
+assert.sameValue(called, 1);
+
+const result = instance.getISOCalendarFields();
+assert.sameValue(result.month, 5, "month result");
+assert.sameValue(result.day, 2, "day result");
+assert.sameValue(called, 1);
+assert.sameValue(Object.getPrototypeOf(result), Object.prototype);

polyfill/test/YearMonth/prototype/getISOCalendarFields/branding.js

@@ -0,0 +1,16 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+const getISOCalendarFields = Temporal.YearMonth.prototype.getISOCalendarFields;
+
+assert.sameValue(typeof getISOCalendarFields, "function");
+
+assert.throws(TypeError, () => getISOCalendarFields.call(undefined), "undefined");
+assert.throws(TypeError, () => getISOCalendarFields.call(null), "null");
+assert.throws(TypeError, () => getISOCalendarFields.call(true), "true");
+assert.throws(TypeError, () => getISOCalendarFields.call(""), "empty string");
+assert.throws(TypeError, () => getISOCalendarFields.call(Symbol()), "symbol");
+assert.throws(TypeError, () => getISOCalendarFields.call(1), "1");
+assert.throws(TypeError, () => getISOCalendarFields.call({}), "plain object");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.YearMonth), "Temporal.YearMonth");
+assert.throws(TypeError, () => getISOCalendarFields.call(Temporal.YearMonth.prototype), "Temporal.YearMonth.prototype");

polyfill/test/YearMonth/prototype/getISOCalendarFields/prop-desc.js

@@ -0,0 +1,18 @@
+// Copyright (C) 2020 Igalia, S.L. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+
+/*---
+includes: [propertyHelper.js]
+---*/
+
+assert.sameValue(
+  typeof Temporal.YearMonth.prototype.getISOCalendarFields,
+  "function",
+  "`typeof YearMonth.prototype.getISOCalendarFields` is `function`"
+);
+
+verifyProperty(Temporal.YearMonth.prototype, "getISOCalendarFields", {
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});