react-ws-context 0.1.0

package/dist/index.mjs

@@ -0,0 +1,403 @@
+"use client";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/ws-context/emitter.ts
+function createEmitter() {
+	return {
+		events: {},
+		emit(event, ...args) {
+			const callbacks = this.events[event] || [];
+			for (let i = 0, len = callbacks.length; i < len; i++) callbacks[i](...args);
+		},
+		on(event, cb) {
+			(this.events[event] ||= []).push(cb);
+			return () => {
+				this.events[event] = this.events[event]?.filter((fn) => fn !== cb);
+			};
+		}
+	};
+}
+function useEmitter() {
+	const [emitter] = useState(() => createEmitter());
+	return emitter;
+}
+//#endregion
+//#region src/ws-context/ws-events.ts
+function createWsEventsContext() {
+	return createContext(null);
+}
+function createUseWsEvents(EmitterCtx) {
+	function useWsEvents(type, handler) {
+		const emitter = useContext(EmitterCtx);
+		if (!emitter) throw new Error("useWsEvents 必須包在對應的 WsProvider 內");
+		const handlerRef = useRef(handler);
+		handlerRef.current = handler;
+		useEffect(() => {
+			return emitter.on(type, ((...args) => {
+				handlerRef.current(...args);
+			}));
+		}, [type, emitter]);
+	}
+	return useWsEvents;
+}
+//#endregion
+//#region src/ws-context/liveness/resolve-ping.ts
+function resolvePingPayload(ping) {
+	return typeof ping === "function" ? ping() : ping;
+}
+//#endregion
+//#region src/ws-context/liveness/controller.ts
+function createLivenessController(options, onTimeout) {
+	const { intervalMs, timeoutMs, isPong } = options;
+	let intervalId = null;
+	let timeoutId = null;
+	let sendPingRef = null;
+	function clearTimeoutTimer() {
+		if (timeoutId != null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	}
+	function armTimeout() {
+		clearTimeoutTimer();
+		timeoutId = setTimeout(onTimeout, timeoutMs);
+	}
+	function tick() {
+		sendPingRef?.();
+		armTimeout();
+	}
+	return {
+		start(sendPing) {
+			sendPingRef = sendPing;
+			tick();
+			intervalId = setInterval(tick, intervalMs);
+		},
+		stop() {
+			if (intervalId != null) {
+				clearInterval(intervalId);
+				intervalId = null;
+			}
+			clearTimeoutTimer();
+			sendPingRef = null;
+		},
+		onMessage(data) {
+			if (isPong(data)) clearTimeoutTimer();
+		}
+	};
+}
+function createPingSender(ping, sendJson) {
+	return () => {
+		sendJson(resolvePingPayload(ping));
+	};
+}
+//#endregion
+//#region src/ws-context/liveness/liveness.ts
+const DISABLED_LIVENESS = {
+	start() {},
+	stop() {},
+	onMessage() {}
+};
+function createLiveness(options, getActiveSocket) {
+	let controller = null;
+	return {
+		start(ws) {
+			controller?.stop();
+			controller = createLivenessController(options, () => {
+				const current = getActiveSocket();
+				if (current?.readyState === WebSocket.OPEN) current.close();
+			});
+			const sendPing = createPingSender(options.ping, (data) => {
+				if (ws.readyState !== WebSocket.OPEN) return false;
+				ws.send(JSON.stringify(data));
+				return true;
+			});
+			controller.start(sendPing);
+		},
+		stop() {
+			controller?.stop();
+			controller = null;
+		},
+		onMessage(data) {
+			controller?.onMessage(data);
+		}
+	};
+}
+function useLiveness(options, getActiveSocket) {
+	const [session] = useState(() => options ? createLiveness(options, getActiveSocket) : DISABLED_LIVENESS);
+	return session;
+}
+//#endregion
+//#region src/ws-context/outgoing-queue.ts
+function createOutgoingQueue(max) {
+	let items = [];
+	return {
+		enqueue(data) {
+			if (max <= 0 || items.length >= max) return false;
+			items.push(data);
+			return true;
+		},
+		clear() {
+			items = [];
+		},
+		flush(send) {
+			const queued = items;
+			items = [];
+			for (const data of queued) send(data);
+		}
+	};
+}
+function useOutgoingQueue(max) {
+	const [queue] = useState(() => createOutgoingQueue(max));
+	return queue;
+}
+//#endregion
+//#region src/ws-context/store.ts
+function createStore(initialState) {
+	let state = initialState;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		getState: () => state,
+		getInitialState: () => initialState,
+		setState: (partial) => {
+			const nextPartial = typeof partial === "function" ? partial(state) : partial;
+			if (Object.is(nextPartial, state)) return;
+			const prev = state;
+			state = Object.assign({}, state, nextPartial);
+			for (const listener of listeners) listener(state, prev);
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+//#endregion
+//#region src/ws-context/use-store.ts
+function useStore(store, selector) {
+	return useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getInitialState()));
+}
+//#endregion
+//#region src/ws-context/ws-store.ts
+function createWsStore(init = "idle") {
+	return createStore({ status: init });
+}
+/** 每個 `WsProvider` 各有一份 {@link WsState} store */
+function useWsStoreApi() {
+	const [store] = useState(() => createWsStore());
+	return store;
+}
+function createWsStoreContext() {
+	return createContext(null);
+}
+/** 訂閱 {@link WsState}；建議以 selector 只取需要的連線層欄位。 */
+function createUseWsStore(StoreCtx) {
+	function useWsStore(selector) {
+		const store = useContext(StoreCtx);
+		if (!store) throw new Error("useWsStore 必須包在對應的 WsProvider 內");
+		return useStore(store, selector ?? ((state) => state));
+	}
+	return useWsStore;
+}
+//#endregion
+//#region src/ws-context/ws-actions.ts
+function createWsActionsContext() {
+	return createContext(null);
+}
+function createUseWsActions(ActionsCtx) {
+	function useWsActions() {
+		const value = useContext(ActionsCtx);
+		if (!value) throw new Error("useWsActions 必須包在對應的 WsProvider 內");
+		return value;
+	}
+	return useWsActions;
+}
+//#endregion
+//#region src/ws-context/socket.ts
+function detachAndClose(ws) {
+	ws.onopen = null;
+	ws.onmessage = null;
+	ws.onerror = null;
+	ws.onclose = null;
+	if (ws.readyState < WebSocket.CLOSING) ws.close();
+}
+function clearReconnectTimer(timerRef) {
+	if (timerRef.current != null) {
+		clearTimeout(timerRef.current);
+		timerRef.current = null;
+	}
+}
+function clientCloseEvent(reason) {
+	return new CloseEvent("close", {
+		code: 1e3,
+		reason,
+		wasClean: true
+	});
+}
+//#endregion
+//#region src/ws-context/index.tsx
+function defaultParse(data) {
+	if (typeof data !== "string") return data;
+	try {
+		return JSON.parse(data);
+	} catch {
+		return data;
+	}
+}
+/**
+* @example
+* ```ts
+* export const { WsProvider, useWsActions, useWsStore, useWsEvents } =
+*   createWsContext({ url: "ws://localhost:8080" });
+* ```
+*/
+function createWsContext(options) {
+	const { url, protocols, autoConnect = true, reconnectMs = 0, outgoingQueueMax = 0, parse = defaultParse, liveness } = options;
+	const ActionsCtx = createWsActionsContext();
+	const useWsActions = createUseWsActions(ActionsCtx);
+	const StoreCtx = createWsStoreContext();
+	const useWsStore = createUseWsStore(StoreCtx);
+	const EmitterCtx = createWsEventsContext();
+	const useWsEvents = createUseWsEvents(EmitterCtx);
+	function WsProvider({ children }) {
+		const wsRef = useRef(null);
+		const store = useWsStoreApi();
+		const emitter = useEmitter();
+		const intentionalCloseRef = useRef(false);
+		const reconnectTimerRef = useRef(null);
+		const outgoingQueue = useOutgoingQueue(outgoingQueueMax);
+		const livenessSession = useLiveness(liveness, () => wsRef.current);
+		const setStatus = useCallback((status) => {
+			store.setState({ status });
+		}, [store]);
+		const getStatus = useCallback(() => store.getState().status, [store]);
+		const disconnect = useCallback(() => {
+			intentionalCloseRef.current = true;
+			clearReconnectTimer(reconnectTimerRef);
+			livenessSession.stop();
+			outgoingQueue.clear();
+			const ws = wsRef.current;
+			wsRef.current = null;
+			if (ws) {
+				detachAndClose(ws);
+				setStatus("closed");
+				emitter.emit("close", clientCloseEvent("client disconnect"));
+			} else setStatus("closed");
+		}, [
+			setStatus,
+			emitter,
+			outgoingQueue,
+			livenessSession
+		]);
+		const connect = useCallback(() => {
+			if (typeof window === "undefined") return;
+			clearReconnectTimer(reconnectTimerRef);
+			intentionalCloseRef.current = false;
+			livenessSession.stop();
+			const prev = wsRef.current;
+			if (prev) {
+				wsRef.current = null;
+				detachAndClose(prev);
+				emitter.emit("close", clientCloseEvent("reconnect"));
+			}
+			setStatus("connecting");
+			const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
+			wsRef.current = ws;
+			ws.onopen = (event) => {
+				if (wsRef.current !== ws) return;
+				setStatus("open");
+				outgoingQueue.flush((data) => ws.send(data));
+				livenessSession.start(ws);
+				emitter.emit("open", event);
+			};
+			ws.onmessage = (event) => {
+				if (wsRef.current !== ws) return;
+				const data = parse(event.data);
+				livenessSession.onMessage(data);
+				emitter.emit("message", data, event);
+			};
+			ws.onerror = (event) => {
+				if (wsRef.current !== ws) return;
+				emitter.emit("error", event);
+			};
+			ws.onclose = (event) => {
+				if (wsRef.current === ws) wsRef.current = null;
+				livenessSession.stop();
+				setStatus("closed");
+				emitter.emit("close", event);
+				if (intentionalCloseRef.current || reconnectMs <= 0) return;
+				reconnectTimerRef.current = setTimeout(() => {
+					connect();
+				}, reconnectMs);
+			};
+		}, [
+			setStatus,
+			emitter,
+			outgoingQueue,
+			livenessSession
+		]);
+		useEffect(() => {
+			if (autoConnect) connect();
+			return () => {
+				intentionalCloseRef.current = true;
+				clearReconnectTimer(reconnectTimerRef);
+				livenessSession.stop();
+				outgoingQueue.clear();
+				const ws = wsRef.current;
+				wsRef.current = null;
+				if (ws) {
+					detachAndClose(ws);
+					emitter.emit("close", clientCloseEvent("provider unmount"));
+				}
+			};
+		}, [
+			connect,
+			emitter,
+			outgoingQueue,
+			livenessSession
+		]);
+		const send = useCallback((data) => {
+			const ws = wsRef.current;
+			if (ws && ws.readyState === WebSocket.OPEN) {
+				ws.send(data);
+				return true;
+			}
+			return outgoingQueue.enqueue(data);
+		}, [outgoingQueue]);
+		const sendJson = useCallback((data) => send(JSON.stringify(data)), [send]);
+		const actions = useMemo(() => ({
+			send,
+			sendJson,
+			connect,
+			disconnect,
+			getStatus
+		}), [
+			send,
+			sendJson,
+			connect,
+			disconnect,
+			getStatus
+		]);
+		return /* @__PURE__ */ jsx(ActionsCtx.Provider, {
+			value: actions,
+			children: /* @__PURE__ */ jsx(StoreCtx.Provider, {
+				value: store,
+				children: /* @__PURE__ */ jsx(EmitterCtx.Provider, {
+					value: emitter,
+					children
+				})
+			})
+		});
+	}
+	return {
+		WsProvider,
+		useWsActions,
+		useWsStore,
+		useWsEvents
+	};
+}
+//#endregion
+export { createWsContext };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/ws-context/emitter.ts","../src/ws-context/ws-events.ts","../src/ws-context/liveness/resolve-ping.ts","../src/ws-context/liveness/controller.ts","../src/ws-context/liveness/liveness.ts","../src/ws-context/outgoing-queue.ts","../src/ws-context/store.ts","../src/ws-context/use-store.ts","../src/ws-context/ws-store.ts","../src/ws-context/ws-actions.ts","../src/ws-context/socket.ts","../src/ws-context/index.tsx"],"sourcesContent":["// Typed event emitter。\n// 執行期邏輯對齊 nanoevents 的 createNanoEvents（幾乎逐行相同）；型別為本套件收斂版。\n// Project: nanoevents — https://github.com/ai/nanoevents\n// Author: Andrey Sitnik — https://github.com/ai\n// License: MIT — https://github.com/ai/nanoevents/blob/main/LICENSE\n// Source:\n//   - https://github.com/ai/nanoevents/blob/main/index.js\n//   - https://github.com/ai/nanoevents/blob/main/index.d.ts\n// Modifications: 內嵌以達成零 runtime 依賴；新增 useEmitter（React useState 包裝）。\n\nimport { useState } from \"react\";\n\nexport interface Emitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n> {\n  events: { [E in keyof Events]?: Array<Events[E]> };\n  emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void;\n  on<E extends keyof Events>(event: E, cb: Events[E]): () => void;\n}\n\nexport function createEmitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n>(): Emitter<Events> {\n  return {\n    events: {},\n    emit(event, ...args) {\n      const callbacks = this.events[event] || [];\n      for (let i = 0, len = callbacks.length; i < len; i++) {\n        callbacks[i]!(...args);\n      }\n    },\n    on(event, cb) {\n      (this.events[event] ||= []).push(cb);\n      return () => {\n        this.events[event] = this.events[event]?.filter((fn) => fn !== cb);\n      };\n    },\n  };\n}\n\nexport function useEmitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n>(): Emitter<Events> {\n  const [emitter] = useState(() => createEmitter<Events>());\n  return emitter;\n}\n","import {\n  createContext,\n  useContext,\n  useEffect,\n  useRef,\n  type Context,\n} from \"react\";\nimport type { Emitter } from \"./emitter\";\nimport type { WsEvents } from \"./types\";\n\nexport function createWsEventsContext() {\n  return createContext<Emitter<WsEvents> | null>(null);\n}\n\nexport function createUseWsEvents(\n  EmitterCtx: Context<Emitter<WsEvents> | null>,\n) {\n  function useWsEvents<E extends keyof WsEvents>(\n    type: E,\n    handler: WsEvents[E],\n  ): void {\n    const emitter = useContext(EmitterCtx);\n    if (!emitter) {\n      throw new Error(\"useWsEvents 必須包在對應的 WsProvider 內\");\n    }\n\n    const handlerRef = useRef(handler);\n    handlerRef.current = handler;\n\n    useEffect(() => {\n      return emitter.on(type, ((...args: never[]) => {\n        (handlerRef.current as (...a: never[]) => void)(...args);\n      }) as WsEvents[E]);\n    }, [type, emitter]);\n  }\n\n  return useWsEvents;\n}\n","import type { LivenessOptions } from \"./types\";\n\nexport function resolvePingPayload(ping: LivenessOptions[\"ping\"]): unknown {\n  return typeof ping === \"function\" ? ping() : ping;\n}\n","import { resolvePingPayload } from \"./resolve-ping\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface LivenessController {\n  /** 開始探活 */\n  start: (sendPing: () => void) => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nexport function createLivenessController(\n  options: LivenessOptions,\n  onTimeout: () => void,\n): LivenessController {\n  const { intervalMs, timeoutMs, isPong } = options;\n\n  let intervalId: ReturnType<typeof setInterval> | null = null;\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let sendPingRef: (() => void) | null = null;\n\n  function clearTimeoutTimer(): void {\n    if (timeoutId != null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  }\n\n  function armTimeout(): void {\n    clearTimeoutTimer();\n    timeoutId = setTimeout(onTimeout, timeoutMs);\n  }\n\n  function tick(): void {\n    sendPingRef?.();\n    armTimeout();\n  }\n\n  return {\n    start(sendPing) {\n      sendPingRef = sendPing;\n      tick();\n      intervalId = setInterval(tick, intervalMs);\n    },\n\n    stop() {\n      if (intervalId != null) {\n        clearInterval(intervalId);\n        intervalId = null;\n      }\n      clearTimeoutTimer();\n      sendPingRef = null;\n    },\n\n    onMessage(data) {\n      if (isPong(data)) clearTimeoutTimer();\n    },\n  };\n}\n\nexport function createPingSender(\n  ping: LivenessOptions[\"ping\"],\n  sendJson: (data: unknown) => boolean,\n): () => void {\n  return () => {\n    sendJson(resolvePingPayload(ping));\n  };\n}\n","import { useState } from \"react\";\nimport {\n  createLivenessController,\n  createPingSender,\n  type LivenessController,\n} from \"./controller\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface Liveness {\n  /** 開始探活 */\n  start: (ws: WebSocket) => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nconst DISABLED_LIVENESS: Liveness = {\n  start() {},\n  stop() {},\n  onMessage() {},\n};\n\nexport function createLiveness(\n  options: LivenessOptions,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  let controller: LivenessController | null = null;\n\n  return {\n    start(ws) {\n      controller?.stop();\n      controller = createLivenessController(options, () => {\n        const current = getActiveSocket();\n        if (current?.readyState === WebSocket.OPEN) current.close();\n      });\n      const sendPing = createPingSender(options.ping, (data) => {\n        if (ws.readyState !== WebSocket.OPEN) return false;\n        ws.send(JSON.stringify(data));\n        return true;\n      });\n      controller.start(sendPing);\n    },\n\n    stop() {\n      controller?.stop();\n      controller = null;\n    },\n\n    onMessage(data) {\n      controller?.onMessage(data);\n    },\n  };\n}\n\nexport function useLiveness(\n  options: LivenessOptions | undefined,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  const [session] = useState(() =>\n    options ? createLiveness(options, getActiveSocket) : DISABLED_LIVENESS,\n  );\n  return session;\n}\n","import { useState } from \"react\";\n\nexport type OutgoingData = Parameters<WebSocket[\"send\"]>[0];\n\nexport interface OutgoingQueue {\n  /** 列隊 */\n  enqueue: (data: OutgoingData) => boolean;\n  /** 清空 */\n  clear: () => void;\n  /** 依序送出後清空 */\n  flush: (send: (data: OutgoingData) => void) => void;\n}\n\nexport function createOutgoingQueue(max: number): OutgoingQueue {\n  let items: OutgoingData[] = [];\n\n  return {\n    enqueue(data) {\n      if (max <= 0 || items.length >= max) return false;\n      items.push(data);\n      return true;\n    },\n    clear() {\n      items = [];\n    },\n    flush(send) {\n      const queued = items;\n      items = [];\n      for (const data of queued) send(data);\n    },\n  };\n}\n\nexport function useOutgoingQueue(max: number): OutgoingQueue {\n  const [queue] = useState(() => createOutgoingQueue(max));\n  return queue;\n}\n","// 精簡外部 store：只保留本套件需要的 getState / setState / subscribe / getInitialState。\n// 靈感與行為對齊 zustand/vanilla（非完整搬移；無 middleware、無 replace、無 initializer factory）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts\n// Modifications: 內嵌子集以達成零 runtime 依賴。\n\nexport type StoreApi<State> = {\n  getState: () => State;\n  getInitialState: () => State;\n  setState: (\n    partial: Partial<State> | ((state: State) => Partial<State>),\n  ) => void;\n  subscribe: (listener: (state: State, prev: State) => void) => () => void;\n};\n\nexport function createStore<State extends object>(\n  initialState: State,\n): StoreApi<State> {\n  let state = initialState;\n  const listeners = new Set<(state: State, prev: State) => void>();\n\n  return {\n    getState: () => state,\n    getInitialState: () => initialState,\n    setState: (partial) => {\n      const nextPartial =\n        typeof partial === \"function\" ? partial(state) : partial;\n      if (Object.is(nextPartial, state)) return;\n      const prev = state;\n      state = Object.assign({}, state, nextPartial);\n      for (const listener of listeners) listener(state, prev);\n    },\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n  };\n}\n","// 訂閱外部 store（selector + useSyncExternalStore）。\n// 靈感來自 zustand/react 的 useStore（非完整搬移；selector 必填、無 useDebugValue）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/react.ts\n// Modifications: 內嵌以達成零 runtime 依賴。\n// 用途：訂閱 WsState（連線健康／佇列／重連）；訊息不走此 store。\n\nimport { useSyncExternalStore } from \"react\";\nimport type { StoreApi } from \"./store\";\n\nexport function useStore<State, Selected>(\n  store: StoreApi<State>,\n  selector: (state: State) => Selected,\n): Selected {\n  return useSyncExternalStore(\n    store.subscribe,\n    () => selector(store.getState()),\n    () => selector(store.getInitialState()),\n  );\n}\n","import { createContext, useContext, useState, type Context } from \"react\";\nimport { createStore, type StoreApi } from \"./store\";\nimport { useStore } from \"./use-store\";\n\n/**\n * 連線生命週期狀態（`WsState` 的一環）。\n *\n * - `idle` — 尚未連線\n * - `connecting` — 連線中\n * - `open` — 已連線\n * - `closed` — 已斷線\n *\n * 錯誤用 `useWsEvents(\"error\")`；不另設 error status。\n */\nexport type WsStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\";\n\n/**\n * 可訂閱的連線層 state（低頻更新）。\n *\n * 只放：**連線健康**、**outbound 佇列**、**重連** 等連線生命週期資訊。\n * 不放：訊息 payload、訊息歷史、業務資料（請用 `useWsEvents` 或自行管理 state）。\n *\n * 未來可能擴充例如 `reconnectAttempt`、`pendingCount`；新增欄位時請維持低頻、可 selector 訂閱。\n */\nexport type WsState = {\n  /** 連線生命週期狀態 */\n  status: WsStatus;\n};\n\nexport type WsStoreApi = StoreApi<WsState>;\n\nexport function createWsStore(init: WsStatus = \"idle\"): WsStoreApi {\n  return createStore<WsState>({ status: init });\n}\n\n/** 每個 `WsProvider` 各有一份 {@link WsState} store */\nexport function useWsStoreApi(): WsStoreApi {\n  const [store] = useState(() => createWsStore());\n  return store;\n}\n\nexport function createWsStoreContext() {\n  return createContext<WsStoreApi | null>(null);\n}\n\n/** 訂閱 {@link WsState}；建議以 selector 只取需要的連線層欄位。 */\nexport function createUseWsStore(StoreCtx: Context<WsStoreApi | null>) {\n  function useWsStore(): WsState;\n  function useWsStore<T>(selector: (state: WsState) => T): T;\n  function useWsStore<T>(selector?: (state: WsState) => T): T {\n    const store = useContext(StoreCtx);\n    if (!store) {\n      throw new Error(\"useWsStore 必須包在對應的 WsProvider 內\");\n    }\n    const select = selector ?? ((state: WsState) => state as T);\n    return useStore(store, select);\n  }\n\n  return useWsStore;\n}\n","import { createContext, useContext, type Context } from \"react\";\nimport type { WsContextValue } from \"./types\";\n\nexport function createWsActionsContext() {\n  return createContext<WsContextValue | null>(null);\n}\n\nexport function createUseWsActions(ActionsCtx: Context<WsContextValue | null>) {\n  function useWsActions(): WsContextValue {\n    const value = useContext(ActionsCtx);\n    if (!value) {\n      throw new Error(\"useWsActions 必須包在對應的 WsProvider 內\");\n    }\n    return value;\n  }\n\n  return useWsActions;\n}\n","import type { RefObject } from \"react\";\n\nexport function detachAndClose(ws: WebSocket): void {\n  ws.onopen = null;\n  ws.onmessage = null;\n  ws.onerror = null;\n  ws.onclose = null;\n  if (ws.readyState < WebSocket.CLOSING) ws.close();\n}\n\nexport function clearReconnectTimer(\n  timerRef: RefObject<ReturnType<typeof setTimeout> | null>,\n): void {\n  if (timerRef.current != null) {\n    clearTimeout(timerRef.current);\n    timerRef.current = null;\n  }\n}\n\nexport function clientCloseEvent(reason: string): CloseEvent {\n  return new CloseEvent(\"close\", {\n    code: 1000,\n    reason,\n    wasClean: true,\n  });\n}\n","import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  type PropsWithChildren,\n} from \"react\";\nimport { useEmitter } from \"./emitter\";\nimport { createUseWsEvents, createWsEventsContext } from \"./ws-events\";\nimport type { CreateWsContextOptions, WsContextValue, WsEvents } from \"./types\";\nimport { useLiveness } from \"./liveness/liveness\";\nimport { useOutgoingQueue } from \"./outgoing-queue\";\nimport {\n  createUseWsStore,\n  createWsStoreContext,\n  useWsStoreApi,\n  type WsStatus,\n} from \"./ws-store\";\nimport { createUseWsActions, createWsActionsContext } from \"./ws-actions\";\nimport {\n  clearReconnectTimer,\n  clientCloseEvent,\n  detachAndClose,\n} from \"./socket\";\n\nexport type { CreateWsContextOptions, WsContextValue, WsEvents } from \"./types\";\n\nfunction defaultParse(data: MessageEvent[\"data\"]): unknown {\n  if (typeof data !== \"string\") return data;\n  try {\n    return JSON.parse(data) as unknown;\n  } catch {\n    return data;\n  }\n}\n\n/**\n * @example\n * ```ts\n * export const { WsProvider, useWsActions, useWsStore, useWsEvents } =\n *   createWsContext({ url: \"ws://localhost:8080\" });\n * ```\n */\nexport function createWsContext(options: CreateWsContextOptions) {\n  const {\n    url,\n    protocols,\n    autoConnect = true,\n    reconnectMs = 0,\n    outgoingQueueMax = 0,\n    parse = defaultParse,\n    liveness,\n  } = options;\n\n  const ActionsCtx = createWsActionsContext();\n  const useWsActions = createUseWsActions(ActionsCtx);\n  const StoreCtx = createWsStoreContext();\n  const useWsStore = createUseWsStore(StoreCtx);\n  const EmitterCtx = createWsEventsContext();\n  const useWsEvents = createUseWsEvents(EmitterCtx);\n\n  function WsProvider({ children }: PropsWithChildren) {\n    const wsRef = useRef<WebSocket | null>(null);\n    const store = useWsStoreApi();\n    const emitter = useEmitter<WsEvents>();\n    const intentionalCloseRef = useRef(false);\n    const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(\n      null,\n    );\n    const outgoingQueue = useOutgoingQueue(outgoingQueueMax);\n    const livenessSession = useLiveness(liveness, () => wsRef.current);\n\n    const setStatus = useCallback(\n      (status: WsStatus) => {\n        store.setState({ status });\n      },\n      [store],\n    );\n\n    const getStatus = useCallback<WsContextValue[\"getStatus\"]>(\n      () => store.getState().status,\n      [store],\n    );\n\n    const disconnect = useCallback<WsContextValue[\"disconnect\"]>(() => {\n      intentionalCloseRef.current = true;\n      clearReconnectTimer(reconnectTimerRef);\n      livenessSession.stop();\n      outgoingQueue.clear();\n      const ws = wsRef.current;\n      wsRef.current = null;\n      if (ws) {\n        detachAndClose(ws);\n        setStatus(\"closed\");\n        emitter.emit(\"close\", clientCloseEvent(\"client disconnect\"));\n      } else {\n        setStatus(\"closed\");\n      }\n    }, [setStatus, emitter, outgoingQueue, livenessSession]);\n\n    const connect = useCallback<WsContextValue[\"connect\"]>(() => {\n      if (typeof window === \"undefined\") return;\n\n      clearReconnectTimer(reconnectTimerRef);\n      intentionalCloseRef.current = false;\n      livenessSession.stop();\n\n      const prev = wsRef.current;\n      if (prev) {\n        wsRef.current = null;\n        detachAndClose(prev);\n        emitter.emit(\"close\", clientCloseEvent(\"reconnect\"));\n      }\n\n      setStatus(\"connecting\");\n\n      const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);\n      wsRef.current = ws;\n\n      ws.onopen = (event) => {\n        if (wsRef.current !== ws) return;\n        setStatus(\"open\");\n        outgoingQueue.flush((data) => ws.send(data));\n        livenessSession.start(ws);\n        emitter.emit(\"open\", event);\n      };\n\n      ws.onmessage = (event) => {\n        if (wsRef.current !== ws) return;\n        const data = parse(event.data);\n        livenessSession.onMessage(data);\n        emitter.emit(\"message\", data, event);\n      };\n\n      ws.onerror = (event) => {\n        if (wsRef.current !== ws) return;\n        emitter.emit(\"error\", event);\n      };\n\n      ws.onclose = (event) => {\n        if (wsRef.current === ws) wsRef.current = null;\n        livenessSession.stop();\n        setStatus(\"closed\");\n        emitter.emit(\"close\", event);\n\n        if (intentionalCloseRef.current || reconnectMs <= 0) return;\n        // ponytail: 固定間隔重連，無 backoff；之後可換成指數退避\n        reconnectTimerRef.current = setTimeout(() => {\n          connect();\n        }, reconnectMs);\n      };\n    }, [setStatus, emitter, outgoingQueue, livenessSession]);\n\n    useEffect(() => {\n      if (autoConnect) connect();\n      return () => {\n        intentionalCloseRef.current = true;\n        clearReconnectTimer(reconnectTimerRef);\n        livenessSession.stop();\n        outgoingQueue.clear();\n        const ws = wsRef.current;\n        wsRef.current = null;\n        if (ws) {\n          detachAndClose(ws);\n          emitter.emit(\"close\", clientCloseEvent(\"provider unmount\"));\n        }\n      };\n    }, [connect, emitter, outgoingQueue, livenessSession]);\n\n    const send = useCallback<WsContextValue[\"send\"]>(\n      (data) => {\n        const ws = wsRef.current;\n        if (ws && ws.readyState === WebSocket.OPEN) {\n          ws.send(data);\n          return true;\n        }\n        return outgoingQueue.enqueue(data);\n      },\n      [outgoingQueue],\n    );\n\n    const sendJson = useCallback<WsContextValue[\"sendJson\"]>(\n      (data) => send(JSON.stringify(data)),\n      [send],\n    );\n\n    const actions = useMemo<WsContextValue>(\n      () => ({\n        send,\n        sendJson,\n        connect,\n        disconnect,\n        getStatus,\n      }),\n      [send, sendJson, connect, disconnect, getStatus],\n    );\n\n    return (\n      <ActionsCtx.Provider value={actions}>\n        <StoreCtx.Provider value={store}>\n          <EmitterCtx.Provider value={emitter}>{children}</EmitterCtx.Provider>\n        </StoreCtx.Provider>\n      </ActionsCtx.Provider>\n    );\n  }\n\n  return {\n    WsProvider,\n    useWsActions,\n    useWsStore,\n    useWsEvents,\n  };\n}\n"],"mappings":"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"}

package/dist/stall/index.d.mts

@@ -0,0 +1,40 @@
+//#region src/stall/constants.d.ts
+/** 客戶端停滯控制訊息的 `type` 欄位值 */
+declare const STALL_MESSAGE_TYPE: "STALL";
+/** 伺服器停滯確認的 `type` 欄位值 */
+declare const STALL_ACK_TYPE: "STALL_ACK";
+//#endregion
+//#region src/stall/types.d.ts
+/**
+ * 停滯控制
+ *
+ * - `stall` 進入停滯
+ * - `release` 恢復正常
+ */
+type StallAction = "stall" | "release";
+/** 客戶端經 WebSocket 送出的停滯控制訊息 */
+interface StallMessage {
+  type: typeof STALL_MESSAGE_TYPE;
+  /** 控制動作 */
+  action: StallAction;
+}
+/** 伺服器回覆的停滯狀態確認 */
+interface StallAck {
+  type: typeof STALL_ACK_TYPE;
+  /** 本次 ack 對應的控制動作 */
+  action: StallAction;
+  /** 回覆當下是否處於停滯中 */
+  active: boolean;
+}
+//#endregion
+//#region src/stall/messages.d.ts
+/** 建立可 `sendJson` 的停滯控制訊息 */
+declare function createStallMessage(action: StallAction): StallMessage;
+/**
+ * 從 `useWsEvents("message", …)` 的 `data` 解析停滯訊息。
+ * 格式不符回傳 `null`。
+ */
+declare function parseStallMessage(data: unknown): StallMessage | null;
+//#endregion
+export { STALL_ACK_TYPE, STALL_MESSAGE_TYPE, type StallAck, type StallAction, type StallMessage, createStallMessage, parseStallMessage };
+//# sourceMappingURL=index.d.mts.map

package/dist/stall/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/stall/constants.ts","../../src/stall/types.ts","../../src/stall/messages.ts"],"mappings":";;cACa;;cAGA;;;;;;;;;KCID;;UAGK;EACf,aAAa;;EAEb,QAAQ;;;UAIO;EACf,aAAa;;EAEb,QAAQ;;EAER;;;;;iBCnBc,mBAAmB,QAAQ,cAAc;;;;;iBAQzC,kBAAkB,gBAAgB"}

package/dist/stall/index.mjs

@@ -0,0 +1,32 @@
+//#region src/stall/constants.ts
+/** 客戶端停滯控制訊息的 `type` 欄位值 */
+const STALL_MESSAGE_TYPE = "STALL";
+/** 伺服器停滯確認的 `type` 欄位值 */
+const STALL_ACK_TYPE = "STALL_ACK";
+//#endregion
+//#region src/stall/messages.ts
+/** 建立可 `sendJson` 的停滯控制訊息 */
+function createStallMessage(action) {
+	return {
+		type: STALL_MESSAGE_TYPE,
+		action
+	};
+}
+/**
+* 從 `useWsEvents("message", …)` 的 `data` 解析停滯訊息。
+* 格式不符回傳 `null`。
+*/
+function parseStallMessage(data) {
+	if (typeof data !== "object" || data == null) return null;
+	const msg = data;
+	if (msg.type !== "STALL") return null;
+	if (msg.action === "stall" || msg.action === "release") return {
+		type: STALL_MESSAGE_TYPE,
+		action: msg.action
+	};
+	return null;
+}
+//#endregion
+export { STALL_ACK_TYPE, STALL_MESSAGE_TYPE, createStallMessage, parseStallMessage };
+
+//# sourceMappingURL=index.mjs.map

package/dist/stall/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/stall/constants.ts","../../src/stall/messages.ts"],"sourcesContent":["/** 客戶端停滯控制訊息的 `type` 欄位值 */\nexport const STALL_MESSAGE_TYPE = \"STALL\" as const;\n\n/** 伺服器停滯確認的 `type` 欄位值 */\nexport const STALL_ACK_TYPE = \"STALL_ACK\" as const;\n","import { STALL_MESSAGE_TYPE } from \"./constants\";\nimport type { StallAction, StallMessage } from \"./types\";\n\n/** 建立可 `sendJson` 的停滯控制訊息 */\nexport function createStallMessage(action: StallAction): StallMessage {\n  return { type: STALL_MESSAGE_TYPE, action };\n}\n\n/**\n * 從 `useWsEvents(\"message\", …)` 的 `data` 解析停滯訊息。\n * 格式不符回傳 `null`。\n */\nexport function parseStallMessage(data: unknown): StallMessage | null {\n  if (typeof data !== \"object\" || data == null) return null;\n  const msg = data as Record<string, unknown>;\n  if (msg.type !== STALL_MESSAGE_TYPE) return null;\n  if (msg.action === \"stall\" || msg.action === \"release\") {\n    return { type: STALL_MESSAGE_TYPE, action: msg.action };\n  }\n  return null;\n}\n"],"mappings":";;AACA,MAAa,qBAAqB;;AAGlC,MAAa,iBAAiB;;;;ACA9B,SAAgB,mBAAmB,QAAmC;CACpE,OAAO;EAAE,MAAM;EAAoB;CAAO;AAC5C;;;;;AAMA,SAAgB,kBAAkB,MAAoC;CACpE,IAAI,OAAO,SAAS,YAAY,QAAQ,MAAM,OAAO;CACrD,MAAM,MAAM;CACZ,IAAI,IAAI,SAAA,SAA6B,OAAO;CAC5C,IAAI,IAAI,WAAW,WAAW,IAAI,WAAW,WAC3C,OAAO;EAAE,MAAM;EAAoB,QAAQ,IAAI;CAAO;CAExD,OAAO;AACT"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "react-ws-context",
+  "version": "0.1.0",
+  "description": "React WebSocket connection layer — separate hooks for actions, connection state, and message events to avoid unnecessary re-renders",
+  "keywords": [
+    "react",
+    "react-hooks",
+    "hooks",
+    "websocket",
+    "ws",
+    "context",
+    "client"
+  ],
+  "license": "MIT",
+  "author": "GaiaYang (https://github.com/GaiaYang)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GaiaYang/react-ws.git",
+    "directory": "packages/react-ws"
+  },
+  "homepage": "https://github.com/GaiaYang/react-ws/tree/main/packages/react-ws#readme",
+  "bugs": {
+    "url": "https://github.com/GaiaYang/react-ws/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./stall": {
+      "development": "./src/stall/index.ts",
+      "types": "./dist/stall/index.d.mts",
+      "import": "./dist/stall/index.mjs",
+      "default": "./dist/stall/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jsdom": "^30.0.1",
+    "prettier": "^3.9.6",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsdown": "^0.22.14",
+    "typescript": "^5",
+    "typescript-eslint": "^8.63.0",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  }
+}