From fc843e32a9c41a6bcf986a425c37c4d8a47b6626 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 9 Jan 2025 13:19:34 -0500 Subject: [PATCH] More feedback --- .../reference/global_objects/eval/index.md | 2 +- .../intl/datetimeformat/format/index.md | 4 +++- .../intl/datetimeformat/formatrange/index.md | 4 +++- .../formatrangetoparts/index.md | 4 +++- .../datetimeformat/formattoparts/index.md | 4 +++- .../intl/datetimeformat/index.md | 14 ++++++------ .../temporal/instant/add/index.md | 2 +- .../instant/epochmilliseconds/index.md | 20 +++++++++++++++++ .../instant/epochnanoseconds/index.md | 22 ++++++++++++++++++- .../temporal/instant/from/index.md | 2 +- .../instant/fromepochmilliseconds/index.md | 2 +- .../instant/fromepochnanoseconds/index.md | 2 +- .../temporal/instant/instant/index.md | 2 +- .../temporal/instant/subtract/index.md | 2 +- .../zoneddatetime/epochnanoseconds/index.md | 2 +- 15 files changed, 68 insertions(+), 20 deletions(-) diff --git a/files/en-us/web/javascript/reference/global_objects/eval/index.md b/files/en-us/web/javascript/reference/global_objects/eval/index.md index 5438796cc7628e8..a29bece55fcdf7c 100644 --- a/files/en-us/web/javascript/reference/global_objects/eval/index.md +++ b/files/en-us/web/javascript/reference/global_objects/eval/index.md @@ -192,7 +192,7 @@ Consider this code: function looseJsonParse(obj) { return eval(`(${obj})`); } -console.log(looseJsonParse("{ a: 4 - 1, b: function () {}, c: new Date() }")); +console.log(looseJsonParse("{ a: 4 - 1, b: function () {}, c: new Map() }")); ``` Simply using indirect eval and forcing strict mode can make the code much better: diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/format/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/format/index.md index c0fadbfa720cda4..a2ea42772ac2917 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/format/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/format/index.md @@ -20,7 +20,9 @@ format(date) ### Parameters - `date` - - : The date to format. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}}; can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}}, if the `DateTimeFormat` object was configured to print at least one relevant part of the date. Note that {{jsxref("Temporal.ZonedDateTime")}} always throws a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} instead. + - : The date to format. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}} object. Additionally can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}} object if the `DateTimeFormat` object was configured to print at least one relevant part of the date. + > [!NOTE] + > A {{jsxref("Temporal.ZonedDateTime")}} object will always throw a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} or convert it to a {{jsxref("Temporal.PlainDateTime")}} object instead. ### Return value diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrange/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrange/index.md index 55272aafb479ae9..57cd7a96cd5b969 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrange/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrange/index.md @@ -23,7 +23,9 @@ formatRange(startDate, endDate) ### Parameters - `startDate` - - : The start of the date range. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}}; can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}}, if the `DateTimeFormat` object was configured to print at least one relevant part of the date. Note that {{jsxref("Temporal.ZonedDateTime")}} always throws a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} instead. + - : The start of the date range. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}} object. Additionally can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}} object if the `DateTimeFormat` object was configured to print at least one relevant part of the date. + > [!NOTE] + > A {{jsxref("Temporal.ZonedDateTime")}} object will always throw a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} or convert it to a {{jsxref("Temporal.PlainDateTime")}} object instead. - `endDate` - : The end of the date range. Must have the same type as `startDate`. diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrangetoparts/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrangetoparts/index.md index 0b24bfc06d2aed0..bac201040ea4218 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrangetoparts/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formatrangetoparts/index.md @@ -21,7 +21,9 @@ formatRangeToParts(startDate, endDate) ### Parameters - `startDate` - - : The start of the date range. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}}; can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}}, if the `DateTimeFormat` object was configured to print at least one relevant part of the date. Note that {{jsxref("Temporal.ZonedDateTime")}} always throws a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} instead. + - : The start of the date range. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}} object. Additionally can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}} object if the `DateTimeFormat` object was configured to print at least one relevant part of the date. + > [!NOTE] + > A {{jsxref("Temporal.ZonedDateTime")}} object will always throw a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} or convert it to a {{jsxref("Temporal.PlainDateTime")}} object instead. - `endDate` - : The end of the date range. Must have the same type as `startDate`. diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formattoparts/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formattoparts/index.md index 56307799bd0e196..646ae2dd84d1560 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formattoparts/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/formattoparts/index.md @@ -20,7 +20,9 @@ formatToParts(date) ### Parameters - `date` {{optional_inline}} - - : The date to format. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}}; can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}}, if the `DateTimeFormat` object was configured to print at least one relevant part of the date. Note that {{jsxref("Temporal.ZonedDateTime")}} always throws a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} instead. + - : The date to format. Can be a {{jsxref("Date")}} or {{jsxref("Temporal.PlainDateTime")}} object. Additionally can be a {{jsxref("Temporal.PlainTime")}}, {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainYearMonth")}}, or {{jsxref("Temporal.PlainMonthDay")}} object if the `DateTimeFormat` object was configured to print at least one relevant part of the date. + > [!NOTE] + > A {{jsxref("Temporal.ZonedDateTime")}} object will always throw a `TypeError`; use {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} or convert it to a {{jsxref("Temporal.PlainDateTime")}} object instead. ### Return value diff --git a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md index 87a9e3f2c048794..97c5198f98606f7 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/datetimeformat/index.md @@ -189,10 +189,10 @@ console.log(usedOptions.timeZone); - {{jsxref("Date.prototype.toLocaleString()")}} - {{jsxref("Date.prototype.toLocaleDateString()")}} - {{jsxref("Date.prototype.toLocaleTimeString()")}} -- {{domxref("Temporal/Instant/toLocaleString", "Temporal.Instant.prototype.toLocaleString()")}} -- {{domxref("Temporal/PlainDate/toLocaleString", "Temporal.PlainDate.prototype.toLocaleString()")}} -- {{domxref("Temporal/PlainDateTime/toLocaleString", "Temporal.PlainDateTime.prototype.toLocaleString()")}} -- {{domxref("Temporal/PlainTime/toLocaleString", "Temporal.PlainTime.prototype.toLocaleString()")}} -- {{domxref("Temporal/PlainYearMonth/toLocaleString", "Temporal.PlainYearMonth.prototype.toLocaleString()")}} -- {{domxref("Temporal/PlainMonthDay/toLocaleString", "Temporal.PlainMonthDay.prototype.toLocaleString()")}} -- {{domxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} +- {{jsxref("Temporal/Instant/toLocaleString", "Temporal.Instant.prototype.toLocaleString()")}} +- {{jsxref("Temporal/PlainDate/toLocaleString", "Temporal.PlainDate.prototype.toLocaleString()")}} +- {{jsxref("Temporal/PlainDateTime/toLocaleString", "Temporal.PlainDateTime.prototype.toLocaleString()")}} +- {{jsxref("Temporal/PlainTime/toLocaleString", "Temporal.PlainTime.prototype.toLocaleString()")}} +- {{jsxref("Temporal/PlainYearMonth/toLocaleString", "Temporal.PlainYearMonth.prototype.toLocaleString()")}} +- {{jsxref("Temporal/PlainMonthDay/toLocaleString", "Temporal.PlainMonthDay.prototype.toLocaleString()")}} +- {{jsxref("Temporal/ZonedDateTime/toLocaleString", "Temporal.ZonedDateTime.prototype.toLocaleString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/add/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/add/index.md index 78c3be6e71a6934..0514f618b560180 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/add/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/add/index.md @@ -29,7 +29,7 @@ A new {{jsxref("Temporal.Instant")}} object representing adding `duration` to th - {{jsxref("RangeError")}} - : Thrown in one of the following cases: - `duration` is a [calendar duration](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) (it has a non-zero `years`, `months`, or `weeks`), or has a non-zero `days`, because calendar durations are ambiguous without a calendar and time reference. - - The sum of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±108 days. + - The sum of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±108 days (about ±273,972.6 years). ## Description diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochmilliseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochmilliseconds/index.md index c74d7cee17ea955..06df9fdec150757 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochmilliseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochmilliseconds/index.md @@ -23,6 +23,26 @@ const instant2 = Temporal.Instant.from("1969-08-01T12:34:56.789Z"); console.log(instant2.epochMilliseconds); // -13173903211 ``` +### Changing epochMilliseconds + +This is the method that allows you to move by any amount of time: + +```js +const instant = Temporal.Instant.from("2021-08-01T12:34:56.789Z"); +const instant1hourLater = instant.add({ hours: 1 }); +console.log(instant1hourLater.epochMilliseconds); // 1627824896789 +``` + +If you already know the change in milliseconds, you can also directly construct a new `Temporal.Instant` object: + +```js +const instant = Temporal.Instant.from("2021-08-01T12:34:56.789Z"); +const instant1hourLater = Temporal.Instant.fromEpochMilliseconds( + instant.epochMilliseconds + 3600000, +); +console.log(instant1hourLater.epochMilliseconds); // 1627824896789 +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochnanoseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochnanoseconds/index.md index 25b0a85ec225dcd..4c0006f095a0c42 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochnanoseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/epochnanoseconds/index.md @@ -11,7 +11,7 @@ The **`epochNanoseconds`** accessor property of {{jsxref("Temporal.Instant")}} i The set accessor of `epochNanoseconds` is `undefined`. You cannot change this property directly. To create a new `Temporal.Instant` object with the desired new `epochNanoseconds` value, use the {{jsxref("Temporal/Instant/add", "add()")}} or {{jsxref("Temporal/Instant/subtract", "subtract()")}} method with the appropriate duration. -An instant can only represent ±108 days around the epoch, which is ±8.64e21 nanoseconds. Attempts to set `epochNanosecond` beyond this boundary throws a {{jsxref("RangeError")}}. +An instant can only represent ±108 days (about ±273,972.6 years) around the epoch, which is ±8.64e21 nanoseconds. Attempting to set `epochNanosecond` beyond this boundary throws a {{jsxref("RangeError")}}. ## Examples @@ -25,6 +25,26 @@ const instant2 = Temporal.Instant.from("1969-08-01T12:34:56.789Z"); console.log(instant2.epochNanoseconds); // -13173903211000000n ``` +### Changing epochNanoseconds + +This is the method that allows you to move by any amount of time: + +```js +const instant = Temporal.Instant.from("2021-08-01T12:34:56.789Z"); +const instant1hourLater = instant.add({ hours: 1 }); +console.log(instant1hourLater.epochNanoseconds); // 1627824896789000000n +``` + +If you already know the change in nanoseconds, you can also directly construct a new `Temporal.Instant` object: + +```js +const instant = Temporal.Instant.from("2021-08-01T12:34:56.789Z"); +const instant1hourLater = Temporal.Instant.fromEpochNanoseconds( + instant.epochNanoseconds + 3600000000000n, +); +console.log(instant1hourLater.epochNanoseconds); // 1627824896789000000n +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/from/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/from/index.md index 530dbd0c0fb9aef..844ef574f0f3786 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/from/index.md @@ -31,7 +31,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `i - {{jsxref("TypeError")}} - : Thrown if `info` is not a `Temporal.Instant` instance or a string. - {{jsxref("RangeError")}} - - : Thrown if the string is not a valid RFC 9557 string, or if the date and time are outside the range of representable instants (±108 days). + - : Thrown if the string is not a valid RFC 9557 string, or if the date and time are outside the range of representable instants (±108 days, or about ±273,972.6 years). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md index 4c6cd257a6c0b03..4020fea6a7dd6d0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md @@ -29,7 +29,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `e ### Exceptions - {{jsxref("RangeError")}} - - : Thrown if `epochMilliseconds` is outside the range of a representable instant, which is ±108 days (±8.64e15 milliseconds), or if it cannot be converted to a BigInt (e.g., not an integer). + - : Thrown if `epochMilliseconds` is outside the range of a representable instant, which is ±108 days (±8.64e15 milliseconds, or about ±273,972.6 years), or if it cannot be converted to a BigInt (e.g., not an integer). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md index f2f053d681b0f0a..e07f6b740218a9f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md @@ -29,7 +29,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `e ### Exceptions - {{jsxref("RangeError")}} - - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±108 days (±8.64e21 nanoseconds). + - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±108 days (±8.64e21 nanoseconds, or about ±273,972.6 years). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md index 7d6ed5dcfbd10c1..090372e5cbad9ee 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md @@ -31,7 +31,7 @@ A new `Temporal.Instant` object representing the instant in time specified by `e ### Exceptions - {{jsxref("RangeError")}} - - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±108 days. + - : Thrown if `epochNanoseconds` is outside the range of a representable instant, which is ±108 days (±8.64e21 nanoseconds, or about ±273,972.6 years). ## Examples diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md index 244b4d635770411..26f8f7bc05fee06 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md @@ -31,7 +31,7 @@ A new {{jsxref("Temporal.Instant")}} object representing subtracting `duration` - {{jsxref("RangeError")}} - : Thrown in one of the following cases: - `duration` is a [calendar duration](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) (it has a non-zero `years`, `months`, or `weeks`), or has a non-zero `days`, because calendar durations are ambiguous without a calendar and time reference. - - The difference of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±108 days. + - The difference of `this` and `duration` overflows the maximum or underflows the minimum representable instant, which is ±108 days (about ±273,972.6 years). ## Description diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/epochnanoseconds/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/epochnanoseconds/index.md index b55d50ace0aab1c..3406149c2963b85 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/epochnanoseconds/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/epochnanoseconds/index.md @@ -11,7 +11,7 @@ The **`epochNanoseconds`** accessor property of {{jsxref("Temporal.ZonedDateTime The set accessor of `epochNanoseconds` is `undefined`. You cannot change this property directly. To create a new `Temporal.ZonedDateTime` object with the desired new `epochNanoseconds` value, use the {{jsxref("Temporal/ZonedDateTime/add", "add()")}} or {{jsxref("Temporal/ZonedDateTime/subtract", "subtract()")}} method with the appropriate duration. -An instant can only represent ±108 days around the epoch, which is ±8.64e21 nanoseconds. Attempts to set `epochNanosecond` beyond this boundary throws a {{jsxref("RangeError")}}. +An instant can only represent ±108 days (about ±273,972.6 years) around the epoch, which is ±8.64e21 nanoseconds. Attempting to set `epochNanosecond` beyond this boundary throws a {{jsxref("RangeError")}}. ## Examples