clarity-js 0.6.23

package/src/core/task.ts

@@ -0,0 +1,180 @@
+import { AsyncTask, Priority, RequestIdleCallbackDeadline, RequestIdleCallbackOptions, Task, Timer } from "@clarity-types/core";
+import { Setting, TaskFunction, TaskResolve, Tasks } from "@clarity-types/core";
+import { Code, Metric, 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);
+        tracker[id].yield = (await wait()).timeRemaining();
+        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 painiting. This can be accomplished in two different ways (hacks):
+//   (1) Use MessageChannel to pass the message, and browser will receive the message right after pain 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/time.ts

@@ -0,0 +1,14 @@
+let startTime = 0;
+
+export function start(): void {
+    startTime = performance.now();
+}
+
+export function time(ts: number = null): number {
+    ts = ts ? ts : performance.now();
+    return Math.max(Math.round(ts - startTime), 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.6.23";
+export default version;

package/src/data/baseline.ts

@@ -0,0 +1,89 @@
+import { Event, BooleanFlag } from "@clarity-types/data";
+import { BaselineData, BaselineState } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import encode from "@src/data/encode";
+
+export let state: BaselineState = null;
+let buffer: BaselineData = null;
+let update: boolean = false;
+
+export function start(): void {
+    update = false;
+    reset();
+}
+
+export function reset(): void {
+    // Baseline state holds the previous values - if it is updated in the current payload,
+    // reset the state to current value after sending the previous state
+    if (update) {
+        state = { time: time(), event: Event.Baseline, data: {
+            visible: buffer.visible,
+            docWidth: buffer.docWidth,
+            docHeight: buffer.docHeight,
+            screenWidth: buffer.screenWidth,
+            screenHeight: buffer.screenHeight,
+            scrollX: buffer.scrollX,
+            scrollY: buffer.scrollY,
+            pointerX: buffer.pointerX,
+            pointerY: buffer.pointerY,
+            activityTime: buffer.activityTime
+          }
+        };
+    }
+    buffer = buffer ? buffer : {
+        visible: BooleanFlag.True,
+        docWidth: 0,
+        docHeight: 0,
+        screenWidth: 0,
+        screenHeight: 0,
+        scrollX: 0,
+        scrollY: 0,
+        pointerX: 0,
+        pointerY: 0,
+        activityTime: 0
+    };
+}
+
+export function track(event: Event, x: number, y: number): void {
+    switch (event) {
+        case Event.Document:
+            buffer.docWidth = x;
+            buffer.docHeight = y;
+            break;
+        case Event.Resize:
+            buffer.screenWidth = x;
+            buffer.screenHeight = y;
+            break;
+        case Event.Scroll:
+            buffer.scrollX = x;
+            buffer.scrollY = y;
+            break;
+        default:
+            buffer.pointerX = x;
+            buffer.pointerY = y;
+            break;
+    }
+    update = true;
+}
+
+export function activity(t: number): void {
+    buffer.activityTime = t;
+}
+
+export function visibility(t: number, visible: string): void {
+    buffer.visible = visible === "visible" ? BooleanFlag.True : BooleanFlag.False;
+    if (!buffer.visible) {
+        activity(t);
+    }
+    update = true;
+}
+
+export function compute(): void {
+    if (update) {
+        encode(Event.Baseline);
+    }
+}
+
+export function stop(): void {
+    reset();
+}

package/src/data/compress.ts

@@ -0,0 +1,31 @@
+import { Constant } from "@clarity-types/data";
+
+const supported = Constant.CompressionStream in window;
+
+export default async function(input: string): Promise<Uint8Array> {
+    try {
+        if (supported) {
+            // Create a readable stream from given input string and
+            // pipe it through text encoder and compression stream to gzip it
+            const stream = new ReadableStream({async start(controller) {
+                controller.enqueue(input);
+                controller.close();
+            }}).pipeThrough(new TextEncoderStream()).pipeThrough(new window[Constant.CompressionStream]("gzip"));
+            return new Uint8Array(await read(stream));
+        }
+    } catch { /* do nothing */ }
+    return null;
+}
+
+async function read(stream: ReadableStream): Promise<number[]> {
+    const reader = stream.getReader();
+    const chunks:number[] = [];
+    let done = false;
+    let value: number[] = [];
+    while (!done) {
+      ({ done, value } = await reader.read());
+      if (done) { return chunks; }
+      chunks.push(...value);
+    }
+    return chunks;
+}

package/src/data/custom.ts

@@ -0,0 +1,18 @@
+import { Constant, CustomData, Event } from "@clarity-types/data";
+import * as core from "@src/core";
+import encode from "./encode";
+
+export let data: CustomData = null;
+
+export function event(key: string, value: string): void {
+    if (core.active() &&
+        key &&
+        value &&
+        typeof key === Constant.String &&
+        typeof value === Constant.String &&
+        key.length < 255 &&
+        value.length < 255) {
+        data = { key, value};
+        encode(Event.Custom);
+    }
+}

package/src/data/dimension.ts

@@ -0,0 +1,42 @@
+import { Check, Event, Dimension, DimensionData, Setting } from "@clarity-types/data";
+import * as limit from "@src/data/limit";
+import encode from "./encode";
+
+export let data: DimensionData = null;
+export let updates: DimensionData = null;
+
+export function start(): void {
+    data = {};
+    updates = {};
+}
+
+export function stop(): void {
+    data = {};
+    updates = {};
+}
+
+export function log(dimension: Dimension, value: string): void {
+    // Check valid value before moving ahead
+    if (value) {
+        // Ensure received value is casted into a string if it wasn't a string to begin with
+        value = `${value}`;
+        if (!(dimension in data)) { data[dimension] = []; }
+        if (data[dimension].indexOf(value) < 0) {
+            data[dimension].push(value);
+            // If this is a new value, track it as part of updates object
+            // This allows us to only send back new values in subsequent payloads
+            if (!(dimension in updates)) { updates[dimension] = []; }
+            updates[dimension].push(value);
+            // Limit check to ensure we have a cap on number of dimensions we can collect
+            if (data[dimension].length > Setting.CollectionLimit) { limit.trigger(Check.Collection); }
+        }
+    }
+}
+
+export function compute(): void {
+    encode(Event.Dimension);
+}
+
+export function reset(): void {
+    updates = {};
+}

package/src/data/encode.ts

@@ -0,0 +1,109 @@
+import { Event, Token } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import * as baseline from "@src/data/baseline";
+import * as custom from "@src/data/custom";
+import * as dimension from "@src/data/dimension";
+import * as limit from "@src/data/limit";
+import * as metric from "@src/data/metric";
+import * as ping from "@src/data/ping";
+import * as summary from "@src/data/summary";
+import * as upgrade from "@src/data/upgrade";
+import * as variable from "@src/data/variable";
+import { queue, track } from "./upload";
+
+export default function(event: Event): void {
+    let t = time();
+    let tokens: Token[] = [t, event];
+    switch (event) {
+        case Event.Baseline:
+            let b = baseline.state;
+            if (b) {
+                tokens = [b.time, b.event];
+                tokens.push(b.data.visible);
+                tokens.push(b.data.docWidth);
+                tokens.push(b.data.docHeight);
+                tokens.push(b.data.screenWidth);
+                tokens.push(b.data.screenHeight);
+                tokens.push(b.data.scrollX);
+                tokens.push(b.data.scrollY);
+                tokens.push(b.data.pointerX);
+                tokens.push(b.data.pointerY);
+                tokens.push(b.data.activityTime);
+                queue(tokens, false);
+            }
+            baseline.reset();
+            break;
+        case Event.Ping:
+            tokens.push(ping.data.gap);
+            queue(tokens);
+            break;
+        case Event.Limit:
+            tokens.push(limit.data.check);
+            queue(tokens, false);
+            break;
+        case Event.Upgrade:
+            tokens.push(upgrade.data.key);
+            queue(tokens);
+            break;
+        case Event.Upload:
+            tokens.push(track.sequence);
+            tokens.push(track.attempts);
+            tokens.push(track.status);
+            queue(tokens, false);
+            break;
+        case Event.Custom:
+            tokens.push(custom.data.key);
+            tokens.push(custom.data.value);
+            queue(tokens);
+            break;
+        case Event.Variable:
+            let variableKeys = Object.keys(variable.data);
+            if (variableKeys.length > 0) {
+                for (let v of variableKeys) {
+                    tokens.push(v);
+                    tokens.push(variable.data[v]);
+                }
+                variable.reset();
+                queue(tokens, false);
+            }
+            break;
+        case Event.Metric:
+            let metricKeys = Object.keys(metric.updates);
+            if (metricKeys.length > 0) {
+                for (let m of metricKeys) {
+                    let key = parseInt(m, 10);
+                    tokens.push(key);
+                    // For computation, we need microseconds precision that performance.now() API offers
+                    // However, for data over the wire, we round it off to milliseconds precision.
+                    tokens.push(Math.round(metric.updates[m]));
+                }
+                metric.reset();
+                queue(tokens, false);
+            }
+            break;
+        case Event.Dimension:
+            let dimensionKeys = Object.keys(dimension.updates);
+            if (dimensionKeys.length > 0) {
+                for (let d of dimensionKeys) {
+                    let key = parseInt(d, 10);
+                    tokens.push(key);
+                    tokens.push(dimension.updates[d]);
+                }
+                dimension.reset();
+                queue(tokens, false);
+            }
+            break;
+        case Event.Summary:
+            let eventKeys = Object.keys(summary.data);
+            if (eventKeys.length > 0) {
+                for (let e of eventKeys) {
+                    let key = parseInt(e, 10);
+                    tokens.push(key);
+                    tokens.push([].concat(...summary.data[e]));
+                }
+                summary.reset();
+                queue(tokens, false);
+            }
+            break;
+    }
+}

package/src/data/envelope.ts

@@ -0,0 +1,46 @@
+import { BooleanFlag, Token, Upload, Envelope } from "@clarity-types/data";
+import { time } from "@src/core/time";
+import version from "@src/core/version";
+import * as metadata from "@src/data/metadata";
+
+export let data: Envelope = null;
+
+export function start(): void {
+  const m = metadata.data;
+  data = {
+    version,
+    sequence: 0,
+    start: 0,
+    duration: 0,
+    projectId: m.projectId,
+    userId: m.userId,
+    sessionId: m.sessionId,
+    pageNum: m.pageNum,
+    upload: Upload.Async,
+    end: BooleanFlag.False
+  };
+}
+
+export function stop(): void {
+    data = null;
+}
+
+export function envelope(last: boolean): Token[] {
+  data.start = data.start + data.duration;
+  data.duration = time() - data.start;
+  data.sequence++;
+  data.upload = last && "sendBeacon" in navigator ? Upload.Beacon : Upload.Async;
+  data.end = last ? BooleanFlag.True : BooleanFlag.False;
+  return [
+    data.version,
+    data.sequence,
+    data.start,
+    data.duration,
+    data.projectId,
+    data.userId,
+    data.sessionId,
+    data.pageNum,
+    data.upload,
+    data.end
+  ];
+}

package/src/data/index.ts

@@ -0,0 +1,43 @@
+import measure from "@src/core/measure";
+import * as baseline from "@src/data/baseline";
+import * as envelope from "@src/data/envelope";
+import * as dimension from "@src/data/dimension";
+import * as metadata from "@src/data/metadata";
+import { Module } from "@clarity-types/core";
+import * as metric from "@src/data/metric";
+import * as ping from "@src/data/ping";
+import * as limit from "@src/data/limit";
+import * as summary from "@src/data/summary";
+import * as upgrade from "@src/data/upgrade";
+import * as upload from "@src/data/upload";
+import * as variable from "@src/data/variable";
+export { event } from "@src/data/custom";
+export { consent, metadata } from "@src/data/metadata";
+export { upgrade } from "@src/data/upgrade";
+export { set, identify } from "@src/data/variable";
+
+const modules: Module[] = [baseline, dimension, variable, limit, summary, metadata, envelope, upload, ping, upgrade];
+
+export function start(): void {
+    // Metric needs to be initialized before we can start measuring. so metric is not wrapped in measure
+    metric.start();
+    modules.forEach(x => measure(x.start)());
+}
+
+export function stop(): void {
+    // Stop modules in the reverse order of their initialization
+    // The ordering below should respect inter-module dependency.
+    // E.g. if upgrade depends on upload, then upgrade needs to end before upload.
+    // Similarly, if upload depends on metadata, upload needs to end before metadata.
+    modules.slice().reverse().forEach(x => measure(x.stop)());
+    metric.stop();
+}
+
+export function compute(): void {
+    variable.compute();
+    baseline.compute();
+    dimension.compute();
+    metric.compute();
+    summary.compute();
+    limit.compute();
+}

package/src/data/limit.ts

@@ -0,0 +1,42 @@
+import { Check, Event, LimitData, Setting } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+import { report } from "@src/core/report";
+import { time } from "@src/core/time";
+import * as envelope from "@src/data/envelope";
+import * as metadata from "@src/data/metadata";
+import encode from "./encode";
+
+export let data: LimitData;
+
+export function start(): void {
+    data = { check: Check.None };
+}
+
+export function check(bytes: number): void {
+    if (data.check === Check.None) {
+        let reason = data.check;
+        reason = envelope.data.sequence >= Setting.PayloadLimit ? Check.Payload : reason;
+        reason = time() > Setting.ShutdownLimit ? Check.Shutdown : reason;
+        reason = bytes > Setting.PlaybackBytesLimit ? Check.Shutdown : reason;
+        if (reason !== data.check) {
+            trigger(reason);
+        }
+    }
+}
+
+export function trigger(reason: Check): void {
+    report(reason);
+    data.check = reason;
+    metadata.clear();
+    clarity.stop();
+}
+
+export function compute(): void {
+    if (data.check !== Check.None) {
+        encode(Event.Limit);
+    }
+}
+
+export function stop(): void {
+    data = null;
+}