Reference for stage 3 temporal (#37344)

* Reference for stage 3 temporal * More description * Duration docs * Fix link * Complete Duration docs * Instant docs * Now docs * TZ and calendar docs * PlainDate docs * Change ISO format description * ZonedDateTime-specific stuff docs * PlainMonthDay docs, copy date-related fields to PlainDateTime * PlainYearMonth docs * PlainTime docs * Intl docs * PlainDateTime docs * ZonedDateTime docs, easy part * ZonedDateTime docs... and that shall be all * Simplifications and fixes * typo * Apply suggestions from code review Co-authored-by: Justin Grant <[email protected]> * ISO 8601 -> RFC 9557 * Clarify time zone ID input * Time zone ID is required * Slight reorg * Apply suggestions from code review Co-authored-by: Chris Mills <[email protected]> * More feedback * More reviews * Reviews * Reviews, Temporal.Now * Mention precision of Temporal.Now methods * Reviews, landing pages * Apply suggestions from code review Co-authored-by: Eric A. Meyer <[email protected]> * Time zone / calendar / time components * Reviews, other constructors * Reviews, other constructors, arithmetic, monthCode * Update index.md * Update index.md * Update index.md * Reviews, some (?) conversion methods * Last group of reviews * Mention toTemporalInstant RangeError --------- Co-authored-by: Justin Grant <[email protected]> Co-authored-by: Chris Mills <[email protected]> Co-authored-by: Eric A. Meyer <[email protected]> Co-authored-by: Brian Smith <[email protected]>
mdn · Jan 20, 2025 · a4e9bce · a4e9bce
1 parent e5249d6
commit a4e9bce
Show file tree

Hide file tree

Showing 282 changed files with 17,552 additions and 105 deletions.
diff --git a/files/en-us/web/javascript/data_structures/index.md b/files/en-us/web/javascript/data_structures/index.md
@@ -197,7 +197,7 @@ Objects are ad-hoc key-value pairs, so they are often used as maps. However, the
 
 ### Dates
 
-When representing dates, the best choice is to use the built-in [`Date`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) utility in JavaScript.
+JavaScript provides two sets of APIs for representing dates: the legacy {{jsxref("Date")}} object and the modern {{jsxref("Temporal")}} object. `Date` has many undesirable design choices and should be avoided in new code if possible.
 
 ### Indexed collections: Arrays and typed Arrays
 

diff --git a/files/en-us/web/javascript/guide/expressions_and_operators/index.md b/files/en-us/web/javascript/guide/expressions_and_operators/index.md
@@ -1038,16 +1038,16 @@ if the specified object is of the specified object type. The syntax is:
 object instanceof objectType
 ```
 
-where `object` is the object to test against `objectType`, and `objectType` is a constructor representing a type, such as {{jsxref("Date")}} or {{jsxref("Array")}}.
+where `object` is the object to test against `objectType`, and `objectType` is a constructor representing a type, such as {{jsxref("Map")}} or {{jsxref("Array")}}.
 
 Use `instanceof` when you need to confirm the type of an object at runtime.
 For example, when catching exceptions, you can branch to different exception-handling code depending on the type of exception thrown.
 
-For example, the following code uses `instanceof` to determine whether `theDay` is a `Date` object. Because `theDay` is a `Date` object, the statements in the `if` statement execute.
+For example, the following code uses `instanceof` to determine whether `obj` is a `Map` object. Because `obj` is a `Map` object, the statements inside the `if` block execute.
 
 ```js
-const theDay = new Date(1995, 12, 17);
-if (theDay instanceof Date) {
+const obj = new Map();
+if (obj instanceof Map) {
   // statements to execute
 }
 ```

diff --git a/files/en-us/web/javascript/guide/introduction/index.md b/files/en-us/web/javascript/guide/introduction/index.md
@@ -28,7 +28,7 @@ The JavaScript documentation on MDN includes the following:
 
 JavaScript is a cross-platform, object-oriented scripting language used to make webpages interactive (e.g., having complex animations, clickable buttons, popup menus, etc.). There are also more advanced server side versions of JavaScript such as Node.js, which allow you to add more functionality to a website than downloading files (such as realtime collaboration between multiple computers). Inside a host environment (for example, a web browser), JavaScript can be connected to the objects of its environment to provide programmatic control over them.
 
-JavaScript contains a standard library of objects, such as `Array`, `Date`, and `Math`, and a core set of language elements such as operators, control structures, and statements. Core JavaScript can be extended for a variety of purposes by supplementing it with additional objects; for example:
+JavaScript contains a standard library of objects, such as `Array`, `Map`, and `Math`, and a core set of language elements such as operators, control structures, and statements. Core JavaScript can be extended for a variety of purposes by supplementing it with additional objects; for example:
 
 - _Client-side JavaScript_ extends the core language by supplying objects to control a browser and its _Document Object Model_ (DOM). For example, client-side extensions allow an application to place elements on an HTML form and respond to user events such as mouse clicks, form input, and page navigation.
 - _Server-side JavaScript_ extends the core language by supplying objects relevant to running JavaScript on a server. For example, server-side extensions allow an application to communicate with a database, provide continuity of information from one invocation to another of the application, or perform file manipulations on a server.

diff --git a/files/en-us/web/javascript/guide/representing_dates_times/index.md b/files/en-us/web/javascript/guide/representing_dates_times/index.md
@@ -6,6 +6,9 @@ page-type: guide
 
 {{jsSidebar("JavaScript Guide")}} {{PreviousNext("Web/JavaScript/Guide/Numbers_and_strings", "Web/JavaScript/Guide/Regular_expressions")}}
 
+> [!NOTE]
+> The `Date` object is now considered legacy and should be avoided in new code. We will update this page with modern alternatives soon.
+
 ## Date object
 
 JavaScript does not have a date data type. However, you can use the {{jsxref("Date")}} object and its methods to work with dates and times in your applications. The `Date` object has a large number of methods for setting, getting, and manipulating dates. It does not have any properties.

diff --git a/files/en-us/web/javascript/index.md b/files/en-us/web/javascript/index.md
@@ -74,7 +74,7 @@ Learn how to program in JavaScript from the ground up with our beginner's tutori
 Browse the complete [JavaScript reference](/en-US/docs/Web/JavaScript/Reference) documentation.
 
 - [Standard objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects)
-  - : Get to know standard built-in objects {{jsxref("Array")}}, {{jsxref("Boolean")}}, {{jsxref("Date")}}, {{jsxref("Error")}}, {{jsxref("Function")}}, {{jsxref("JSON")}}, {{jsxref("Math")}}, {{jsxref("Number")}}, {{jsxref("Object")}}, {{jsxref("RegExp")}}, {{jsxref("String")}}, {{jsxref("Map")}}, {{jsxref("Set")}}, {{jsxref("WeakMap")}}, {{jsxref("WeakSet")}}, and others.
+  - : Get to know standard built-in objects: {{jsxref("Array")}}, {{jsxref("Boolean")}}, {{jsxref("Error")}}, {{jsxref("Function")}}, {{jsxref("JSON")}}, {{jsxref("Math")}}, {{jsxref("Number")}}, {{jsxref("Object")}}, {{jsxref("RegExp")}}, {{jsxref("String")}}, {{jsxref("Map")}}, {{jsxref("Set")}}, {{jsxref("WeakMap")}}, {{jsxref("WeakSet")}}, and others.
 - [Expressions and operators](/en-US/docs/Web/JavaScript/Reference/Operators)
   - : Learn more about the behavior of JavaScript's operators {{jsxref("Operators/instanceof", "instanceof")}}, {{jsxref("Operators/typeof", "typeof")}}, {{jsxref("Operators/new", "new")}}, {{jsxref("Operators/this", "this")}}, the [operator precedence](/en-US/docs/Web/JavaScript/Reference/Operators/Operator_precedence), and more.
 - [Statements and declarations](/en-US/docs/Web/JavaScript/Reference/Statements)

diff --git a/files/en-us/web/javascript/language_overview/index.md b/files/en-us/web/javascript/language_overview/index.md
@@ -26,7 +26,7 @@ Everything else is known as an [Object](/en-US/docs/Web/JavaScript/Data_structur
 
 - {{jsxref("Function")}}
 - {{jsxref("Array")}}
-- {{jsxref("Date")}}
+- {{jsxref("Map")}}
 - {{jsxref("RegExp")}}
 - {{jsxref("Error")}}
 

diff --git a/files/en-us/web/javascript/reference/classes/public_class_fields/index.md b/files/en-us/web/javascript/reference/classes/public_class_fields/index.md
@@ -177,7 +177,7 @@ const instance2 = new DerivedWithConstructor(); // Logs 1
 
 ### Using class fields
 
-Class fields cannot depend on arguments of the constructor, so field initializers usually evaluate to the same value for each instance (unless the same expression can evaluate to different values each time, such as {{jsxref("Date.now()")}} or object initializers).
+Class fields cannot depend on arguments of the constructor, so field initializers usually evaluate to the same value for each instance (unless the same expression can evaluate to different values each time, such as {{jsxref("Math.random()")}} or object initializers).
 
 ```js example-bad
 class Person {

diff --git a/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/array/tolocalestring/index.md
@@ -27,7 +27,7 @@ toLocaleString(locales, options)
 - `locales` {{optional_inline}}
   - : A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the `locales` argument, see [the parameter description on the `Intl` main page](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
 - `options` {{optional_inline}}
-  - : An object with configuration properties. For numbers, see {{jsxref("Number.prototype.toLocaleString()")}}; for dates, see {{jsxref("Date.prototype.toLocaleString()")}}.
+  - : An object with configuration properties. What you can pass here depends on what elements are being converted. For example, for numbers, see {{jsxref("Number.prototype.toLocaleString()")}}.
 
 ### Return value
 
@@ -47,15 +47,7 @@ The `toLocaleString()` method is [generic](/en-US/docs/Web/JavaScript/Reference/
 
 ### Using locales and options
 
-The elements of the array are converted to strings using their
-`toLocaleString` methods.
-
-- `Object`: {{jsxref("Object.prototype.toLocaleString()")}}
-- `Number`: {{jsxref("Number.prototype.toLocaleString()")}}
-- `Date`: {{jsxref("Date.prototype.toLocaleString()")}}
-
-Always display the currency for the strings and numbers in the `prices`
-array:
+The elements of the array are converted to strings using their `toLocaleString` methods. For example, this snippet implicitly calls the {{jsxref("Number.prototype.toLocaleString()")}} method to display the currency for the strings and numbers in the `prices` array:
 
 ```js
 const prices = ["￥7", 500, 8123, 12];
@@ -64,8 +56,6 @@ prices.toLocaleString("ja-JP", { style: "currency", currency: "JPY" });
 // "￥7,￥500,￥8,123,￥12"
 ```
 
-For more examples, see also the [`Intl.NumberFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) and [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) pages.
-
 ### Using toLocaleString() on sparse arrays
 
 `toLocaleString()` treats empty slots the same as `undefined` and produces an extra separator:
@@ -108,4 +98,4 @@ console.log(Array.prototype.toLocaleString.call(arrayLike));
 - {{jsxref("Intl.ListFormat")}}
 - {{jsxref("Object.prototype.toLocaleString()")}}
 - {{jsxref("Number.prototype.toLocaleString()")}}
-- {{jsxref("Date.prototype.toLocaleString()")}}
+- {{jsxref("Temporal/PlainDate/toLocaleString", "Temporal.PlainDate.prototype.toLocaleString()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/bigint/tolocalestring/index.md
@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.BigInt.toLocaleString
 
 {{JSRef}}
 
-The **`toLocaleString()`** method of {{jsxref("BigInt")}} values returns a string with a language-sensitive representation of this BigInt. In implementations with [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) support, this method simply calls `Intl.NumberFormat`.
+The **`toLocaleString()`** method of {{jsxref("BigInt")}} values returns a string with a language-sensitive representation of this BigInt. In implementations with [`Intl.NumberFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) support, this method delegates to `Intl.NumberFormat`.
 
 Every time `toLocaleString` is called, it has to perform a search in a big database of localization strings, which is potentially inefficient. When the method is called many times with the same arguments, it is better to create a {{jsxref("Intl.NumberFormat")}} object and use its {{jsxref("Intl/NumberFormat/format", "format()")}} method, because a `NumberFormat` object remembers the arguments passed to it and may decide to cache a slice of the database, so future `format` calls can search for localization strings within a more constrained context.
 

diff --git a/files/en-us/web/javascript/reference/global_objects/date/index.md b/files/en-us/web/javascript/reference/global_objects/date/index.md
@@ -10,7 +10,7 @@ browser-compat: javascript.builtins.Date
 JavaScript **`Date`** objects represent a single moment in time in a platform-independent format. `Date` objects encapsulate an integral number that represents milliseconds since the midnight at the beginning of January 1, 1970, UTC (the _epoch_).
 
 > [!NOTE]
-> TC39 is working on [Temporal](https://tc39.es/proposal-temporal/docs/index.html), a new Date/Time API. Read more about it on the [Igalia blog](https://blogs.igalia.com/compilers/2020/06/23/dates-and-times-in-javascript/). It is not yet ready for production use!
+> With the introduction of the {{jsxref("Temporal")}} API, the `Date` object is considered a legacy feature. Consider using `Temporal` for new code and migrate existing code over to it if possible (check the [browser compatibility](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#browser_compatibility). We will be writing a usage guide soon!
 
 ## Description
 
@@ -275,7 +275,7 @@ These properties are defined on `Date.prototype` and shared by all `Date` instan
 - {{jsxref("Date.prototype.toISOString()")}}
   - : Converts a date to a string following the ISO 8601 Extended Format.
 - {{jsxref("Date.prototype.toJSON()")}}
-  - : Returns a string representing the `Date` using {{jsxref("Date/toISOString", "toISOString()")}}. Intended for use by {{jsxref("JSON.stringify()")}}.
+  - : Returns a string representing the `Date` using {{jsxref("Date/toISOString", "toISOString()")}}. Intended to be implicitly called by {{jsxref("JSON.stringify()")}}.
 - {{jsxref("Date.prototype.toLocaleDateString()")}}
   - : Returns a string with a locality sensitive representation of the date portion of this date based on system settings.
 - {{jsxref("Date.prototype.toLocaleString()")}}
@@ -284,6 +284,8 @@ These properties are defined on `Date.prototype` and shared by all `Date` instan
   - : Returns a string with a locality-sensitive representation of the time portion of this date, based on system settings.
 - {{jsxref("Date.prototype.toString()")}}
   - : Returns a string representing the specified `Date` object. Overrides the {{jsxref("Object.prototype.toString()")}} method.
+- {{jsxref("Date.prototype.toTemporalInstant()")}}
+  - : Returns a new {{jsxref("Temporal.Instant")}} object with the same {{jsxref("Temporal/Instant/epochMilliseconds", "epochMilliseconds")}} value as this date's [timestamp](#the_epoch_timestamps_and_invalid_date).
 - {{jsxref("Date.prototype.toTimeString()")}}
   - : Returns the "time" portion of the `Date` as a human-readable string.
 - {{jsxref("Date.prototype.toUTCString()")}}

diff --git a/.../en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md b/.../en-us/web/javascript/reference/global_objects/date/tolocaledatestring/index.md
@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Date.toLocaleDateString
 
 {{JSRef}}
 
-The **`toLocaleDateString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of the date portion of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`.
+The **`toLocaleDateString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of the date portion of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method delegates to `Intl.DateTimeFormat`.
 
 Every time `toLocaleString` is called, it has to perform a search in a big database of localization strings, which is potentially inefficient. When the method is called many times with the same arguments, it is better to create a {{jsxref("Intl.DateTimeFormat")}} object and use its {{jsxref("Intl/DateTimeFormat/format", "format()")}} method, because a `DateTimeFormat` object remembers the arguments passed to it and may decide to cache a slice of the database, so future `format` calls can search for localization strings within a more constrained context.
 

diff --git a/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/date/tolocalestring/index.md
@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Date.toLocaleString
 
 {{JSRef}}
 
-The **`toLocaleString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`.
+The **`toLocaleString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method delegates to `Intl.DateTimeFormat`.
 
 Every time `toLocaleString` is called, it has to perform a search in a big database of localization strings, which is potentially inefficient. When the method is called many times with the same arguments, it is better to create a {{jsxref("Intl.DateTimeFormat")}} object and use its {{jsxref("Intl/DateTimeFormat/format", "format()")}} method, because a `DateTimeFormat` object remembers the arguments passed to it and may decide to cache a slice of the database, so future `format` calls can search for localization strings within a more constrained context.
 

diff --git a/.../en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md b/.../en-us/web/javascript/reference/global_objects/date/tolocaletimestring/index.md
@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Date.toLocaleTimeString
 
 {{JSRef}}
 
-The **`toLocaleTimeString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of the time portion of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`.
+The **`toLocaleTimeString()`** method of {{jsxref("Date")}} instances returns a string with a language-sensitive representation of the time portion of this date in the local timezone. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method delegates to `Intl.DateTimeFormat`.
 
 Every time `toLocaleTimeString` is called, it has to perform a search in a big database of localization strings, which is potentially inefficient. When the method is called many times with the same arguments, it is better to create a {{jsxref("Intl.DateTimeFormat")}} object and use its {{jsxref("Intl/DateTimeFormat/format", "format()")}} method, because a `DateTimeFormat` object remembers the arguments passed to it and may decide to cache a slice of the database, so future `format` calls can search for localization strings within a more constrained context.
 

diff --git a/...s/en-us/web/javascript/reference/global_objects/date/totemporalinstant/index.md b/...s/en-us/web/javascript/reference/global_objects/date/totemporalinstant/index.md
@@ -0,0 +1,59 @@
+---
+title: Date.prototype.toTemporalInstant()
+slug: Web/JavaScript/Reference/Global_Objects/Date/toTemporalInstant
+page-type: javascript-instance-method
+browser-compat: javascript.builtins.Date.toTemporalInstant
+---
+
+{{JSRef}}
+
+The **`toTemporalInstant()`** method of {{jsxref("Date")}} instances returns a new {{jsxref("Temporal.Instant")}} object with the same {{jsxref("Temporal/Instant/epochMilliseconds", "epochMilliseconds")}} value as this date's [timestamp](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date).
+
+Use this method to convert legacy `Date` values to the `Temporal` API, then further convert it to other {{jsxref("Temporal")}} classes as necessary.
+
+## Syntax
+
+```js-nolint
+toTemporalInstant()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A new {{jsxref("Temporal.Instant")}} object with the same {{jsxref("Temporal/Instant/epochMilliseconds", "epochMilliseconds")}} value as this date's timestamp. Its microsecond and nanosecond components are always `0`.
+
+### Exceptions
+
+- {{jsxref("RangeError")}}
+  - : Thrown if the date is [invalid](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date) (it has a timestamp of `NaN`).
+
+## Examples
+
+### Using toTemporalInstant()
+
+```js
+const legacyDate = new Date("2021-07-01T12:34:56.789Z");
+const instant = legacyDate.toTemporalInstant();
+
+// Further convert it to other objects
+const zdt = instant.toZonedDateTimeISO("UTC");
+const date = zdt.toPlainDate();
+console.log(date.toString()); // 2021-07-01
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("Temporal.Instant")}}
+- {{jsxref("Temporal.ZonedDateTime")}}
+- {{jsxref("Temporal/Instant/fromEpochMilliseconds", "Temporal.Instant.fromEpochMilliseconds()")}}