Normative: Remove support for sub-minute offsets in ISO strings

docs/instant.md

@@ -573,7 +573,7 @@ one.equals(one); // => true
 
 **Returns:** a string in the ISO 8601 date format representing `instant`.
 
-This method overrides the `Object.prototype.toString()` method and provides a convenient, unambiguous string representation of `instant`.
+This method overrides the `Object.prototype.toString()` method and provides a convenient string representation of `instant`.
 The string can be passed to `Temporal.Instant.from()` to create a new `Temporal.Instant` object.
 
 The output precision can be controlled with the `fractionalSecondDigits` or `smallestUnit` option.
@@ -582,7 +582,7 @@ If no options are given, the default is `fractionalSecondDigits: 'auto'`, which
 The value is truncated to fit the requested precision, unless a different rounding mode is given with the `roundingMode` option, as in `Temporal.PlainDateTime.round()`.
 Note that rounding may change the value of other units as well.
 
-If the `timeZone` option is given, then the string will express the time in the given time zone, and contain the time zone's UTC offset.
+If the `timeZone` option is given, then the string will express the time in the given time zone, and contain the time zone's UTC offset, rounded to the nearest minute.
 
 Example usage:
 

docs/zoneddatetime.md

@@ -1262,7 +1262,7 @@ Examples:
 - `2011-12-03T10:15:30+01:00[Europe/Paris]`
 - `2011-12-03T10:15:30+09:00[Asia/Tokyo][u-ca=japanese]`
 
-This method overrides the `Object.prototype.toString()` method and provides a convenient, unambiguous string representation of `zonedDateTime`.
+This method overrides the `Object.prototype.toString()` method and provides a convenient string representation of `zonedDateTime`.
 The string is "round-trippable".
 This means that it can be passed to `Temporal.ZonedDateTime.from()` to create a new `Temporal.ZonedDateTime` object with the same field values as the original.
 
@@ -1277,6 +1277,7 @@ By setting the `calendarName` option to `'always'` or `'never'` this can be over
 For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).
 
 Likewise, passing `'never'` to the `timeZoneName` or `offset` options controls whether the time zone offset (`+01:00`) or name annotation (`[Europe/Paris]`) are shown.
+If the time zone offset is shown, it is always shown rounded to the nearest minute.
 
 The string format output by this method can be parsed by [`java.time.ZonedDateTime`](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) as long as the calendar annotation is not output.
 For more information on `Temporal`'s extensions to the ISO string format and the progress towards becoming a published standard, see [ISO standard extensions](./iso-string-ext.md).

polyfill/lib/ecmascript.mjs

