react-realtime-hooks 1.4.1 → 1.4.3

package/README.md

@@ -38,6 +38,7 @@ Real apps need:
 - Discriminated connection snapshots: `idle`, `connecting`, `open`, `reconnecting`, `closing`, `closed`, `error`.
 - First-class TypeScript support with generic message types and custom parsers/serializers.
 - SSR-safe by default. No browser-only globals are touched during server render.
+- Strict Mode safe. Works correctly under React 18+ `<StrictMode>` and Next.js dev double-mount — see [Strict Mode Safety](#strict-mode-safety).
 - Zero runtime dependencies beyond React.
 - Manual controls stay available when you need them: `open()`, `close()`, `reconnect()`, `send()`.
 
@@ -655,6 +656,19 @@ That keeps the gate predictable when multiple blockers apply at once.
 - No transport polyfills are bundled. Provide your own runtime support where needed.
 - Browser-native transport constraints still apply: auth, proxy, CORS, and network policy are outside the hook's control.
 
+## Strict Mode Safety
+
+All hooks are safe to use under React 18+ `<React.StrictMode>` and the Next.js App Router's dev mode, both of which intentionally mount → unmount → mount each component on first render to surface effect-cleanup bugs.
+
+Concretely:
+
+- `useWebSocket` and `useEventSource` defer the actual `new WebSocket(...)` / `new EventSource(...)` call by a microtask. If the component unmounts before that microtask runs (the Strict Mode discard mount), no transport is ever created. If the mount survives, exactly one transport is created — never two.
+- All effects in the library tear down their timers, listeners, and transports synchronously in the cleanup function. There is no "zombie" `setInterval`, no orphaned `addEventListener`, no leaked `WebSocket` left in `CONNECTING` after a discarded mount.
+- Latest-state refs are committed via `useInsertionEffect`, not by writing to `ref.current` during render. A discarded render never leaves the ref out of sync with the committed tree.
+- The library's own test suite runs every hook test inside `<React.StrictMode>` by default, so any regression that only shows up under double-mount is caught in CI.
+
+If you observe a Strict Mode regression — e.g. two simultaneous WebSocket connections, an `EventSource` that survives a closed component, or a heartbeat that keeps firing after unmount — please open an issue with a minimal repro. That class of bug is supposed to be impossible by construction, and we treat it as a correctness defect.
+
 ## Testing And Quality
 
 The package includes behavior tests for:

package/dist/index.cjs

@@ -466,7 +466,9 @@ var useReconnect = (options = {}) => {
     () => createInitialState(normalizedOptions.enabled)
   );
   const stateRef = react.useRef(state);
-  stateRef.current = state;
+  react.useInsertionEffect(() => {
+    stateRef.current = state;
+  });
   const commitState = (next) => {
     const resolved = typeof next === "function" ? next(stateRef.current) : next;
     stateRef.current = resolved;
@@ -599,7 +601,9 @@ var useHeartbeat = (options) => {
     () => createInitialState2(enabled && startOnMount)
   );
   const stateRef = react.useRef(state);
-  stateRef.current = state;
+  react.useInsertionEffect(() => {
+    stateRef.current = state;
+  });
   const commitState = (next) => {
     const resolved = typeof next === "function" ? next(stateRef.current) : next;
     stateRef.current = resolved;
@@ -938,11 +942,14 @@ var useWebSocket = (options) => {
   const nextSocketEpochRef = react.useRef(0);
   const controller = useWebSocketController();
   const [openNonce, setOpenNonce] = react.useState(0);
+  const initialStatus = !supported || resolvedUrl === null ? "closed" : connect ? "connecting" : "idle";
   const [state, setState] = react.useState(
-    () => createInitialState4(connect ? "connecting" : "idle")
+    () => createInitialState4(initialStatus)
   );
   const stateRef = react.useRef(state);
-  stateRef.current = state;
+  react.useInsertionEffect(() => {
+    stateRef.current = state;
+  });
   const reconnectEnabled = options.reconnect !== false && supported && resolvedUrl !== null;
   const reconnect = useReconnect(
     options.reconnect === false ? { enabled: false } : {
@@ -1511,11 +1518,14 @@ var useEventSource = (options) => {
   const suppressReconnectRef = react.useRef(false);
   const terminalErrorRef = react.useRef(null);
   const [openNonce, setOpenNonce] = react.useState(0);
+  const initialStatus = !supported || resolvedUrl === null ? "closed" : connect ? "connecting" : "idle";
   const [state, setState] = react.useState(
-    () => createInitialState5(connect ? "connecting" : "idle")
+    () => createInitialState5(initialStatus)
   );
   const stateRef = react.useRef(state);
-  stateRef.current = state;
+  react.useInsertionEffect(() => {
+    stateRef.current = state;
+  });
   const reconnectEnabled = options.reconnect !== false && supported && resolvedUrl !== null;
   const reconnect = useReconnect(
     options.reconnect === false ? { enabled: false } : {