@tracelog/lib 0.1.0 → 0.2.1

package/dist/cjs/managers/state.manager.d.ts

@@ -1,5 +1,38 @@
 import { State } from '../types';
+/**
+ * Resets the global state to its initial empty state.
+ * Used primarily for testing and cleanup scenarios.
+ */
+export declare function resetGlobalState(): void;
+/**
+ * Abstract base class providing state management capabilities to TraceLog components.
+ *
+ * All managers and handlers extend this class to access and modify the shared global state.
+ * State operations are synchronous and thread-safe within the single-threaded browser environment.
+ */
 export declare abstract class StateManager {
+    /**
+     * Gets a value from the global state
+     */
     protected get<T extends keyof State>(key: T): State[T];
+    /**
+     * Sets a value in the global state
+     */
     protected set<T extends keyof State>(key: T, value: State[T]): void;
+    /**
+     * Gets the entire state object (for debugging purposes)
+     */
+    protected getState(): Readonly<State>;
+    /**
+     * Checks if a state key is considered critical for logging
+     */
+    private isCriticalStateKey;
+    /**
+     * Determines if a state change should be logged
+     */
+    private shouldLog;
+    /**
+     * Formats values for logging (avoiding large object dumps)
+     */
+    private formatLogValue;
 }

package/dist/cjs/managers/state.manager.js

@@ -1,23 +1,96 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StateManager = void 0;
+exports.resetGlobalState = resetGlobalState;
 const logging_1 = require("../utils/logging");
+const constants_1 = require("../constants");
+/**
+ * Global state store shared across all TraceLog components
+ */
 const globalState = {};
