@wireflowapp/react-websocket 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @wireflowapp/react-websocket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hook adapter for native WebSocket connection management in **Wireflow**.
+
+## Features
+
+- **Reactive Status**: Exposes `"Idle" | "Connecting" | "Connected" | "Failed"` as React state.
+- **Reference-Stable**: Prevents infinite reconnect loops from inline option objects and callback functions.
+- **Strict Mode Ready**: Supports React 18+ double mounting and fast refresh without leaking resources.
+- **Next.js & SSR Friendly**: Ships with `"use client"` directive.
+
+## Installation
+
+```bash
+pnpm add @wireflowapp/react-websocket @wireflowapp/websocket-core @wireflowapp/core
+```
+
+## Quick Start
+
+```tsx
+import { useWebSocket } from "@wireflowapp/react-websocket";
+
+export function ChatComponent() {
+  const { status, connect, retry, disconnect, send } = useWebSocket("wss://example.com/ws", {
+    retryAttempts: 5,
+    retryDelay: 3000,
+    onMessage: (event) => {
+      console.log("Message received:", event.data);
+    },
+  });
+
+  return (
+    <div>
+      <div>Status: {status}</div>
+      <button onClick={() => send("Ping")}>Send</button>
+      <button onClick={disconnect}>Disconnect</button>
+      <button onClick={retry}>Retry</button>
+    </div>
+  );
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import { ConnectionStatus } from '@wireflowapp/core';
+import { WebSocketOptions, WebSocketDataType, WebSocketClient } from '@wireflowapp/websocket-core';
+
+interface UseWebSocketOptions extends WebSocketOptions {
+}
+interface UseWebSocketResult {
+    /**
+     * Current connection status.
+     */
+    readonly status: ConnectionStatus;
+    /**
+     * Initiates connection to the WebSocket server.
+     */
+    connect: () => void;
+    /**
+     * Manually retries connection if currently idle or failed.
+     */
+    retry: () => void;
+    /**
+     * Disconnects the active socket connection and cancels retry timers.
+     */
+    disconnect: () => void;
+    /**
+     * Transmits data through the active WebSocket connection.
+     */
+    send: (data: WebSocketDataType) => boolean;
+    /**
+     * The underlying WebSocketClient instance.
+     */
+    client: WebSocketClient | null;
+}
+
+/**
+ * React hook providing reactive connection state and controls over a native WebSocket connection.
+ *
+ * @param url The WebSocket server URL to connect to.
+ * @param options Optional configuration parameters and lifecycle event handlers.
+ */
+declare function useWebSocket(url: string, options?: UseWebSocketOptions): UseWebSocketResult;
+
+export { type UseWebSocketOptions, type UseWebSocketResult, useWebSocket };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { ConnectionStatus } from '@wireflowapp/core';
+import { WebSocketOptions, WebSocketDataType, WebSocketClient } from '@wireflowapp/websocket-core';
+
+interface UseWebSocketOptions extends WebSocketOptions {
+}
+interface UseWebSocketResult {
+    /**
+     * Current connection status.
+     */
+    readonly status: ConnectionStatus;
+    /**
+     * Initiates connection to the WebSocket server.
+     */
+    connect: () => void;
+    /**
+     * Manually retries connection if currently idle or failed.
+     */
+    retry: () => void;
+    /**
+     * Disconnects the active socket connection and cancels retry timers.
+     */
+    disconnect: () => void;
+    /**
+     * Transmits data through the active WebSocket connection.
+     */
+    send: (data: WebSocketDataType) => boolean;
+    /**
+     * The underlying WebSocketClient instance.
+     */
+    client: WebSocketClient | null;
+}
+
+/**
+ * React hook providing reactive connection state and controls over a native WebSocket connection.
+ *
+ * @param url The WebSocket server URL to connect to.
+ * @param options Optional configuration parameters and lifecycle event handlers.
+ */
+declare function useWebSocket(url: string, options?: UseWebSocketOptions): UseWebSocketResult;
+
+export { type UseWebSocketOptions, type UseWebSocketResult, useWebSocket };

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useWebSocket: () => useWebSocket
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/useWebSocket.ts
+var import_react = require("react");
+var import_websocket_core = require("@wireflowapp/websocket-core");
+function useWebSocket(url, options = {}) {
+  const [status, setStatus] = (0, import_react.useState)("Idle");
+  const clientRef = (0, import_react.useRef)(null);
+  const callbacksRef = (0, import_react.useRef)({
+    onOpen: options.onOpen,
+    onClose: options.onClose,
+    onError: options.onError,
+    onMessage: options.onMessage,
+    onStatusChange: options.onStatusChange
+  });
+  callbacksRef.current = {
+    onOpen: options.onOpen,
+    onClose: options.onClose,
+    onError: options.onError,
+    onMessage: options.onMessage,
+    onStatusChange: options.onStatusChange
+  };
+  const protocolsSerialized = Array.isArray(options.protocols) ? options.protocols.join(",") : options.protocols;
+  const retryAttempts = options.retryAttempts;
+  const retryDelay = options.retryDelay;
+  const autoConnect = options.autoConnect;
+  const retryOnDisconnect = options.retryOnDisconnect;
+  const binaryType = options.binaryType;
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined" && typeof WebSocket === "undefined") {
+      return;
+    }
+    const clientOptions = {
+      protocols: options.protocols,
+      binaryType,
+      retryAttempts,
+      retryDelay,
+      autoConnect: autoConnect ?? true,
+      retryOnDisconnect: retryOnDisconnect ?? true,
+      onOpen: (e) => callbacksRef.current.onOpen?.(e),
+      onClose: (e) => callbacksRef.current.onClose?.(e),
+      onError: (e) => callbacksRef.current.onError?.(e),
+      onMessage: (e) => callbacksRef.current.onMessage?.(e),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus);
+        callbacksRef.current.onStatusChange?.(newStatus);
+      }
+    };
+    const client = new import_websocket_core.WebSocketClient(url, clientOptions);
+    clientRef.current = client;
+    setStatus(client.status);
+    return () => {
+      client.dispose();
+      clientRef.current = null;
+    };
+  }, [
+    url,
+    protocolsSerialized,
+    binaryType,
+    retryAttempts,
+    retryDelay,
+    autoConnect,
+    retryOnDisconnect
+  ]);
+  const connect = (0, import_react.useCallback)(() => {
+    clientRef.current?.connect();
+  }, []);
+  const retry = (0, import_react.useCallback)(() => {
+    clientRef.current?.retry();
+  }, []);
+  const disconnect = (0, import_react.useCallback)(() => {
+    clientRef.current?.disconnect();
+  }, []);
+  const send = (0, import_react.useCallback)((data) => {
+    return clientRef.current?.send(data) ?? false;
+  }, []);
+  return (0, import_react.useMemo)(
+    () => ({
+      status,
+      connect,
+      retry,
+      disconnect,
+      send,
+      client: clientRef.current
+    }),
+    [status, connect, retry, disconnect, send]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useWebSocket
+});

package/dist/index.mjs

@@ -0,0 +1,93 @@
+"use client";
+
+// src/hooks/useWebSocket.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  WebSocketClient
+} from "@wireflowapp/websocket-core";
+function useWebSocket(url, options = {}) {
+  const [status, setStatus] = useState("Idle");
+  const clientRef = useRef(null);
+  const callbacksRef = useRef({
+    onOpen: options.onOpen,
+    onClose: options.onClose,
+    onError: options.onError,
+    onMessage: options.onMessage,
+    onStatusChange: options.onStatusChange
+  });
+  callbacksRef.current = {
+    onOpen: options.onOpen,
+    onClose: options.onClose,
+    onError: options.onError,
+    onMessage: options.onMessage,
+    onStatusChange: options.onStatusChange
+  };
+  const protocolsSerialized = Array.isArray(options.protocols) ? options.protocols.join(",") : options.protocols;
+  const retryAttempts = options.retryAttempts;
+  const retryDelay = options.retryDelay;
+  const autoConnect = options.autoConnect;
+  const retryOnDisconnect = options.retryOnDisconnect;
+  const binaryType = options.binaryType;
+  useEffect(() => {
+    if (typeof window === "undefined" && typeof WebSocket === "undefined") {
+      return;
+    }
+    const clientOptions = {
+      protocols: options.protocols,
+      binaryType,
+      retryAttempts,
+      retryDelay,
+      autoConnect: autoConnect ?? true,
+      retryOnDisconnect: retryOnDisconnect ?? true,
+      onOpen: (e) => callbacksRef.current.onOpen?.(e),
+      onClose: (e) => callbacksRef.current.onClose?.(e),
+      onError: (e) => callbacksRef.current.onError?.(e),
+      onMessage: (e) => callbacksRef.current.onMessage?.(e),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus);
+        callbacksRef.current.onStatusChange?.(newStatus);
+      }
+    };
+    const client = new WebSocketClient(url, clientOptions);
+    clientRef.current = client;
+    setStatus(client.status);
+    return () => {
+      client.dispose();
+      clientRef.current = null;
+    };
+  }, [
+    url,
+    protocolsSerialized,
+    binaryType,
+    retryAttempts,
+    retryDelay,
+    autoConnect,
+    retryOnDisconnect
+  ]);
+  const connect = useCallback(() => {
+    clientRef.current?.connect();
+  }, []);
+  const retry = useCallback(() => {
+    clientRef.current?.retry();
+  }, []);
+  const disconnect = useCallback(() => {
+    clientRef.current?.disconnect();
+  }, []);
+  const send = useCallback((data) => {
+    return clientRef.current?.send(data) ?? false;
+  }, []);
+  return useMemo(
+    () => ({
+      status,
+      connect,
+      retry,
+      disconnect,
+      send,
+      client: clientRef.current
+    }),
+    [status, connect, retry, disconnect, send]
+  );
+}
+export {
+  useWebSocket
+};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@wireflowapp/react-websocket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "React hook adapter for native WebSocket connection management with Wireflow",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@wireflowapp/core": "1.0.0",
+    "@wireflowapp/websocket-core": "1.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "websocket",
+    "wireflow",
+    "real-time"
+  ],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }