clarity-js 0.8.42 → 0.8.44

package/src/performance/interaction.ts

@@ -1,125 +1,125 @@
-import { PerformanceEventTiming, Interaction } from '@clarity-types/data';
-
-// Estimate variables to keep track of interactions
-let interactionCountEstimate = 0;
-let minKnownInteractionId = Infinity;
-let maxKnownInteractionId = 0;
-
-let prevInteractionCount = 0; // Used to track interaction count between pages
-
-const MAX_INTERACTIONS_TO_CONSIDER = 10; // Maximum number of interactions we consider for INP
-const DEFAULT_DURATION_THRESHOLD = 40; // Threshold to ignore very short interactions
-
-// List to store the longest interaction events
-const longestInteractionList: Interaction[] = [];
-// Map to track interactions by their ID, ensuring we handle duplicates
-const longestInteractionMap: Map<number, Interaction> = new Map();
-
-/**
- * Update the approx number of interactions estimate count if the interactionCount is not supported.
- * The difference between `maxKnownInteractionId` and `minKnownInteractionId` gives us a rough range of how many interactions have occurred.
- * Dividing by 7 helps approximate the interaction count more accurately, since interaction IDs are spread out across a large range.
- */
-const countInteractions = (entry: PerformanceEventTiming) => {
-  if ('interactionCount' in performance) {
-    interactionCountEstimate = performance.interactionCount as number;
-    return;
-  }
-
-  if (entry.interactionId) {
-    minKnownInteractionId = Math.min(
-      minKnownInteractionId,
-      entry.interactionId
-    );
-    maxKnownInteractionId = Math.max(
-      maxKnownInteractionId,
-      entry.interactionId
-    );
-
-    interactionCountEstimate = maxKnownInteractionId
-      ? (maxKnownInteractionId - minKnownInteractionId) / 7 + 1
-      : 0;
-  }
-};
-
-const getInteractionCount = () => {
-  return interactionCountEstimate || 0;
-};
-
-const getInteractionCountForNavigation = () => {
-  return getInteractionCount() - prevInteractionCount;
-};
-
-/**
- * Estimates the 98th percentile (P98) of the longest interactions by selecting
- * the candidate interaction based on the current interaction count.
- * Dividing by 50 is a heuristic to estimate the 98th percentile (P98) interaction.
- * This assumes one out of every 50 interactions represents the P98 interaction.
- * By dividing the total interaction count by 50, we get an index to approximate 
- * the slowest 2% of interactions, helping identify a likely P98 candidate.
- */
-export const estimateP98LongestInteraction = () => {
-  if(!longestInteractionList.length){
-    return -1;
-  }
-
-  const candidateInteractionIndex = Math.min(
-    longestInteractionList.length - 1,
-    Math.floor(getInteractionCountForNavigation() / 50)
-  );
-
-  return longestInteractionList[candidateInteractionIndex].latency;
-};
-
-/**
- * Resets the interaction tracking, usually called after navigation to a new page.
- */
-export const resetInteractions = () => {
-  prevInteractionCount = getInteractionCount();
-  longestInteractionList.length = 0;
-  longestInteractionMap.clear();
-};
-
-/**
- * Processes a PerformanceEventTiming entry by updating the longest interaction list.
- */
-export const processInteractionEntry = (entry: PerformanceEventTiming) => {
-  // Ignore entries with 0 interactionId or very short durations
-  if (!entry.interactionId || entry.duration < DEFAULT_DURATION_THRESHOLD) {
-    return;
-  }
-
-  countInteractions(entry);
-
-  const minLongestInteraction =
-    longestInteractionList[longestInteractionList.length - 1];
-
-  const existingInteraction = longestInteractionMap.get(entry.interactionId!);
-
-  // Either update existing, add new, or replace shortest interaction if necessary
-  if (
-    existingInteraction ||
-    longestInteractionList.length < MAX_INTERACTIONS_TO_CONSIDER ||
-    entry.duration > minLongestInteraction?.latency
-  ) {
-    if (!existingInteraction) {
-      const interaction = {
-        id: entry.interactionId,
-        latency: entry.duration,
-      };
-      longestInteractionMap.set(interaction.id, interaction);
-      longestInteractionList.push(interaction);
-    } else if (entry.duration > existingInteraction.latency) {
-      existingInteraction.latency = entry.duration;
-    }
-
-    longestInteractionList.sort((a, b) => b.latency - a.latency);
-
-    // Trim the list to the maximum number of interactions to consider
-    if (longestInteractionList.length > MAX_INTERACTIONS_TO_CONSIDER) {
-      longestInteractionList
-        .splice(MAX_INTERACTIONS_TO_CONSIDER)
-        .forEach((i) => longestInteractionMap.delete(i.id));
-    }
-  }
-};
+import { PerformanceEventTiming, Interaction } from '@clarity-types/data';
+
+// Estimate variables to keep track of interactions
+let interactionCountEstimate = 0;
+let minKnownInteractionId = Infinity;
+let maxKnownInteractionId = 0;
+
+let prevInteractionCount = 0; // Used to track interaction count between pages
+
+const MAX_INTERACTIONS_TO_CONSIDER = 10; // Maximum number of interactions we consider for INP
+const DEFAULT_DURATION_THRESHOLD = 40; // Threshold to ignore very short interactions
+
+// List to store the longest interaction events
+const longestInteractionList: Interaction[] = [];
+// Map to track interactions by their ID, ensuring we handle duplicates
+const longestInteractionMap: Map<number, Interaction> = new Map();
+
+/**
+ * Update the approx number of interactions estimate count if the interactionCount is not supported.
+ * The difference between `maxKnownInteractionId` and `minKnownInteractionId` gives us a rough range of how many interactions have occurred.
+ * Dividing by 7 helps approximate the interaction count more accurately, since interaction IDs are spread out across a large range.
+ */
+const countInteractions = (entry: PerformanceEventTiming) => {
+  if ('interactionCount' in performance) {
+    interactionCountEstimate = performance.interactionCount as number;
+    return;
+  }
+
+  if (entry.interactionId) {
+    minKnownInteractionId = Math.min(
+      minKnownInteractionId,
+      entry.interactionId
+    );
+    maxKnownInteractionId = Math.max(
+      maxKnownInteractionId,
+      entry.interactionId
+    );
+
+    interactionCountEstimate = maxKnownInteractionId
+      ? (maxKnownInteractionId - minKnownInteractionId) / 7 + 1
+      : 0;
+  }
+};
+
+const getInteractionCount = () => {
+  return interactionCountEstimate || 0;
+};
+
+const getInteractionCountForNavigation = () => {
+  return getInteractionCount() - prevInteractionCount;
+};
+
+/**
+ * Estimates the 98th percentile (P98) of the longest interactions by selecting
+ * the candidate interaction based on the current interaction count.
+ * Dividing by 50 is a heuristic to estimate the 98th percentile (P98) interaction.
+ * This assumes one out of every 50 interactions represents the P98 interaction.
+ * By dividing the total interaction count by 50, we get an index to approximate 
+ * the slowest 2% of interactions, helping identify a likely P98 candidate.
+ */
+export const estimateP98LongestInteraction = () => {
+  if(!longestInteractionList.length){
+    return -1;
+  }
+
+  const candidateInteractionIndex = Math.min(
+    longestInteractionList.length - 1,
+    Math.floor(getInteractionCountForNavigation() / 50)
+  );
+
+  return longestInteractionList[candidateInteractionIndex].latency;
+};
+
+/**
+ * Resets the interaction tracking, usually called after navigation to a new page.
+ */
+export const resetInteractions = () => {
+  prevInteractionCount = getInteractionCount();
+  longestInteractionList.length = 0;
+  longestInteractionMap.clear();
+};
+
+/**
+ * Processes a PerformanceEventTiming entry by updating the longest interaction list.
+ */
+export const processInteractionEntry = (entry: PerformanceEventTiming) => {
+  // Ignore entries with 0 interactionId or very short durations
+  if (!entry.interactionId || entry.duration < DEFAULT_DURATION_THRESHOLD) {
+    return;
+  }
+
+  countInteractions(entry);
+
+  const minLongestInteraction =
+    longestInteractionList[longestInteractionList.length - 1];
+
+  const existingInteraction = longestInteractionMap.get(entry.interactionId!);
+
+  // Either update existing, add new, or replace shortest interaction if necessary
+  if (
+    existingInteraction ||
+    longestInteractionList.length < MAX_INTERACTIONS_TO_CONSIDER ||
+    entry.duration > minLongestInteraction?.latency
+  ) {
+    if (!existingInteraction) {
+      const interaction = {
+        id: entry.interactionId,
+        latency: entry.duration,
+      };
+      longestInteractionMap.set(interaction.id, interaction);
+      longestInteractionList.push(interaction);
+    } else if (entry.duration > existingInteraction.latency) {
+      existingInteraction.latency = entry.duration;
+    }
+
+    longestInteractionList.sort((a, b) => b.latency - a.latency);
+
+    // Trim the list to the maximum number of interactions to consider
+    if (longestInteractionList.length > MAX_INTERACTIONS_TO_CONSIDER) {
+      longestInteractionList
+        .splice(MAX_INTERACTIONS_TO_CONSIDER)
+        .forEach((i) => longestInteractionMap.delete(i.id));
+    }
+  }
+};