@@ -731,6 +731,7 @@ export const ES = ObjectAssign({}, ES2020, {
     if (relativeTo === undefined) return relativeTo;
 
     let offsetBehaviour = 'option';
+    let matchMinutes = false;
     let year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, calendar, timeZone, offset;
     if (ES.Type(relativeTo) === 'Object') {
       if (ES.IsTemporalZonedDateTime(relativeTo) || ES.IsTemporalDateTime(relativeTo)) return relativeTo;
@@ -781,6 +782,7 @@ export const ES = ObjectAssign({}, ES2020, {
       }
       if (!calendar) calendar = ES.GetISO8601Calendar();
       calendar = ES.ToTemporalCalendar(calendar);
+      matchMinutes = true;
     }
     if (timeZone) {
       timeZone = ES.ToTemporalTimeZone(timeZone);
@@ -800,7 +802,8 @@ export const ES = ObjectAssign({}, ES2020, {
         offsetNs,
         timeZone,
         'compatible',
-        'reject'
+        'reject',
+        matchMinutes
       );
       return ES.CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar);
     }
@@ -1271,7 +1274,8 @@ export const ES = ObjectAssign({}, ES2020, {
     offsetNs,
     timeZone,
     disambiguation,
-    offsetOpt
+    offsetOpt,
+    matchMinute
   ) => {
     const DateTime = GetIntrinsic('%Temporal.PlainDateTime%');
     const dt = new DateTime(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
@@ -1307,7 +1311,14 @@ export const ES = ObjectAssign({}, ES2020, {
     const possibleInstants = ES.GetPossibleInstantsFor(timeZone, dt);
     for (const candidate of possibleInstants) {
       const candidateOffset = ES.GetOffsetNanosecondsFor(timeZone, candidate);
-      if (candidateOffset === offsetNs) return GetSlot(candidate, EPOCHNANOSECONDS);
+      const roundedCandidateOffset = ES.RoundNumberToIncrement(
+        bigInt(candidateOffset),
+        60e9,
+        'halfExpand'
+      ).toJSNumber();
+      if (candidateOffset === offsetNs || (matchMinute && roundedCandidateOffset === offsetNs)) {
+        return GetSlot(candidate, EPOCHNANOSECONDS);
+      }
     }
 
     // the user-provided offset doesn't match any instants for this time
@@ -1324,6 +1335,7 @@ export const ES = ObjectAssign({}, ES2020, {
   },
   ToTemporalZonedDateTime: (item, options = ObjectCreate(null)) => {
     let year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, timeZone, offset, calendar;
+    let matchMinute = false;
     let offsetBehaviour = 'option';
     if (ES.Type(item) === 'Object') {
       if (ES.IsTemporalZonedDateTime(item)) return item;
@@ -1365,6 +1377,7 @@ export const ES = ObjectAssign({}, ES2020, {
       timeZone = new TemporalTimeZone(ianaName);
       if (!calendar) calendar = ES.GetISO8601Calendar();
       calendar = ES.ToTemporalCalendar(calendar);
+      matchMinute = true; // ISO strings may specify offset with less precision
     }
     let offsetNs = 0;
     if (offsetBehaviour === 'option') offsetNs = ES.ParseOffsetString(offset);
@@ -1384,7 +1397,8 @@ export const ES = ObjectAssign({}, ES2020, {
       offsetNs,
       timeZone,
       disambiguation,
-      offsetOpt
+      offsetOpt,
+      matchMinute
     );
     return ES.CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar);
   },
@@ -1985,7 +1999,10 @@ export const ES = ObjectAssign({}, ES2020, {
       precision
     );
     let timeZoneString = 'Z';
-    if (timeZone !== undefined) timeZoneString = ES.BuiltinTimeZoneGetOffsetStringFor(outputTimeZone, instant);
+    if (timeZone !== undefined) {
+      const offsetNs = ES.GetOffsetNanosecondsFor(outputTimeZone, instant);
+      timeZoneString = ES.FormatISOTimeZoneOffsetString(offsetNs);
+    }
     return `${year}-${month}-${day}T${hour}:${minute}${seconds}${timeZoneString}`;
   },
   TemporalDurationToString: (duration, precision = 'auto', options = undefined) => {
@@ -2159,7 +2176,10 @@ export const ES = ObjectAssign({}, ES2020, {
       precision
     );
     let result = `${year}-${month}-${day}T${hour}:${minute}${seconds}`;
-    if (showOffset !== 'never') result += ES.BuiltinTimeZoneGetOffsetStringFor(tz, instant);
+    if (showOffset !== 'never') {
+      const offsetNs = ES.GetOffsetNanosecondsFor(tz, instant);
+      result += ES.FormatISOTimeZoneOffsetString(offsetNs);
+    }
     if (showTimeZone !== 'never') result += `[${tz}]`;
     const calendarID = ES.ToString(GetSlot(zdt, CALENDAR));
     result += ES.FormatCalendarAnnotation(calendarID, showCalendar);
@@ -2210,6 +2230,17 @@ export const ES = ObjectAssign({}, ES2020, {
     }
     return `${sign}${hourString}:${minuteString}${post}`;
   },
+  FormatISOTimeZoneOffsetString: (offsetNanoseconds) => {
+    offsetNanoseconds = ES.RoundNumberToIncrement(bigInt(offsetNanoseconds), 60e9, 'halfExpand').toJSNumber();
+    const sign = offsetNanoseconds < 0 ? '-' : '+';
+    offsetNanoseconds = MathAbs(offsetNanoseconds);
+    const minutes = (offsetNanoseconds / 60e9) % 60;
+    const hours = MathFloor(offsetNanoseconds / 3600e9);
+
+    const hourString = ES.ISODateTimePartString(hours);
+    const minuteString = ES.ISODateTimePartString(minutes);
+    return `${sign}${hourString}:${minuteString}`;
+  },
   GetEpochFromISOParts: (year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) => {
     // Note: Date.UTC() interprets one and two-digit years as being in the
     // 20th century, so don't use it

polyfill/lib/zoneddatetime.mjs

@@ -246,7 +246,8 @@ export class ZonedDateTime {
       offsetNs,
       timeZone,
       disambiguation,
-      offset
+      offset,
+      /* matchMinute = */ false
     );
 
     return ES.CreateTemporalZonedDateTime(epochNanoseconds, GetSlot(this, TIME_ZONE), calendar);
@@ -657,7 +658,8 @@ export class ZonedDateTime {
       offsetNs,
       timeZone,
       'compatible',
-      'prefer'
+      'prefer',
+      /* matchMinute = */ false
     );
 
     return ES.CreateTemporalZonedDateTime(epochNanoseconds, timeZone, GetSlot(this, CALENDAR));

polyfill/test/duration.mjs

@@ -653,6 +653,21 @@ describe('Duration', () => {
       equal(`${oneDay.add(hours24, { relativeTo: '2019-11-02T00:00' })}`, 'P2D');
       equal(`${oneDay.add(hours24, { relativeTo: { year: 2019, month: 11, day: 2 } })}`, 'P2D');
     });
+    it('throws on wrong offset for ZonedDateTime relativeTo string', () => {
+      throws(() => oneDay.add(hours24, { relativeTo: '1971-01-01T00:00+02:00[Africa/Monrovia]' }), RangeError);
+    });
+    it('does not throw on HH:MM rounded offset for ZonedDateTime relativeTo string', () => {
+      equal(`${oneDay.add(hours24, { relativeTo: '1971-01-01T00:00-00:45[Africa/Monrovia]' })}`, 'P2D');
+    });
+    it('throws on HH:MM rounded offset for ZonedDateTime relativeTo property bag', () => {
+      throws(
+        () =>
+          oneDay.add(hours24, {
+            relativeTo: { year: 1971, month: 1, day: 1, offset: '-00:45', timeZone: 'Africa/Monrovia' }
+          }),
+        RangeError
+      );
+    });
     it('at least the required properties must be present in relativeTo', () => {
       throws(() => oneDay.add(hours24, { relativeTo: { month: 11, day: 3 } }), TypeError);
       throws(() => oneDay.add(hours24, { relativeTo: { year: 2019, month: 11 } }), TypeError);
@@ -839,6 +854,21 @@ describe('Duration', () => {
       equal(`${oneDay.subtract(hours24, { relativeTo: '2019-11-02T00:00' })}`, 'PT0S');
       equal(`${oneDay.subtract(hours24, { relativeTo: { year: 2019, month: 11, day: 2 } })}`, 'PT0S');
     });
+    it('throws on wrong offset for ZonedDateTime relativeTo string', () => {
+      throws(() => oneDay.subtract(hours24, { relativeTo: '1971-01-01T00:00+02:00[Africa/Monrovia]' }), RangeError);
+    });
+    it('does not throw on HH:MM rounded offset for ZonedDateTime relativeTo string', () => {
+      equal(`${oneDay.subtract(hours24, { relativeTo: '1971-01-01T00:00-00:45[Africa/Monrovia]' })}`, 'PT0S');
+    });
+    it('throws on HH:MM rounded offset for ZonedDateTime relativeTo property bag', () => {
+      throws(
+        () =>
+          oneDay.subtract(hours24, {
+            relativeTo: { year: 1971, month: 1, day: 1, offset: '-00:45', timeZone: 'Africa/Monrovia' }
+          }),
+        RangeError
+      );
+    });
     it('at least the required properties must be present in relativeTo', () => {
       throws(() => oneDay.subtract(hours24, { relativeTo: { month: 11, day: 3 } }), TypeError);
       throws(() => oneDay.subtract(hours24, { relativeTo: { year: 2019, month: 11 } }), TypeError);
@@ -1102,6 +1132,28 @@ describe('Duration', () => {
         throws(() => d.round({ smallestUnit: 'seconds', relativeTo }), RangeError);
       });
     });
+    it('throws on wrong offset for ZonedDateTime relativeTo string', () => {
+      throws(
+        () => d.round({ smallestUnit: 'seconds', relativeTo: '1971-01-01T00:00+02:00[Africa/Monrovia]' }),
+        RangeError
+      );
+    });
+    it('does not throw on HH:MM rounded offset for ZonedDateTime relativeTo string', () => {
+      equal(
+        `${d.round({ smallestUnit: 'seconds', relativeTo: '1971-01-01T00:00-00:45[Africa/Monrovia]' })}`,
+        'P5Y5M5W5DT5H5M5S'
+      );
+    });
+    it('throws on HH:MM rounded offset for ZonedDateTime relativeTo property bag', () => {
+      throws(
+        () =>
+          d.round({
+            smallestUnit: 'seconds',
+            relativeTo: { year: 1971, month: 1, day: 1, offset: '-00:45', timeZone: 'Africa/Monrovia' }
+          }),
+        RangeError
+      );
+    });
     it('relativeTo object must contain at least the required correctly-spelled properties', () => {
       throws(() => hours25.round({ largestUnit: 'days', relativeTo: { month: 11, day: 3 } }), TypeError);
       throws(() => hours25.round({ largestUnit: 'days', relativeTo: { year: 2019, month: 11 } }), TypeError);
@@ -1455,6 +1507,23 @@ describe('Duration', () => {
         throws(() => d.total({ unit: 'months', relativeTo }), RangeError);
       });
     });
+    it('throws on wrong offset for ZonedDateTime relativeTo string', () => {
+      throws(() => d.total({ unit: 'months', relativeTo: '1971-01-01T00:00+02:00[Africa/Monrovia]' }), RangeError);
+    });
+    it('does not throw on HH:MM rounded offset for ZonedDateTime relativeTo string', () => {
+      const oneMonth = Duration.from({ months: 1 });
+      equal(oneMonth.total({ unit: 'months', relativeTo: '1971-01-01T00:00-00:45[Africa/Monrovia]' }), 1);
+    });
+    it('throws on HH:MM rounded offset for ZonedDateTime relativeTo property bag', () => {
+      throws(
+        () =>
+          d.total({
+            unit: 'months',
+            relativeTo: { year: 1971, month: 1, day: 1, offset: '-00:45', timeZone: 'Africa/Monrovia' }
+          }),
+        RangeError
+      );
+    });
     it('relativeTo object must contain at least the required correctly-spelled properties', () => {
       throws(() => d.total({ unit: 'months', relativeTo: {} }), TypeError);
       throws(() => d.total({ unit: 'months', relativeTo: { years: 2020, month: 1, day: 1 } }), TypeError);

polyfill/test/instant.mjs

@@ -32,7 +32,7 @@ describe('Instant', () => {
     it('sub-minute offset', () => {
       const inst = Instant.from('1900-01-01T12:00Z');
       const timeZone = Temporal.TimeZone.from('Europe/Amsterdam');
-      equal(inst.toString({ timeZone }), '1900-01-01T12:19:32+00:19:32');
+      equal(inst.toString({ timeZone }), '1900-01-01T12:19:32+00:20');
     });
     const i1 = Instant.from('1976-11-18T15:23Z');
     const i2 = Instant.from('1976-11-18T15:23:30Z');

polyfill/test/timezone.mjs

@@ -78,7 +78,8 @@ describe('TimeZone', () => {
     const dtm = Temporal.PlainDateTime.from('1900-01-01T12:00');
     it(`${zone} has ID ${zone}`, () => equal(zone.id, `${zone}`));
     it(`${zone} has offset +00:19:32 in ns`, () => equal(zone.getOffsetNanosecondsFor(inst), 1172000000000));
-    it(`${zone} has offset +00:19:32`, () => equal(zone.getOffsetStringFor(inst), '+00:19:32'));
+    it(`${zone} has offset +00:19:32, does not truncate to HH:MM`, () =>
+      equal(zone.getOffsetStringFor(inst), '+00:19:32'));
     it(`(${zone}).getPlainDateTimeFor(${inst})`, () =>
       equal(`${zone.getPlainDateTimeFor(inst)}`, '1900-01-01T12:19:32'));
     it(`(${zone}).getInstantFor(${dtm})`, () => equal(`${zone.getInstantFor(dtm)}`, '1900-01-01T11:40:28Z'));

polyfill/test/usertimezone.mjs

@@ -161,11 +161,11 @@ describe('Userland time zone', () => {
       equal(`${obj.getInstantFor(dt)}`, '1976-11-18T15:23:31.2345679Z');
     });
     it('converts to string', () => equal(`${obj}`, obj.id));
-    it('offset prints in instant.toString', () =>
-      equal(inst.toString({ timeZone: obj }), '1969-12-31T23:59:58.888888889-00:00:01.111111111'));
-    it('prints in zdt.toString', () => {
+    it('offset prints with minute precision in instant.toString', () =>
+      equal(inst.toString({ timeZone: obj }), '1969-12-31T23:59:58.888888889+00:00'));
+    it('offset prints with minute precision prints in zdt.toString', () => {
       const zdt = new Temporal.ZonedDateTime(0n, obj);
-      equal(zdt.toString(), '1969-12-31T23:59:58.888888889-00:00:01.111111111[Custom/Subminute]');
+      equal(zdt.toString(), '1969-12-31T23:59:58.888888889+00:00[Custom/Subminute]');
     });
     it('has no next transitions', () => assert.equal(obj.getNextTransition(), null));
     it('has no previous transitions', () => assert.equal(obj.getPreviousTransition(), null));

polyfill/test/zoneddatetime.mjs

@@ -726,6 +726,70 @@ describe('ZonedDateTime', () => {
         });
       });
     });
+    describe('sub-minute time zone offsets', () => {
+      ['use', 'ignore', 'prefer', 'reject'].forEach((offset) => {
+        it(`accepts the exact offset string (offset=${offset})`, () => {
+          const zdt1 = ZonedDateTime.from('1971-01-01T12:00-00:44:30[Africa/Monrovia]', { offset });
+          equal(`${zdt1}`, '1971-01-01T12:00:00-00:45[Africa/Monrovia]');
+          equal(zdt1.offset, '-00:44:30');
+
+          const zdt2 = ZonedDateTime.from('1921-01-01T12:00+00:19:32[Europe/Amsterdam]', { offset });
+          equal(`${zdt2}`, '1921-01-01T12:00:00+00:20[Europe/Amsterdam]');
+          equal(zdt2.offset, '+00:19:32');
+        });
+      });
+      it('prioritizes the offset string with HH:MM precision when offset=use', () => {
+        const zdt1 = ZonedDateTime.from('1971-01-01T12:00-00:45[Africa/Monrovia]', { offset: 'use' });
+        equal(`${zdt1}`, '1971-01-01T12:00:30-00:45[Africa/Monrovia]');
+        equal(zdt1.offset, '-00:44:30');
+
+        const zdt2 = ZonedDateTime.from('1921-01-01T12:00+00:20[Europe/Amsterdam]', { offset: 'use' });
+        equal(`${zdt2}`, '1921-01-01T11:59:32+00:20[Europe/Amsterdam]');
+        equal(zdt2.offset, '+00:19:32');
+      });
+      ['ignore', 'prefer', 'reject'].forEach((offset) => {
+        it(`accepts the offset string with HH:MM precision (offset=${offset})`, () => {
+          const zdt1 = ZonedDateTime.from('1971-01-01T12:00-00:45[Africa/Monrovia]', { offset });
+          equal(`${zdt1}`, '1971-01-01T12:00:00-00:45[Africa/Monrovia]');
+          equal(zdt1.offset, '-00:44:30');
+
+          const zdt2 = ZonedDateTime.from('1921-01-01T12:00+00:20[Europe/Amsterdam]', { offset });
+          equal(`${zdt2}`, '1921-01-01T12:00:00+00:20[Europe/Amsterdam]');
+          equal(zdt2.offset, '+00:19:32');
+        });
+      });
+      it('does not do fuzzy matching on HH:MM offset string passed in a property bag in from()', () => {
+        const properties = { year: 1971, month: 1, day: 1, hour: 12, offset: '-00:45', timeZone: 'Africa/Monrovia' };
+        const zdt1 = ZonedDateTime.from(properties, { offset: 'use' });
+        equal(`${zdt1}`, '1971-01-01T12:00:30-00:45[Africa/Monrovia]');
+
+        const zdt2 = ZonedDateTime.from(properties, { offset: 'ignore' });
+        equal(`${zdt2}`, '1971-01-01T12:00:00-00:45[Africa/Monrovia]');
+
+        const zdt3 = ZonedDateTime.from(properties, { offset: 'prefer' });
+        equal(`${zdt3}`, '1971-01-01T12:00:00-00:45[Africa/Monrovia]');
+
+        throws(() => ZonedDateTime.from(properties, { offset: 'reject' }), RangeError);
+      });
+      it('does not do fuzzy matching on HH:MM offset string passed in a property bag in with()', () => {
+        const zdt = ZonedDateTime.from({ year: 1971, month: 1, day: 1, hour: 12, timeZone: 'Africa/Monrovia' });
+
+        const zdt1 = zdt.with({ month: 2, offset: '-00:45' }, { offset: 'use' });
+        equal(`${zdt1}`, '1971-02-01T12:00:30-00:45[Africa/Monrovia]');
+
+        const zdt2 = zdt.with({ month: 2, offset: '-00:45' }, { offset: 'ignore' });
+        equal(`${zdt2}`, '1971-02-01T12:00:00-00:45[Africa/Monrovia]');
+
+        const zdt3 = zdt.with({ month: 2, offset: '-00:45' }, { offset: 'prefer' });
+        equal(`${zdt3}`, '1971-02-01T12:00:00-00:45[Africa/Monrovia]');
+
+        throws(() => zdt.with({ month: 2, offset: '-00:45' }, { offset: 'reject' }), RangeError);
+      });
+      it('does not truncate offset property to minutes', () => {
+        const zdt = ZonedDateTime.from({ year: 1971, month: 1, day: 1, hour: 12, timeZone: 'Africa/Monrovia' });
+        equal(zdt.offset, '-00:44:30');
+      });
+    });
   });
 
   describe('ZonedDateTime.with()', () => {