Normative: Partial stack of removals

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

docs/ambiguity.md

@@ -113,11 +113,11 @@ dateTime = Temporal.PlainDateTime.from('2019-12-17T07:48');
 zdt = dateTime.toZonedDateTime('Asia/Tokyo');
   // => 2019-12-17T07:48:00+09:00[Asia/Tokyo]
 
-// Get the exact time in seconds, milliseconds, or nanoseconds since the UNIX epoch.
+// Get the exact time in seconds, milliseconds or nanoseconds since the UNIX epoch.
 inst = zdt.toInstant();
 epochNano = inst.epochNanoseconds; // => 1576536480000000000n
 epochMilli = inst.epochMilliseconds; // => 1576536480000
-epochSecs = inst.epochSeconds; // => 1576536480
+epochSecs = Math.floor(inst.epochMilliseconds / 1000); // => 1576536480
 ```
 <!-- prettier-ignore-end -->
 

docs/cookbook/getTimeStamp.mjs

@@ -9,5 +9,6 @@ const timeStamp = Temporal.Now.instant();
 
 // Timestamp in Milliseconds
 timeStamp.epochMilliseconds;
+
 // Timestamp in Seconds
-timeStamp.epochSeconds;
+Math.floor(timeStamp.epochMilliseconds / 1000);

docs/cookbook/makeExpandedTemporal.mjs

@@ -156,31 +156,17 @@ class ExpandedPlainDateTime extends Temporal.PlainDateTime {
   }
 }
 
-class ExpandedPlainTime extends Temporal.PlainTime {
-  toPlainDateTime(date) {
-    return ExpandedPlainDateTime._convert(super.toPlainDateTime(date), date.year);
-  }
-
-  static from(item) {
-    const { hour, minute, second, millisecond, microsecond, nanosecond } = super.from(item);
-    return new ExpandedPlainTime(hour, minute, second, millisecond, microsecond, nanosecond);
-  }
-}
-
 function makeExpandedTemporal() {
   return {
     ...Temporal,
     PlainDate: ExpandedPlainDate,
-    PlainDateTime: ExpandedPlainDateTime,
-    PlainTime: ExpandedPlainTime
+    PlainDateTime: ExpandedPlainDateTime
   };
 }
 
 const ExpandedTemporal = makeExpandedTemporal();
 
 const date = ExpandedTemporal.PlainDate.from({ year: 635427810, month: 2, day: 2 });
 assert.equal(date.toString(), '+0635427810-02-02');
-const dateTime = ExpandedTemporal.PlainTime.from('10:23').toPlainDateTime(date);
-assert.equal(dateTime.toString(), '+0635427810-02-02T10:23:00');
 const dateFromString = ExpandedTemporal.PlainDateTime.from('-0075529144-02-29T12:53:27.55');
 assert.equal(dateFromString.year, -75529144n);

docs/instant.md

@@ -134,29 +134,6 @@ instant === Temporal.Instant.from(instant); // => false
 ```
 <!-- prettier-ignore-end -->
 
-### Temporal.Instant.**fromEpochSeconds**(_epochSeconds_: number) : Temporal.Instant
-
-**Parameters:**
-
-- `epochSeconds` (number): A number of seconds.
-
-**Returns:** a new `Temporal.Instant` object.
-
-This static method creates a new `Temporal.Instant` object with seconds precision.
-`epochSeconds` is the number of seconds between the Unix epoch (midnight UTC on January 1, 1970) and the desired exact time.
-
-The number of seconds since the Unix epoch is a common measure of exact time in many computer systems.
-Use this method if you need to interface with such a system.
-
-Example usage:
-
-```js
-// Same examples as in new Temporal.Instant(), but with seconds precision
-instant = Temporal.Instant.fromEpochSeconds(1553906700);
-epoch = Temporal.Instant.fromEpochSeconds(0); // => 1970-01-01T00:00:00Z
-turnOfTheCentury = Temporal.Instant.fromEpochSeconds(-2208988800); // => 1900-01-01T00:00:00Z
-```
-
 ### Temporal.Instant.**fromEpochMilliseconds**(_epochMilliseconds_: number) : Temporal.Instant
 
 **Parameters:**
@@ -165,7 +142,11 @@ turnOfTheCentury = Temporal.Instant.fromEpochSeconds(-2208988800); // => 1900-01
 
 **Returns:** a new `Temporal.Instant` object.
 
