refactor: streamline Long Tasks and LoAF handling by removing unused interfaces and improving script serialization

Author: Dobrunia

packages/javascript/src/addons/longTasks.ts

@@ -8,8 +8,9 @@
  * Sets up observers and fires `onEntry` per detected entry — fire and forget.
  */
 
-import type { EventContext, Json, JsonNode } from '@hawk.so/types';
-import log from '../utils/log';
+import type { EventContext, Json } from '@hawk.so/types';
+import type { LoAFEntry, LoAFScript, LongTaskPerformanceEntry } from '../types/long-tasks';
+import { compactJson } from '../utils/compactJson';
 
 /**
  * Configuration for main-thread blocking detection
@@ -49,69 +50,6 @@ export interface LongTaskEvent {
   context: EventContext;
 }
 
-/**
- * Long Task attribution (container-level info only)
- */
-interface LongTaskAttribution {
-  name: string;
-  entryType: string;
-  containerType?: string;
-  containerSrc?: string;
-  containerId?: string;
-  containerName?: string;
-}
-
-/**
- * Long Task entry with attribution
- */
-interface LongTaskPerformanceEntry extends PerformanceEntry {
-  attribution?: LongTaskAttribution[];
-}
-
-/**
- * LoAF script timing (PerformanceScriptTiming)
- */
-interface LoAFScript {
-  name: string;
-  invoker?: string;
-  invokerType?: string;
-  sourceURL?: string;
-  sourceFunctionName?: string;
-  sourceCharPosition?: number;
-  duration: number;
-  startTime: number;
-  executionStart?: number;
-  forcedStyleAndLayoutDuration?: number;
-  pauseDuration?: number;
-  windowAttribution?: string;
-}
-
-/**
- * LoAF entry shape (spec is still evolving)
- */
-interface LoAFEntry extends PerformanceEntry {
-  blockingDuration?: number;
-  renderStart?: number;
-  styleAndLayoutStart?: number;
-  firstUIEventTimestamp?: number;
-  scripts?: LoAFScript[];
-}
-
-/**
- * Build a Json object from entries, dropping null / undefined / empty-string values
- */
-function compact(entries: [string, JsonNode | null | undefined][]): Json {
-  const result: Json = {};
-
-  for (const [key, value] of entries) {
-    if (value != null && value !== '') {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
 /**
  * Check whether the browser supports a given PerformanceObserver entry type
  *
@@ -133,7 +71,7 @@ function supportsEntryType(type: string): boolean {
  * Serialize a LoAF script entry into a Json-compatible object
  */
 function serializeScript(s: LoAFScript): Json {
-  return compact([
+  return compactJson([
     ['invoker', s.invoker],
     ['invokerType', s.invokerType],
     ['sourceURL', s.sourceURL],
@@ -147,15 +85,21 @@ function serializeScript(s: LoAFScript): Json {
   ]);
 }
 
+/**
+ * Return LoAF scripts that contain useful source attribution for debugging.
+ * We keep only scripts that have at least function name or source URL.
+ */
+function getRelevantLoAFScripts(loaf: LoAFEntry): LoAFScript[] {
+  return loaf.scripts?.filter((s) => s.sourceURL || s.sourceFunctionName) ?? [];
+}
+
 /**
  * Subscribe to Long Tasks (>50 ms) via PerformanceObserver
  *
  * @param onEntry - callback fired for each detected long task
  */
 function observeLongTasks(onEntry: (e: LongTaskEvent) => void): void {
   if (!supportsEntryType('longtask')) {
-    log('Long Tasks API is not supported in this browser', 'info');
-
     return;
   }
 
@@ -166,7 +110,7 @@ function observeLongTasks(onEntry: (e: LongTaskEvent) => void): void {
         const durationMs = Math.round(task.duration);
         const attr = task.attribution?.[0];
 
-        const details = compact([
+        const details = compactJson([
           ['kind', 'longtask'],
           ['entryName', task.name],
           ['startTime', Math.round(task.startTime)],
@@ -194,8 +138,6 @@ function observeLongTasks(onEntry: (e: LongTaskEvent) => void): void {
  */
 function observeLoAF(onEntry: (e: LongTaskEvent) => void): void {
   if (!supportsEntryType('long-animation-frame')) {
-    log('Long Animation Frames (LoAF) API is not supported in this browser', 'info');
-
     return;
   }
 
@@ -204,21 +146,21 @@ function observeLoAF(onEntry: (e: LongTaskEvent) => void): void {
       for (const entry of list.getEntries()) {
         const loaf = entry as LoAFEntry;
         const durationMs = Math.round(loaf.duration);
-        const blockingDurationMs = loaf.blockingDuration !== null
+        const blockingDurationMs = loaf.blockingDuration !== undefined && loaf.blockingDuration !== null
           ? Math.round(loaf.blockingDuration)
           : null;
 
-        const relevantScripts = loaf.scripts?.filter((s) => s.sourceURL || s.sourceFunctionName);
+        const relevantScripts = getRelevantLoAFScripts(loaf);
 
-        const scripts = relevantScripts?.length
+        const scripts = relevantScripts.length
           ? relevantScripts.reduce<Json>((acc, s, i) => {
             acc[`script_${i}`] = serializeScript(s);
 
             return acc;
           }, {})
           : null;
 
-        const details = compact([
+        const details = compactJson([
           ['kind', 'loaf'],
           ['startTime', Math.round(loaf.startTime)],
           ['durationMs', durationMs],
@@ -233,7 +175,7 @@ function observeLoAF(onEntry: (e: LongTaskEvent) => void): void {
           ? ` (blocking ${blockingDurationMs} ms)`
           : '';
 
-        const topScript = relevantScripts?.[0];
+        const topScript = relevantScripts[0];
         const culprit = topScript?.sourceFunctionName
           || topScript?.invoker
           || topScript?.sourceURL

packages/javascript/src/types/hawk-initial-settings.ts

@@ -105,6 +105,9 @@ export interface HawkInitialSettings {
    * Observes Long Tasks and Long Animation Frames (LoAF) via PerformanceObserver
    * and sends a dedicated event when blocking is detected.
    *
+   * This is an umbrella option by design: Long Tasks and LoAF describe the same
+   * domain (main-thread blocking), so both toggles live under one config key.
+   *
    * Chromium-only (Chrome, Edge). On unsupported browsers the observers
    * simply won't start — no errors, no overhead.
    *

packages/javascript/src/types/long-tasks.ts

@@ -0,0 +1,72 @@
+/**
+ * Long Task attribution information from Performance API.
+ * Describes the container associated with the long task.
+ */
+export interface LongTaskAttribution {
+  /** Attribution source name (`self`, `same-origin-ancestor`, etc.) */
+  name: string;
+  /** Entry type name from the attribution object */
+  entryType: string;
+  /** Container type (`iframe`, `embed`, `object`) */
+  containerType?: string;
+  /** Source URL of the container */
+  containerSrc?: string;
+  /** DOM id of the container element */
+  containerId?: string;
+  /** DOM name of the container element */
+  containerName?: string;
+}
+
+/**
+ * Long Task entry with attribution details.
+ */
+export interface LongTaskPerformanceEntry extends PerformanceEntry {
+  /** Attribution list for the long task */
+  attribution?: LongTaskAttribution[];
+}
+
+/**
+ * LoAF script timing information (PerformanceScriptTiming).
+ */
+export interface LoAFScript {
+  /** Script display name */
+  name: string;
+  /** Script invoker (e.g. `TimerHandler:setTimeout`) */
+  invoker?: string;
+  /** Invoker type (`event-listener`, `user-callback`, etc.) */
+  invokerType?: string;
+  /** Source URL of the script */
+  sourceURL?: string;
+  /** Function name associated with the script execution */
+  sourceFunctionName?: string;
+  /** Character position in source */
+  sourceCharPosition?: number;
+  /** Script duration in milliseconds */
+  duration: number;
+  /** Start time in milliseconds from navigation start */
+  startTime: number;
+  /** Execution start timestamp */
+  executionStart?: number;
+  /** Forced style/layout duration in milliseconds */
+  forcedStyleAndLayoutDuration?: number;
+  /** Paused time in milliseconds */
+  pauseDuration?: number;
+  /** Window attribution (`self`, `ancestor`, `descendant`) */
+  windowAttribution?: string;
+}
+
+/**
+ * Long Animation Frame entry shape.
+ */
+export interface LoAFEntry extends PerformanceEntry {
+  /** Blocking duration in milliseconds */
+  blockingDuration?: number;
+  /** Render start timestamp */
+  renderStart?: number;
+  /** Style/layout start timestamp */
+  styleAndLayoutStart?: number;
+  /** First UI event timestamp */
+  firstUIEventTimestamp?: number;
+  /** Script timing records for the frame */
+  scripts?: LoAFScript[];
+}

packages/javascript/src/utils/compactJson.ts

@@ -0,0 +1,19 @@
+import type { Json, JsonNode } from '@hawk.so/types';
+
+/**
+ * Build a JSON object from key-value pairs.
+ * Drops `null`, `undefined`, and empty strings.
+ *
+ * Useful for compact event payload construction without repetitive `if` chains.
+ */
+export function compactJson(entries: [string, JsonNode | null | undefined][]): Json {
+  const result: Json = {};
+
+  for (const [key, value] of entries) {
+    if (value != null && value !== '') {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

packages/javascript/tests/compact-json.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { compactJson } from '../src/utils/compactJson';
+
+describe('compactJson', () => {
+  it('should keep non-empty primitive values', () => {
+    const result = compactJson([
+      ['name', 'hawk'],
+      ['count', 0],
+      ['enabled', false],
+    ]);
+
+    expect(result).toEqual({
+      name: 'hawk',
+      count: 0,
+      enabled: false,
+    });
+  });
+
+  it('should drop null, undefined and empty string values', () => {
+    const result = compactJson([
+      ['a', null],
+      ['b', undefined],
+      ['c', ''],
+      ['d', 'ok'],
+    ]);
+
+    expect(result).toEqual({
+      d: 'ok',
+    });
+  });
+
+  it('should keep nested json objects', () => {
+    const result = compactJson([
+      ['meta', { source: 'test' }],
+      ['duration', 123],
+    ]);
+
+    expect(result).toEqual({
+      meta: { source: 'test' },
+      duration: 123,
+    });
+  });
+});