feat: add useSse hooks

Author: meet-student

config/hooks.ts

@@ -32,6 +32,7 @@ export const menus = [
       'useTextSelection',
       'useWebSocket',
       'useTheme',
+      'useSse',
     ],
   },
   {

packages/hooks/src/index.ts

@@ -73,6 +73,7 @@ import useUpdateEffect from './useUpdateEffect';
 import useUpdateLayoutEffect from './useUpdateLayoutEffect';
 import useVirtualList from './useVirtualList';
 import useWebSocket from './useWebSocket';
+import useSse from './useSse';
 import useWhyDidYouUpdate from './useWhyDidYouUpdate';
 import useMutationObserver from './useMutationObserver';
 import useTheme from './useTheme';
@@ -133,6 +134,7 @@ export {
   useFavicon,
   useCountDown,
   useWebSocket,
+  useSse,
   useLockFn,
   useUnmountedRef,
   useExternal,

packages/hooks/src/useSse/__tests__/index.spec.ts

@@ -0,0 +1,103 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import useSse, { ReadyState } from '../index';
+
+class MockEventSource {
+  url: string;
+  withCredentials: boolean;
+  readyState: number;
+  onopen: ((this: EventSource, ev: Event) => any) | null = null;
+  onmessage: ((this: EventSource, ev: MessageEvent) => any) | null = null;
+  onerror: ((this: EventSource, ev: Event) => any) | null = null;
+  private listeners: Record<string, Array<(ev: Event) => void>> = {};
+
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSED = 2;
+
+  constructor(url: string, init?: EventSourceInit) {
+    this.url = url;
+    this.withCredentials = Boolean(init?.withCredentials);
+    this.readyState = MockEventSource.CONNECTING;
+    setTimeout(() => {
+      this.readyState = MockEventSource.OPEN;
+      this.onopen && this.onopen(new Event('open'));
+    }, 10);
+  }
+
+  addEventListener(type: string, listener: (ev: Event) => void) {
+    if (!this.listeners[type]) this.listeners[type] = [];
+    this.listeners[type].push(listener);
+  }
+
+  dispatchEvent(type: string, event: Event) {
+    this.listeners[type]?.forEach((l) => l(event));
+  }
+
+  emitMessage(data: any) {
+    this.onmessage && this.onmessage(new MessageEvent('message', { data }));
+  }
+
+  emitError() {
+    this.onerror && this.onerror(new Event('error'));
+  }
+
+  close() {
+    this.readyState = MockEventSource.CLOSED;
+  }
+}
+
+describe('useSse', () => {
+  const OriginalEventSource = (globalThis as any).EventSource;
+
+  afterEach(() => {
+    (globalThis as any).EventSource = OriginalEventSource;
+  });
+
+  test('should connect and receive message', async () => {
+    (globalThis as any).EventSource = MockEventSource as any;
+
+    const hooks = renderHook(() => useSse('/sse'));
+
+    // not manual: should start connecting immediately
+    expect(hooks.result.current.readyState).toBe(ReadyState.Connecting);
+
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 20));
+    });
+
+    expect(hooks.result.current.readyState).toBe(ReadyState.Open);
+
+    act(() => {
+      const es = hooks.result.current.eventSource as unknown as MockEventSource;
+      es.emitMessage('hello');
+    });
+    expect(hooks.result.current.latestMessage?.data).toBe('hello');
+  });
+
+  test('manual should not auto connect', async () => {
+    (globalThis as any).EventSource = MockEventSource as any;
+
+    const hooks = renderHook(() => useSse('/sse', { manual: true }));
+    expect(hooks.result.current.readyState).toBe(ReadyState.Closed);
+
+    await act(async () => {
+      hooks.result.current.connect();
+      await new Promise((r) => setTimeout(r, 20));
+    });
+
+    expect(hooks.result.current.readyState).toBe(ReadyState.Open);
+  });
+
+  test('disconnect should close', async () => {
+    (globalThis as any).EventSource = MockEventSource as any;
+
+    const hooks = renderHook(() => useSse('/sse'));
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 20));
+    });
+    expect(hooks.result.current.readyState).toBe(ReadyState.Open);
+    act(() => hooks.result.current.disconnect());
+    expect(hooks.result.current.readyState).toBe(ReadyState.Closed);
+  });
+});

