@tracelog/lib 0.0.1

package/dist/esm/handlers/performance.handler.js

@@ -0,0 +1,218 @@
+import { StateManager } from '../managers/state.manager';
+import { EventType } from '../types';
+import { LONG_TASK_THROTTLE_MS } from '../constants';
+import { PRECISION_FOUR_DECIMALS, PRECISION_TWO_DECIMALS } from '../constants';
+import { debugLog } from '../utils/logging';
+export class PerformanceHandler extends StateManager {
+    constructor(eventManager) {
+        super();
+        this.reportedByNav = new Map();
+        this.observers = [];
+        this.lastLongTaskSentAt = 0;
+        this.eventManager = eventManager;
+    }
+    async startTracking() {
+        debugLog.debug('PerformanceHandler', 'Starting performance tracking');
+        await this.initWebVitals();
+        this.observeLongTasks();
+        this.reportTTFB();
+    }
+    stopTracking() {
+        debugLog.debug('PerformanceHandler', 'Stopping performance tracking', { observersCount: this.observers.length });
+        this.observers.forEach((obs, index) => {
+            try {
+                obs.disconnect();
+            }
+            catch (error) {
+                debugLog.warn('PerformanceHandler', 'Failed to disconnect performance observer', {
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                    observerIndex: index,
+                });
+            }
+        });
+        this.observers.length = 0;
+        this.reportedByNav.clear();
+        debugLog.debug('PerformanceHandler', 'Performance tracking cleanup completed', {
+            remainingObservers: this.observers.length,
+            clearedNavReports: true,
+        });
+    }
+    observeWebVitalsFallback() {
+        // TTFB - should be captured immediately as it's available from navigation timing
+        this.reportTTFB();
+        // LCP
+        this.safeObserve('largest-contentful-paint', (list) => {
+            const entries = list.getEntries();
+            const last = entries[entries.length - 1];
+            if (!last) {
+                return;
+            }
+            this.sendVital({ type: 'LCP', value: Number(last.startTime.toFixed(PRECISION_TWO_DECIMALS)) });
+        }, { type: 'largest-contentful-paint', buffered: true }, true);
+        // CLS (layout-shift)
+        let clsValue = 0;
+        this.safeObserve('layout-shift', (list) => {
+            const entries = list.getEntries();
+            for (const entry of entries) {
+                if (entry.hadRecentInput === true) {
+                    continue;
+                }
+                const value = typeof entry.value === 'number' ? entry.value : 0;
+                clsValue += value;
+            }
+            this.sendVital({ type: 'CLS', value: Number(clsValue.toFixed(PRECISION_FOUR_DECIMALS)) });
+        }, { type: 'layout-shift', buffered: true });
+        // FCP
+        this.safeObserve('paint', (list) => {
+            for (const entry of list.getEntries()) {
+                if (entry.name === 'first-contentful-paint') {
+                    this.sendVital({ type: 'FCP', value: Number(entry.startTime.toFixed(PRECISION_TWO_DECIMALS)) });
+                }
+            }
+        }, { type: 'paint', buffered: true }, true);
+        // INP via performance event timing (where supported)
+        this.safeObserve('event', (list) => {
+            let worst = 0;
+            const entries = list.getEntries();
+            for (const entry of entries) {
+                const dur = (entry.processingEnd ?? 0) - (entry.startTime ?? 0);
+                worst = Math.max(worst, dur);
+            }
+            if (worst > 0) {
+                this.sendVital({ type: 'INP', value: Number(worst.toFixed(PRECISION_TWO_DECIMALS)) });
+            }
+        }, { type: 'event', buffered: true });
+    }
+    async initWebVitals() {
+        try {
+            const { onLCP, onCLS, onFCP, onTTFB, onINP } = await import('web-vitals');
+            const report = (type) => (metric) => {
+                const value = Number(metric.value.toFixed(PRECISION_TWO_DECIMALS));
+                this.sendVital({ type, value });
+            };
+            onLCP(report('LCP'));
+            onCLS(report('CLS'));
+            onFCP(report('FCP'));
+            onTTFB(report('TTFB'));
+            onINP(report('INP'));
+        }
+        catch (error) {
+            debugLog.warn('PerformanceHandler', 'Failed to load web-vitals library, using fallback', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            this.observeWebVitalsFallback();
+        }
+    }
+    reportTTFB() {
+        try {
+            const nav = performance.getEntriesByType('navigation')[0];
+            if (!nav) {
+                debugLog.debug('PerformanceHandler', 'Navigation timing not available for TTFB');
+                return;
+            }
+            const ttfb = nav.responseStart;
+            // TTFB can be 0 in some browsers (especially Mobile Safari) when:
+            // - Response is served from cache
+            // - Connection is reused
+            // - Browser cannot determine exact timing
+            // We still report it as it's a valid measurement
+            if (typeof ttfb === 'number' && Number.isFinite(ttfb)) {
+                this.sendVital({ type: 'TTFB', value: Number(ttfb.toFixed(PRECISION_TWO_DECIMALS)) });
+            }
+            else {
+                debugLog.debug('PerformanceHandler', 'TTFB value is not a valid number', { ttfb });
+            }
+        }
+        catch (error) {
+            debugLog.warn('PerformanceHandler', 'Failed to report TTFB', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+    observeLongTasks() {
+        this.safeObserve('longtask', (list) => {
+            const entries = list.getEntries();
+            for (const entry of entries) {
+                const duration = Number(entry.duration.toFixed(PRECISION_TWO_DECIMALS));
+                const now = Date.now();
+                if (now - this.lastLongTaskSentAt >= LONG_TASK_THROTTLE_MS) {
+                    this.trackWebVital('LONG_TASK', duration);
+                    this.lastLongTaskSentAt = now;
+                }
+            }
+        }, { type: 'longtask', buffered: true });
+    }
+    sendVital(sample) {
+        const navId = this.getNavigationId();
+        const key = `${sample.type}`;
+        if (navId) {
+            if (!this.reportedByNav.has(navId)) {
+                this.reportedByNav.set(navId, new Set());
+            }
+            const sent = this.reportedByNav.get(navId);
+            if (sent.has(key)) {
+                return;
+            }
+            sent.add(key);
+        }
+        this.trackWebVital(sample.type, sample.value);
+    }
+    trackWebVital(type, value) {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            debugLog.warn('PerformanceHandler', 'Invalid web vital value', { type, value });
+            return;
+        }
+        this.eventManager.track({
+            type: EventType.WEB_VITALS,
+            web_vitals: {
+                type,
+                value,
+            },
+        });
+    }
+    getNavigationId() {
+        try {
+            const nav = performance.getEntriesByType('navigation')[0];
+            if (!nav) {
+                return null;
+            }
+            return `${Math.round(nav.startTime)}_${window.location.pathname}`;
+        }
+        catch (error) {
+            debugLog.warn('PerformanceHandler', 'Failed to get navigation ID', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            return null;
+        }
+    }
+    safeObserve(type, cb, options, once = false) {
+        try {
+            if (typeof PerformanceObserver === 'undefined')
+                return;
+            const supported = PerformanceObserver.supportedEntryTypes;
+            if (supported && !supported.includes(type))
+                return;
+            const obs = new PerformanceObserver((list, observer) => {
+                cb(list, observer);
+                if (once) {
+                    try {
+                        observer.disconnect();
+                    }
+                    catch {
+                        // Intentionally ignored
+                    }
+                }
+            });
+            obs.observe((options ?? { type, buffered: true }));
+            if (!once) {
+                this.observers.push(obs);
+            }
+        }
+        catch (error) {
+            debugLog.warn('PerformanceHandler', 'Failed to create performance observer', {
+                type,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+}

package/dist/esm/handlers/scroll.handler.d.ts

@@ -0,0 +1,16 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+export declare class ScrollHandler extends StateManager {
+    private readonly eventManager;
+    private readonly containers;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private setupScrollContainer;
+    private calculateScrollData;
+    private getScrollTop;
+    private getViewportHeight;
+    private getScrollHeight;
+    private isElementScrollable;
+    private safeQuerySelector;
+}

package/dist/esm/handlers/scroll.handler.js

@@ -0,0 +1,134 @@
+import { SCROLL_DEBOUNCE_TIME_MS, SIGNIFICANT_SCROLL_DELTA } from '../constants';
+import { EventType, ScrollDirection } from '../types';
+import { StateManager } from '../managers/state.manager';
+import { debugLog } from '../utils/logging';
+export class ScrollHandler extends StateManager {
+    constructor(eventManager) {
+        super();
+        this.containers = [];
+        this.eventManager = eventManager;
+    }
+    startTracking() {
+        const raw = this.get('config').scrollContainerSelectors;
+        const selectors = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
+        debugLog.debug('ScrollHandler', 'Starting scroll tracking', { selectorsCount: selectors.length });
+        const elements = selectors
+            .map((sel) => this.safeQuerySelector(sel))
+            .filter((element) => element instanceof HTMLElement);
+        if (elements.length === 0) {
+            elements.push(window);
+        }
+        for (const element of elements) {
+            this.setupScrollContainer(element);
+        }
+    }
+    stopTracking() {
+        debugLog.debug('ScrollHandler', 'Stopping scroll tracking', { containersCount: this.containers.length });
+        for (const container of this.containers) {
+            if (container.debounceTimer) {
+                clearTimeout(container.debounceTimer);
+            }
+            if (container.element instanceof Window) {
+                window.removeEventListener('scroll', container.listener);
+            }
+            else {
+                container.element.removeEventListener('scroll', container.listener);
+            }
+        }
+        this.containers.length = 0;
+    }
+    setupScrollContainer(element) {
+        // Skip setup for non-scrollable elements
+        if (element !== window && !this.isElementScrollable(element)) {
+            return;
+        }
+        const container = {
+            element,
+            lastScrollPos: this.getScrollTop(element),
+            debounceTimer: null,
+            listener: () => { },
+        };
+        const handleScroll = () => {
+            if (this.get('suppressNextScroll')) {
+                this.set('suppressNextScroll', false);
+                return;
+            }
+            if (container.debounceTimer) {
+                clearTimeout(container.debounceTimer);
+            }
+            container.debounceTimer = window.setTimeout(() => {
+                const scrollData = this.calculateScrollData(container);
+                if (scrollData) {
+                    this.eventManager.track({
+                        type: EventType.SCROLL,
+                        scroll_data: scrollData,
+                    });
+                }
+                container.debounceTimer = null;
+            }, SCROLL_DEBOUNCE_TIME_MS);
+        };
+        container.listener = handleScroll;
+        this.containers.push(container);
+        if (element instanceof Window) {
+            window.addEventListener('scroll', handleScroll, { passive: true });
+        }
+        else {
+            element.addEventListener('scroll', handleScroll, { passive: true });
+        }
+    }
+    calculateScrollData(container) {
+        const { element, lastScrollPos } = container;
+        const scrollTop = this.getScrollTop(element);
+        const viewportHeight = this.getViewportHeight(element);
+        const scrollHeight = this.getScrollHeight(element);
+        // Check if the page is actually scrollable at runtime
+        if (element === window && scrollHeight <= viewportHeight) {
+            return null;
+        }
+        const direction = scrollTop > lastScrollPos ? ScrollDirection.DOWN : ScrollDirection.UP;
+        const depth = scrollHeight > viewportHeight
+            ? Math.min(100, Math.max(0, Math.floor((scrollTop / (scrollHeight - viewportHeight)) * 100)))
+            : 0;
+        // Only update if scroll position changed significantly
+        const positionDelta = Math.abs(scrollTop - lastScrollPos);
+        if (positionDelta < SIGNIFICANT_SCROLL_DELTA) {
+            return null;
+        }
+        container.lastScrollPos = scrollTop;
+        return { depth, direction };
+    }
+    getScrollTop(element) {
+        return element instanceof Window ? window.scrollY : element.scrollTop;
+    }
+    getViewportHeight(element) {
+        return element instanceof Window ? window.innerHeight : element.clientHeight;
+    }
+    getScrollHeight(element) {
+        return element instanceof Window ? document.documentElement.scrollHeight : element.scrollHeight;
+    }
+    isElementScrollable(element) {
+        const style = getComputedStyle(element);
+        const hasScrollableOverflow = style.overflowY === 'auto' ||
+            style.overflowY === 'scroll' ||
+            style.overflowX === 'auto' ||
+            style.overflowX === 'scroll' ||
+            style.overflow === 'auto' ||
+            style.overflow === 'scroll';
+        // Element must have scrollable overflow AND content that exceeds the container
+        const hasOverflowContent = element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth;
+        return hasScrollableOverflow && hasOverflowContent;
+    }
+    safeQuerySelector(selector) {
+        try {
+            return document.querySelector(selector);
+        }
+        catch (error) {
+            // Invalid CSS selector - log warning and continue
+            debugLog.clientWarn('ScrollHandler', 'Invalid CSS selector', {
+                selector,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            return null;
+        }
+    }
+}

package/dist/esm/handlers/session.handler.d.ts

@@ -0,0 +1,29 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+import { StorageManager } from '../managers/storage.manager';
+export declare class SessionHandler extends StateManager {
+    private readonly eventManager;
+    private readonly storageManager;
+    private readonly sessionStorageKey;
+    private sessionManager;
+    private recoveryManager;
+    private _crossTabSessionManager;
+    private heartbeatInterval;
+    private _isInitializingCrossTab;
+    private get crossTabSessionManager();
+    private shouldUseCrossTabs;
+    constructor(storageManager: StorageManager, eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private initializeSessionRecoveryManager;
+    private initializeCrossTabSessionManager;
+    private createOrJoinSession;
+    private forceCleanupSession;
+    private trackSession;
+    private startInitialSession;
+    private checkOrphanedSessions;
+    private persistSession;
+    private clearPersistedSession;
+    private startHeartbeat;
+    private stopHeartbeat;
+}