react-broadcast-sync 1.0.0

package/src/tests/useBroadcastChannel.test.tsx

@@ -0,0 +1,504 @@
+import { renderHook, act } from '@testing-library/react';
+import { useBroadcastChannel } from '../hooks/useBroadcastChannel';
+
+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);
+    }
+  }
+}
+
+const waitForChannel = async () => {
+  return new Promise<void>((resolve) => {
+    const checkChannel = () => {
+      if (mockChannels.length > 0) {
+        resolve();
+      } else {
+        setTimeout(checkChannel, 0);
+      }
+    };
+    checkChannel();
+  });
+};
+
+beforeAll(() => {
+  global.BroadcastChannel = MockBroadcastChannel as any;
+});
+
+beforeEach(() => {
+  mockChannels = [];
+  global.BroadcastChannel = MockBroadcastChannel as any;
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+  global.BroadcastChannel = MockBroadcastChannel as any;
+});
+
+afterAll(() => {
+  delete (global as any).BroadcastChannel;
+});
+
+describe('useBroadcastChannel', () => {
+  it('posts and receives message', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      result.current.postMessage('greeting', { text: 'hi' });
+    });
+
+    const incomingMessage = {
+      id: 'external-1',
+      type: 'greeting',
+      message: { text: 'hi' },
+      source: 'another-tab',
+      timestamp: Date.now()
+    };
+
+    act(() => {
+      channel.simulateMessage(incomingMessage);
+    });
+
+    expect(result.current.messages.length).toBe(1);
+    expect(result.current.messages[0].message).toEqual({ text: 'hi' });
+  });
+
+  it('ignores self messages', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      result.current.postMessage('test', 'msg');
+      const selfMsg = result.current.sentMessages[0];
+      channel.simulateMessage(selfMsg);
+    });
+
+    expect(result.current.messages).toEqual([]);
+  });
+
+  it('clears a specific message', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    const msg = {
+      id: '123',
+      type: 'greeting',
+      message: 'hi',
+      source: 'external',
+      timestamp: Date.now()
+    };
+
+    act(() => {
+      channel.simulateMessage(msg);
+    });
+
+    expect(result.current.messages.length).toBe(1);
+
+    act(() => {
+      result.current.clearMessage('123');
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('clears all messages', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: '1',
+        type: 'a',
+        message: 'a',
+        source: 'x',
+        timestamp: Date.now()
+      });
+      channel.simulateMessage({
+        id: '2',
+        type: 'b',
+        message: 'b',
+        source: 'x',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(2);
+
+    act(() => {
+      result.current.clearAllMessages();
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('clears sent message', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    
+    act(() => {
+      result.current.postMessage('test-type', { key: 'value' });
+    });
+
+    const sentId = result.current.sentMessages[0]?.id;
+    expect(result.current.sentMessages.length).toBe(1);
+
+    act(() => {
+      result.current.clearSentMessage(sentId);
+    });
+
+    expect(result.current.sentMessages.length).toBe(0);
+  });
+
+  it('handles channel not available error', () => {
+    jest.useFakeTimers();
+
+    const original = global.BroadcastChannel;
+    // @ts-ignore
+    delete global.BroadcastChannel;
+
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+
+    act(() => {
+      result.current.postMessage('test', { a: 1 });
+    });
+
+    expect(result.current.error).toBe(
+      'BroadcastChannel is not supported in this browser. Please check browser compatibility.'
+    );
+
+    global.BroadcastChannel = original;
+    jest.useRealTimers();
+  });
+
+  it('sets error when BroadcastChannel is not supported', () => {
+    const original = global.BroadcastChannel;
+    delete (global as any).BroadcastChannel;
+
+    const { result } = renderHook(() => useBroadcastChannel('unsupported-channel'));
+
+    expect(result.current.error).toBe('BroadcastChannel is not supported in this browser. Please check browser compatibility.');
+    global.BroadcastChannel = original;
+  });
+
+  it('handles invalid messages', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({ invalid: 'message' });
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('handles expired messages', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    const expiredMessage = {
+      id: 'expired-1',
+      type: 'test',
+      message: 'expired',
+      source: 'another-tab',
+      timestamp: Date.now() - 1000000,
+      expirationDate: Date.now() - 1000000
+    };
+
+    act(() => {
+      channel.simulateMessage(expiredMessage);
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('handles duplicate messages within TTL', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel', { deduplicationTTL: 5000 }));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    const message = {
+      id: 'duplicate-1',
+      type: 'test',
+      message: 'duplicate',
+      source: 'another-tab',
+      timestamp: Date.now()
+    };
+
+    act(() => {
+      channel.simulateMessage(message);
+      channel.simulateMessage(message);
+    });
+
+    expect(result.current.messages.length).toBe(1);
+  });
+
+  it('handles internal clear message from other source', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'to-clear',
+        type: 'test',
+        message: 'will be cleared',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(1);
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'to-clear',
+        type: '__INTERNAL__:CLEAR_MESSAGE:' + btoa('react-broadcast-sync:CLEAR_MESSAGE:test-channel-'),
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('handles internal clear all messages from other source', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'msg1',
+        type: 'test1',
+        message: 'first',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+      channel.simulateMessage({
+        id: 'msg2',
+        type: 'test2',
+        message: 'second',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(2);
+
+    act(() => {
+      channel.simulateMessage({
+        id: '__INTERNAL__:CLEAR_ALL_MESSAGES:' + btoa('react-broadcast-sync:CLEAR_ALL_MESSAGES:test-channel-'),
+        type: '__INTERNAL__:CLEAR_ALL_MESSAGES:' + btoa('react-broadcast-sync:CLEAR_ALL_MESSAGES:test-channel-'),
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(0);
+  });
+
+  it('performs cleanup of expired messages', async () => {
+    jest.useFakeTimers();
+    const { result } = renderHook(() => useBroadcastChannel('test-channel', { cleaningInterval: 1000 }));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'expired-2',
+        type: 'test',
+        message: 'expired',
+        source: 'another-tab',
+        timestamp: Date.now() - 1000000,
+        expirationDate: Date.now() - 1000000
+      });
+    });
+
+    act(() => {
+      jest.advanceTimersByTime(1000);
+    });
+
+    expect(result.current.messages.length).toBe(0);
+    jest.useRealTimers();
+  });
+
+  it('handles registered types filtering', async () => {
+    const { result } = renderHook(() => 
+      useBroadcastChannel('test-channel', { registeredTypes: ['allowed-type'] })
+    );
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'unregistered',
+        type: 'unregistered-type',
+        message: 'test',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(0);
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'registered',
+        type: 'allowed-type',
+        message: 'test',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(1);
+  });
+
+  it('handles keepLatestMessage option', async () => {
+    const { result } = renderHook(() => 
+      useBroadcastChannel('test-channel', { keepLatestMessage: true })
+    );
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'msg1',
+        type: 'test',
+        message: 'first',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+      channel.simulateMessage({
+        id: 'msg2',
+        type: 'test',
+        message: 'second',
+        source: 'another-tab',
+        timestamp: Date.now()
+      });
+    });
+
+    expect(result.current.messages.length).toBe(1);
+    expect(result.current.messages[0].message).toBe('second');
+  });
+
+  it('handles cleanup debounce', async () => {
+    jest.useFakeTimers();
+    const { result } = renderHook(() => 
+      useBroadcastChannel('test-channel', { 
+        cleaningInterval: 1000,
+        cleanupDebounceMs: 500
+      })
+    );
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    act(() => {
+      channel.simulateMessage({
+        id: 'expired-3',
+        type: 'test',
+        message: 'expired',
+        source: 'another-tab',
+        timestamp: Date.now() - 1000000,
+        expirationDate: Date.now() - 1000000
+      });
+    });
+
+    act(() => {
+      jest.advanceTimersByTime(1500);
+    });
+    await Promise.resolve();
+
+    expect(result.current.messages.length).toBe(0);
+    jest.useRealTimers();
+  });
+
+  it('handles error when posting message fails', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    channel.postMessage.mockImplementationOnce(() => {
+      throw new Error('Failed to post message');
+    });
+
+    act(() => {
+      result.current.postMessage('test', { data: 'test' });
+    });
+
+    expect(result.current.error).toBe('Failed to send message');
+  });
+
+  it('handles error when processing message fails', async () => {
+    jest.useFakeTimers();
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+    const channel = mockChannels[0];
+
+    const badMessage: any = {};
+    Object.defineProperty(badMessage, 'id', {
+      get() { throw new Error('fail'); }
+    });
+    badMessage.type = 'test';
+    badMessage.source = 'z';
+    badMessage.timestamp = Date.now();
+
+    await act(async () => {
+      channel.simulateMessage(badMessage);
+      await Promise.resolve();
+    });
+    await Promise.resolve();
+    expect(result.current.error).toBe('Error processing broadcast message');
+    jest.useRealTimers();
+  });
+
+  it('handles error when BroadcastChannel initialization fails', () => {
+    const originalBroadcastChannel = global.BroadcastChannel;
+    delete (global as any).BroadcastChannel;
+
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+
+    expect(result.current.error).toBe('BroadcastChannel is not supported in this browser. Please check browser compatibility.');
+
+    global.BroadcastChannel = originalBroadcastChannel;
+  });
+
+  it('creates message with expiration duration', async () => {
+    const { result } = renderHook(() => useBroadcastChannel('test-channel'));
+    await waitForChannel();
+
+    act(() => {
+      result.current.postMessage('test', { data: 'test' }, { expirationDuration: 5000 });
+    });
+
+    const sentMessage = result.current.sentMessages[0];
+    expect(sentMessage.expirationDate).toBeDefined();
+    expect(sentMessage.expirationDate).toBeGreaterThan(Date.now());
+  });
+});

package/src/types/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Options for configuring the broadcast channel
+ */
+export interface BroadcastOptions {
+  /** Custom source name for this instance */
+  sourceName?: string;
+  
+  /** Interval in milliseconds for cleaning expired messages (default: 1000) */
+  cleaningInterval?: number;
+  
+  /** If true, only the latest message is kept */
+  keepLatestMessage?: boolean;
+  
+  /** Array of allowed message types */
+  registeredTypes?: string[];
+  
+  /** Channel namespace for isolation */
+  namespace?: string;
+
+  /** TTL for deduplication in milliseconds (default: 5 minutes) */
+  deduplicationTTL?: number;
+
+  /** Debounce time for messages cleanup in milliseconds (default: 1000) */
+  cleanupDebounceMs?: number;
+}
+
+/**
+ * Options for sending messages
+ */
+export interface SendMessageOptions {
+  /** Message expiration duration in milliseconds */
+  expirationDuration?: number;
+  
+  /** Specific expiration timestamp */
+  expirationDate?: number;
+}
+
+/**
+ * Structure of a broadcast message
+ */
+export interface BroadcastMessage {
+  /** Unique message identifier */
+  id: string;
+  
+  /** Message type for categorization */
+  type: string;
+  
+  /** Message content */
+  message: any;
+  
+  /** Creation timestamp */
+  timestamp: number;
+  
+  /** Source identifier */
+  source: string;
+  
+  /** Optional expiration timestamp */
+  expirationDate?: number;
+}
+
+/**
+ * Actions and state provided by the broadcast channel hook
+ */
+export interface BroadcastActions {
+  /** The resolved channel name including namespace */
+  channelName: string;
+  
+  /** Array of received messages */
+  messages: BroadcastMessage[];
+  
+  /** Array of sent messages */
+  sentMessages: BroadcastMessage[];
+  
+  /** Function to send a message */
+  postMessage: (
+    messageType: string,
+    messageContent: any,
+    options?: SendMessageOptions
+  ) => void;
+  
+  /** Function to clear a specific message */
+  clearMessage: (id: string) => void;
+  
+  /** Function to clear all messages */
+  clearAllMessages: () => void;
+  
+  /** Function to clear a specific sent message */
+  clearSentMessage: (id: string) => void;
+  
+  /** Current error state */
+  error: string | null;
+}

package/src/utils/debug.ts

@@ -0,0 +1,47 @@
+declare const process: { env: { [key: string]: string | undefined } };
+
+const isDebugMode = () => {
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.REACT_APP_DEBUG_BROADCAST === 'true';
+  }
+  return false;
+};
+
+type LogLevel = 'info' | 'warn' | 'error';
+
+const log = (level: LogLevel, message: string, data?: any) => {
+  if (!isDebugMode()) return;
+
+  const timestamp = new Date().toISOString();
+  const prefix = `[${timestamp}] [react-broadcast-sync]`;
+  switch (level) {
+    case 'info':
+      console.log(prefix, message, data || '');
+      break;
+    case 'warn':
+      console.warn(prefix, message, data || '');
+      break;
+    case 'error':
+      console.error(prefix, message, data || '');
+      break;
+  }
+};
+
+export const debug = {
+  channel: {
+    created: (channelName: string) => log('info', 'Channel created:', channelName),
+    closed: (channelName: string) => log('info', 'Channel closed:', channelName),
+  },
+  message: {
+    sent: (message: any) => log('info', 'Message sent:', message),
+    received: (message: any) => log('info', 'Message received:', message),
+    cleared: (messageId: string) => log('info', 'Message cleared:', messageId),
+    expired: (messageId: string) => log('info', 'Message expired:', messageId),
+    duplicate: (messageId: string) => log('warn', 'Duplicate message ignored:', messageId),
+  },
+  cleanup: {
+    started: () => log('info', 'Cleanup started'),
+    completed: (removedCount: number) => log('info', 'Cleanup completed:', { removedCount }),
+  },
+  error: (error: string) => log('error', 'Error:', error),
+};