feat: add useSSE and useAudioPlayer

Author: shijistar

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 # Changelog
 
+## 1.4.9
+
+2025-9-2
+
+### Features
+
+#### hooks
+
+- ✨ add a new hook `useSSE` which provides a simple way to connect and communicate with a Server-Sent Events (SSE) server.
+- ✨ add a new hook `useAudioPlayer` used to play audio from a given source URL or streaming data.
+- ✨ add a new util `utils.arrayBufferToBase64` used to convert an ArrayBuffer to a Base64 encoded string.
+- ✨ add a new util `utils.base64ToArrayBuffer` used to convert a Base64 encoded string to an ArrayBuffer.
+
+### Notable Changes
+
+- 🔥 `utils.toBase64` method is renamed to `utils.stringToBase64`.
+- 🔥 `utils.fromBase64` method is renamed to `utils.base64ToString`.
+
+### Bug Fixes
+
+- 🐞 Fix sourcemap are not referenced correctly in `assets`
+
 ## 1.4.8
 
 2025-9-1

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-codes/react-easy",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "description": "Simplify React and AntDesign development with practical components and hooks",
   "keywords": [
     "react",
@@ -39,6 +39,7 @@
   },
   "dependencies": {
     "@lexical/react": "^0.33.1",
+    "@microsoft/fetch-event-source": "^2.0.1",
     "@stomp/stompjs": "^7.1.1",
     "i18next": "^24.2.3",
     "lexical": "^0.33.1",

package.json

@@ -1,5 +1,8 @@
+export { default as useAudioPlayer } from './useAudioPlayer';
 export { default as useRefValue } from './useRefValue';
 export { default as useRefFunction } from './useRefFunction';
+export * from './useSSE';
+export { default as useSSE } from './useSSE';
 export * from './useStompSocket';
 export { default as useStompSocket } from './useStompSocket';
 export type { ValidatorRuleMap } from './useValidators';

src/hooks/index.ts

@@ -0,0 +1,13 @@
+import { useRef } from 'react';
+import AudioPlayer, { type AudioPlayerInit } from '../utils/AudioPlayer';
+
+/**
+ * - **EN:** A hook that provides an instance of the AudioPlayer class for managing audio playback.
+ * - **CN:** 一个提供AudioPlayer类实例的钩子，用于管理音频播放。
+ */
+const useAudioPlayer = (props?: AudioPlayerInit): AudioPlayer => {
+  const ref = useRef<AudioPlayer>(new AudioPlayer(props));
+  return ref.current;
+};
+
+export default useAudioPlayer;

src/hooks/useAudioPlayer.ts

@@ -0,0 +1,123 @@
+import { useEffect, useRef, useState } from 'react';
+import type { EventSourceMessage, FetchEventSourceInit } from '@microsoft/fetch-event-source';
+import { fetchEventSource } from '@microsoft/fetch-event-source';
+import useRefFunction from './useRefFunction';
+import useRefValue from './useRefValue';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface UseSSEProps<T = any> {
+  /** The URL to connect to */
+  url: RequestInfo;
+  /** Options for the connection. */
+  connectOptions?: Omit<FetchEventSourceInit, 'onmessage' | 'onerror' | 'onclose'>;
+  /** Automatically connect to the SSE channel. Default is `false`. */
+  autoConnect?: boolean;
+  /** Automatically close the connection when the component unmounts. Default is `true`. */
+  autoClose?: boolean;
+  /** Function to parse the incoming message. If not provided, the default JSON parser will be used. */
+  parseMessage?: (original: EventSourceMessage) => T;
+  /** Callback function to handle incoming messages. */
+  onMessage?: (messageData: T) => void;
+  /** Callback function to handle errors. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onError?: (error: any) => void;
+  /** Callback function to handle connection closure. */
+  onClose?: () => void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const useSSE = <T = any>(props: UseSSEProps<T>) => {
+  const { url, autoConnect, connectOptions, onMessage, parseMessage, onError, onClose } = props;
+  const autoConnectRef = useRefValue(autoConnect);
+  const [isRequesting, setIsRequesting] = useState(false);
+  const isRequestingRef = useRefValue(isRequesting);
+  const [isConnected, setIsConnected] = useState<boolean>(false);
+  const abortCtrlRef = useRef<AbortController | undefined>(undefined);
+
+  const connect = useRefFunction(async (options?: FetchEventSourceInit & Partial<Pick<UseSSEProps, 'url'>>) => {
+    const {
+      url: connectUrl = url,
+      headers = {},
+      onopen,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      onmessage,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      onclose,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      onerror,
+      ...restOptions
+    } = { ...connectOptions, ...options };
+    abortCtrlRef.current = new AbortController();
+    try {
+      setIsRequesting(true);
+      setIsConnected(false);
+      await fetchEventSource(connectUrl, {
+        method: 'post',
+        signal: abortCtrlRef.current.signal,
+        openWhenHidden: true,
+        onopen: async (response: Response) => {
+          setIsConnected(true);
+          onopen?.(response);
+        },
+        onmessage(event) {
+          if (!isRequestingRef.current) {
+            setIsRequesting(false);
+          }
+          try {
+            let parsed: T;
+            if (parseMessage) {
+              parsed = parseMessage(event);
+            } else {
+              parsed = event.data ? JSON.parse(event.data) : undefined;
+            }
+            if (parsed != null) {
+              onMessage?.(parsed);
+            }
+          } catch (error) {
+            console.error('Error parsing message data:', error);
+            console.log('The underlying event:', event);
+          }
+        },
+        onerror(error) {
+          setIsRequesting(false);
+          onError?.(error);
+        },
+        onclose() {
+          setIsRequesting(false);
+          onClose?.();
+        },
+        headers: {
+          'Content-Type': 'application/json',
+          ...headers,
+        },
+        ...restOptions,
+      });
+    } finally {
+      setIsRequesting(false);
+    }
+  });
+
+  const close = useRefFunction(() => {
+    setIsConnected(false);
+    if (isConnected && abortCtrlRef.current) {
+      abortCtrlRef.current.abort();
+    }
+  });
+
+  useEffect(() => {
+    if (autoConnectRef.current) {
+      connect();
+    }
+    return close;
+  }, []);
+
+  // 清理函数
+  return {
+    connect,
+    close,
+    isRequesting,
+    isConnected,
+  };
+};
+
+export default useSSE;