diff --git a/.changeset/websocket-solid-2-async.md b/.changeset/websocket-solid-2-async.md new file mode 100644 index 000000000..c7a971f09 --- /dev/null +++ b/.changeset/websocket-solid-2-async.md @@ -0,0 +1,32 @@ +--- +"@solid-primitives/websocket": major +--- + +Upgrade to Solid.js 2.0 (`^2.0.0-beta.7`) and add async-reactive message primitives. + +**Breaking changes** + +- Peer dependency is now `solid-js@^2.0.0-beta.7`. All `createEffect` examples in docs now use the Solid 2.0 split form: `createEffect(compute, effect)`. + +**New: `createWSMessage`** + +Reactive `Accessor` for the most recently received WebSocket message. Cleans up its event listener on owner disposal via `onCleanup`. + +```ts +const message = createWSMessage(ws); +return

{message()}

; +``` + +> Note: uses a signal internally, so under burst conditions only the final message before a flush is tracked by effects. For every-message processing, use the planned `wsMessageIterable` / `createWSData` primitives. + +**`createWSState` signal fix** + +Internal signal now uses `{ ownedWrite: true }` to suppress the Solid 2.0 dev-mode `SIGNAL_WRITE_IN_OWNED_SCOPE` diagnostic, which would fire if `ws.close()` is called from inside a component body or reactive computation. + +**Planned for next minor: async message primitives** + +The following are designed and documented but not yet implemented, based on Solid 2.0's `createMemo(AsyncIterable)` model: + +- `wsMessageIterable` — buffered `AsyncIterable` that never drops burst messages; works with `makeReconnectingWS` +- `createWSData` — async memo over `wsMessageIterable`; suspends `` until first message; integrates with `isPending` and `latest` +- `createWSStore` — reactive store driven by WS messages as draft-mutation patches via `createStore(fn, seed)` diff --git a/packages/websocket/CHANGELOG.md b/packages/websocket/CHANGELOG.md index d123f3f90..04bb848db 100644 --- a/packages/websocket/CHANGELOG.md +++ b/packages/websocket/CHANGELOG.md @@ -1,5 +1,14 @@ # @solid-primitives/websocket +## 2.0.0-beta.0 + +### Major Changes + +- Upgrade to Solid.js 2.0 (`^2.0.0-beta.7`). +- `createWSState`: signal now uses `ownedWrite: true` to suppress dev-mode warnings when `ws.close()` is called from within a component or effect. +- New primitive `createWSMessage`: reactive signal containing the latest received WebSocket message. Cleans up its event listener automatically on owner disposal. +- Updated all JSDoc examples to use the Solid 2.0 split `createEffect(compute, effect)` form. + ## 1.3.2 ### Patch Changes diff --git a/packages/websocket/README.md b/packages/websocket/README.md index 44ccd0248..85cc66076 100644 --- a/packages/websocket/README.md +++ b/packages/websocket/README.md @@ -4,150 +4,279 @@ # @solid-primitives/websocket +[![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/websocket?style=for-the-badge&label=size)](https://bundlephobia.com/package/@solid-primitives/websocket) +[![version](https://img.shields.io/npm/v/@solid-primitives/websocket?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/websocket) [![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process) -Primitive to help establish, maintain and operate a websocket connection. +- [**Docs**](https://primitives.solidjs.community/docs/websocket) -- `makeWS` - sets up a web socket connection with a buffered send -- `createWS` - sets up a web socket connection that disconnects on cleanup -- `createWSState` - creates a reactive signal containing the readyState of a websocket -- `makeReconnectingWS` - sets up a web socket connection that reconnects if involuntarily closed -- `createReconnectingWS` - sets up a reconnecting web socket connection that disconnects on cleanup -- `makeHeartbeatWS` - wraps a reconnecting web socket to send a heart beat and reconnect if the answer fails +Primitives to help establish, maintain, and operate WebSocket connections in Solid. -All of them return a WebSocket instance extended with a `message` prop containing an accessor for the last received message for convenience and the ability to receive messages to send before the connection is opened. +## Connection primitives -## How to use it +- [`makeWS`](#makews) — raw WebSocket with a buffered send queue (manual cleanup) +- [`createWS`](#createws) — same, but closes on owner disposal +- [`createWSState`](#createwsstate) — reactive `readyState` signal (`0`–`3`) +- [`makeReconnectingWS`](#makereconnectingws) — auto-reconnects on involuntary close (manual cleanup) +- [`createReconnectingWS`](#createreconnectingws) — same, but closes on owner disposal +- [`makeHeartbeatWS`](#makeheartbeatws) — wraps a reconnecting WS with a heartbeat/pong watchdog + +### Message primitives + +- [`createWSMessage`](#createwsmessage) — reactive signal for the **latest** received message +- [`wsMessageIterable`](#wsmessageiterable) — buffered `AsyncIterable` over WS messages +- [`createWSData`](#createwsdata) — async memo compatible with ``, `isPending`, and `latest` +- [`createWSStore`](#createwsstore) — reactive store driven by WS message patches + +--- + +## Connection primitives + +### `makeWS` + +Sets up a WebSocket with a buffered send queue. Messages sent before the connection opens are queued and flushed on `open`. Does **not** close on cleanup — use `createWS` for that. + +```ts +const ws = makeWS("ws://localhost:5000"); +createEffect( + () => serverMessage(), + msg => ws.send(msg), +); +onCleanup(() => ws.close()); +``` + +### `createWS` + +Same as `makeWS`, but registers `ws.close()` with `onCleanup`. + +```ts +const ws = createWS("ws://localhost:5000"); +createEffect( + () => serverMessage(), + msg => ws.send(msg), +); +``` + +### `createWSState` + +Returns a reactive `Accessor<0 | 1 | 2 | 3>` tracking the WebSocket's `readyState`. ```ts const ws = createWS("ws://localhost:5000"); const state = createWSState(ws); -const states = ["Connecting", "Connected", "Disconnecting", "Disconnected"]; -ws.send("it works"); -createEffect(on(ws.message, msg => console.log(msg), { defer: true })); -return

Connection: {states[state()]}

; - -const socket = makeHeartbeatWS( - makeReconnectingWS(`ws://${location.hostName}/api/ws`, undefined, { timeout: 500 }), - { message: "👍" }, +const labels = ["Connecting", "Open", "Closing", "Closed"] as const; + +return