+/**
+ * Resets the global state to its initial empty state.
+ * Used primarily for testing and cleanup scenarios.
+ */
+function resetGlobalState() {
+    Object.keys(globalState).forEach((key) => {
+        delete globalState[key];
+    });
+}
+/**
+ * Abstract base class providing state management capabilities to TraceLog components.
+ *
+ * All managers and handlers extend this class to access and modify the shared global state.
+ * State operations are synchronous and thread-safe within the single-threaded browser environment.
+ */
 class StateManager {
+    /**
+     * Gets a value from the global state
+     */
     get(key) {
         return globalState[key];
     }
+    /**
+     * Sets a value in the global state
+     */
     set(key, value) {
         const oldValue = globalState[key];
-        globalState[key] = value;
-        // Log critical state changes
-        if (key === 'sessionId' || key === 'config' || key === 'hasStartSession') {
-            logging_1.debugLog.debug('StateManager', 'Critical state updated', {
+        if (key === 'config' && value) {
+            const configValue = value;
+            if (configValue) {
+                const samplingRate = configValue.samplingRate ?? constants_1.DEFAULT_SAMPLING_RATE;
+                const normalizedSamplingRate = samplingRate > 0 ? samplingRate : constants_1.DEFAULT_SAMPLING_RATE;
+                const hasNormalizedSampling = normalizedSamplingRate !== samplingRate;
+                if (hasNormalizedSampling) {
+                    const normalizedConfig = { ...configValue, samplingRate: normalizedSamplingRate };
+                    globalState[key] = normalizedConfig;
+                }
+                else {
+                    globalState[key] = configValue;
+                }
+            }
+            else {
+                globalState[key] = value;
+            }
+        }
+        else {
+            globalState[key] = value;
+        }
+        // Log critical state changes for debugging
+        if (this.isCriticalStateKey(key) && this.shouldLog(oldValue, globalState[key])) {
+            logging_1.debugLog.debug('StateManager', 'State updated', {
                 key,
-                oldValue: key === 'config' ? !!oldValue : oldValue,
-                newValue: key === 'config' ? !!value : value,
+                oldValue: this.formatLogValue(key, oldValue),
+                newValue: this.formatLogValue(key, globalState[key]),
             });
         }
     }
+    /**
+     * Gets the entire state object (for debugging purposes)
+     */
+    getState() {
+        return { ...globalState };
+    }
+    /**
+     * Checks if a state key is considered critical for logging
+     */
+    isCriticalStateKey(key) {
+        return key === 'sessionId' || key === 'config' || key === 'hasStartSession';
+    }
+    /**
+     * Determines if a state change should be logged
+     */
+    shouldLog(oldValue, newValue) {
+        return oldValue !== newValue;
+    }
+    /**
+     * Formats values for logging (avoiding large object dumps)
+     */
+    formatLogValue(key, value) {
+        if (key === 'config') {
+            return value ? '(configured)' : '(not configured)';
+        }
+        return value;
+    }
 }
 exports.StateManager = StateManager;

package/dist/cjs/managers/storage.manager.d.ts

@@ -1,10 +1,34 @@
+/**
+ * Manages localStorage with automatic fallback to in-memory storage.
+ * Provides a consistent interface for storing session data, configuration,
+ * and analytics metadata across browser environments.
+ */
 export declare class StorageManager {
     private readonly storage;
     private readonly fallbackStorage;
-    private storageAvailable;
     constructor();
+    /**
+     * Retrieves an item from storage
+     */
     getItem(key: string): string | null;
+    /**
+     * Stores an item in storage
+     */
     setItem(key: string, value: string): void;
+    /**
+     * Removes an item from storage
+     */
     removeItem(key: string): void;
-    private init;
+    /**
+     * Clears all TracLog-related items from storage
+     */
+    clear(): void;
+    /**
+     * Checks if storage is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize localStorage with feature detection
+     */
+    private initializeStorage;
 }

package/dist/cjs/managers/storage.manager.js

@@ -1,22 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageManager = void 0;
-const logging_1 = require("../utils/logging");
+const debug_logger_utils_1 = require("../utils/logging/debug-logger.utils");
+/**
+ * Manages localStorage with automatic fallback to in-memory storage.
+ * Provides a consistent interface for storing session data, configuration,
+ * and analytics metadata across browser environments.
+ */
 class StorageManager {
     constructor() {
-        this.storage = null;
         this.fallbackStorage = new Map();
-        this.storageAvailable = false;
-        this.storage = this.init();
-        this.storageAvailable = this.storage !== null;
-        if (!this.storageAvailable) {
-            logging_1.debugLog.warn('StorageManager', 'localStorage not available, using memory fallback');
+        this.storage = this.initializeStorage();
+        if (!this.storage) {
+            debug_logger_utils_1.debugLog.warn('StorageManager', 'localStorage not available, using memory fallback');
         }
     }
+    /**
+     * Retrieves an item from storage
+     */
     getItem(key) {
-        if (!this.storageAvailable) {
-            return this.fallbackStorage.get(key) ?? null;
-        }
         try {
             if (this.storage) {
                 return this.storage.getItem(key);
@@ -24,53 +26,84 @@ class StorageManager {
             return this.fallbackStorage.get(key) ?? null;
         }
         catch (error) {
-            logging_1.debugLog.warn('StorageManager', 'Storage getItem failed, using memory fallback', { key, error });
-            this.storageAvailable = false;
+            debug_logger_utils_1.debugLog.warn('StorageManager', 'Failed to get item, using fallback', { key, error });
             return this.fallbackStorage.get(key) ?? null;
         }
     }
+    /**
+     * Stores an item in storage
+     */
     setItem(key, value) {
-        if (!this.storageAvailable) {
-            this.fallbackStorage.set(key, value);
-            return;
-        }
         try {
             if (this.storage) {
                 this.storage.setItem(key, value);
                 return;
             }
-            this.fallbackStorage.set(key, value);
         }
         catch (error) {
-            logging_1.debugLog.warn('StorageManager', 'Storage setItem failed, using memory fallback', { key, error });
-            this.storageAvailable = false;
-            this.fallbackStorage.set(key, value);
+            debug_logger_utils_1.debugLog.warn('StorageManager', 'Failed to set item, using fallback', { key, error });
         }
+        // Always update fallback for consistency
+        this.fallbackStorage.set(key, value);
     }
+    /**
+     * Removes an item from storage
+     */
     removeItem(key) {
-        if (!this.storageAvailable) {
-            this.fallbackStorage.delete(key);
-            return;
-        }
         try {
             if (this.storage) {
                 this.storage.removeItem(key);
-                return;
             }
-            this.fallbackStorage.delete(key);
         }
         catch (error) {
-            logging_1.debugLog.warn('StorageManager', 'Storage removeItem failed, using memory fallback', { key, error });
-            this.storageAvailable = false;
-            this.fallbackStorage.delete(key);
+            debug_logger_utils_1.debugLog.warn('StorageManager', 'Failed to remove item', { key, error });
+        }
+        // Always clean fallback
+        this.fallbackStorage.delete(key);
+    }
+    /**
+     * Clears all TracLog-related items from storage
+     */
+    clear() {
+        if (!this.storage) {
+            this.fallbackStorage.clear();
+            return;
+        }
+        try {
+            const keysToRemove = [];
+            for (let i = 0; i < this.storage.length; i++) {
+                const key = this.storage.key(i);
+                if (key?.startsWith('tracelog_')) {
+                    keysToRemove.push(key);
+                }
+            }
+            keysToRemove.forEach((key) => this.storage.removeItem(key));
+            this.fallbackStorage.clear();
+            debug_logger_utils_1.debugLog.debug('StorageManager', 'Cleared storage', { itemsRemoved: keysToRemove.length });
+        }
+        catch (error) {
+            debug_logger_utils_1.debugLog.error('StorageManager', 'Failed to clear storage', { error });
+            this.fallbackStorage.clear();
         }
     }
-    init() {
+    /**
+     * Checks if storage is available
+     */
+    isAvailable() {
+        return this.storage !== null;
+    }
+    /**
+     * Initialize localStorage with feature detection
+     */
+    initializeStorage() {
+        if (typeof window === 'undefined') {
+            return null;
+        }
         try {
-            const test = '__storage_test__';
-            const storage = window['localStorage'];
-            storage.setItem(test, test);
-            storage.removeItem(test);
+            const storage = window.localStorage;
+            const testKey = '__tracelog_test__';
+            storage.setItem(testKey, 'test');
+            storage.removeItem(testKey);
             return storage;
         }
         catch {

package/dist/cjs/managers/tags.manager.d.ts

@@ -1,12 +1,36 @@
 import { DeviceType, EventData } from '../types';
 import { StateManager } from './state.manager';
 export declare class TagsManager extends StateManager {
+    /**
+     * Gets matching tag IDs for an event based on configured tag conditions
+     */
     getEventTagsIds(event: EventData, deviceType: DeviceType): string[];
-    private checkEventTypePageView;
-    private checkEventTypeClick;
-    private matchUrlMatches;
-    private matchDeviceType;
-    private matchElementSelector;
-    private matchUtmCondition;
-    private checkElementFieldEquals;
+    /**
+     * Evaluates all conditions for a tag using logical operators
+     */
+    private evaluateTagConditions;
+    /**
+     * Evaluates a single tag condition
+     */
+    private evaluateCondition;
+    /**
+     * Unified string matching logic for all string-based conditions
+     */
+    private matchStringCondition;
+    /**
+     * Element-specific matching logic with optimized data extraction
+     */
+    private matchElementCondition;
+    /**
+     * Exact field matching for element EQUALS operations
+     */
+    private matchElementFieldExact;
+    /**
+     * Builds searchable element data string with null safety
+     */
+    private buildElementDataString;
+    /**
+     * Safe regex testing with error handling
+     */
+    private testRegex;
 }