-Same as `Temporal.Instant.fromEpochSeconds()`, but with millisecond (10<sup>&minus;3</sup> second) precision.
+This static method creates a new `Temporal.Instant` object with milliseconds precision (i.e., zero values in all units smaller than a millisecond).
+`epochMilliseconds` is the number of milliseconds from the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time) of January 1, 1970 at 00:00 UTC until the desired exact time, ignoring leap seconds.
+
+The number of seconds or milliseconds since the Unix epoch is a common measure of exact time in many computer systems.
+Use this method if you need to interface with such a system.
 
 The number of milliseconds since the Unix epoch is also returned from the `getTime()` and `valueOf()` methods of legacy JavaScript `Date` objects, as well as `Date.now()`.
 However, for conversion from legacy `Date` to `Temporal.Instant`, use `Date.prototype.toTemporalInstant`:
@@ -178,17 +159,11 @@ instant = legacyDate.toTemporalInstant(); // recommended
 
 // Use fromEpochMilliseconds, for example, if you have epoch millisecond data stored in a file
 todayMs = Temporal.Instant.fromEpochMilliseconds(msReadFromFile);
-```
-
-### Temporal.Instant.**fromEpochMicroseconds**(_epochMicroseconds_ : bigint) : Temporal.Instant
-
-**Parameters:**
 
-- `epochMicroseconds` (bigint): A number of microseconds.
-
-**Returns:** a new `Temporal.Instant` object.
-
-Same as `Temporal.Instant.fromEpochSeconds()`, but with microsecond (10<sup>&minus;6</sup> second) precision.
+// If you have epoch seconds data:
+epochSecs = 1553906700;  // e.g., read from a file
+instant = Temporal.Instant.fromEpochMilliseconds(epochSecs * 1000);
+```
 
 ### Temporal.Instant.**fromEpochNanoseconds**(_epochNanoseconds_ : bigint) : Temporal.Instant
 
@@ -198,9 +173,15 @@ Same as `Temporal.Instant.fromEpochSeconds()`, but with microsecond (10<sup>&min
 
 **Returns:** a new `Temporal.Instant` object.
 
-Same as `Temporal.Instant.fromEpochSeconds()`, but with nanosecond (10<sup>&minus;9</sup> second) precision.
+Same as `Temporal.Instant.fromEpochMilliseconds()`, but with nanosecond (10<sup>&minus;9</sup> second) precision.
 Also the same as `new Temporal.Instant(epochNanoseconds)`.
 
+If you have epoch microseconds data, you can use this function to create a `Temporal.Instant` from that:
+```js
+epochMicros = 1553906700_000_000n;
+instant = Temporal.Instant.fromEpochNanoseconds(epochMicros * 1000n);
+```
+
 ### Temporal.Instant.**compare**(_one_: Temporal.Instant | string, _two_: Temporal.Instant | string) : number
 
 **Parameters:**
@@ -223,55 +204,49 @@ This function can be used to sort arrays of `Temporal.Instant` objects.
 For example:
 
 ```javascript
-one = Temporal.Instant.fromEpochSeconds(1.0e9);
-two = Temporal.Instant.fromEpochSeconds(1.1e9);
-three = Temporal.Instant.fromEpochSeconds(1.2e9);
+one = Temporal.Instant.fromEpochMilliseconds(1.0e12);
+two = Temporal.Instant.fromEpochMilliseconds(1.1e12);
+three = Temporal.Instant.fromEpochMilliseconds(1.2e12);
 sorted = [three, one, two].sort(Temporal.Instant.compare);
 sorted.join(' ');
 // => '2001-09-09T01:46:40Z 2004-11-09T11:33:20Z 2008-01-10T21:20:00Z'
 ```
 
 ## Properties
 
-### instant.**epochSeconds** : number
+### instant.**epochMilliseconds** : number
 
-The value of this property is an integer number of seconds between the Unix epoch (midnight UTC on January 1, 1970) and `instant`.
+The value of this property is an integer number of milliseconds from the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time) of January 1, 1970 at 00:00 UTC until `instant`, ignoring leap seconds.
 This number will be negative if `instant` is before 1970.
-The number of seconds is truncated towards zero.
-
-Use this property if you need to interface with some other system that reckons time in seconds since the Unix epoch.
-
-Example usage:
+The number of milliseconds is truncated towards the beginning of time.
 
