@gemx-dev/clarity-js 0.8.39

package/src/core/index.ts

@@ -0,0 +1,81 @@
+import { Config } from "@clarity-types/core";
+import { Constant } from "@clarity-types/data";
+import configuration from "@src/core/config";
+import * as event from "@src/core/event";
+import * as history from "@src/core/history";
+import * as report from "@src/core/report";
+import * as task from "@src/core/task";
+import * as time from "@src/core/time";
+import * as clarity from "@src/clarity";
+import * as custom from "@src/data/custom";
+
+let status = false;
+
+export function start(): void {
+    status = true;
+    time.start();
+    task.reset();
+    event.reset();
+    report.reset();
+    history.start();
+}
+
+export function stop(): void {
+    history.stop();
+    report.reset();
+    event.reset();
+    task.reset();
+    time.stop();
+    status = false;
+}
+
+export function active(): boolean {
+    return status;
+}
+
+export function check(): boolean {
+    try {
+        let globalPrivacyControlSet = navigator && "globalPrivacyControl" in navigator && navigator['globalPrivacyControl'] == true;
+        return status === false &&
+            typeof Promise !== "undefined" &&
+            window["MutationObserver"] &&
+            document["createTreeWalker"] &&
+            "now" in Date &&
+            "now" in performance &&
+            typeof WeakMap !== "undefined" &&
+            !globalPrivacyControlSet
+    } catch (ex) {
+        return false;
+    }
+}
+
+export function config(override: Config): boolean {
+    // Process custom configuration overrides, if available
+    if (override === null || status) { return false; }
+    for (let key in override) {
+        if (key in configuration) { configuration[key] = override[key]; }
+    }
+    return true;
+}
+
+// Suspend ends the current Clarity instance after a configured timeout period
+// The way it differs from the "end" call is that it starts listening to
+// user interaction events as soon as it terminates existing clarity instance.
+// On the next interaction, it automatically starts another instance under a different page id
+// E.g. if configured timeout is 10m, and user stays inactive for an hour.
+// In this case, we will suspend clarity after 10m of inactivity and after another 50m when user interacts again
+// Clarity will restart and start another instance seamlessly. Effectively not missing any active time, but also
+// not holding the session during inactive time periods.
+export function suspend(): void {
+    if (status) {
+        custom.event(Constant.Clarity, Constant.Suspend);
+        clarity.stop();
+        ["mousemove", "touchstart"].forEach(x => event.bind(document, x, restart));
+        ["resize", "scroll", "pageshow"].forEach(x => event.bind(window, x, restart));
+    }
+}
+
+function restart(): void {
+    clarity.start();
+    custom.event(Constant.Clarity, Constant.Restart);
+}

package/src/core/measure.ts

@@ -0,0 +1,19 @@
+import { Code, Metric, Setting, Severity } from "@clarity-types/data";
+import { report } from "@src/core/report";
+import * as metric from "@src/data/metric";
+import * as internal from "@src/diagnostic/internal";
+
+// tslint:disable-next-line: ban-types
+export default function (method: Function): Function {
+    return function (): void {
+        let start = performance.now();
+        try { method.apply(this, arguments); } catch (ex) { throw report(ex); }
+        let duration = performance.now() - start;
+        metric.sum(Metric.TotalCost, duration);
+        if (duration > Setting.LongTask) {
+            metric.count(Metric.LongTaskCount);
+            metric.max(Metric.ThreadBlockedTime, duration);
+            method.dn && internal.log(Code.FunctionExecutionTime, Severity.Info, `${method.dn}-${duration}`);
+        }
+    };
+}

package/src/core/report.ts

@@ -0,0 +1,35 @@
+import { Report } from "@clarity-types/core";
+import config from "@src/core/config";
+import { data } from "@src/data/envelope";
+
+let history: string[];
+
+export function reset(): void {
+    history = [];
+}
+
+export function report(e: Error): Error {
+    console.log(`🚀 🐥 ~ report ~ e:`, e);
+    // Do not report the same message twice for the same page
+    if (history && history.indexOf(e.message) === -1) {
+        const url = config.report;
+        console.log(`🚀 🐥 ~ report ~ url:`, url);
+        if (url && url.length > 0 && data) {
+            let payload: Report = { v: data.version, p: data.projectId, u: data.userId, s: data.sessionId, n: data.pageNum };
+            if (e.message) {
+                payload.m = e.message;
+            }
+            if (e.stack) {
+                payload.e = e.stack;
+            }
+            // Using POST request instead of a GET request (img-src) to not violate existing CSP rules
+            // Since, Clarity already uses XHR to upload data, we stick with similar POST mechanism for reporting too
+            let xhr = new XMLHttpRequest();
+            console.log(`🚀 🐥 ~ report ~ xhr:`, xhr);
+            xhr.open("POST", url, true);
+            xhr.send(JSON.stringify(payload));
+            history.push(e.message);
+        }
+    }
+    return e;
+}

