Observable Socket (Frontend, NPM)

Tiny reactive WebSocket client and context provider that let you call WebSocket routes like HTTP endpoints — designed for full compatibility with the companion Django/Channels backend django-channels-router.

• ⚡ Call named routes with sendAndWait() — like fetch(), but over WebSocket.
• 🔁 Built-in heartbeat, reconnect, and timeout management.
• 🧩 Multiple sockets handled safely in React via ObservableSocketProvider.
• 💬 Cleanly typed messages with uuid correlation.
• 🧠 Global headers and per-socket config.

---

Install

npm i @djanext/observable-socket
# or
pnpm add @djanext/observable-socket

---

Quick Start (Vanilla)

import { ObservableSocket, Message } from "@djanext/observable-socket";

const ws = new ObservableSocket(
  "app",
  "wss://example.com/ws/app/",
  (name, connected) => console.log("Connected:", connected),
  (res) => console.log("Server says:", res),
  { requestTimeout: 15000, globalHeaders: { token: "XYZ" } }
)

const res = await ws.sendAndWait(new Message("sayHello", { name: "Alireza" }))
console.log(res.message?.payload) // "Hello, Alireza!"

---

React Integration

'use client'
import React from "react"
import { ObservableSocketProvider, useObservableSocket } from "@djanext/observable-socket"
import { Message } from "@djanext/observable-socket"

export default function App() {
  return (
    <ObservableSocketProvider>
      <Dashboard />
    </ObservableSocketProvider>
  );
}

function Dashboard() {
  const { addSocket, getSocket, removeSocket } = useObservableSocket();

  React.useEffect(() => {
    addSocket(
      "app",
      process.env.NEXT_PUBLIC_WS_URL!,
      (res) => console.log("Push:", res),
      false,
      { globalHeaders: { apiKey: "123" } }
    )
  }, [addSocket])

  const handleClick = async () => {
    const app = getSocket("app")
    if (!app) return alert("Socket not ready!")
    const result = await app.socket.sendAndWait(new Message("sayHello", { name: "World" }))
    console.log(result)
  }

  return <button onClick={handleClick}>Say Hello</button>
}

💡 Note: React is listed as a peerDependency — only required if you use the ObservableSocketProvider or React hooks. For non-React environments, import directly from @djanext/observable-socket/core.

---

API

ObservableSocket

Method	Description
sendMessage(message)	Fire-and-forget send.
sendAndWait(message)	Returns a Promise resolved with { message, success }.
onResponse(request, callback)	Register a one-off response handler.
close()	Manually close the socket (stops heartbeats).

ObservableSocketProvider (React)

Function	Description
addSocket(name, url, onMessage?, force?, config?)	Creates a new socket. If name exists and force is not true, returns { ok:false, reason:'exists', item }.
getSocket(name)	Returns { socket, socketState }.
removeSocket(name)	Closes and removes a socket by name.

Config Options (Partial<SocketConfig>)

Option	Default	Description
requestTimeout	30000	Per-request timeout (ms)
queManager	false	Enable expiry check for pending requests
heartbeatRate	60000	Interval between PINGs
heartbeatTimeoutDuration	59000	Wait before assuming no PONG
maxReconnectAttempts	5	Max automatic retries
globalHeaders	{}	Headers merged into all messages

---

Example Message

{
  "uuid": "9b7c...",
  "route": "sayHello",
  "headers": { "token": "XYZ" },
  "payload": { "name": "Ali" },
  "status": 200
}

---

Multi-Socket & Race-Safety Notes

• Functional setState avoids stale closures.
• Each socket instance gets a random instanceId → old sockets can’t overwrite new states.
• Prevents duplicate connections unless force = true.
• Includes removeSocket() for safe cleanup (used internally on unmount).

---

Server Side

Use the Django/Channels package observable-socket-router
It handles route mapping, hydrate/dehydrate, and status responses.

---

License

MIT