-```js
-instant = Temporal.Instant.from('2019-03-30T01:45+01:00');
-instant.epochSeconds; // => 1553906700
-```
-
-### instant.**epochMilliseconds** : number
-
-Same as `epochSeconds`, but with millisecond (10<sup>&minus;3</sup> second) precision.
-The number of seconds is truncated towards zero.
+Use this property if you need to interface with some other system that reckons time in milliseconds since the Unix epoch.
 
 This method can be useful in particular to create an old-style JavaScript `Date` object, if one is needed.
 An example:
 
 ```js
 instant = Temporal.Instant.from('2019-03-30T00:45Z');
 new Date(instant.epochMilliseconds); // => 2019-03-30T00:45:00.000Z
-```
-
-### instant.**epochMicroseconds** : bigint
 
-Same as `epochSeconds`, but the value is a bigint with microsecond (10<sup>&minus;6</sup> second) precision.
-The number of seconds is truncated towards zero.
+// If you need epoch seconds data:
+epochSecs = Math.floor(instant.epochMillieconds / 1000); // => 1553906700
+```
 
 ### instant.**epochNanoseconds** : bigint
 
-Same as `epochSeconds`, but the value is a bigint with nanosecond (10<sup>&minus;9</sup> second) precision.
+Same as `epochMilliseconds`, but the value is a bigint with nanosecond (10<sup>&minus;9</sup> second) precision.
 
 The value of this property is suitable to be passed to `new Temporal.Instant()`.
 
+If you need epoch microseconds data, you can divide the epoch nanoseconds by 1000, but note that bigint division is a truncation, whereas you should use floor rounding to calculate epoch microseconds in the case of a negative value.
+That can be done with bigints like this:
+
+```js
+ns = instant.epochNanoseconds;
+epochMicros = ns / 1000n + ((ns % 1000n) < 0n ? -1n : 0n);
+```
+
 ## Methods
 
 ### instant.**toZonedDateTimeISO**(_timeZone_: object | string) : Temporal.ZonedDateTime
@@ -289,51 +264,25 @@ The value of this property is suitable to be passed to `new Temporal.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.
 
-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:
 
 ```js
 // Converting a specific exact time to a calendar date / wall-clock time
-timestamp = Temporal.Instant.fromEpochSeconds(1553993100);
+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.fromEpochSeconds(0);
-timeZone = Temporal.TimeZone.from('America/New_York');
-epoch.toZonedDateTime({ timeZone, calendar: 'gregory' });
+epoch = Temporal.Instant.fromEpochMilliseconds(0);
+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'
@@ -470,8 +419,8 @@ approxMissionLength = startOfMoonMission.until(endOfMoonMission, {
   // => PT195H
 
 // A billion (10^9) seconds since the epoch in different units
-epoch = Temporal.Instant.fromEpochSeconds(0);
-billion = Temporal.Instant.fromEpochSeconds(1e9);
+epoch = Temporal.Instant.fromEpochMilliseconds(0);
+billion = Temporal.Instant.fromEpochMilliseconds(1e9);
 epoch.until(billion);
   // => PT1000000000S
 epoch.until(billion, { largestUnit: 'hour' });
@@ -612,8 +561,8 @@ If `other` is not a `Temporal.Instant` object, then it will be converted to one
 Example usage:
 
 ```javascript
-one = Temporal.Instant.fromEpochSeconds(1.0e9);
-two = Temporal.Instant.fromEpochSeconds(1.1e9);
+one = Temporal.Instant.fromEpochMilliseconds(1.0e12);
+two = Temporal.Instant.fromEpochMilliseconds(1.1e12);
 one.equals(two); // => false
 one.equals(one); // => true
 ```

docs/ja/ambiguity.md

@@ -101,7 +101,7 @@ zdt = dateTime.toZonedDateTime('Asia/Tokyo');
 inst = zdt.toInstant();
 epochNano = inst.epochNanoseconds; // => 1576536480000000000n
 epochMilli = inst.epochMilliseconds; // => 1576536480000
-epochSecs = inst.epochSeconds; // => 1576536480
+epochSecs = Math.floor(inst.epochMilliseconds / 1000); // => 1576536480
 ```
 <!-- prettier-ignore-end -->