react-broadcast-sync 1.3.0 → 1.5.0

package/src/hooks/useBroadcastChannel.ts

@@ -3,10 +3,10 @@ import {
   BroadcastActions,
   BroadcastMessage,
   BroadcastOptions,
-  ClearMessage,
   ClearReceivedMessagesOptions,
   ClearSentMessagesOptions,
   GetLatestMessageOptions,
+  InternalMessage,
   SendMessageOptions,
 } from '../types/types';
 import {
@@ -20,10 +20,32 @@ import {
 } from '../utils/messageUtils';
 import { debug } from '../utils/debug';
 
-const INTERNAL_MESSAGE_TYPES: Record<string, ClearMessage> = {
+const INTERNAL_MESSAGE_TYPES: Record<string, InternalMessage> = {
   CLEAR_SENT_MESSAGES: 'CLEAR_SENT_MESSAGES',
+  PING: 'PING',
+  PONG: 'PONG',
 } as const;
 
+let flushSyncFn: undefined | ((cb: () => void) => void) = undefined;
+if (process.env.NODE_ENV === 'test') {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    flushSyncFn = require('react-dom').flushSync;
+  } catch {
+    // ignore error in test env
+  }
+}
+
+/**
+ * useBroadcastChannel hook
+ *
+ * Note: When batching is enabled (batchingDelayMs > 0), messages sent over the channel may be received as either:
+ *   - a single BroadcastMessage (object), or
+ *   - an array of BroadcastMessage (batch)
+ *
+ * The event handler in this hook supports both formats. If you listen to the channel directly, always check:
+ *   if (Array.isArray(event.data)) { ... } else { ... }
+ */
 export const useBroadcastChannel = (
   channelName: string,
   options: BroadcastOptions = {}
@@ -36,16 +58,25 @@ export const useBroadcastChannel = (
     namespace = '',
     deduplicationTTL = 5 * 60 * 1000,
     cleanupDebounceMs = 0,
+    batchingDelayMs = 20,
+    excludedBatchMessageTypes = [],
   } = options;
 
   // State
   const [messages, setMessages] = useState<BroadcastMessage[]>([]);
   const [sentMessages, setSentMessages] = useState<BroadcastMessage[]>([]);
   const [error, setError] = useState<string | null>(null);
+  const [isPingInProgress, setIsPingInProgress] = useState(false);
 
   // Refs
   const channel = useRef<BroadcastChannel | null>(null);
   const receivedMessageIds = useRef(new Map<string, number>());
+  const activeSourcesCollector = useRef<Set<string> | null>(null);
+  const batchingTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const batchingMessagesRef = useRef<BroadcastMessage[]>([]);
+  const batchingErrorRef = useRef(false);
+
+  // Memoized values
   const source = useMemo(() => sourceName || generateSourceName(), [sourceName]);
   const internalTypes = useMemo(
     () => ({
@@ -54,12 +85,15 @@ export const useBroadcastChannel = (
         channelName,
         namespace
       ),
+      PING: getInternalMessageType(INTERNAL_MESSAGE_TYPES.PING, channelName, namespace),
+      PONG: getInternalMessageType(INTERNAL_MESSAGE_TYPES.PONG, channelName, namespace),
     }),
     [channelName, namespace]
   );
 
   const resolvedChannelName = useMemo(() => {
-    return `${channelName}-${namespace}`;
+    // Only append dash if namespace is non-empty
+    return namespace ? `${channelName}-${namespace}` : channelName;
   }, [channelName, namespace]);
 
   const stableRegisteredTypes = useMemo(() => registeredTypes, [JSON.stringify(registeredTypes)]);
@@ -82,6 +116,45 @@ export const useBroadcastChannel = (
     setTimeout(() => setError(null), 3000);
   }, []);
 
+  const ping = useCallback(
+    (timeoutMs: number = 300): Promise<string[]> => {
+      if (isPingInProgress) {
+        debug.ping.inProgress();
+        return Promise.resolve([]);
+      }
+
+      if (!channel.current) {
+        const error =
+          'BroadcastChannel is not supported in this browser. Please check browser compatibility.';
+        debug.error(error);
+        setErrorMessage(error);
+        return Promise.resolve([]);
+      }
+
+      // Set synchronously before returning the promise
+      if (flushSyncFn) {
+        flushSyncFn(() => setIsPingInProgress(true));
+      } else {
+        setIsPingInProgress(true);
+      }
+      const collector = new Set<string>();
+      activeSourcesCollector.current = collector;
+
+      channel.current.postMessage(createMessage(internalTypes.PING, null, source));
+
+      return new Promise(resolve => {
+        setTimeout(() => {
+          setIsPingInProgress(false);
+          if (activeSourcesCollector.current === collector) {
+            activeSourcesCollector.current = null;
+          }
+          resolve(Array.from(collector));
+        }, timeoutMs);
+      });
+    },
+    [internalTypes.PING, source, setErrorMessage, isPingInProgress, flushSyncFn]
+  );
+
   const postMessage = useCallback(
     (messageType: string, messageContent: any, options: SendMessageOptions = {}) => {
       const channelCurrent = channel.current;
@@ -93,18 +166,45 @@ export const useBroadcastChannel = (
         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);
+      const message = createMessage(messageType, messageContent, source, options);
+      // Only batch if batchingDelayMs > 0 and messageType is not excluded
+      const shouldSendImmediately =
+        !batchingDelayMs || batchingDelayMs < 0 || excludedBatchMessageTypes.includes(messageType);
+      if (shouldSendImmediately) {
+        try {
+          channelCurrent.postMessage(message);
+        } catch (e) {
+          const error = 'Failed to send message';
+          debug.error(error);
+          setErrorMessage(error);
+          batchingErrorRef.current = true;
+        }
+      } else {
+        batchingMessagesRef.current.push(message);
+        if (!batchingTimeoutRef.current) {
+          batchingTimeoutRef.current = setTimeout(() => {
+            if (batchingErrorRef.current) {
+              batchingMessagesRef.current = [];
+              batchingTimeoutRef.current = null;
+              return;
+            }
+            try {
+              channelCurrent.postMessage(batchingMessagesRef.current);
+            } catch (e) {
+              const error = 'Failed to send message';
+              debug.error(error);
+              setErrorMessage(error);
+              batchingErrorRef.current = true;
+            }
+            batchingMessagesRef.current = [];
+            batchingTimeoutRef.current = null;
+          }, batchingDelayMs);
+        }
       }
+      debug.message.sent(message);
+      setSentMessages(prev => [...prev, message]);
     },
-    [source, setErrorMessage]
+    [source, setErrorMessage, batchingDelayMs, excludedBatchMessageTypes]
   );
 
   const clearReceivedMessages = useCallback((options: ClearReceivedMessagesOptions = {}) => {
@@ -197,12 +297,25 @@ export const useBroadcastChannel = (
                 const idMatches = ids.length === 0 || ids.includes(msg.id);
                 const typeMatches = types.length === 0 || types.includes(msg.type);
 
-                // Remove when BOTH criteria match (wildcards included)
                 return !(idMatches && typeMatches);
               }),
             ]);
 