packages/hooks/src/useSse/demo/demo1.tsx

@@ -0,0 +1,39 @@
+import React, { useMemo, useRef } from 'react';
+import { useSse } from 'ahooks';
+
+enum ReadyState {
+  Connecting = 0,
+  Open = 1,
+  Closed = 2,
+}
+
+export default () => {
+  const historyRef = useRef<any[]>([]);
+  const { readyState, latestMessage, connect, disconnect } = useSse('/api/sse');
+
+  historyRef.current = useMemo(() => historyRef.current.concat(latestMessage), [latestMessage]);
+
+  return (
+    <div>
+      <button onClick={() => connect()} style={{ marginRight: 8 }}>
+        {readyState === ReadyState.Connecting ? 'connecting' : 'connect'}
+      </button>
+      <button
+        onClick={() => disconnect()}
+        style={{ marginRight: 8 }}
+        disabled={readyState !== ReadyState.Open}
+      >
+        disconnect
+      </button>
+      <div style={{ marginTop: 8 }}>readyState: {readyState}</div>
+      <div style={{ marginTop: 8 }}>
+        <p>received message: </p>
+        {historyRef.current.map((m, i) => (
+          <p key={i} style={{ wordWrap: 'break-word' }}>
+            {m?.data}
+          </p>
+        ))}
+      </div>
+    </div>
+  );
+};

packages/hooks/src/useSse/index.en-US.md