package/src/performance/navigation.ts

@@ -1,31 +1,31 @@
-import { Event } from "@clarity-types/data";
-import { NavigationData } from "@clarity-types/performance";
-import encode from "./encode";
-
-export let data: NavigationData = null;
-
-export function reset(): void {
-    data = null;
-}
-
-export function compute(entry: PerformanceNavigationTiming): void {
-    data = {
-        fetchStart: Math.round(entry.fetchStart),
-        connectStart: Math.round(entry.connectStart),
-        connectEnd: Math.round(entry.connectEnd),
-        requestStart: Math.round(entry.requestStart),
-        responseStart: Math.round(entry.responseStart),
-        responseEnd: Math.round(entry.responseEnd),
-        domInteractive: Math.round(entry.domInteractive),
-        domComplete: Math.round(entry.domComplete),
-        loadEventStart: Math.round(entry.loadEventStart),
-        loadEventEnd: Math.round(entry.loadEventEnd),
-        redirectCount: Math.round(entry.redirectCount),
-        size: entry.transferSize ? entry.transferSize : 0,
-        type: entry.type,
-        protocol: entry.nextHopProtocol,
-        encodedSize: entry.encodedBodySize ? entry.encodedBodySize : 0,
-        decodedSize: entry.decodedBodySize ? entry.decodedBodySize : 0
-    };
-    encode(Event.Navigation);
-}
+import { Event } from "@clarity-types/data";
+import { NavigationData } from "@clarity-types/performance";
+import encode from "./encode";
+
+export let data: NavigationData = null;
+
+export function reset(): void {
+    data = null;
+}
+
+export function compute(entry: PerformanceNavigationTiming): void {
+    data = {
+        fetchStart: Math.round(entry.fetchStart),
+        connectStart: Math.round(entry.connectStart),
+        connectEnd: Math.round(entry.connectEnd),
+        requestStart: Math.round(entry.requestStart),
+        responseStart: Math.round(entry.responseStart),
+        responseEnd: Math.round(entry.responseEnd),
+        domInteractive: Math.round(entry.domInteractive),
+        domComplete: Math.round(entry.domComplete),
+        loadEventStart: Math.round(entry.loadEventStart),
+        loadEventEnd: Math.round(entry.loadEventEnd),
+        redirectCount: Math.round(entry.redirectCount),
+        size: entry.transferSize ? entry.transferSize : 0,
+        type: entry.type,
+        protocol: entry.nextHopProtocol,
+        encodedSize: entry.encodedBodySize ? entry.encodedBodySize : 0,
+        decodedSize: entry.decodedBodySize ? entry.decodedBodySize : 0
+    };
+    encode(Event.Navigation);
+}

