From a72ee1c1100b61fe097b6c9b4e5e5447f3fa299e Mon Sep 17 00:00:00 2001
From: Florian Scholz <fs@florianscholz.com>
Date: Thu, 13 Oct 2022 07:57:31 +0200
Subject: [PATCH] Document EventCounts API (#21516)

---
 files/en-us/web/api/eventcounts/index.md      | 74 +++++++++++++++++++
 .../web/api/performance/eventcounts/index.md  | 55 ++++++++++++++
 files/en-us/web/api/performance/index.md      |  3 +
 3 files changed, 132 insertions(+)
 create mode 100644 files/en-us/web/api/eventcounts/index.md
 create mode 100644 files/en-us/web/api/performance/eventcounts/index.md

diff --git a/files/en-us/web/api/eventcounts/index.md b/files/en-us/web/api/eventcounts/index.md
new file mode 100644
index 000000000000000..02782228f73c0c5
--- /dev/null
+++ b/files/en-us/web/api/eventcounts/index.md
@@ -0,0 +1,74 @@
+---
+title: EventCounts
+slug: Web/API/EventCounts
+page-type: web-api-interface
+tags:
+  - API
+  - Reference
+  - Interface
+  - Maplike
+browser-compat: api.EventCounts
+---
+
+{{APIRef("Event Timing")}}
+
+The **`EventCounts`** interface is a read-only map where the keys are event types and the values are the number of events that have been dispatched for that event type.
+
+As a read-only map, `EventCounts` is similar to a {{jsxref("Map")}}, however, it doesn't implement the `clear()`, `delete()`, and `set()` methods.
+
+## Constructor
+
+This interface has no constructor. You typically get an instance of this object using the {{domxref("performance.eventCounts")}} property.
+
+## Instance properties
+
+- `size`
+  - : See {{jsxref("Map.prototype.size")}} for details.
+
+## Instance methods
+
+- `entries()`
+  - : See {{jsxref("Map.prototype.entries()")}} for details.
+- `forEach()`
+  - : See {{jsxref("Map.prototype.forEach()")}} for details.
+- `get()`
+  - : See {{jsxref("Map.prototype.get()")}} for details.
+- `has()`
+  - : See {{jsxref("Map.prototype.has()")}} for details.
+- `keys()`
+  - : See {{jsxref("Map.prototype.keys()")}} for details.
+- `values()`
+  - : See {{jsxref("Map.prototype.values()")}} for details.
+
+## Examples
+
+### Working with EventCount maps
+
+Below are a few examples to get information from an `EventCounts` map. Note that the map is read-only and the `clear()`, `delete()`, and `set()` methods aren't available.
+
+```js
+for (entry of performance.eventCounts.entries()) {
+  const type = entry[0];
+  const count = entry[1];
+}
+
+const clickCount = performance.eventCounts.get("click"); 
+
+const isExposed = performance.eventCounts.has("mousemove");
+const exposedEventsCount = performance.eventCounts.size;
+const exposedEventsList = [...performance.eventCounts.keys()];
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("performance.eventCounts")}}
+- {{domxref("PerformanceEventTiming")}}
+- {{jsxref("Map")}}
diff --git a/files/en-us/web/api/performance/eventcounts/index.md b/files/en-us/web/api/performance/eventcounts/index.md
new file mode 100644
index 000000000000000..be25bf1f55d1c4b
--- /dev/null
+++ b/files/en-us/web/api/performance/eventcounts/index.md
@@ -0,0 +1,55 @@
+---
+title: Performance.eventCounts
+slug: Web/API/Performance/eventCounts
+page-type: web-api-instance-property
+browser-compat: api.Performance.eventCounts
+tags: 
+  - Property
+---
+
+{{APIRef("Event Timing")}}
+
+The read-only `performance.eventCounts` property is an {{domxref("EventCounts")}} map containing the number of events which have been dispatched per event type.
+
+Not all event types are exposed. You can only get counts for event types supported by the {{domxref("PerformanceEventTiming")}} interface.
+
+## Value
+
+An {{domxref("EventCounts")}} map.
+(A read-only {{jsxref("Map")}} without the `clear()`, `delete()`, and `set()` methods).
+
+## Examples
+
+### Reporting event types and their counts
+
+If you like to send event counts to your analytics, you may want to implement a function like `sendToEventAnalytics` which takes the event counts from the `performance.eventCounts` map and then uses the [Fetch API](/en-US/docs/Web/API/Fetch_API) to post the data to your endpoint.
+
+```js
+// Report all exposed events
+for (entry of performance.eventCounts.entries()) {
+  const type = entry[0];
+  const count = entry[1];
+  // sendToEventAnalytics(type, count);
+}
+
+// Report a specific event
+const clickCount = performance.eventCounts.get("click");
+// sendToEventAnalytics("click", clickCount);
+
+// Check if an event count is exposed for a type
+const isExposed = performance.eventCounts.has("mousemove"); // false
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("EventCounts")}}
+- {{domxref("PerformanceEventTiming")}}
+- {{jsxref("Map")}}
diff --git a/files/en-us/web/api/performance/index.md b/files/en-us/web/api/performance/index.md
index c157f8c7d3caaef..acc9b5202039691 100644
--- a/files/en-us/web/api/performance/index.md
+++ b/files/en-us/web/api/performance/index.md
@@ -26,6 +26,9 @@ An object of this type can be obtained by calling the {{domxref("window.performa
 
 _The `Performance` interface doesn't inherit any properties._
 
+- {{domxref("Performance.eventCounts")}} {{ReadOnlyInline}}
+  - : An {{domxref("EventCounts")}} map containing the number of events which have been dispatched per event type.
+
 - {{domxref("Performance.navigation")}} {{ReadOnlyInline}} {{Deprecated_Inline}}
 
   - : A legacy {{domxref("PerformanceNavigation")}} object that provides useful context about the operations included in the times listed in `timing`, including whether the page was a load or a refresh, how many redirections occurred, and so forth.