package/src/core/scrub.ts

@@ -0,0 +1,202 @@
+import { Privacy } from "@clarity-types/core";
+import * as Data from "@clarity-types/data";
+import * as Layout from "@clarity-types/layout";
+import config from "@src/core/config";
+
+const catchallRegex = /\S/gi;
+const maxUrlLength = 255;
+let unicodeRegex = true;
+let digitRegex = null;
+let letterRegex = null;
+let currencyRegex = null;
+
+export function text(value: string, hint: string, privacy: Privacy, mangle: boolean = false, type?: string): string {
+    if (value) {
+        if (hint == "input" && (type === "checkbox" || type === "radio")) {
+            return value;
+        }
+
+        switch (privacy) {
+            case Privacy.None:
+                return value;
+            case Privacy.Sensitive:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                    case "value":
+                    case "placeholder":
+                    case "click":
+                        return redact(value);
+                    case "input":
+                    case "change":
+                        return mangleToken(value);
+                }
+                return value;
+            case Privacy.Text:
+            case Privacy.TextImage:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                    case Layout.Constant.DataAttribute:
+                        return mangle ? mangleText(value) : mask(value);
+                    case "src":
+                    case "srcset":
+                    case "title":
+                    case "alt":
+                        if (privacy === Privacy.TextImage) {
+                            if (hint === 'src' && value?.startsWith('blob:')) {
+                                return 'blob:';
+                            }
+                            return Data.Constant.Empty;
+                        }
+                        return value;
+                    case "value":
+                    case "click":
+                    case "input":
+                    case "change":
+                        return mangleToken(value);
+                    case "placeholder":
+                        return mask(value);
+                }
+                break;
+            case Privacy.Exclude:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                    case Layout.Constant.DataAttribute:
+                        return mangle ? mangleText(value) : mask(value);
+                    case "value":
+                    case "input":
+                    case "click":
+                    case "change":
+                        return Array(Data.Setting.WordLength).join(Data.Constant.Mask);
+                    case "checksum":
+                        return Data.Constant.Empty;
+                }
+                break;
+            case Privacy.Snapshot:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                    case Layout.Constant.DataAttribute:
+                        return scrub(value, Data.Constant.Letter, Data.Constant.Digit);
+                    case "value":
+                    case "input":
+                    case "click":
+                    case "change":
+                        return Array(Data.Setting.WordLength).join(Data.Constant.Mask);
+                    case "checksum":
+                    case "src":
+                    case "srcset":
+                    case "alt":
+                    case "title":
+                        return Data.Constant.Empty;
+                }
+                break;
+        }
+    }
+    return value;
+}
+
+export function url(input: string, electron: boolean = false, truncate: boolean = false): string {
+    let result = input;
+    // Replace the URL for Electron apps so we don't send back file:/// URL
+    if (electron) {
+        result = `${Data.Constant.HTTPS}${Data.Constant.Electron}`;
+    } else {
+        let drop = config.drop;
+        if (drop && drop.length > 0 && input && input.indexOf("?") > 0) {
+            let [path, query] = input.split("?");
+            let swap = Data.Constant.Dropped;
+            result = path + "?" + query.split("&").map(p => drop.some(x => p.indexOf(`${x}=`) === 0) ? `${p.split("=")[0]}=${swap}` : p).join("&");
+        }
+    }
+
+    if (truncate) {
+        result = result.substring(0, maxUrlLength);
+    }
+    return result;
+}
+
+function mangleText(value: string): string {
+    let trimmed = value.trim();
+    if (trimmed.length > 0) {
+        let first = trimmed[0];
+        let index = value.indexOf(first);
+        let prefix = value.substr(0, index);
+        let suffix = value.substr(index + trimmed.length);
+        return `${prefix}${trimmed.length.toString(36)}${suffix}`;
+    }
+    return value;
+}
+
+function mask(value: string): string {
+    return value.replace(catchallRegex, Data.Constant.Mask);
+}
+
+export function scrub(value: string, letter: string, digit: string): string {
+    regex(); // Initialize regular expressions
+    return value ? value.replace(letterRegex, letter).replace(digitRegex, digit) : value;
+}
+
+function mangleToken(value: string): string {
+    let length = ((Math.floor(value.length / Data.Setting.WordLength) + 1) * Data.Setting.WordLength);
+    let output: string = Layout.Constant.Empty;
+    for (let i = 0; i < length; i++) {
+        output += i > 0 && i % Data.Setting.WordLength === 0 ? Data.Constant.Space : Data.Constant.Mask;
+    }
+    return output;
+}
+
+function regex(): void {
+    // Initialize unicode regex, if supported by the browser
+    // Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Unicode_Property_Escapes
+    if (unicodeRegex && digitRegex === null) {
+        try {
+            digitRegex = new RegExp("\\p{N}", "gu");
+            letterRegex = new RegExp("\\p{L}", "gu");
+            currencyRegex = new RegExp("\\p{Sc}", "gu");
+        } catch { unicodeRegex = false; }
+    }
+}
+
+function redact(value: string): string {
+    let spaceIndex = -1;
+    let gap = 0;
+    let hasDigit = false;
+    let hasEmail = false;
+    let hasWhitespace = false;
+    let array = null;
+
+    regex(); // Initialize regular expressions
+
+    for (let i = 0; i < value.length; i++) {
+        let c = value.charCodeAt(i);
+        hasDigit = hasDigit || (c >= Data.Character.Zero && c <= Data.Character.Nine); // Check for digits in the current word
+        hasEmail = hasEmail || c === Data.Character.At; // Check for @ sign anywhere within the current word
+        hasWhitespace = c === Data.Character.Tab || c === Data.Character.NewLine || c === Data.Character.Return || c === Data.Character.Blank;
+
+        // Process each word as an individual token to redact any sensitive information
+        if (i === 0 || i === value.length - 1 || hasWhitespace) {
+            // Performance optimization: Lazy load string -> array conversion only when required
+            if (hasDigit || hasEmail) {
+                if (array === null) { array = value.split(Data.Constant.Empty); }
+                // Work on a token at a time so we don't have to apply regex to a larger string
+                let token = value.substring(spaceIndex + 1, hasWhitespace ? i : i + 1);
+                // Check if unicode regex is supported, otherwise fallback to calling mask function on this token
+                if (unicodeRegex && currencyRegex !== null) {
+                    // Do not redact information if the token contains a currency symbol
+                    token = token.match(currencyRegex) ? token : scrub(token, Data.Constant.Letter, Data.Constant.Digit);
+                } else {
+                    token = mask(token);
+                }
+                // Merge token back into array at the right place
+                array.splice(spaceIndex + 1 - gap, token.length, token);
+                gap += token.length - 1;
+            }
+            // Reset digit and email flags after every word boundary, except the beginning of string
+            if (hasWhitespace) {
+                hasDigit = false;
+                hasEmail = false;
+                spaceIndex = i;
+            }
+        }
+    }
+    return array ? array.join(Data.Constant.Empty) : value;
+}