-            // After handling we don't want to process this internal control packet further
+            return;
+          }
+          if (message.type === internalTypes.PING) {
+            channel.current?.postMessage(createMessage(internalTypes.PONG, null, source));
+            return;
+          }
+
+          if (message.type === internalTypes.PONG) {
+            const pongSource = message.source;
+            const collector = activeSourcesCollector.current;
+
+            if (collector && collector.has(pongSource) === false) {
+              collector.add(pongSource);
+            }
+
             return;
           }
         }
@@ -263,7 +376,16 @@ export const useBroadcastChannel = (
     channel.current = bc;
     debug.channel.created(resolvedChannelName);
 
-    bc.addEventListener('message', handleMessage);
+    bc.addEventListener('message', (event: MessageEvent) => {
+      // event.data may be a single message or an array of messages (batch)
+      if (Array.isArray(event.data)) {
+        event.data.forEach((message: BroadcastMessage) => {
+          handleMessage({ data: message } as MessageEvent<BroadcastMessage>);
+        });
+      } else {
+        handleMessage(event);
+      }
+    });
     return () => {
       closeChannel();
     };
@@ -291,9 +413,9 @@ export const useBroadcastChannel = (
   useEffect(() => {
     const interval = setInterval(() => {
       const now = Date.now();
-      for (const [id, timestamp] of receivedMessageIds.current.entries()) {
+      for (const [key, timestamp] of receivedMessageIds.current.entries()) {
         if (now - timestamp >= deduplicationTTL) {
-          receivedMessageIds.current.delete(id);
+          receivedMessageIds.current.delete(key);
         }
       }
     }, 60 * 1000);
@@ -301,10 +423,35 @@ export const useBroadcastChannel = (
     return () => clearInterval(interval);
   }, [deduplicationTTL]);
 
+  useEffect(() => {
+    return () => {
+      // Always flush any unsent batched messages on unmount
+      if (batchingMessagesRef.current.length > 0 && channel.current && !batchingErrorRef.current) {
+        try {
+          channel.current.postMessage(batchingMessagesRef.current);
+        } catch (e) {
+          const error = 'Failed to send message';
+          debug.error(error);
+          setErrorMessage(error);
+        }
+        batchingMessagesRef.current = [];
+        // Allow event loop to process delivery for tests
+        setTimeout(() => {}, 0);
+      }
+      if (batchingTimeoutRef.current) {
+        clearTimeout(batchingTimeoutRef.current);
+        batchingTimeoutRef.current = null;
+      }
+      batchingErrorRef.current = false;
+    };
+  }, []);
+
   return {
     channelName: resolvedChannelName,
     messages,
     sentMessages,
+    isPingInProgress,
+    ping,
     postMessage,
     clearReceivedMessages,
     clearSentMessages,

package/src/tests/BroadcastProvider.test.tsx

@@ -65,7 +65,7 @@ describe('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[0].name).toBe('test-channel');
     expect(mockChannels[1].name).toBe('test-channel');
   });
 

package/src/tests/useBroadcastChannel.same-tab.test.tsx

@@ -16,7 +16,12 @@ class MockBroadcastChannel {
       if (channel.onmessage) {
         // Use setTimeout to simulate async behavior
         setTimeout(() => {
-          channel.onmessage!({ data } as MessageEvent);
+          // Support both single and batched (array) messages
+          if (Array.isArray(data)) {
+            data.forEach(msg => channel.onmessage!({ data: msg } as MessageEvent));
+          } else {
+            channel.onmessage!({ data } as MessageEvent);
+          }
         }, 0);
       }
     });
@@ -37,7 +42,12 @@ class MockBroadcastChannel {
   simulateMessage(data: any) {
     if (this.onmessage) {
       setTimeout(() => {
-        this.onmessage!({ data } as MessageEvent);
+        // Support both single and batched (array) messages
+        if (Array.isArray(data)) {
+          data.forEach(msg => this.onmessage!({ data: msg } as MessageEvent));
+        } else {
+          this.onmessage!({ data } as MessageEvent);
+        }
       }, 0);
     }
   }
@@ -74,6 +84,7 @@ describe('useBroadcastChannel - Same Tab Multi-Hook Behavior', () => {
   const testOptions = {
     cleaningInterval: 0, // Disable auto cleanup to avoid act warnings
     deduplicationTTL: 60000, // Long TTL for tests
+    batchingDelayMs: 0, // Disable batching for immediate delivery in tests
   };
 
   describe('1. Two Hooks with Different Source Names', () => {
@@ -204,8 +215,8 @@ describe('useBroadcastChannel - Same Tab Multi-Hook Behavior', () => {
       await waitForAsync();
 
       // Verify both hooks are working (channel name includes namespace suffix)
-      expect(hook1.current.channelName).toBe(`${CHANNEL_NAME}-`);
-      expect(hook2.current.channelName).toBe(`${CHANNEL_NAME}-`);
+      expect(hook1.current.channelName).toBe(`${CHANNEL_NAME}`);
+      expect(hook2.current.channelName).toBe(`${CHANNEL_NAME}`);
 
       // Unmount hook1
       unmount1();