package/src/performance/observer.ts

@@ -1,112 +1,112 @@
-import { Code, Constant, Dimension, Metric, Severity, PerformanceEventTiming } from "@clarity-types/data";
-import config from "@src/core/config";
-import { bind } from "@src/core/event";
-import measure from "@src/core/measure";
-import { setTimeout } from "@src/core/timeout";
-import * as dimension from "@src/data/dimension";
-import * as metric from "@src/data/metric";
-import * as internal from "@src/diagnostic/internal";
-import * as navigation from "@src/performance/navigation";
-import * as interaction from "@src/performance/interaction";
-
-let observer: PerformanceObserver;
-const types: string[] = [Constant.Navigation, Constant.Resource, Constant.LongTask, Constant.FID, Constant.CLS, Constant.LCP, Constant.PerformanceEventTiming];
-
-export function start(): void {
-    // Capture connection properties, if available
-    if (navigator && navigator["connection"]) {
-        dimension.log(Dimension.ConnectionType, navigator["connection"]["effectiveType"]);
-    }
-
-    // Check the browser support performance observer as a pre-requisite for any performance measurement
-    if (window["PerformanceObserver"] && PerformanceObserver.supportedEntryTypes) {
-        // Start monitoring performance data after page has finished loading.
-        // If the document.readyState is not yet complete, we intentionally call observe using a setTimeout.
-        // This allows us to capture loadEventEnd on navigation timeline.
-        if (document.readyState !== "complete") {
-            bind(window, "load", setTimeout.bind(this, observe, 0));
-        } else { observe(); }
-    } else { internal.log(Code.PerformanceObserver, Severity.Info); }
-}
-
-function observe(): void {
-    // Some browsers will throw an error for unsupported entryType, e.g. "layout-shift"
-    // In those cases, we log it as a warning and continue with rest of the Clarity processing
-    try {
-        if (observer) { observer.disconnect(); }
-        observer = new PerformanceObserver(measure(handle) as PerformanceObserverCallback);
-        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe
-        // "buffered" flag indicates whether buffered entries should be queued into the observer's buffer.
-        // It must only be used only with the "type" option, and cannot be used with entryTypes.
-        // This is why we need to individually "observe" each supported type
-        for (let x of types) {
-            if (PerformanceObserver.supportedEntryTypes.indexOf(x) >= 0) {
-                // Initialize CLS with a value of zero. It's possible (and recommended) for sites to not have any cumulative layout shift.
-                // In those cases, we want to still initialize the metric in Clarity
-                if (x === Constant.CLS) { metric.sum(Metric.CumulativeLayoutShift, 0); }
-                observer.observe({type: x, buffered: true});
-            }
-        }
-    } catch { internal.log(Code.PerformanceObserver, Severity.Warning); }
-}
-
-function handle(entries: PerformanceObserverEntryList): void {
-    process(entries.getEntries());
-}
-
-function process(entries: PerformanceEntryList): void {
-    let visible = "visibilityState" in document ? document.visibilityState === "visible" : true;
-    for (let i = 0; i < entries.length; i++) {
-        let entry = entries[i];
-        switch (entry.entryType) {
-            case Constant.Navigation:
-                navigation.compute(entry as PerformanceNavigationTiming);
-                break;
-            case Constant.Resource:
-                let name = entry.name;
-                dimension.log(Dimension.NetworkHosts, host(name));
-                if (name === config.upload || name === config.fallback) { metric.max(Metric.UploadTime, entry.duration); }
-                break;
-            case Constant.LongTask:
-                metric.count(Metric.LongTaskCount);
-                break;
-            case Constant.FID:
-                if (visible) { metric.max(Metric.FirstInputDelay, entry["processingStart"] - entry.startTime); }
-                break;
-            case Constant.PerformanceEventTiming:
-                if (visible && 'PerformanceEventTiming' in window &&  'interactionId' in PerformanceEventTiming.prototype)
-                {
-                    interaction.processInteractionEntry(entry as PerformanceEventTiming); 
-                    // Logging it as dimension because we're always looking for the last value.
-                    dimension.log(Dimension.InteractionNextPaint, interaction.estimateP98LongestInteraction().toString()); 
-                }
-                break;
-            case Constant.CLS:
-                // Scale the value to avoid sending back floating point number
-                if (visible && !entry["hadRecentInput"]) { metric.sum(Metric.CumulativeLayoutShift, entry["value"] * 1000); }
-                break;
-            case Constant.LCP:
-                if (visible) { metric.max(Metric.LargestPaint, entry.startTime); }
-                break;
-        }
-    }
-}
-
-export function stop(): void {
-    if (observer) { observer.disconnect(); }
-    observer = null;
-    interaction.resetInteractions();
-    anchorCache = null;
-}
-
-// Cached anchor element for optimal performance & memory management
-let anchorCache: HTMLAnchorElement | null = null;
-
-function host(url: string): string {
-    if (!anchorCache) {
-        anchorCache = document.createElement("a");
-    }
-
-    anchorCache.href = url;
-    return anchorCache.host;
-}
+import { Code, Constant, Dimension, Metric, Severity, PerformanceEventTiming } from "@clarity-types/data";
+import config from "@src/core/config";
+import { bind } from "@src/core/event";
+import measure from "@src/core/measure";
+import { setTimeout } from "@src/core/timeout";
+import * as dimension from "@src/data/dimension";
+import * as metric from "@src/data/metric";
+import * as internal from "@src/diagnostic/internal";
+import * as navigation from "@src/performance/navigation";
+import * as interaction from "@src/performance/interaction";
+
+let observer: PerformanceObserver;
+const types: string[] = [Constant.Navigation, Constant.Resource, Constant.LongTask, Constant.FID, Constant.CLS, Constant.LCP, Constant.PerformanceEventTiming];
+
+export function start(): void {
+    // Capture connection properties, if available
+    if (navigator && navigator["connection"]) {
+        dimension.log(Dimension.ConnectionType, navigator["connection"]["effectiveType"]);
+    }
+
+    // Check the browser support performance observer as a pre-requisite for any performance measurement
+    if (window["PerformanceObserver"] && PerformanceObserver.supportedEntryTypes) {
+        // Start monitoring performance data after page has finished loading.
+        // If the document.readyState is not yet complete, we intentionally call observe using a setTimeout.
+        // This allows us to capture loadEventEnd on navigation timeline.
+        if (document.readyState !== "complete") {
+            bind(window, "load", setTimeout.bind(this, observe, 0));
+        } else { observe(); }
+    } else { internal.log(Code.PerformanceObserver, Severity.Info); }
+}
+
+function observe(): void {
+    // Some browsers will throw an error for unsupported entryType, e.g. "layout-shift"
+    // In those cases, we log it as a warning and continue with rest of the Clarity processing
+    try {
+        if (observer) { observer.disconnect(); }
+        observer = new PerformanceObserver(measure(handle) as PerformanceObserverCallback);
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe
+        // "buffered" flag indicates whether buffered entries should be queued into the observer's buffer.
+        // It must only be used only with the "type" option, and cannot be used with entryTypes.
+        // This is why we need to individually "observe" each supported type
+        for (let x of types) {
+            if (PerformanceObserver.supportedEntryTypes.indexOf(x) >= 0) {
+                // Initialize CLS with a value of zero. It's possible (and recommended) for sites to not have any cumulative layout shift.
+                // In those cases, we want to still initialize the metric in Clarity
+                if (x === Constant.CLS) { metric.sum(Metric.CumulativeLayoutShift, 0); }
+                observer.observe({type: x, buffered: true});
+            }
+        }
+    } catch { internal.log(Code.PerformanceObserver, Severity.Warning); }
+}
+
+function handle(entries: PerformanceObserverEntryList): void {
+    process(entries.getEntries());
+}
+
+function process(entries: PerformanceEntryList): void {
+    let visible = "visibilityState" in document ? document.visibilityState === "visible" : true;
+    for (let i = 0; i < entries.length; i++) {
+        let entry = entries[i];
+        switch (entry.entryType) {
+            case Constant.Navigation:
+                navigation.compute(entry as PerformanceNavigationTiming);
+                break;
+            case Constant.Resource:
+                let name = entry.name;
+                dimension.log(Dimension.NetworkHosts, host(name));
+                if (name === config.upload || name === config.fallback) { metric.max(Metric.UploadTime, entry.duration); }
+                break;
+            case Constant.LongTask:
+                metric.count(Metric.LongTaskCount);
+                break;
+            case Constant.FID:
+                if (visible) { metric.max(Metric.FirstInputDelay, entry["processingStart"] - entry.startTime); }
+                break;
+            case Constant.PerformanceEventTiming:
+                if (visible && 'PerformanceEventTiming' in window &&  'interactionId' in PerformanceEventTiming.prototype)
+                {
+                    interaction.processInteractionEntry(entry as PerformanceEventTiming); 
+                    // Logging it as dimension because we're always looking for the last value.
+                    dimension.log(Dimension.InteractionNextPaint, interaction.estimateP98LongestInteraction().toString()); 
+                }
+                break;
+            case Constant.CLS:
+                // Scale the value to avoid sending back floating point number
+                if (visible && !entry["hadRecentInput"]) { metric.sum(Metric.CumulativeLayoutShift, entry["value"] * 1000); }
+                break;
+            case Constant.LCP:
+                if (visible) { metric.max(Metric.LargestPaint, entry.startTime); }
+                break;
+        }
+    }
+}
+
+export function stop(): void {
+    if (observer) { observer.disconnect(); }
+    observer = null;
+    interaction.resetInteractions();
+    anchorCache = null;
+}
+
+// Cached anchor element for optimal performance & memory management
+let anchorCache: HTMLAnchorElement | null = null;
+
+function host(url: string): string {
+    if (!anchorCache) {
+        anchorCache = document.createElement("a");
+    }
+
+    anchorCache.href = url;
+    return anchorCache.host;
+}