package/src/core/task.ts

@@ -0,0 +1,181 @@
+import { AsyncTask, Priority, RequestIdleCallbackDeadline, RequestIdleCallbackOptions, Task, Timer } from "@clarity-types/core";
+import { TaskFunction, TaskResolve, Tasks } from "@clarity-types/core";
+import { Code, Metric, Setting, Severity } from "@clarity-types/data";
+import * as metadata from "@src/data/metadata";
+import * as metric from "@src/data/metric";
+import * as internal from "@src/diagnostic/internal";
+
+// Track the start time to be able to compute duration at the end of the task
+const idleTimeout = 5000;
+let tracker: Tasks = {};
+let queuedTasks: AsyncTask[] = [];
+let activeTask: AsyncTask = null;
+let pauseTask: Promise<void> = null;
+let resumeResolve: TaskResolve = null;
+
+export function pause(): void {
+    if (pauseTask === null) {
+        pauseTask = new Promise<void>((resolve: TaskResolve): void => {
+            resumeResolve = resolve;
+        });
+    }
+}
+
+export function resume(): void {
+    if (pauseTask) {
+        resumeResolve();
+        pauseTask = null;
+        if (activeTask === null) { run(); }
+    }
+}
+
+export function reset(): void {
+    tracker = {};
+    queuedTasks = [];
+    activeTask = null;
+    pauseTask = null;
+}
+
+export async function schedule(task: TaskFunction, priority: Priority = Priority.Normal): Promise<void> {
+    // If this task is already scheduled, skip it
+    for (let q of queuedTasks) {
+        if (q.task === task) {
+            return;
+        }
+    }
+
+    let promise = new Promise<void>((resolve: TaskResolve): void => {
+        let insert = priority === Priority.High ? "unshift" : "push";
+        // Queue this task for asynchronous execution later
+        // We also store a unique page identifier (id) along with the task to ensure
+        // ensure that we do not accidentally execute this task in context of a different page
+        queuedTasks[insert]({ task, resolve, id: metadata.id() });
+    });
+
+    // If there is no active task running, and Clarity is not in pause state,
+    // invoke the first task in the queue synchronously. This ensures that we don't yield the thread during unload event
+    if (activeTask === null && pauseTask === null) { run(); }
+
+    return promise;
+}
+
+function run(): void {
+    let entry = queuedTasks.shift();
+    if (entry) {
+        activeTask = entry;
+        entry.task().then((): void => {
+            // Bail out if the context in which this task was operating is different from the current page
+            // An example scenario where task could span across pages is Single Page Applications (SPA)
+            // A task that started on page #1, but completes on page #2
+            if (entry.id !== metadata.id()) { return; }
+            entry.resolve();
+            activeTask = null; // Reset active task back to null now that the promise is resolved
+            run();
+        }).catch((error: Error): void => {
+            // If one of the scheduled tasks failed, log, recover and continue processing rest of the tasks
+            if (entry.id !== metadata.id()) { return; }
+            if (error) { internal.log(Code.RunTask, Severity.Warning, error.name, error.message, error.stack); }
+            activeTask = null;
+            run();
+        });
+    }
+}
+
+export function state(timer: Timer): Task {
+    let id = key(timer);
+    if (id in tracker) {
+        let elapsed = performance.now() - tracker[id].start;
+        return (elapsed > tracker[id].yield) ? Task.Wait : Task.Run;
+    }
+    // If this task is no longer being tracked, send stop message to the caller
+    return Task.Stop;
+}
+
+export function start(timer: Timer): void {
+    tracker[key(timer)] = { start: performance.now(), calls: 0, yield: Setting.LongTask };
+}
+
+function restart(timer: Timer): void {
+    let id = key(timer);
+    if (tracker && tracker[id]) {
+        let c = tracker[id].calls;
+        let y = tracker[id].yield;
+        start(timer);
+        tracker[id].calls = c + 1;
+        tracker[id].yield = y;
+    }
+}
+
+export function stop(timer: Timer): void {
+    let end = performance.now();
+    let id = key(timer);
+    let duration = end - tracker[id].start;
+    metric.sum(timer.cost, duration);
+    metric.count(Metric.InvokeCount);
+
+    // For the first execution, which is synchronous, time is automatically counted towards TotalDuration.
+    // However, for subsequent asynchronous runs, we need to manually update TotalDuration metric.
+    if (tracker[id].calls > 0) { metric.sum(Metric.TotalCost, duration); }
+}
+
+export async function suspend(timer: Timer): Promise<Task> {
+    // Suspend and yield the thread only if the task is still being tracked
+    // It's possible that Clarity is wrapping up instrumentation on a page and we are still in the middle of an async task.
+    // In that case, we do not wish to continue yielding thread.
+    // Instead, we will turn async task into a sync task and maximize our chances of getting some data back.
+    let id = key(timer);
+    if (id in tracker) {
+        stop(timer);
+        // some customer polyfills for requestIdleCallback return null 
+        tracker[id].yield = (await wait())?.timeRemaining() || Setting.LongTask;
+        restart(timer);
+    }
+    // After we are done with suspending task, ensure that we are still operating in the right context
+    // If the task is still being tracked, continue running the task, otherwise ask caller to stop execution
+    return id in tracker ? Task.Run : Task.Stop;
+}
+
+function key(timer: Timer): string {
+    return `${timer.id}.${timer.cost}`;
+}
+
+async function wait(): Promise<RequestIdleCallbackDeadline> {
+    if (pauseTask) { await pauseTask; }
+    return new Promise<RequestIdleCallbackDeadline>((resolve: (deadline: RequestIdleCallbackDeadline) => void): void => {
+        requestIdleCallback(resolve, { timeout: idleTimeout });
+    });
+}
+
+// Use native implementation of requestIdleCallback if it exists.
+// Otherwise, fall back to a custom implementation using requestAnimationFrame & MessageChannel.
+// While it's not possible to build a perfect polyfill given the nature of this API, the following code attempts to get close.
+// Background context: requestAnimationFrame invokes the js code right before: style, layout and paint computation within the frame.
+// This means, that any code that runs as part of requestAnimationFrame will by default be blocking in nature. Not what we want.
+// For non-blocking behavior, We need to know when browser has finished painting. This can be accomplished in two different ways (hacks):
+//   (1) Use MessageChannel to pass the message, and browser will receive the message right after paint event has occured.
+//   (2) Use setTimeout call within requestAnimationFrame. This also works, but there's a risk that browser may throttle setTimeout calls.
+// Given this information, we are currently using (1) from above. More information on (2) as well as some additional context is below:
+// https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Performance_best_practices_for_Firefox_fe_engineers
+function requestIdleCallbackPolyfill(callback: (deadline: RequestIdleCallbackDeadline) => void, options: RequestIdleCallbackOptions): void {
+    const startTime = performance.now();
+    const channel = new MessageChannel();
+    const incoming = channel.port1;
+    const outgoing = channel.port2;
+    incoming.onmessage = (event: MessageEvent): void => {
+        let currentTime = performance.now();
+        let elapsed = currentTime - startTime;
+        let duration = currentTime - event.data;
+        if (duration > Setting.LongTask && elapsed < options.timeout) {
+            requestAnimationFrame((): void => { outgoing.postMessage(currentTime); });
+        } else {
+            let didTimeout = elapsed > options.timeout;
+            callback({
+                didTimeout,
+                timeRemaining: (): number => didTimeout ? Setting.LongTask : Math.max(0, Setting.LongTask - duration)
+            });
+        }
+    };
+    requestAnimationFrame((): void => { outgoing.postMessage(performance.now()); });
+}
+
+let requestIdleCallback = window["requestIdleCallback"] || requestIdleCallbackPolyfill;

