react-broadcast-sync 1.0.0

package/src/hooks/useBroadcastChannel.ts

@@ -0,0 +1,232 @@
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { BroadcastActions, BroadcastMessage, BroadcastOptions, SendMessageOptions } from '../types/types';
+import { 
+  generateSourceName, 
+  isValidMessage, 
+  isMessageExpired, 
+  createMessage,
+  getInternalMessageType,
+  isInternalType,
+  isValidInternalClearMessage,
+  debounce,
+} from '../utils/messageUtils';
+import { debug } from '../utils/debug';
+
+const INTERNAL_MESSAGE_TYPES = {
+    CLEAR_MESSAGE: 'CLEAR_MESSAGE',
+    CLEAR_ALL_MESSAGES: 'CLEAR_ALL_MESSAGES',
+  } as const;
+
+export const useBroadcastChannel = (
+  channelName: string,
+  options: BroadcastOptions = {}
+): BroadcastActions => {
+  const {
+    sourceName,
+    cleaningInterval = 1000,
+    keepLatestMessage = false,
+    registeredTypes = [], 
+    namespace = '',
+    deduplicationTTL = 5 * 60 * 1000,
+    cleanupDebounceMs = 0
+  } = options;
+
+  // State
+  const [messages, setMessages] = useState<BroadcastMessage[]>([]);
+  const [sentMessages, setSentMessages] = useState<BroadcastMessage[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  // Refs
+  const channel = useRef<BroadcastChannel | null>(null);
+  const receivedMessageIds = useRef(new Map<string, number>());
+  const source = useRef(sourceName || generateSourceName()).current;
+  const internalTypes = useRef({
+    CLEAR_MESSAGE: getInternalMessageType(INTERNAL_MESSAGE_TYPES.CLEAR_MESSAGE, channelName, namespace),
+    CLEAR_ALL_MESSAGES: getInternalMessageType(INTERNAL_MESSAGE_TYPES.CLEAR_ALL_MESSAGES, channelName, namespace),
+  }).current;
+
+  const resolvedChannelName = useMemo(() => {
+    return `${channelName}-${namespace}`;
+  }, [channelName, namespace]);
+
+  const performCleanup = useCallback(() => {
+    setMessages(prev => prev.filter(msg => !isMessageExpired(msg)));
+  }, []);
+
+  const debouncedCleanup = useRef<{
+    (...args: Parameters<typeof performCleanup>): void;
+    cancel: () => void;
+  }>(
+    cleanupDebounceMs > 0
+      ? debounce(performCleanup, cleanupDebounceMs)
+      : Object.assign(performCleanup, { cancel: () => {} })
+  ).current;
+
+  const setErrorMessage = useCallback((error: string) => {
+    setError(error);
+    setTimeout(() => setError(null), 3000);
+  }, []);
+
+  const clearMessage = useCallback((id: string) => {
+    setMessages(prev => prev.filter(msg => msg.id !== id));
+    setSentMessages(prev => prev.filter(msg => msg.id !== id));
+    channel.current?.postMessage({ 
+      id, 
+      type: internalTypes.CLEAR_MESSAGE, 
+      source 
+    });
+    debug.message.cleared(id);
+  }, [source, internalTypes.CLEAR_MESSAGE]);
+
+  const clearAllMessages = useCallback(() => {
+    setMessages([]);
+    setSentMessages([]);
+    channel.current?.postMessage({ 
+      id: internalTypes.CLEAR_ALL_MESSAGES, 
+      type: internalTypes.CLEAR_ALL_MESSAGES, 
+      source 
+    });
+  }, [source, internalTypes.CLEAR_ALL_MESSAGES]);
+
+  const clearSentMessage = useCallback((id: string) => {
+    setSentMessages(prev => prev.filter(msg => msg.id !== id));
+    channel.current?.postMessage({ 
+      id, 
+      type: internalTypes.CLEAR_MESSAGE, 
+      source 
+    });
+  }, [source, internalTypes.CLEAR_MESSAGE]);
+
+  const postMessage = useCallback((
+    messageType: string,
+    messageContent: any,
+    options: SendMessageOptions = {}
+  ) => {
+    const channelCurrent = channel.current;
+    if (!channelCurrent) {
+      const error = 'Channel not available';
+      debug.error(error);
+      setErrorMessage(error);
+      return;
+    }
+
+    try {
+      const message = createMessage(messageType, messageContent, source, options);
+      channelCurrent.postMessage(message);
+      debug.message.sent(message);
+      setSentMessages(prev => [...prev, message]);
+    } catch (e) {
+      const error = 'Failed to send message';
+      debug.error(error);
+      setErrorMessage(error);
+    }
+  }, [source, setErrorMessage]);
+
+  const handleMessage = useCallback((event: MessageEvent) => {
+    try {
+      const message: BroadcastMessage = event.data;
+      debug.message.received(message);
+
+      if (!isValidMessage(message)) return;
+      if (message.source === source) return;
+      if (!isInternalType(message.type) && registeredTypes.length > 0 && !registeredTypes.includes(message.type)) return;
+      if (isMessageExpired(message)) {
+        debug.message.expired(message.id);
+        return;
+      }
+
+      if (isValidInternalClearMessage(message)) {
+        if (message.type === internalTypes.CLEAR_MESSAGE) {
+          setMessages(prev =>
+            prev.filter(msg => !(msg.id === message.id && msg.source === message.source))
+          );
+          return;
+        }
+      
+        if (message.type === internalTypes.CLEAR_ALL_MESSAGES) {
+          setMessages(prev => prev.filter(msg => msg.source !== message.source));
+          return;
+        }
+      }
+
+      const now = Date.now();
+      const receivedAt = receivedMessageIds.current.get(message.id);
+      if (receivedAt && now - receivedAt < deduplicationTTL) {
+        debug.message.duplicate(message.id);
+        return;
+      }
+
+      receivedMessageIds.current.set(message.id, now);
+      setMessages(prev => keepLatestMessage ? [message] : [...prev, message]);
+    } catch (e) {
+      const error = 'Error processing broadcast message';
+      debug.error(error);
+      setErrorMessage(error);
+    }
+  }, [source, registeredTypes, keepLatestMessage, setErrorMessage, internalTypes, deduplicationTTL]);
+
+  useEffect(() => {
+    if (typeof BroadcastChannel === 'undefined') {
+      const error = 'BroadcastChannel is not supported in this browser. Please check browser compatibility.';
+      debug.error(error);
+      setErrorMessage(error);
+      return;
+    }
+
+    const bc = new BroadcastChannel(resolvedChannelName);
+    channel.current = bc;
+    debug.channel.created(resolvedChannelName);
+
+    bc.addEventListener('message', handleMessage);
+    return () => {
+      bc.removeEventListener('message', handleMessage);
+      bc.close();
+      debug.channel.closed(resolvedChannelName);
+    };
+  }, [resolvedChannelName, handleMessage, setErrorMessage]);
+
+  useEffect(() => {
+    if (cleaningInterval <= 0) return;
+
+    const interval = setInterval(() => {
+      debug.cleanup.started();
+      const before = messages.length;
+      debouncedCleanup();
+      debug.cleanup.completed(before - messages.length);
+    }, cleaningInterval);
+
+    return () => {
+      clearInterval(interval);
+      // Cancel any pending debounced cleanup on unmount
+      if (cleanupDebounceMs > 0) {
+        debouncedCleanup.cancel?.();
+      }
+    };
+  }, [cleaningInterval, debouncedCleanup, cleanupDebounceMs]);
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const now = Date.now();
+      for (const [id, timestamp] of receivedMessageIds.current.entries()) {
+        if (now - timestamp >= deduplicationTTL) {
+          receivedMessageIds.current.delete(id);
+        }
+      }
+    }, 60 * 1000);
+  
+    return () => clearInterval(interval);
+  }, [deduplicationTTL]);
+
+  return {
+    channelName: resolvedChannelName,
+    messages,
+    sentMessages,
+    postMessage,
+    clearMessage,
+    clearAllMessages,
+    clearSentMessage,
+    error,
+  };
+};
+
+export default useBroadcastChannel; 