Status: {labels[state()]}

; +``` + +### `createWSMessage` + +Returns a reactive `Accessor` that holds the **most recently received** message. Starts as `undefined`. + +```ts +const ws = createWS("ws://localhost:5000"); +const message = createWSMessage(ws); + +return

Last message: {message()}

; +``` + +> **Note — "latest wins" semantics.** `createWSMessage` uses a signal internally. In Solid 2.0, signal writes are batched: if two messages arrive before the reactive flush, only the second is seen by effects. This is fine for "current state" displays, but if your protocol can burst messages and you need to process every one, use [`wsMessageIterable`](#wsmessageiterable) or [`createWSData`](#createwsdata) instead. + +### `makeReconnectingWS` + +Returns a `WebSocket`-shaped proxy that transparently opens a new underlying connection whenever the server closes it involuntarily. + +```ts +const ws = makeReconnectingWS("ws://localhost:5000", undefined, { delay: 3000, retries: Infinity }); +createEffect( + () => serverMessage(), + msg => ws.send(msg), ); -// with the primitives starting with `make...`, one needs to manually clean up: -socket.send("this will reconnect if connection fails"); +onCleanup(() => ws.close()); ``` -### Definitions +### `createReconnectingWS` + +Same as `makeReconnectingWS`, but closes on owner disposal. + +### `makeHeartbeatWS` + +Wraps a `ReconnectingWebSocket` to send a periodic heartbeat. If no response arrives within `wait` ms the connection is force-reconnected. ```ts -/** Arguments of the primitives */ -type WSProps = [url: string, protocols?: string | string[]]; -type WSMessage = string | ArrayBufferLike | ArrayBufferView | Blob; -type WSReadyState = WebSocket.CONNECTING | WebSocket.OPEN | WebSocket.CLOSING | WebSocket.CLOSED; -type WSEventMap = { - close: CloseEvent; - error: Event; - message: MessageEvent; - open: Event; -}; -type ReconnectingWebSocket = WebSocket & { - reconnect: () => void; - // ws.send.before is meant to be used by heartbeat - send: ((msg: WSMessage) => void) & { before: () => void }; -}; -type WSHeartbeatOptions = { - /** - * Heartbeat message being sent to the server in order to validate the connection - * @default "ping" - */ - message?: WSMessage; - /** - * The time between messages being sent in milliseconds - * @default 1000 - */ - interval?: number; - /** - * The time after the heartbeat message being sent to wait for the next message in milliseconds - * @default 1500 - */ - wait?: number; -}; +const ws = makeHeartbeatWS(createReconnectingWS("ws://localhost:5000"), { + message: "ping", + interval: 1000, + wait: 1500, +}); +``` + +--- + +## Async message primitives + +These three primitives leverage Solid's async reactivity — `createMemo` with `AsyncIterable`, `` boundaries, `isPending`, and `latest` — to provide a more powerful and correct model for WebSocket data. + +### `wsMessageIterable` + +```ts +function wsMessageIterable(ws: WebSocket): AsyncIterable ``` -If you want to use the messages as a signal, have a look at the [`event-listener`](../event-listener/README.md) package: +The foundational building block. Returns a buffered `AsyncIterable` over a WebSocket's message stream. Messages that arrive while a consumer is busy are queued; none are dropped. The event listener is removed automatically when the iterator's `return()` method is called (Solid does this on memo disposal). ```ts -import { createWS } from "@solid-primitives/websocket"; -import { createEventSignal } from "@solid-primitives/event-listener"; +// Compose freely with any Solid 2.0 async primitive: +const latestQuote = createMemo(async function* () { + for await (const raw of wsMessageIterable(ws)) { + yield JSON.parse(raw) as Quote; + } +}); +``` -const ws = createWS("ws://localhost:5000"); -const messageEvent = createEventSignal(ws, "message"); -const message = () => messageEvent().data; +Works correctly with `makeReconnectingWS` — event listeners are re-attached to each new underlying connection, so the iterable survives reconnects transparently. + +**Why this doesn't drop messages:** Unlike `createWSMessage`, each yielded value triggers its own reactive flush. Messages that arrive while an earlier one is being processed are buffered and drained in order, so no message is skipped. + +### `createWSData` + +```ts +function createWSData( + ws: WebSocket, + options?: { transform?: (msg: T) => U }, +): Accessor ``` -Otherwise, you can simply use the message event to get message.data: +An async memo wrapping `wsMessageIterable`. Suspends the nearest `` boundary until the first message arrives; subsequent updates work with `isPending` and `latest`. The optional `transform` is applied to each raw message before the memo value is updated. + +```tsx +const ws = createReconnectingWS("wss://prices.example.com"); +const price = createWSData(ws, { transform: JSON.parse }); + +return ( + Waiting for first quote…

}> +