package/src/core/throttle.ts

@@ -0,0 +1,46 @@
+/**
+ * Creates a throttled version of the provided function that only executes at most once
+ * every specified duration in milliseconds, ensuring the last event is not lost.
+ * @param func - The function to throttle.
+ * @param duration - The duration in milliseconds to wait before allowing the next execution.
+ * @returns A throttled version of the provided function with a cleanup method.
+ */
+export default function throttle<T extends (...args: any[]) => void>(func: T, duration: number): T & { cleanup: () => void } {
+  let lastExecutionTime = 0;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let lastArgs: Parameters<T> | null = null;
+
+  function throttledFunction(...args: Parameters<T>) {
+    const now = performance.now();
+    const timeSinceLastExecution = now - lastExecutionTime;
+
+    // If the function is called during the throttling period, store the arguments to ensure we don't drop the last event
+    if (lastExecutionTime !== 0 && timeSinceLastExecution < duration) {
+      lastArgs = args;
+
+      if (timeoutId) return;
+
+      timeoutId = setTimeout(() => {
+        lastExecutionTime = performance.now();
+        func.apply(this, lastArgs!);
+        lastArgs = null;
+        timeoutId = null;
+      }, duration - timeSinceLastExecution);
+    } else {
+      // Execute immediately if outside the throttling period (including the first run)
+      lastExecutionTime = now;
+      func.apply(this, args);
+    }
+  }
+
+  // Add cleanup method to clear pending timeouts
+  throttledFunction.cleanup = function () {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+      lastArgs = null;
+    }
+  };
+
+  return throttledFunction as T & { cleanup: () => void };
+}

