@capsitech/react-utilities 0.1.14 → 0.1.15

package/lib/Utilities/CrossTabApiCoordinator.d.ts

@@ -0,0 +1,105 @@
+/**
+ * CrossTabApiCoordinator - Ensures API calls execute only once across multiple browser tabs
+ * Uses Web Locks API for coordination and BroadcastChannel for result sharing
+ */
+/**
+ * Options for CrossTabApiCoordinator:
+ * - `cacheTTL`: Time in milliseconds to cache results to prevent duplicate calls (default: 1000ms)
+ * - `timeout`: Time in milliseconds before a request times out (default: 30000ms)
+ */
+interface CrossTabApiCoordinatorOptions {
+    cacheTTL?: number;
+    timeout?: number;
+}
+/**
+ * The `CrossTabApiCoordinator` uses modern browser APIs to coordinate API calls:
+ * - **Web Locks API**: Ensures only one tab executes the call
+ * - **BroadcastChannel API**: Shares results with other tabs
+ * - **Built-in caching**: Prevents duplicate calls within a time window
+ * - **Fallback**: Automatically falls back to direct API calls if browser APIs aren't supported.
+ */
+declare class CrossTabApiCoordinator {
+    private channels;
+    private pendingRequests;
+    private cache;
+    private readonly CACHE_TTL;
+    private readonly REQUEST_TIMEOUT;
+    private readonly MAX_CACHE_SIZE;
+    private cleanupInterval;
+    private isSupported;
+    constructor();
+    /**
+     * Check if required browser APIs are supported
+     */
+    private checkBrowserSupport;
+    /**
+     * Start periodic cache cleanup to prevent memory leaks
+     */
+    private startPeriodicCleanup;
+    /**
+     * Remove stale cache entries
+     */
+    private cleanupStaleCache;
+    /**
+     * Remove stale pending requests
+     */
+    private cleanupStalePendingRequests;
+    /**
+     * Validate broadcast message structure
+     */
+    private isValidMessage;
+    /**
+     * Serialize data for broadcast (handle circular references and non-cloneable objects)
+     */
+    private serializeData;
+    /**
+     * Execute an API call coordinated across tabs
+     * @param key Unique identifier for this API call (e.g., 'phoneCall-get-123')
+     * @param apiCall Function that returns a Promise with the API call
+     * @param options Configuration options
+     */
+    execute<T>(key: string, apiCall: () => Promise<T>, options?: CrossTabApiCoordinatorOptions): Promise<T>;
+    /**
+     * Handle messages from other tabs
+     */
+    private handleMessage;
+    /**
+     * Resolve all pending requests for a key
+     */
+    private resolvePendingRequests;
+    /**
+     * Reject all pending requests for a key
+     */
+    private rejectPendingRequests;
+    /**
+     * Cleanup a specific request
+     */
+    private cleanupRequest;
+    /**
+     * Cleanup broadcast channel
+     */
+    private cleanupChannel;
+    /**
+     * Clear cache for a specific key or all keys
+     */
+    clearCache(key?: string): void;
+    /**
+     * Cleanup all resources
+     */
+    cleanup(): void;
+}
+export declare const CrossTabApi: CrossTabApiCoordinator;
+/**
+ * Helper function to wrap API calls with cross-tab coordination
+ * @example
+ * const result = await CoordinateCrossTabApiCall(
+ *   'phoneCall-get-' + callId,
+ *   () => PhoneCallService.get(callId, true)
+ * );
+ *
+ * @param key (string): Unique identifier for this API call. Same key = shared execution.
+ * @param apiCall (() => Promise<T>): Function that returns the API call promise.
+ * @param options (optional)
+ */
+export declare function CoordinateCrossTabApiCall<T>(key: string, apiCall: () => Promise<T>, options?: CrossTabApiCoordinatorOptions): Promise<T>;
+export {};

package/lib/Utilities/CrossTabApiCoordinator.js