price()) ? "stale" : ""}> + Bid: {price().bid} / Ask: {price().ask} +

+ +); +``` + +Comparison with `createWSMessage`: + +| | `createWSMessage` | `createWSData` | +| ---------------------------------------- | ------------------------- | -------------------------------- | +| Drops burst messages | Yes | No | +| Works with `` | No | Yes | +| `isPending()` support | No | Yes | +| `latest()` support | No | Yes | +| Returns `undefined` before first message | Yes | No — throws (suspends) | +| Best for | Simple last-value display | State-source WS, real-time feeds | + +### `createWSStore` ```ts -import { createStore } from "solid-js/store"; -import { createReconnectingWS, WSMessage } from "@solid-primitives/websocket"; +function createWSStore( + ws: WebSocket, + options: { + initial: S; + patch: (draft: S, msg: T) => void; + }, +): [store: Store, setStore: StoreSetter] +``` + +A reactive store driven by WebSocket messages as incremental patches. `patch` is called for each incoming message with a mutable draft of the store — mutate it directly, no return value needed. The event listener is removed on owner disposal. + +```tsx +interface AppState { + users: string[]; + status: "connecting" | "online" | "offline"; +} + +const ws = createReconnectingWS("wss://app.example.com"); +const [state] = createWSStore(ws, { + initial: { users: [], status: "connecting" }, + patch(draft, msg) { + Object.assign(draft, JSON.parse(msg)); + }, +}); + +return

Users online: {state.users.length}

