Rewrite PerformanceNavigationTiming pages (#22683)

* Rewrite PerformanceNavigationTiming pages * Apply suggestions from code review Co-authored-by: wbamberg <[email protected]> * Update descriptions & use event handler throughout * Add PerformanceObserver examples Co-authored-by: wbamberg <[email protected]>
mdn · Dec 5, 2022 · 8eb6168 · 8eb6168
1 parent 4556989
commit 8eb6168
Show file tree

Hide file tree

Showing 12 changed files with 425 additions and 296 deletions.
diff --git a/files/en-us/web/api/performancenavigationtiming/domcomplete/index.md b/files/en-us/web/api/performancenavigationtiming/domcomplete/index.md
@@ -12,42 +12,39 @@ browser-compat: api.PerformanceNavigationTiming.domComplete
 
 {{APIRef("Performance API")}}
 
-The **`domComplete`** read-only property returns a
-{{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to the
-time immediately before the user agent sets the current document readiness of the
-current document to _[complete](https://html.spec.whatwg.org/multipage/syntax.html#the-end)_.
+The **`domComplete`** read-only property returns a {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the user agent sets the document's [`readyState`](/en-US/docs/Web/API/Document/readyState) to `"complete"`.
+
+See also the `complete` state of {{domxref("Document.readyState")}} which corresponds to this property and refers to the state in which the document and all sub-resources have finished loading. The state also indicates that the {{domxref("Window/load_event", "load")}} event is about to fire.
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp","timestamp")}} representing a time value equal to the
-time immediately before the user agent sets the current document readiness of the
-current document to _[complete](https://html.spec.whatwg.org/multipage/syntax.html#the-end)_.
+A {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the user agent sets the document's [`readyState`](/en-US/docs/Web/API/Document/readyState) to `"complete"`.
 
 ## Examples
 
-The following example illustrates this property's usage.
+### Logging DOM completion time
+
+The `domComplete` property can be used to log the time when the DOM is complete.
+
+Example using a {{domxref("PerformanceObserver")}}, which notifies of new `navigation` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    console.log(`${entry.name}: domComplete time: ${entry.domComplete}ms`);
+  });
+});
+
+observer.observe({ type: "navigation", buffered: true });
+```
+
+Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `navigation` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function printNavTimingData() {
-  // Use getEntriesByType() to just get the "navigation" events
-  performance.getEntriesByType("navigation")
-    .forEach((p, i) => {
-      console.log(`= Navigation entry[${i}]`);
-
-      // DOM Properties
-      console.log(`DOM content loaded = ${p.domContentLoadedEventEnd - p.domContentLoadedEventStart}`);
-      console.log(`DOM complete = ${p.domComplete}`);
-      console.log(`DOM interactive = ${p.domInteractive}`);
-
-      // Document load and unload time
-      console.log(`document load = ${p.loadEventEnd - p.loadEventStart}`);
-      console.log(`document unload = ${p.unloadEventEnd - p.unloadEventStart}`);
-
-      // Other properties
-      console.log(`type = ${p.type}`);
-      console.log(`redirectCount = ${p.redirectCount}`);
-    });
-}
+const entries = performance.getEntriesByType("navigation");
+entries.forEach((entry) => {
+  console.log(`${entry.name}: domComplete time: ${entry.domComplete}ms`);
+});
 ```
 
 ## Specifications
@@ -57,3 +54,7 @@ function printNavTimingData() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Document.readyState")}}
diff --git a/files/en-us/web/api/performancenavigationtiming/domcontentloadedeventend/index.md b/files/en-us/web/api/performancenavigationtiming/domcontentloadedeventend/index.md
@@ -12,42 +12,47 @@ browser-compat: api.PerformanceNavigationTiming.domContentLoadedEventEnd
 
 {{APIRef("Performance API")}}
 
-The **`domContentLoadedEventEnd`** read-only property returns a
-{{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to the
-time immediately after the current document's [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end)
-event completes.
+The **`domContentLoadedEventEnd`** read-only property returns a {{domxref("DOMHighResTimeStamp")}} representing the time immediately after the current document's [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler completes.
+
+Typically frameworks and libraries wait for the `DOMContentLoaded` event before starting to run their code. We can use the `domContentLoadedEventEnd` and the [`domContentLoadedEventStart`](/en-US/docs/Web/API/PerformanceNavigationTiming/domContentLoadedEventStart) properties to calculate how long this takes to run.
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to
-the time immediately after the current document's [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end)
-event completes.
+A {{domxref("DOMHighResTimeStamp")}} representing the time immediately after the current document's [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler completes.
 
 ## Examples
 
-The following example illustrates this property's usage.
+### Measuring `DOMContentLoaded` event handler time
+
+The `domContentLoadedEventEnd` property can be used to measure how long it takes process the [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler.
+
+Example using a {{domxref("PerformanceObserver")}}, which notifies of new `navigation` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const domContentLoadedTime =
+      entry.domContentLoadedEventEnd - entry.domContentLoadedEventStart;
+    console.log(
+      `${entry.name}: DOMContentLoaded processing time: ${domContentLoadedTime}ms`
+    );
+  });
+});
+
+observer.observe({ type: "navigation", buffered: true });
+```
+
+Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `navigation` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function printNavTimingData() {
-  // Use getEntriesByType() to just get the "navigation" events
-  performance.getEntriesByType("navigation")
-    .forEach((p, i) => {
-      console.log(`= Navigation entry[${i}]`);
-
-      // DOM Properties
-      console.log(`DOM content loaded = ${p.domContentLoadedEventEnd - p.domContentLoadedEventStart}`);
-      console.log(`DOM complete = ${p.domComplete}`);
-      console.log(`DOM interactive = ${p.domInteractive}`);
-
-      // Document load and unload time
-      console.log(`document load = ${p.loadEventEnd - p.loadEventStart}`);
-      console.log(`document unload = ${p.unloadEventEnd - p.unloadEventStart}`);
-
-      // Other properties
-      console.log(`type = ${p.type}`);
-      console.log(`redirectCount = ${p.redirectCount}`);
-    });
-}
+const entries = performance.getEntriesByType("navigation");
+entries.forEach((entry) => {
+  const domContentLoadedTime =
+    entry.domContentLoadedEventEnd - entry.domContentLoadedEventStart;
+  console.log(
+    `${entry.name}: DOMContentLoaded processing time: ${domContentLoadedTime}ms`
+  );
+});
 ```
 
 ## Specifications
@@ -57,3 +62,7 @@ function printNavTimingData() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [DOMContentLoaded](/en-US/docs/Web/API/Document/DOMContentLoaded_event)
diff --git a/...s/en-us/web/api/performancenavigationtiming/domcontentloadedeventstart/index.md b/...s/en-us/web/api/performancenavigationtiming/domcontentloadedeventstart/index.md
@@ -12,42 +12,47 @@ browser-compat: api.PerformanceNavigationTiming.domContentLoadedEventStart
 
 {{APIRef("Performance API")}}
 
-The **`domContentLoadedEventStart`** read-only property returns
-a {{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to
-the time immediately before the user agent fires the [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end)
-event at the current document.
+The **`domContentLoadedEventStart`** read-only property returns a {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the current document's [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler starts.
+
+Typically frameworks and libraries wait for the `DOMContentLoaded` event before starting to run their code. We can use the `domContentLoadedEventStart` and the [`domContentLoadedEventEnd`](/en-US/docs/Web/API/PerformanceNavigationTiming/domContentLoadedEventEnd) properties to calculate how long this takes to run.
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to
-the time immediately before the user agent fires the [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end)
-event at the current document.
+A {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the current document's [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler starts.
 
 ## Examples
 
-The following example illustrates this property's usage.
+### Measuring `DOMContentLoaded` event handler time
+
+The `domContentLoadedEventStart` property can be used to measure how long it takes process the [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event handler.
+
+Example using a {{domxref("PerformanceObserver")}}, which notifies of new `navigation` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const domContentLoadedTime =
+      entry.domContentLoadedEventEnd - entry.domContentLoadedEventStart;
+    console.log(
+      `${entry.name}: DOMContentLoaded processing time: ${domContentLoadedTime}ms`
+    );
+  });
+});
+
+observer.observe({ type: "navigation", buffered: true });
+```
+
+Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `navigation` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function printNavTimingData() {
-  // Use getEntriesByType() to just get the "navigation" events
-  performance.getEntriesByType("navigation")
-    .forEach((p, i) => {
-      console.log(`= Navigation entry[${i}]`);
-
-      // DOM Properties
-      console.log(`DOM content loaded = ${p.domContentLoadedEventEnd - p.domContentLoadedEventStart}`);
-      console.log(`DOM complete = ${p.domComplete}`);
-      console.log(`DOM interactive = ${p.domInteractive}`);
-
-      // Document load and unload time
-      console.log(`document load = ${p.loadEventEnd - p.loadEventStart}`);
-      console.log(`document unload = ${p.unloadEventEnd - p.unloadEventStart}`);
-
-      // Other properties
-      console.log(`type = ${p.type}`);
-      console.log(`redirectCount = ${p.redirectCount}`);
-    });
-}
+const entries = performance.getEntriesByType("navigation");
+entries.forEach((entry) => {
+  const domContentLoadedTime =
+    entry.domContentLoadedEventEnd - entry.domContentLoadedEventStart;
+  console.log(
+    `${entry.name}: DOMContentLoaded processing time: ${domContentLoadedTime}ms`
+  );
+});
 ```
 
 ## Specifications
@@ -57,3 +62,7 @@ function printNavTimingData() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [DOMContentLoaded](/en-US/docs/Web/API/Document/DOMContentLoaded_event)
diff --git a/files/en-us/web/api/performancenavigationtiming/dominteractive/index.md b/files/en-us/web/api/performancenavigationtiming/dominteractive/index.md
@@ -12,42 +12,45 @@ browser-compat: api.PerformanceNavigationTiming.domInteractive
 
 {{APIRef("Performance API")}}
 
-The **`domInteractive`** read-only property returns a
-{{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to the
-time immediately before the user agent sets the current document readiness of the
-current document to [interactive](https://html.spec.whatwg.org/multipage/syntax.html#the-end).
+The **`domInteractive`** read-only property returns a {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the user agent sets the document's [`readyState`](/en-US/docs/Web/API/Document/readyState) to `"interactive"`.
+
+> **Note:** This property is **not** {{Glossary("Time to interactive")}} (TTI). This property refers to the time when DOM construction is finished and interaction to it from JavaScript is possible. See also the `interactive` state of {{domxref("Document.readyState")}} which corresponds to this property.
+
+Measuring DOM processing time may not be consequential unless your site has a very large HTML source to a construct a Document Object Model from.
+
+If there is no parser-blocking JavaScript then the [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) event (see [`domContentLoadedEventStart`](/en-US/docs/Web/API/PerformanceNavigationTiming/domContentLoadedEventStart) for the timestamp) will fire immediately after `domInteractive`.
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp","timestamp")}} representing the time value equal to
-the time immediately before the user agent sets the current document readiness of the
-current document to [interactive](https://html.spec.whatwg.org/multipage/syntax.html#the-end).
+A {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the user agent sets the document's [`readyState`](/en-US/docs/Web/API/Document/readyState) to `"interactive"`.
 
 ## Examples
 
-The following example illustrates this property's usage.
+### Logging DOM interaction time
+
+The `domInteractive` property can be used to log the time when the DOM construction has finished and interaction with it is possible.
+
+Example using a {{domxref("PerformanceObserver")}}, which notifies of new `navigation` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    console.log(
+      `${entry.name}: domInteractive time: ${entry.domInteractive}ms`
+    );
+  });
+});
+
+observer.observe({ type: "navigation", buffered: true });
+```
+
+Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `navigation` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function printNavTimingData() {
-  // Use getEntriesByType() to just get the "navigation" events
-  performance.getEntriesByType("navigation")
-    .forEach((p, i) => {
-      console.log(`= Navigation entry[${i}]`);
-
-      // DOM Properties
-      console.log(`DOM content loaded = ${p.domContentLoadedEventEnd - p.domContentLoadedEventStart}`);
-      console.log(`DOM complete = ${p.domComplete}`);
-      console.log(`DOM interactive = ${p.domInteractive}`);
-
-      // Document load and unload time
-      console.log(`document load = ${p.loadEventEnd - p.loadEventStart}`);
-      console.log(`document unload = ${p.unloadEventEnd - p.unloadEventStart}`);
-
-      // Other properties
-      console.log(`type = ${p.type}`);
-      console.log(`redirectCount = ${p.redirectCount}`);
-    });
-}
+const entries = performance.getEntriesByType("navigation");
+entries.forEach((entry) => {
+  console.log(`${entry.name}: domInteractive time: ${entry.domInteractive}ms`);
+});
 ```
 
 ## Specifications
@@ -57,3 +60,7 @@ function printNavTimingData() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Document.readyState")}}