package/src/core/time.ts

@@ -0,0 +1,26 @@
+let startTime = 0;
+
+function computeStartTime(): number {
+    return performance.now() + performance.timeOrigin;
+}
+
+export function start(): void {
+    startTime = computeStartTime();
+}
+
+// event.timestamp is number of milliseconds elapsed since the document was loaded
+// since iframes can be loaded later the event timestamp is not the same as performance.now()
+// converting everything to absolute time by adding timeorigin of the event view
+// to synchronize times before calculating the difference with start time
+export function time(event: UIEvent | PageTransitionEvent = null): number {
+    // If startTime is 0, Clarity hasn't been started or has been stopped
+    // Use a local baseline to maintain relative timing semantics without affecting global state
+    let baseline = startTime === 0 ? computeStartTime() : startTime;
+    let ts = event && event.timeStamp > 0 ? event.timeStamp : performance.now();
+    let origin = event && (event as UIEvent).view ? (event as UIEvent).view.performance.timeOrigin : performance.timeOrigin;
+    return Math.max(Math.round(ts + origin - baseline), 0);
+}
+
+export function stop(): void {
+    startTime = 0;
+}

package/src/core/timeout.ts

@@ -0,0 +1,10 @@
+import { Event } from "@clarity-types/data";
+import measure from "./measure";
+
+export function setTimeout(handler: (event?: Event | boolean) => void, timeout?: number, event?: Event): number {
+    return window.setTimeout(measure(handler), timeout, event);
+}
+
+export function clearTimeout(handle: number): void {
+    return window.clearTimeout(handle);
+}

package/src/core/version.ts

@@ -0,0 +1,2 @@
+let version = "0.8.39";
+export default version;