package/src/index.ts

@@ -0,0 +1,9 @@
+export { useBroadcastChannel } from './hooks/useBroadcastChannel';
+export { BroadcastProvider, useBroadcastProvider } from './BroadcastProvider';
+
+export type {
+  BroadcastOptions,
+  SendMessageOptions,
+  BroadcastMessage,
+  BroadcastActions
+} from './types/types';

package/src/tests/BroadcastProvider.test.tsx

@@ -0,0 +1,163 @@
+import { render, screen, act } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { BroadcastProvider, useBroadcastProvider } from '../BroadcastProvider';
+
+// Mock BroadcastChannel
+let mockChannels: any[] = [];
+
+class MockBroadcastChannel {
+  name: string;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  postMessage = jest.fn();
+  close = jest.fn();
+  addEventListener = jest.fn((event: string, callback: (event: MessageEvent) => void) => {
+    if (event === 'message') {
+      this.onmessage = callback;
+    }
+  });
+  removeEventListener = jest.fn();
+
+  constructor(name: string) {
+    this.name = name;
+    mockChannels.push(this);
+  }
+
+  simulateMessage(data: any) {
+    if (this.onmessage) {
+      this.onmessage({ data } as MessageEvent);
+    }
+  }
+}
+
+// Test component that uses the provider
+const TestComponent = () => {
+  const { messages, error } = useBroadcastProvider();
+  return (
+    <div>
+      <div data-testid="error">{error}</div>
+      <div data-testid="messages">
+        {messages.map((msg) => (
+          <div key={msg.id} data-testid={`message-${msg.id}`}>
+            {msg.message.text}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+describe('BroadcastProvider', () => {
+  beforeEach(() => {
+    mockChannels = [];
+    global.BroadcastChannel = MockBroadcastChannel as any;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('creates a broadcast channel with the provided name', () => {
+    render(
+      <BroadcastProvider channelName="test-channel">
+        <TestComponent />
+      </BroadcastProvider>
+    );
+
+    // The provider creates two channels - one in the provider and one in useBroadcastChannel
+    expect(mockChannels).toHaveLength(2);
+    expect(mockChannels[0].name).toBe('test-channel-');
+    expect(mockChannels[1].name).toBe('test-channel');
+  });
+
+  it('provides context values to children', () => {
+    render(
+      <BroadcastProvider channelName="test-channel">
+        <TestComponent />
+      </BroadcastProvider>
+    );
+
+    expect(screen.getByTestId('error')).toHaveTextContent('');
+    expect(screen.getByTestId('messages')).toBeEmptyDOMElement();
+  });
+
+  it('handles messages through the provider', () => {
+    render(
+      <BroadcastProvider channelName="test-channel">
+        <TestComponent />
+      </BroadcastProvider>
+    );
+
+    const message = {
+      id: 'test-1',
+      type: 'test',
+      message: { text: 'Hello' },
+      source: 'other-tab',
+      timestamp: Date.now()
+    };
+
+    act(() => {
+      mockChannels[0].simulateMessage(message);
+    });
+
+    expect(screen.getByTestId('message-test-1')).toHaveTextContent('Hello');
+  });
+
+  it('handles errors when BroadcastChannel is not supported', () => {
+    const originalBroadcastChannel = global.BroadcastChannel;
+    delete (global as any).BroadcastChannel;
+
+    render(
+      <BroadcastProvider channelName="test-channel">
+        <TestComponent />
+      </BroadcastProvider>
+    );
+
+    expect(screen.getByTestId('error')).toHaveTextContent(
+      'BroadcastChannel is not supported in this browser. Please check browser compatibility.'
+    );
+
+    // Restore BroadcastChannel for other tests
+    global.BroadcastChannel = originalBroadcastChannel;
+  });
+
+  it('cleans up channel on unmount', () => {
+    const { unmount } = render(
+      <BroadcastProvider channelName="test-channel">
+        <TestComponent />
+      </BroadcastProvider>
+    );
+
+    unmount();
+
+    expect(mockChannels[0].close).toHaveBeenCalled();
+  });
+
+  it('handles error boundary when child component throws', () => {
+    const ThrowComponent = () => {
+      throw new Error('Test error');
+    };
+
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    
+    render(
+      <BroadcastProvider channelName="test-channel">
+        <ThrowComponent />
+      </BroadcastProvider>
+    );
+
+    expect(screen.getByText('Error occurred in BroadcastProvider')).toBeInTheDocument();
+    expect(consoleError).toHaveBeenCalledWith('BroadcastChannel error:', expect.any(Error));
+    
+    consoleError.mockRestore();
+  });
+
+  it('throws error when useBroadcastProvider is used outside provider', () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    
+    expect(() => {
+      render(<TestComponent />);
+    }).toThrow('useBroadcastProvider must be used within a BroadcastProvider');
+    
+    consoleError.mockRestore();
+  });
+}); 

package/src/tests/debug.test.ts

@@ -0,0 +1,199 @@
+// Set debug mode before requiring the debug module
+process.env.REACT_APP_DEBUG_BROADCAST = 'true';
+import { debug } from '../utils/debug';
+
+describe('debug', () => {
+  const originalEnv = process.env;
+  const originalConsole = {
+    log: console.log,
+    warn: console.warn,
+    error: console.error,
+  };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    console.log = jest.fn();
+    console.warn = jest.fn();
+    console.error = jest.fn();
+  });
+
+  afterEach(() => {
+    console.log = originalConsole.log;
+    console.warn = originalConsole.warn;
+    console.error = originalConsole.error;
+    process.env = originalEnv;
+  });
+
+  describe('when debug mode is disabled', () => {
+    beforeEach(() => {
+      process.env.REACT_APP_DEBUG_BROADCAST = 'false';
+    });
+
+    it('does not log anything', () => {
+      debug.channel.created('test-channel');
+      debug.message.sent({ id: '123' });
+      debug.error('test error');
+
+      expect(console.log).not.toHaveBeenCalled();
+      expect(console.warn).not.toHaveBeenCalled();
+      expect(console.error).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('when debug mode is enabled', () => {
+    beforeEach(() => {
+      process.env.REACT_APP_DEBUG_BROADCAST = 'true';
+    });
+
+    it('logs channel events', () => {
+      debug.channel.created('test-channel');
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Channel created:',
+        'test-channel'
+      );
+
+      debug.channel.closed('test-channel');
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Channel closed:',
+        'test-channel'
+      );
+    });
+
+    it('logs message events', () => {
+      const testMessage = { id: '123', type: 'test' };
+      
+      debug.message.sent(testMessage);
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Message sent:',
+        testMessage
+      );
+
+      debug.message.received(testMessage);
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Message received:',
+        testMessage
+      );
+
+      debug.message.cleared('123');
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Message cleared:',
+        '123'
+      );
+
+      debug.message.expired('123');
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Message expired:',
+        '123'
+      );
+
+      debug.message.duplicate('123');
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Duplicate message ignored:',
+        '123'
+      );
+    });
+
+    it('logs cleanup events', () => {
+      debug.cleanup.started();
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Cleanup started',
+        ''
+      );
+
+      debug.cleanup.completed(5);
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Cleanup completed:',
+        { removedCount: 5 }
+      );
+    });
+
+    it('logs errors', () => {
+      debug.error('test error');
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringMatching(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\] \[react-broadcast-sync\]/),
+        'Error:',
+        'test error'
+      );
+    });
+
+    it('logs info with no data', () => {
+      debug.channel.created('test-channel');
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringMatching(/\[.*react-broadcast-sync\]/),
+        'Channel created:',
+        'test-channel'
+      );
+    });
+
+    it('logs warn with no data', () => {
+      debug.message.duplicate('123');
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringMatching(/\[.*react-broadcast-sync\]/),
+        'Duplicate message ignored:',
+        '123'
+      );
+    });
+
+    it('logs error with no data', () => {
+      debug.error('error!');
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringMatching(/\[.*react-broadcast-sync\]/),
+        'Error:',
+        'error!'
+      );
+    });
+
+    it('logs message with no data', () => {
+        debug.cleanup.started();
+        expect(console.log).toHaveBeenCalledWith(
+          expect.stringContaining('[react-broadcast-sync]'),
+          'Cleanup started',
+          ''
+        );
+      });
+  });
+
+  describe('when process.env is undefined', () => {
+    beforeEach(() => {
+      // @ts-ignore - Simulating environment where process.env is undefined
+      process.env = undefined;
+    });
+
+    it('does not log anything', () => {
+      debug.channel.created('test-channel');
+      expect(console.log).not.toHaveBeenCalled();
+    });
+  });
+
+  it('logs info messages', () => {
+    debug.channel.created('test-channel');
+    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[react-broadcast-sync]'), 'Channel created:', 'test-channel');
+  });
+
+  it('logs warning messages', () => {
+    debug.message.duplicate('test-id');
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('[react-broadcast-sync]'), 'Duplicate message ignored:', 'test-id');
+  });
+
+  it('logs error messages', () => {
+    debug.error('Test error');
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('[react-broadcast-sync]'), 'Error:', 'Test error');
+  });
+
+  it('logs cleanup information', () => {
+    debug.cleanup.started();
+    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[react-broadcast-sync]'), 'Cleanup started', '');
+
+    debug.cleanup.completed(2);
+    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('[react-broadcast-sync]'), 'Cleanup completed:', { removedCount: 2 });
+  });
+});