package/src/queue.ts

@@ -1,33 +1,33 @@
-import { Constant } from "@clarity-types/data";
-import * as clarity from "@src/clarity";
-
-const w = window; 
-const c = Constant.Clarity;
-
-export function setup() {
-    // Start queuing up calls while Clarity is inactive and we are in a browser enviornment    
-    if (typeof w !== "undefined") {
-        w[c] = function() {
-            (w[c].q = w[c].q || []).push(arguments);
-            // if the start function was called, don't queue it and instead process the queue
-            arguments[0] === "start" && w[c].q.unshift(w[c].q.pop()) && process();
-        };
-    }
-}
-
-export function process() {
-    if (typeof w !== "undefined") {
-        // Do not execute or reset global "clarity" variable if a version of Clarity is already running on the page
-        if (w[c] && w[c].v) { return console.warn("Error CL001: Multiple Clarity tags detected."); }
-
-        // Expose clarity in a browser environment
-        // To be efficient about queuing up operations while Clarity is wiring up, we expose clarity.*(args) => clarity(*, args);
-        // This allows us to reprocess any calls that we missed once Clarity is available on the page
-        // Once Clarity script bundle is loaded on the page, we also initialize a "v" property that holds current version
-        // We use the presence or absence of "v" to determine if we are attempting to run a duplicate instance
-        let queue = w[c] ? (w[c].q || []) : [];
-        w[c] = function(method: string, ...args: any[]): void { return clarity[method](...args); }
-        w[c].v = clarity.version;
-        while (queue.length > 0) { w[c](...queue.shift()); }
-    }
-}
+import { Constant } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+
+const w = window; 
+const c = Constant.Clarity;
+
+export function setup() {
+    // Start queuing up calls while Clarity is inactive and we are in a browser enviornment    
+    if (typeof w !== "undefined") {
+        w[c] = function() {
+            (w[c].q = w[c].q || []).push(arguments);
+            // if the start function was called, don't queue it and instead process the queue
+            arguments[0] === "start" && w[c].q.unshift(w[c].q.pop()) && process();
+        };
+    }
+}
+
+export function process() {
+    if (typeof w !== "undefined") {
+        // Do not execute or reset global "clarity" variable if a version of Clarity is already running on the page
+        if (w[c] && w[c].v) { return console.warn("Error CL001: Multiple Clarity tags detected."); }
+
+        // Expose clarity in a browser environment
+        // To be efficient about queuing up operations while Clarity is wiring up, we expose clarity.*(args) => clarity(*, args);
+        // This allows us to reprocess any calls that we missed once Clarity is available on the page
+        // Once Clarity script bundle is loaded on the page, we also initialize a "v" property that holds current version
+        // We use the presence or absence of "v" to determine if we are attempting to run a duplicate instance
+        let queue = w[c] ? (w[c].q || []) : [];
+        w[c] = function(method: string, ...args: any[]): void { return clarity[method](...args); }
+        w[c].v = clarity.version;
+        while (queue.length > 0) { w[c](...queue.shift()); }
+    }
+}