[IMPL] useWebSocket hook

Author: nDriaDev

apps/react-tools-demo/src/components/hooks/useWebSocket/useWebSocket.md

@@ -109,7 +109,8 @@ export const COMPONENTS = [
 			"useAnimation",
 			"useAudio",
 			"useVideo",
-			"useEventSource"
+			"useEventSource",
+			"useWebSocket"
 		]
 	],
 	//UTILS

apps/react-tools-demo/src/constants/components.ts

@@ -11,27 +11,27 @@ useEventSource<T>({ url, opts, events, immediateConnection, onOpen, onError, onM
 >
 > - __param__: _UseEventSourceProps_  
 object
-> - __param.url__: _UseEventSourceProps_  
+> - __param.url?__: _string|URL_  
 string that represents the location of the remote resource serving the events/messages.
-> - __param.opts?__: _UseEventSourceProps_  
+> - __param.opts?__: _EventSourceInit_  
 options to configure the new connection. The possible entries are: __withCredentials__ -> boolean value, defaulting to false, indicating if CORS should be set to include credentials.
-> - __param.events?__: _UseEventSourceProps_  
+> - __param.events?__: _{name: string, handler?:(evt:MessagEvent)=>void}[]_  
 array of objects with properties __name__ and __handler__ to listen specified events from source.
-> - __param.immediateConnection?__: _UseEventSourceProps_  
+> - __param.immediateConnection?__: _boolean_  
 boolean to start connection immediatly.
-> - __param.onOpen?__: _UseEventSourceProps_  
+> - __param.onOpen?__: _(evt: Event)=>void_  
 function that will be executed when connection is opened.
-> - __param.onError?__: _UseEventSourceProps_  
+> - __param.onError?__: _(evt: Event)=>void_  
 function that will be executed when an error occurred.
-> - __param.onMessage?__: _UseEventSourceProps_  
+> - __param.onMessage?__: _(evt: MessageEvent<T>)=>void_  
 function that will be executed when a message from without event arrived.
 >
 
 > ### Returns
 >
 > __result__:  _UseEventSourceResult_  
 > Object with these properties:
-> - __status__: string rapresenting eventsource state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__
+> - __status__: string rapresenting eventsource state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__.
 > - __data__: last data value arrived from eventSource.
 > - __open__: function that opens connection.
 > - __close__: function that closes connection.

apps/react-tools-demo/src/markdown/useEventSource.md

@@ -0,0 +1,45 @@
+# useWebSocket
+Hook for creating and managing a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) connection to a server, as well as for sending and receiving data on the connection.
+
+## API
+
+```tsx
+useWebSocket<T = string | ArrayBuffer | Blob> ({ url, protocols, binaryType, onOpen, onMessage, onError, onClose, immediateConnection, bufferingData, autoReconnect }: UseWebSocketProps): UseWebSocketResult<T>
+```
+
+> ### Params
+>
+> - __param__: _UseWebSocketProps_  
+object
+> - __param.url?__: _UseWebSocketProps_  
+the URL to which to connect; this should be the URL to which the WebSocket server will respond.
+> - __param.protocols?__: _UseWebSocketProps_  
+either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols.
+> - __param.binaryType?__: _UseWebSocketProps_  
+the type of binary data being received over the WebSocket connection.
+> - __param.immediateConnection?__: _UseWebSocketProps_  
+boolean to open webSocket connection immediatly.
+> - __param.onOpen?__: _UseWebSocketProps_  
+function that will be executed when webSocket connection has been opened.
+> - __param.onMessage?__: _UseWebSocketProps_  
+function that will be executed when message arrived from webSocket.
+> - __param.onError?__: _UseWebSocketProps_  
+function that will be executed when an error occurred.
+> - __param.onClose?__: _UseWebSocketProps_  
+function that will be executed when webSocket connection has been closed.
+> - __param.bufferingData?__: _UseWebSocketProps_  
+boolean that indicates to use a buffer to keep data sent if connection aren't already opened.
+> - __param.autoReconnect?__: _UseWebSocketProps_  
+boolean or object with properties __retries__, __delay__ and __onFailed__. If an error closes connection and its value isn't false or undefined, a connection will be restored every _delay_ milliseconds for __retries__ time: if connection won't be restored __onFailed__ function will be executed if it is present.
+>
+
+> ### Returns
+>
+> __result__:  _UseWebSocketResult_  
+> Object with these properties:
+> - __status__: string rapresenting webSocket state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__.
+> - __data__: last data value arrived from webSocket.
+> - __open__: function that opens connection with optional _url_ param .
+> - __send__: function that sends data by webSocket.
+> - __close__: function that closes connection with optional _code_ and _reason_ params.
+>

apps/react-tools-demo/src/markdown/useWebSocket.md

@@ -112,9 +112,7 @@
 	- [x] useAudio
 	- [x] useVideo
 	- [x] useEventSource
-	- [ ] useWebSocket (https://vueuse.org/core/useWebSocket/)
-	- [ ] useFetch (with suspense ???)
-	- [ ] useAsync
+	- [x] useWebSocket
 	- [ ] useMedia
 	- [ ] useDevicesList (https://vueuse.org/core/useDevicesList/)
 	- [ ] useDisplayMedia
@@ -123,10 +121,11 @@
 	- [ ] useMediaStream
 	- [ ] useObservable — tracks latest value of an Observable
    	- [ ] usePointerTouchSwipe (https://vueuse.org/core/usePointerSwipe/ https://vueuse.org/core/useSwipe/)
-	- [ ] useLock - (https://developer.mozilla.org/en-US/docs/Web/API/LockManager/request)
-	- [ ] useIndexedDB
 	- [ ] useWebWorker (https://vueuse.org/core/useWebWorker/)
 	- [ ] useWebWorkerFn (https://vueuse.org/core/useWebWorkerFn/)
+	- [ ] useIndexedDB
+	- [ ] useFetch (with suspense ???)
+	- [ ] useLock - (https://developer.mozilla.org/en-US/docs/Web/API/LockManager/request)
 	- [ ] useIdleDetection (not work yet. https://developer.mozilla.org/en-US/docs/Web/API/Idle_Detection_API)
 
 - __UTILS__

packages/react-tools/README.md

@@ -89,4 +89,5 @@ export { useRemotePlayback } from './useRemotePlayback';
 export { useAnimation } from './useAnimation';
 export { useAudio } from './useAudio';
 export { useVideo } from './useVideo';
-export { useEventSource } from './useEventSource';
+export { useEventSource } from './useEventSource';
+export { useWebSocket } from './useWebSocket';

packages/react-tools/src/hooks/index.ts

@@ -1,20 +1,20 @@
 import { useCallback, useMemo, useRef } from "react";
 import { UseEventSourceProps, UseEventSourceResult } from "../models";
-import { useEffectOnce, useSyncExternalStore } from ".";
+import { useSyncExternalStore } from ".";
 
 /**
  * **`useEventSource`**: Hook to handle an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or [Server-Sent-Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) connection to an HTTP server, which sends events in text/event-stream format.
  * @param {UseEventSourceProps} param - object
- * @param {UseEventSourceProps} param.url - string that represents the location of the remote resource serving the events/messages.
- * @param {UseEventSourceProps} [param.opts] - options to configure the new connection. The possible entries are: __withCredentials__ -> boolean value, defaulting to false, indicating if CORS should be set to include credentials.
- * @param {UseEventSourceProps} [param.events] - array of objects with properties __name__ and __handler__ to listen specified events from source.
- * @param {UseEventSourceProps} [param.immediateConnection] - boolean to start connection immediatly.
- * @param {UseEventSourceProps} [param.onOpen] - function that will be executed when connection is opened.
- * @param {UseEventSourceProps} [param.onError] - function that will be executed when an error occurred.
- * @param {UseEventSourceProps} [param.onMessage] - function that will be executed when a message from without event arrived.
+ * @param {string|URL} [param.url] - string that represents the location of the remote resource serving the events/messages.
+ * @param {EventSourceInit} [param.opts] - options to configure the new connection. The possible entries are: __withCredentials__ -> boolean value, defaulting to false, indicating if CORS should be set to include credentials.
+ * @param {{name: string, handler?:(evt:MessagEvent)=>void}[]} [param.events] - array of objects with properties __name__ and __handler__ to listen specified events from source.
+ * @param {boolean} [param.immediateConnection] - boolean to start connection immediatly.
+ * @param {(evt: Event)=>void} [param.onOpen] - function that will be executed when connection is opened.
+ * @param {(evt: Event)=>void} [param.onError] - function that will be executed when an error occurred.
+ * @param {(evt: MessageEvent<T>)=>void} [param.onMessage] - function that will be executed when a message from without event arrived.
  * @returns {UseEventSourceResult} result
  * Object with these properties:
- * - __status__: string rapresenting eventsource state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__
+ * - __status__: string rapresenting eventsource state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__.
  * - __data__: last data value arrived from eventSource.
  * - __open__: function that opens connection.
  * - __close__: function that closes connection.
@@ -34,10 +34,10 @@ export const useEventSource = <T>({ url, opts, events, immediateConnection, onOp
 		}
 	}));
 	const cachedState = useRef<{ status: UseEventSourceResult<T>["status"], data: UseEventSourceResult<T>["data"] }>({
-		status: immediateConnection ? "CONNECTING" : "READY",
+		status: immediateConnection && url ? "CONNECTING" : "READY",
 		data: null
 	});
-	if (immediateConnection && !alreadyOpened.current) {
+	if (url && immediateConnection && !alreadyOpened.current) {
 		alreadyOpened.current = true;
 		sourceRef.current = new EventSource(url, opts);
 	}
@@ -76,10 +76,13 @@ export const useEventSource = <T>({ url, opts, events, immediateConnection, onOp
 		});
 	}
 
-	const open = useCallback(() => {
-		sourceRef.current = new EventSource(url, opts);
-		cachedState.current.status = "CONNECTING";
-		notifyRef.current && notifyRef.current();
+	const open = useCallback((urlParam?: UseEventSourceProps["url"]) => {
+		if (url || urlParam) {
+			const urlES = url ?? urlParam as string | URL;
+			sourceRef.current = new EventSource(urlES, opts);
+			cachedState.current.status = "CONNECTING";
+			notifyRef.current && notifyRef.current();
+		}
 	}, [opts, url]);
 
 	const close = useCallback(() => {
@@ -98,7 +101,7 @@ export const useEventSource = <T>({ url, opts, events, immediateConnection, onOp
 		}, []),
 		useMemo(() => {
 			let state: typeof cachedState.current = {
-				status: immediateConnection ? "CONNECTING" : "READY",
+				status: immediateConnection && url ? "CONNECTING" : "READY",
 				data: null
 			}
 			return () => {
@@ -109,13 +112,11 @@ export const useEventSource = <T>({ url, opts, events, immediateConnection, onOp
 				}
 				return state;
 			}
-		}, [immediateConnection])
+		}, [immediateConnection, url])
 	);
 
 	const data = useMemo(() => (state.data), [state.data]);
 
-	useEffectOnce(() => () => close());
-
 	return {
 		status: state.status,
 		data,

packages/react-tools/src/hooks/useEventSource.ts

@@ -0,0 +1,164 @@
+import { useCallback, useMemo, useRef } from "react";
+import { TypedArray, UseWebSocketProps, UseWebSocketResult } from "../models"
+import { useSyncExternalStore } from ".";
+
+/**
+ * **`useWebSocket`**: Hook for creating and managing a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) connection to a server, as well as for sending and receiving data on the connection.
+ * @param {UseWebSocketProps} param - object
+ * @param {UseWebSocketProps} [param.url] - the URL to which to connect; this should be the URL to which the WebSocket server will respond.
+ * @param {UseWebSocketProps} [param.protocols] - either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols.
+ * @param {UseWebSocketProps} [param.binaryType] - the type of binary data being received over the WebSocket connection.
+ * @param {UseWebSocketProps} [param.immediateConnection] - boolean to open webSocket connection immediatly.
+ * @param {UseWebSocketProps} [param.onOpen] - function that will be executed when webSocket connection has been opened.
+ * @param {UseWebSocketProps} [param.onMessage] - function that will be executed when message arrived from webSocket.
+ * @param {UseWebSocketProps} [param.onError] - function that will be executed when an error occurred.
+ * @param {UseWebSocketProps} [param.onClose] - function that will be executed when webSocket connection has been closed.
+ * @param {UseWebSocketProps} [param.bufferingData] - boolean that indicates to use a buffer to keep data sent if connection aren't already opened.
+ * @param {UseWebSocketProps} [param.autoReconnect] - boolean or object with properties __retries__, __delay__ and __onFailed__. If an error closes connection and its value isn't false or undefined, a connection will be restored every _delay_ milliseconds for __retries__ time: if connection won't be restored __onFailed__ function will be executed if it is present.
+ * @returns {UseWebSocketResult} result
+ * Object with these properties:
+ * - __status__: string rapresenting webSocket state connection: __READY__ __CONNECTING__ __OPENED__ or __CLOSED__.
+ * - __data__: last data value arrived from webSocket.
+ * - __open__: function that opens connection with optional _url_ param .
+ * - __send__: function that sends data by webSocket.
+ * - __close__: function that closes connection with optional _code_ and _reason_ params.
+ */
+export const useWebSocket = <T = string | ArrayBuffer | Blob> ({ url, protocols, binaryType, onOpen, onMessage, onError, onClose, immediateConnection, bufferingData, autoReconnect }: UseWebSocketProps): UseWebSocketResult<T> => {
+	const wsRef = useRef<WebSocket>();
+	const alreadyOpened = useRef(false);
+	const notifyRef = useRef<() => void>();
+	const dataBuffer = useRef<(string | ArrayBuffer | Blob | TypedArray)[]>([]);
+	const retryConnectId = useRef<ReturnType<typeof setTimeout>>();
+	const urlRef = useRef<UseWebSocketProps["url"]>(url);
+	const cachedState = useRef<{ status: UseWebSocketResult<T>["status"], data: UseWebSocketResult<T>["data"] }>({
+		status: immediateConnection && url ? "CONNECTING" : "READY",
+		data: null
+	});
+	const wsInitialized = !!wsRef.current;
+	const currentStatus = cachedState.current.status;
+
+	const sendBuffer = useCallback(() => {
+		if (bufferingData && wsInitialized && currentStatus === "OPENED") {
+			dataBuffer.current.forEach(data => {
+				wsRef.current!.send(data);
+			});
+			dataBuffer.current = [];
+		}
+	}, [bufferingData, currentStatus, wsInitialized])
+
+	if (url && immediateConnection && !alreadyOpened.current) {
+		wsRef.current = new WebSocket(url, protocols);
+	}
+
+	if (wsRef.current) {
+		binaryType && (wsRef.current.binaryType = binaryType);
+		wsRef.current.onopen = (evt: Event) => {
+			!!retryConnectId.current && clearInterval(retryConnectId.current);
+			cachedState.current.status = "OPENED";
+			!!onOpen && onOpen(evt);
+			notifyRef.current && notifyRef.current();
+			sendBuffer();
+		};
+		wsRef.current.onclose = (evt: CloseEvent) => {
+			cachedState.current.status = "CLOSED";
+			!!retryConnectId.current && clearInterval(retryConnectId.current);
+			!!onClose && onClose(evt);
+			wsRef.current = undefined;
+			notifyRef.current && notifyRef.current();
+		};
+		wsRef.current.onmessage = (evt: MessageEvent) => {
+			cachedState.current.data = evt.data;
+			!!onMessage && onMessage(evt);
+			notifyRef.current && notifyRef.current();
+		};
+		wsRef.current.onerror = (evt: Event) => {
+			cachedState.current.status = "CLOSED";
+			!!onError && onError(evt);
+			notifyRef.current && notifyRef.current();
+			if (autoReconnect && !retryConnectId.current) {
+				let retries: number, delay: number, onFailed: (() => void) | undefined;
+				if (typeof autoReconnect === "boolean") {
+					retries = 1;
+					delay = 1000;
+				} else {
+					retries = autoReconnect.retries;
+					delay = autoReconnect.delay;
+					onFailed = autoReconnect.onFailed;
+				}
+				retryConnectId.current = setInterval(() => {
+					if (retries === 0) {
+						clearInterval(retryConnectId.current);
+						retryConnectId.current = undefined;
+						!!onFailed && onFailed();
+					} else {
+						wsRef.current = undefined;
+						wsRef.current = new WebSocket(urlRef.current!, protocols);
+						cachedState.current.status = "CONNECTING";
+						notifyRef.current && notifyRef.current();
+					}
+				}, delay);
+			}
+		}
+	}
+
+	const open = useCallback((urlParam?: UseWebSocketProps["url"]) => {
+		if (!wsInitialized && (url || urlParam)) {
+			const urlWs = url || urlParam as string | URL;
+			wsRef.current = new WebSocket(urlWs, protocols);
+			binaryType && (wsRef.current.binaryType = binaryType);
+			cachedState.current.status = "CONNECTING";
+			notifyRef.current && notifyRef.current();
+		}
+	}, [protocols, url, wsInitialized, binaryType]);
+
+	const send = useCallback((data: string | ArrayBuffer | Blob | TypedArray) => {
+		if ((!wsInitialized || currentStatus !== "OPENED") && bufferingData) {
+			dataBuffer.current.push(data);
+		} else {
+			sendBuffer();
+			wsRef.current?.send(data);
+		}
+	}, [bufferingData, currentStatus, wsInitialized, sendBuffer]);
+
+	const close = useCallback((code?: number, reason?: string) => {
+		if (wsInitialized && currentStatus === "OPENED") {
+			wsRef.current?.close(code, reason);
+			cachedState.current.status = "CLOSED";
+			notifyRef.current && notifyRef.current();
+		}
+	}, [wsInitialized, currentStatus]);
+
+	const state = useSyncExternalStore(
+		useCallback(notif => {
+			notifyRef.current = notif;
+			return () => {
+				notifyRef.current = undefined;
+			}
+		}, []),
+		useMemo(() => {
+			let state: typeof cachedState.current = {
+				status: immediateConnection && url ? "CONNECTING" : "READY",
+				data: null
+			}
+			return () => {
+				if (state.data !== cachedState.current.data || state.status !== cachedState.current.status) {
+					state = {
+						...cachedState.current
+					}
+				}
+				return state;
+			}
+		}, [immediateConnection, url])
+	);
+
+	const status = useMemo(() => state.status, [state.status]);
+	const data = useMemo(() => state.data, [state.data]);
+
+	return {
+		status,
+		data,
+		open,
+		send,
+		close
+	}
+}