@@ -0,0 +1,54 @@
+---
+nav:
+  path: /hooks
+---
+
+# useSse
+
+Listen to Server-Sent Events (SSE) stream with auto reconnect and lifecycle helpers.
+
+### Examples
+
+```tsx
+import React, { useMemo, useRef } from 'react';
+import { useSse } from 'ahooks';
+
+export default () => {
+  const historyRef = useRef<any[]>([]);
+  const { readyState, latestMessage, connect, disconnect } = useSse('/api/sse');
+
+  historyRef.current = useMemo(() => historyRef.current.concat(latestMessage), [latestMessage]);
+
+  return (
+    <div>
+      <button onClick={() => connect()} style={{ marginRight: 8 }}>connect</button>
+      <button onClick={() => disconnect()} style={{ marginRight: 8 }}>disconnect</button>
+      <div>readyState: {readyState}</div>
+      <div style={{ marginTop: 8 }}>
+        {historyRef.current.map((m, i) => (
+          <p key={i}>{m?.data}</p>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+### API
+
+```ts
+const { readyState, latestMessage, connect, disconnect, eventSource } = useSse(
+  url: string,
+  options?: {
+    manual?: boolean;
+    withCredentials?: boolean;
+    reconnectLimit?: number;
+    reconnectInterval?: number; // ms
+    events?: string[]; // named events
+    onOpen?: (ev: Event, instance: EventSource) => void;
+    onMessage?: (msg: MessageEvent, instance: EventSource) => void;
+    onError?: (ev: Event, instance: EventSource) => void;
+    onEvent?: (eventName: string, ev: MessageEvent, instance: EventSource) => void;
+  }
+)
+```

packages/hooks/src/useSse/index.ts

@@ -0,0 +1,158 @@
+import { useEffect, useRef, useState } from 'react';
+import useLatest from '../useLatest';
+import useMemoizedFn from '../useMemoizedFn';
+import useUnmount from '../useUnmount';
+
+export enum ReadyState {
+  Connecting = 0,
+  Open = 1,
+  Closed = 2,
+}
+
+export interface Options {
+  manual?: boolean;
+  withCredentials?: boolean;
+  reconnectLimit?: number;
+  reconnectInterval?: number;
+  events?: string[];
+  onOpen?: (event: Event, instance: EventSource) => void;
+  onMessage?: (message: MessageEvent, instance: EventSource) => void;
+  onError?: (event: Event, instance: EventSource) => void;
+  onEvent?: (eventName: string, event: MessageEvent, instance: EventSource) => void;
+}
+
+export interface Result {
+  latestMessage?: MessageEvent;
+  connect: () => void;
+  disconnect: () => void;
+  readyState: ReadyState;
+  eventSource?: EventSource;
+}
+
+function useSse(url: string, options: Options = {}): Result {
+  const {
+    manual = false,
+    withCredentials = false,
+    reconnectLimit = 3,
+    reconnectInterval = 3 * 1000,
+    events = [],
+    onOpen,
+    onMessage,
+    onError,
+    onEvent,
+  } = options;
+
+  const onOpenRef = useLatest(onOpen);
+  const onMessageRef = useLatest(onMessage);
+  const onErrorRef = useLatest(onError);
+  const onEventRef = useLatest(onEvent);
+
+  const reconnectTimesRef = useRef(0);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const esRef = useRef<EventSource>(undefined);
+
+  const [latestMessage, setLatestMessage] = useState<MessageEvent>();
+  const [readyState, setReadyState] = useState<ReadyState>(ReadyState.Closed);
+
+  const reconnect = () => {
+    if (
+      reconnectTimesRef.current < reconnectLimit &&
+      esRef.current?.readyState !== ReadyState.Open
+    ) {
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current);
+      }
+      reconnectTimerRef.current = setTimeout(() => {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        connectEs();
+        reconnectTimesRef.current++;
+      }, reconnectInterval);
+    }
+  };
+
+  const bindNamedEvents = (es: EventSource) => {
+    events.forEach((eventName) => {
+      es.addEventListener(eventName, (e) => {
+        onEventRef.current?.(eventName, e as MessageEvent, es);
+      });
+    });
+  };
+
+  const connectEs = () => {
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+    }
+
+    if (esRef.current) {
+      esRef.current.close();
+    }
+
+    const es = new EventSource(url, { withCredentials });
+    setReadyState(ReadyState.Connecting);
+
+    es.onopen = (event) => {
+      if (esRef.current !== es) return;
+      reconnectTimesRef.current = 0;
+      setReadyState(ReadyState.Open);
+      onOpenRef.current?.(event, es);
+    };
+
+    es.onmessage = (message) => {
+      if (esRef.current !== es) return;
+      setLatestMessage(message);
+      onMessageRef.current?.(message, es);
+    };
+
+    es.onerror = (event) => {
+      // Note: native EventSource auto-reconnects. We still provide a manual reconnect mechanism
+      // to give users control when connection is closed or encounters persistent errors.
+      onErrorRef.current?.(event, es);
+      // If closed by server or network, try manual reconnect
+      if (esRef.current === es && es.readyState === EventSource.CLOSED) {
+        setReadyState(ReadyState.Closed);
+        reconnect();
+      } else {
+        setReadyState((es.readyState as ReadyState) ?? ReadyState.Connecting);
+      }
+    };
+
+    bindNamedEvents(es);
+
+    esRef.current = es;
+  };
+
+  const connect = () => {
+    reconnectTimesRef.current = 0;
+    connectEs();
+  };
+
+  const disconnect = () => {
+    if (reconnectTimerRef.current) {
+      clearTimeout(reconnectTimerRef.current);
+    }
+    reconnectTimesRef.current = reconnectLimit;
+    esRef.current?.close();
+    esRef.current = undefined;
+    setReadyState(ReadyState.Closed);
+  };
+
+  useEffect(() => {
+    if (!manual && url) {
+      connect();
+    }
+  }, [url, manual, withCredentials]);
+
+  useUnmount(() => {
+    disconnect();
+  });
+
+  return {
+    latestMessage,
+    connect: useMemoizedFn(connect),
+    disconnect: useMemoizedFn(disconnect),
+    readyState,
+    eventSource: esRef.current,
+  };
+}
+
+export default useSse;