@@ -0,0 +1,407 @@
+/**
+ * CrossTabApiCoordinator - Ensures API calls execute only once across multiple browser tabs
+ * Uses Web Locks API for coordination and BroadcastChannel for result sharing
+ */
+/**
+ * The `CrossTabApiCoordinator` uses modern browser APIs to coordinate API calls:
+ * - **Web Locks API**: Ensures only one tab executes the call
+ * - **BroadcastChannel API**: Shares results with other tabs
+ * - **Built-in caching**: Prevents duplicate calls within a time window
+ * - **Fallback**: Automatically falls back to direct API calls if browser APIs aren't supported.
+ */
+class CrossTabApiCoordinator {
+    channels = new Map();
+    pendingRequests = new Map();
+    cache = new Map();
+    CACHE_TTL = 1000; // 1 second cache to avoid duplicate calls
+    REQUEST_TIMEOUT = 30000; // 30 seconds timeout
+    MAX_CACHE_SIZE = 100; // Prevent memory leaks
+    cleanupInterval = null;
+    isSupported = null;
+    constructor() {
+        // Start periodic cleanup
+        this.startPeriodicCleanup();
+        // Cleanup on page unload
+        if (typeof window !== 'undefined') {
+            window.addEventListener('beforeunload', () => this.cleanup());
+        }
+    }
+    /**
+     * Check if required browser APIs are supported
+     */
+    checkBrowserSupport() {
+        if (this.isSupported !== null) {
+            return this.isSupported;
+        }
+        const hasLocks = typeof navigator !== 'undefined' && 'locks' in navigator;
+        const hasBroadcastChannel = typeof BroadcastChannel !== 'undefined';
+        this.isSupported = hasLocks && hasBroadcastChannel;
+        if (!this.isSupported) {
+            console.warn('CrossTabApiCoordinator: Required APIs not supported. Missing:', !hasLocks ? 'Web Locks API' : '', !hasBroadcastChannel ? 'BroadcastChannel API' : '');
+        }
+        return this.isSupported;
+    }
+    /**
+     * Start periodic cache cleanup to prevent memory leaks
+     */
+    startPeriodicCleanup() {
+        if (this.cleanupInterval)
+            return;
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupStaleCache();
+            this.cleanupStalePendingRequests();
+        }, 60000); // Run every minute
+    }
+    /**
+     * Remove stale cache entries
+     */
+    cleanupStaleCache() {
+        const now = Date.now();
+        const maxAge = 300000; // 5 minutes
+        const entries = Array.from(this.cache.entries());
+        for (const [key, value] of entries) {
+            if (now - value.timestamp > maxAge) {
+                this.cache.delete(key);
+            }
+        }
+        // If cache is still too large, remove oldest entries
+        if (this.cache.size > this.MAX_CACHE_SIZE) {
+            const entries = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp);
+            const toRemove = entries.slice(0, entries.length - this.MAX_CACHE_SIZE);
+            toRemove.forEach(([key]) => this.cache.delete(key));
+        }
+    }
+    /**
+     * Remove stale pending requests
+     */
+    cleanupStalePendingRequests() {
+        const now = Date.now();
+        const maxAge = this.REQUEST_TIMEOUT * 2;
+        const entries = Array.from(this.pendingRequests.entries());
+        for (const [key, requests] of entries) {
+            const validRequests = requests.filter((req) => {
+                if (now - req.timestamp > maxAge) {
+                    // Clear timeout and reject
+                    clearTimeout(req.timeoutId);
+                    req.reject(new Error('Request timed out and cleaned up'));
+                    return false;
+                }
+                return true;
+            });
+            if (validRequests.length === 0) {
+                this.pendingRequests.delete(key);
+                this.cleanupChannel(key);
+            }
+            else if (validRequests.length !== requests.length) {
+                this.pendingRequests.set(key, validRequests);
+            }
+        }
+    }
+    /**
+     * Validate broadcast message structure
+     */
+    isValidMessage(data) {
+        return (data && typeof data === 'object' && typeof data.type === 'string' && (data.type === 'success' || data.type === 'error') && typeof data.key === 'string' && typeof data.timestamp === 'number');
+    }
+    /**
+     * Serialize data for broadcast (handle circular references and non-cloneable objects)
+     */
+    serializeData(data) {
+        try {
+            // Test if data is cloneable by attempting to structure clone
+            structuredClone(data);
+            return data;
+        }
+        catch (error) {
+            // Fallback to JSON serialization for non-cloneable data
+            console.warn('Data contains non-cloneable objects, using JSON serialization');
+            try {
+                return JSON.parse(JSON.stringify(data));
+            }
+            catch (jsonError) {
+                console.error('Failed to serialize data:', jsonError);
+                return null;
+            }
+        }
+    }
+    /**
+     * Execute an API call coordinated across tabs
+     * @param key Unique identifier for this API call (e.g., 'phoneCall-get-123')
+     * @param apiCall Function that returns a Promise with the API call
+     * @param options Configuration options
+     */
+    async execute(key, apiCall, options = {}) {
+        const cacheTTL = options.cacheTTL ?? this.CACHE_TTL;
+        const timeout = options.timeout ?? this.REQUEST_TIMEOUT;
+        // Validate key
+        if (!key || typeof key !== 'string') {
+            throw new Error('Invalid key: must be a non-empty string');
+        }
+        // Check cache first
+        const cached = this.cache.get(key);
+        if (cached && Date.now() - cached.timestamp < cacheTTL) {
+            return cached.data;
+        }
+        // Check if required APIs are supported - fallback to direct execution
+        if (!this.checkBrowserSupport()) {
+            console.warn(`CrossTabApiCoordinator: Browser APIs not supported, executing API call directly for key: ${key}`);
+            return apiCall();
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = `${key}-${Date.now()}-${Math.random()}`;
+            const channelName = `api-coordinator-${key}`;
+            let isResolved = false;
+            // Create timeout with cleanup
+            const timeoutId = setTimeout(() => {
+                if (!isResolved) {
+                    isResolved = true;
+                    this.cleanupRequest(key, requestId);
+                    reject(new Error(`API call timeout for key: ${key}`));
+                }
+            }, timeout);
+            // Store this request
+            if (!this.pendingRequests.has(key)) {
+                this.pendingRequests.set(key, []);
+            }
+            this.pendingRequests.get(key).push({
+                resolve: (value) => {
+                    if (!isResolved) {
+                        isResolved = true;
+                        clearTimeout(timeoutId);
+                        resolve(value);
+                    }
+                },
+                reject: (error) => {
+                    if (!isResolved) {
+                        isResolved = true;
+                        clearTimeout(timeoutId);
+                        reject(error);
+                    }
+                },
+                timestamp: Date.now(),
+                timeoutId,
+            });
+            // Get or create broadcast channel for this key
+            // CRITICAL: Must be created BEFORE attempting lock to avoid missing broadcasts
+            let channel;
+            try {
+                if (!this.channels.has(key)) {
+                    channel = new BroadcastChannel(channelName);
+                    channel.onmessage = (event) => this.handleMessage(key, event);
+                    channel.onmessageerror = (event) => {
+                        console.error('BroadcastChannel message error:', event);
+                    };
+                    this.channels.set(key, channel);
+                }
+                else {
+                    channel = this.channels.get(key);
+                }
+            }
+            catch (error) {
+                console.error('Failed to create BroadcastChannel:', error);
+                console.warn('Falling back to direct API execution without coordination');
+                clearTimeout(timeoutId);
+                this.cleanupRequest(key, requestId);
+                // Fallback to direct execution if BroadcastChannel fails
+                return apiCall().then(resolve).catch(reject);
+            }
+            // Try to acquire lock with ifAvailable - only first tab gets it immediately
+            // Other tabs will fail to get the lock and wait for broadcast
+            navigator.locks
+                .request(`api-${key}`, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+                if (!lock) {
+                    // This tab didn't get the lock - another tab is executing
+                    // Just wait for the broadcast message (already set up via pendingRequests)
+                    return null; // Return control immediately, wait for broadcast
+                }
+                // This tab got the lock - execute the API call
+                try {
+                    const result = await apiCall();
+                    // Serialize data to ensure it can be broadcast
+                    const serializedResult = this.serializeData(result);
+                    // Cache the result
+                    this.cache.set(key, { data: result, timestamp: Date.now() });
+                    // Broadcast result to all tabs (including this one)
+                    try {
+                        const message = {
+                            type: 'success',
+                            data: serializedResult,
+                            key,
+                            timestamp: Date.now(),
+                        };
+                        channel.postMessage(message);
+                    }
+                    catch (broadcastError) {
+                        console.error('Failed to broadcast success:', broadcastError);
+                        // Still resolve local requests even if broadcast fails
+                    }
+                    // Resolve all pending requests in this tab
+                    this.resolvePendingRequests(key, result);
+                    return result;
+                }
+                catch (error) {
+                    // Broadcast error to all tabs
+                    try {
+                        const message = {
+                            type: 'error',
+                            error: error instanceof Error ? error.message : String(error),
+                            key,
+                            timestamp: Date.now(),
+                        };
+                        channel.postMessage(message);
+                    }
+                    catch (broadcastError) {
+                        console.error('Failed to broadcast error:', broadcastError);
+                    }
+                    // Reject all pending requests in this tab
+                    this.rejectPendingRequests(key, error);
+                    throw error;
+                }
+                finally {
+                    // Clean up channel after a delay
+                    setTimeout(() => this.cleanupChannel(key), 5000);
+                }
+            })
+                .catch((error) => {
+                console.error('Lock request failed:', error);
+                console.warn('Falling back to direct API execution without coordination');
+                clearTimeout(timeoutId);
+                this.cleanupRequest(key, requestId);
+                // If lock mechanism fails, fall back to direct execution
+                if (!isResolved) {
+                    isResolved = true;
+                    apiCall().then(resolve).catch(reject);
+                }
+            });
+        });
+    }
+    /**
+     * Handle messages from other tabs
+     */
+    handleMessage(key, event) {
+        // Validate message structure
+        if (!this.isValidMessage(event.data)) {
+            console.warn('Received invalid message:', event.data);
+            return;
+        }
+        const { type, data, error, timestamp } = event.data;
+        // Ignore stale messages (older than 1 minute)
+        if (Date.now() - timestamp > 60000) {
+            return;
+        }
+        if (type === 'success') {
+            // Cache the result
+            this.cache.set(key, { data, timestamp: Date.now() });
+            // Resolve all pending requests
+            this.resolvePendingRequests(key, data);
+        }
+        else if (type === 'error') {
+            // Reject all pending requests
+            this.rejectPendingRequests(key, new Error(error || 'Unknown error'));
+        }
+    }
+    /**
+     * Resolve all pending requests for a key
+     */
+    resolvePendingRequests(key, data) {
+        const requests = this.pendingRequests.get(key) || [];
+        requests.forEach((req) => req.resolve(data));
+        this.pendingRequests.delete(key);
+    }
+    /**
+     * Reject all pending requests for a key
+     */
+    rejectPendingRequests(key, error) {
+        const requests = this.pendingRequests.get(key) || [];
+        requests.forEach((req) => req.reject(error));
+        this.pendingRequests.delete(key);
+    }
+    /**
+     * Cleanup a specific request
+     */
+    cleanupRequest(key, requestId) {
+        const requests = this.pendingRequests.get(key);
+        if (requests) {
+            const filtered = requests.filter((req) => req.timestamp.toString() !== requestId.split('-')[1]);
+            if (filtered.length > 0) {
+                this.pendingRequests.set(key, filtered);
+            }
+            else {
+                this.pendingRequests.delete(key);
+            }
+        }
+    }
+    /**
+     * Cleanup broadcast channel
+     */
+    cleanupChannel(key) {
+        const channel = this.channels.get(key);
+        if (channel && (!this.pendingRequests.has(key) || this.pendingRequests.get(key).length === 0)) {
+            channel.close();
+            this.channels.delete(key);
+        }
+    }
+    /**
+     * Clear cache for a specific key or all keys
+     */
+    clearCache(key) {
+        if (key) {
+            this.cache.delete(key);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    /**
+     * Cleanup all resources
+     */
+    cleanup() {
+        // Clear periodic cleanup
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Clear all timeouts in pending requests
+        this.pendingRequests.forEach((requests) => {
+            requests.forEach((req) => {
+                clearTimeout(req.timeoutId);
+                // Reject pending requests on cleanup
+                try {
+                    req.reject(new Error('Coordinator cleanup'));
+                }
+                catch (e) {
+                    // Ignore if already resolved
+                }
+            });
+        });
+        // Close all channels
+        this.channels.forEach((channel) => {
+            try {
+                channel.close();
+            }
+            catch (e) {
+                console.error('Error closing channel:', e);
+            }
+        });
+        this.channels.clear();
+        this.pendingRequests.clear();
+        this.cache.clear();
+    }
+}
+// Export singleton instance
+export const CrossTabApi = new CrossTabApiCoordinator();
+/**
+ * Helper function to wrap API calls with cross-tab coordination
+ * @example
+ * const result = await CoordinateCrossTabApiCall(
+ *   'phoneCall-get-' + callId,
+ *   () => PhoneCallService.get(callId, true)
+ * );
+ *
+ * @param key (string): Unique identifier for this API call. Same key = shared execution.
+ * @param apiCall (() => Promise<T>): Function that returns the API call promise.
+ * @param options (optional)
+ */
+export async function CoordinateCrossTabApiCall(key, apiCall, options) {
+    return CrossTabApi.execute(key, apiCall, options);
+}

package/lib/Utilities/index.d.ts

@@ -1,6 +1,7 @@
 export * from './ApiUtility.axios';
 export * from './BrowserInfo';
 export * from './Countries';
+export * from './CrossTabApiCoordinator';
 export * from './CustomEventEmitter';
 export * from './dayjs';
 export * from './FastCompare';

package/lib/Utilities/index.js

@@ -1,6 +1,7 @@
 export * from './ApiUtility.axios';
 export * from './BrowserInfo';
 export * from './Countries';
+export * from './CrossTabApiCoordinator';
 export * from './CustomEventEmitter';
 export * from './dayjs';
 export * from './FastCompare';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsitech/react-utilities",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "A set of javascript utility methods",
   "main": "lib/index.js",
   "jsnext:main": "lib/index.js",