; +``` -const ws = createReconnectingWS("ws://localhost:5000"); -const [messages, setMessages] = createStore(); -ws.addEventListener("message", (ev) => setMessages(messages.length, ev.data)); +You can also use the returned setter to apply local updates: - messages}> - {(message) => ...} - +```ts +const [state, setState] = createWSStore(ws, { initial: { count: 0 }, patch }); + +// imperative write from a button click, etc. +setState(s => { s.count = 0; }); ``` -## Setting up a websocket server +--- + +## Composing with `action` (request/response pattern) -While you can use this primitive with solid-start, it already provides a package for websockets that handles both the server and the client side: +For protocols with correlated request/response over a shared WebSocket, Solid `action` is used: ```ts -import { createWebSocketServer } from "solid-start/websocket"; -import server$ from "solid-start/server"; - -const pingPong = createWebSocketServer( - server$(function (webSocket) { - webSocket.addEventListener("message", async msg => { - try { - // Parse the incoming message - let incomingMessage = JSON.parse(msg.data); - console.log(incomingMessage); - - switch (incomingMessage.type) { - case "ping": - webSocket.send( - JSON.stringify([ - { - type: "pong", - data: { - id: incomingMessage.data.id, - time: Date.now(), - }, - }, - ]), - ); - break; - } - } catch (err: any) { - // Report any exceptions directly back to the client. As with our handleErrors() this - // probably isn't what you'd want to do in production, but it's convenient when testing. - webSocket.send(JSON.stringify({ error: err.stack })); +const queryServer = action(function* (payload: RequestPayload) { + const id = crypto.randomUUID(); + + setOptimisticState(draft => { + draft.loading = true; + }); + + ws.send(JSON.stringify({ ...payload, id })); + + const response: ResponsePayload = yield new Promise(resolve => { + const handler = (e: MessageEvent) => { + const msg = JSON.parse(e.data); + if (msg.id === id) { + ws.removeEventListener("message", handler); + resolve(msg); } - }); - }), -); + }; + ws.addEventListener("message", handler); + }); + + refresh(() => serverData()); + return response; +}); ``` -Otherwise, in order to set up your own production-use websocket server, we recommend packages like +--- + +## Type reference -- nodejs: [`ws`](https://github.com/websockets/ws) -- rust: [`websocket`](https://docs.rs/websocket/latest/websocket/) +```ts +type WSMessage = string | ArrayBufferLike | ArrayBufferView | Blob; -## Demo +type WSReconnectOptions = { + delay?: number; // ms between reconnect attempts — default: 3000 + retries?: number; // max reconnect attempts — default: Infinity +}; -You may view a working example here: -https://primitives.solidjs.community/playground/websocket/ +type ReconnectingWebSocket = WebSocket & { + reconnect: () => void; + send: ((msg: WSMessage) => void) & { before?: () => void }; +}; + +type WSHeartbeatOptions = { + message?: WSMessage; // default: "ping" + interval?: number; // ms between heartbeats — default: 1000 + wait?: number; // ms to wait for pong before reconnecting — default: 1500 +}; + +type WSDataOptions = { + transform?: (msg: T) => U; // map each raw message before the memo value updates +}; + +type WSStoreOptions = { + initial: S; // starting store state + patch: (draft: S, msg: T) => void; // mutate the draft for each incoming message +}; +``` ## Changelog diff --git a/packages/websocket/dev/index.tsx b/packages/websocket/dev/index.tsx deleted file mode 100644 index de27e8f3e..000000000 --- a/packages/websocket/dev/index.tsx +++ /dev/null @@ -1,72 +0,0 @@ -import { type Component, For, Show, createSignal, onMount } from "solid-js"; -import { createStore } from "solid-js/store"; -import { type WSMessage, createReconnectingWS } from "../src/index.js"; - -const App: Component = () => { - const [textArea, setTextArea] = createSignal(); - const [messageBox, setMessageBox] = createSignal(); - const ws = createReconnectingWS("wss://socketsbay.com/wss/v2/1/demo/"); - const [messages, setMessages] = createStore([]); - const addMessage = (msg: WSMessage) => { - setMessages(messages.length, msg); - setTimeout(() => messageBox()?.lastElementChild?.scrollIntoView(), 50); - }; - ws.addEventListener("message", msg => msg && addMessage(`RECEIVED: ${msg}`)); - - return ( -
-
-

Chat demo

- -
- - {message => ( -
- {message instanceof Blob && message.type.startsWith("image/") ? ( - - ) : ( - message.toString() - )} -
- )} - -
-
{ - e.preventDefault(); - const field = textArea(); - const text = field?.value; - if (text) { - ws.send(text); - text && addMessage(`SENT: ${text}`); - field.value = ""; - } - }} - > -