react-websocket 2.1.0 → 3.0.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/react.ts"],"sourcesContent":["export * from './core';\nexport { useWebSocket, useWebSocketEvent, useWebSocketStatus } from './react';\nexport type { UseWebSocketOptions, UseWebSocketResult, WebSocketHandlers } from './react';\n","import { useEffect, useInsertionEffect, useRef, useSyncExternalStore } from 'react';\n// Import the client through the `core` entry: the build keeps it external, so both entries\n// share one copy of it (and of `MessageError`).\nimport { createWebSocket } from './core';\nimport type {\n  CloseInfo,\n  EventMap,\n  Snapshot,\n  Status,\n  WebSocketClient,\n  WebSocketOptions\n} from './types';\n\n/**\n * Per-component event handlers. They always see the component's latest props and\n * state, and changing them never reconnects.\n */\nexport interface WebSocketHandlers<In> {\n  /** The socket opened (initially or after a reconnect). */\n  onOpen?: (event: Event) => void;\n  /** A message arrived and passed `parse`/`json` and `schema`. */\n  onMessage?: (message: In, event: MessageEvent) => void;\n  /** A socket closed. Called whether or not it will be retried. */\n  onClose?: (close: CloseInfo) => void;\n  /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */\n  onError?: (error: Event | Error) => void;\n  /**\n   * `false` releases this component's hold on the connection and stops its handlers.\n   * The connection closes once nothing else holds it.\n   * @default true\n   */\n  enabled?: boolean;\n}\n\n/** Options for `useWebSocket(url, options)`: connection options plus handlers. */\nexport interface UseWebSocketOptions<In, Out>\n  extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {}\n\n/** What `useWebSocket` returns: the current {@link Snapshot} plus stable actions. */\nexport interface UseWebSocketResult<In, Out> extends Snapshot<In> {\n  /** Send now, or queue until open. Returns `true` if sent immediately. Stable identity. */\n  send: (message: Out) => boolean;\n  /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */\n  close: (code?: number, reason?: string) => void;\n  /** Drop the socket and connect again right away. Stable identity. */\n  reconnect: () => void;\n  /** The underlying client, or `null` when the URL is `null`/`undefined`. */\n  client: WebSocketClient<In, Out> | null;\n}\n\nconst IDLE: Snapshot<never> = Object.freeze({ status: 'idle', lastMessage: undefined, attempt: 0 });\nconst idleSnapshot = () => IDLE;\nconst idleStatus = (): Status => 'idle';\nconst noopSubscribe = () => () => {};\nconst noopSend = () => false;\nconst noop = () => {};\n\n// Same key as `ON_TEARDOWN` in ./client, which this entry must not import directly.\nconst ON_TEARDOWN = Symbol.for('react-websocket.onTeardown');\n\n// Hooks given the same URL (and protocols) share one connection.\nconst registry = new Map<string, WebSocketClient<any, any>>();\n\nfunction sharedClient<In, Out>(url: string, options: WebSocketOptions<In, Out>) {\n  // Don't let server renders accumulate clients that can never be torn down.\n  if (typeof window === 'undefined') return createWebSocket(url, options);\n  const key = `${url}\\u0000${JSON.stringify(options.protocols ?? null)}`;\n  let client = registry.get(key) as WebSocketClient<In, Out> | undefined;\n  if (!client) {\n    const created: WebSocketClient<In, Out> = createWebSocket(url, {\n      ...options,\n      [ON_TEARDOWN]: () => {\n        if (registry.get(key) === created) registry.delete(key);\n      }\n    } as WebSocketOptions<In, Out>);\n    registry.set(key, created);\n    client = created;\n  }\n  return client;\n}\n\n/** Always-current value for use inside effects and event listeners (a `useEffectEvent` stand-in). */\nfunction useLatest<T>(value: T) {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\nfunction useHold(client: WebSocketClient<any, any> | null, enabled: boolean) {\n  useEffect(() => {\n    if (client && enabled) return client.acquire();\n  }, [client, enabled]);\n}\n\n/**\n * Connect to a WebSocket and re-render with its status and latest message.\n *\n * - With a URL, every component using the same URL (and `protocols`) shares one\n *   connection. Its options come from whichever component created it first.\n * - With a client from `createWebSocket()`, options are the client's; only handlers\n *   and `enabled` apply here.\n * - With `null` or `undefined`, nothing connects and the status stays `idle`.\n *\n * The connection opens on mount and closes one tick after the last component using it\n * unmounts, so StrictMode and `<Activity>` don't open duplicate sockets.\n *\n * Re-renders on status changes and on every message. For high-frequency streams use\n * `useWebSocketEvent` and `useWebSocketStatus` instead.\n *\n * @example\n * ```tsx\n * const { status, lastMessage, send } = useWebSocket<Price, Order>('wss://api.example.com/prices', {\n *   json: true,\n *   onMessage: price => console.log(price)\n * });\n * ```\n */\nexport function useWebSocket<In = unknown, Out = unknown>(\n  url: string | null | undefined,\n  options?: UseWebSocketOptions<In, Out>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  client: WebSocketClient<In, Out> | null | undefined,\n  options?: WebSocketHandlers<In>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  target: string | WebSocketClient<In, Out> | null | undefined,\n  options: UseWebSocketOptions<In, Out> = {}\n): UseWebSocketResult<In, Out> {\n  const client =\n    target == null ? null : typeof target === 'string' ? sharedClient(target, options) : target;\n  const enabled = options.enabled ?? true;\n\n  const snapshot = useSyncExternalStore<Snapshot<In>>(\n    client ? client.subscribe : noopSubscribe,\n    client ? client.getSnapshot : idleSnapshot,\n    idleSnapshot\n  );\n\n  const handlers = useLatest(options);\n  useEffect(() => {\n    if (!client || !enabled) return;\n    const offs = [\n      client.on('open', event => handlers.current.onOpen?.(event)),\n      client.on('message', (message, event) => handlers.current.onMessage?.(message, event)),\n      client.on('close', info => handlers.current.onClose?.(info)),\n      client.on('error', error => handlers.current.onError?.(error))\n    ];\n    return () => offs.forEach(off => off());\n  }, [client, enabled, handlers]);\n  useHold(client, enabled);\n\n  return {\n    ...snapshot,\n    send: client ? client.send : noopSend,\n    close: client ? client.close : noop,\n    reconnect: client ? client.reconnect : noop,\n    client\n  };\n}\n\n/**\n * Listen to a client's events without re-rendering the component. The listener always\n * sees the latest props and state. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));\n * ```\n */\nexport function useWebSocketEvent<In, K extends keyof EventMap<In>>(\n  client: WebSocketClient<In, any> | null | undefined,\n  type: K,\n  listener: EventMap<In>[K]\n): void {\n  const latest = useLatest(listener);\n  useEffect(() => {\n    if (!client) return;\n    const off = client.on(type, ((...args: unknown[]) =>\n      (latest.current as (...a: unknown[]) => void)(...args)) as EventMap<In>[K]);\n    const release = client.acquire();\n    return () => {\n      off();\n      release();\n    };\n  }, [client, type, latest]);\n}\n\n/**\n * The connection status of a client. Re-renders only when the status changes, not on\n * messages. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'\n * ```\n */\nexport function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status {\n  const status = useSyncExternalStore(\n    client ? client.subscribe : noopSubscribe,\n    client ? () => client.getSnapshot().status : idleStatus,\n    idleStatus\n  );\n  useHold(client ?? null, true);\n  return status;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,418 @@
+/**
+ * Where to connect: a URL, or a function that returns one (sync or async).
+ *
+ * A function is called before **every** connection attempt, including reconnects,
+ * so it can put a fresh auth token in the URL. If it throws or rejects, that counts
+ * as a failed attempt and is retried with backoff.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(async () => `wss://api.example.com/live?token=${await getToken()}`);
+ * ```
+ */
+type UrlSource = string | (() => string | Promise<string>);
+/**
+ * Connection state.
+ *
+ * - `idle`: not connected and not trying to be. Nobody is using the client yet, or everyone stopped.
+ * - `connecting`: the first attempt is in progress.
+ * - `open`: connected. `send()` goes out immediately.
+ * - `reconnecting`: the connection dropped (or an attempt failed) and a retry is scheduled or in progress.
+ * - `closed`: stopped for good, by `close()` or after giving up on reconnecting.
+ *   It stays closed until `connect()` or `reconnect()` is called, or every hook unmounts.
+ */
+type Status = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
+/** The client's state as seen by React. A new object is created on every change. */
+interface Snapshot<In> {
+    /** Connection state. */
+    readonly status: Status;
+    /** Most recent message (after `parse`/`json` and `schema`), kept across reconnects. */
+    readonly lastMessage: In | undefined;
+    /** Consecutive failed attempts since the last successful open. `0` while open. */
+    readonly attempt: number;
+}
+/** Details of a closed connection, from the browser's `CloseEvent`. */
+interface CloseInfo {
+    /** Close code: `1000` is a normal close, `1006` an abnormal one (e.g. network loss), `4000`–`4999` are yours. */
+    readonly code: number;
+    /** Close reason sent by the side that closed the connection. Often empty. */
+    readonly reason: string;
+    /** Whether the closing handshake completed. */
+    readonly wasClean: boolean;
+}
+/** Anything `WebSocket.prototype.send` accepts: a string, `Blob`, `ArrayBuffer` or typed array. */
+type SendData = Parameters<WebSocket['send']>[0];
+/** Reconnect timing. Delay before attempt `n` = `min(maxDelay, minDelay * factor ** (n - 1))`, minus jitter. */
+interface ReconnectOptions {
+    /**
+     * Maximum consecutive reconnect attempts. When the last one fails too, the client
+     * gives up: the status becomes `closed` and `ready` rejects. `0` never retries.
+     * @default Infinity
+     */
+    maxAttempts?: number;
+    /**
+     * Delay before the first retry, in ms.
+     * @default 1000
+     */
+    minDelay?: number;
+    /**
+     * Upper bound for the delay, in ms.
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier applied per attempt.
+     * @default 2
+     */
+    factor?: number;
+    /**
+     * Randomly shave up to this fraction (0–1) off each delay, so that many clients
+     * dropped at once don't all reconnect at the same moment.
+     * @default 0.5
+     */
+    jitter?: number;
+    /**
+     * Called on every unexpected close. Return `false` to stop reconnecting.
+     *
+     * @example
+     * ```ts
+     * // Don't retry when the server rejects our credentials.
+     * shouldReconnect: close => close.code !== 4001
+     * ```
+     * @default () => true
+     */
+    shouldReconnect?: (close: CloseInfo) => boolean;
+}
+/** Application-level keep-alive. Useful behind proxies that drop idle connections. */
+interface HeartbeatOptions {
+    /** Send `message` every `interval` ms while open. */
+    interval: number;
+    /**
+     * Sent as-is (it is not passed through `serialize` or `json`).
+     * @default 'ping'
+     */
+    message?: string;
+    /** Incoming data equal to this string is swallowed instead of being delivered as a message. */
+    pong?: string;
+    /**
+     * If nothing at all arrives within this many ms after a ping, the connection is
+     * treated as dead: it closes with code `4000` and reconnects.
+     */
+    timeout?: number;
+}
+/** Bounds for the send queue. */
+interface QueueOptions {
+    /**
+     * Maximum number of messages held while not connected. When full, the oldest
+     * message is dropped.
+     * @default Infinity
+     */
+    limit?: number;
+}
+/**
+ * The minimal [Standard Schema v1](https://standardschema.dev) interface, implemented
+ * by zod (3.24+), valibot (1.0+), arktype (2.0+) and others. You don't need to
+ * import this; pass your schema object directly.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/** The result of a Standard Schema `validate` call. */
+type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+    }>;
+};
+/**
+ * Connection options, shared by `createWebSocket(url, options)` and `useWebSocket(url, options)`.
+ *
+ * @typeParam In - Type of incoming messages (after `parse`/`json`/`schema`).
+ * @typeParam Out - Type accepted by `send()`.
+ */
+interface WebSocketOptions<In = unknown, Out = unknown> {
+    /** Sub-protocol(s) passed to the `WebSocket` constructor. */
+    protocols?: string | string[];
+    /**
+     * How binary messages are exposed.
+     * @default 'blob'
+     */
+    binaryType?: BinaryType;
+    /**
+     * `JSON.parse` incoming and `JSON.stringify` outgoing messages. Messages that fail
+     * to parse are reported to `onError` as a {@link MessageError} and not delivered.
+     * @default false
+     */
+    json?: boolean;
+    /**
+     * Custom decoder for incoming `event.data`. Takes precedence over `json`.
+     * Throwing reports a {@link MessageError} and drops the message.
+     */
+    parse?: (data: unknown) => unknown;
+    /** Custom encoder for outgoing messages. Takes precedence over `json`. */
+    serialize?: (message: Out) => SendData;
+    /**
+     * Validate incoming messages (after parsing) with any Standard Schema library.
+     * Invalid messages are reported to `onError` as a {@link MessageError} and not delivered.
+     * The message type `In` is inferred from it.
+     *
+     * @example
+     * ```ts
+     * createWebSocket(url, { json: true, schema: z.object({ price: z.number() }) });
+     * ```
+     */
+    schema?: StandardSchemaV1<unknown, In>;
+    /**
+     * Reconnect with exponential backoff after an unexpected close. `false` disables it.
+     * @default true
+     */
+    reconnect?: boolean | ReconnectOptions;
+    /** Send a ping on an interval and, optionally, reconnect when the server goes quiet. */
+    heartbeat?: HeartbeatOptions;
+    /**
+     * Buffer `send()` calls made while not connected and send them, in order, on open
+     * (right after `open` listeners run).
+     * `false` drops them instead. `{ limit }` caps the buffer, dropping the oldest.
+     * The queue is cleared by `close()` or when the client gives up.
+     * @default true
+     */
+    queue?: boolean | QueueOptions;
+    /**
+     * Receives debug messages about connection attempts, retries and dropped messages.
+     * @example
+     * ```ts
+     * logger: console.debug
+     * ```
+     */
+    logger?: (message: string, ...details: unknown[]) => void;
+    /**
+     * `WebSocket` implementation to use, e.g. a mock in tests or the `ws` package in Node.
+     * When omitted, the global `WebSocket` is used in browsers. During a server render
+     * (no `window`), nothing connects unless an implementation is passed.
+     */
+    WebSocket?: typeof WebSocket;
+}
+/**
+ * Reported via the `error` event (and `onError`) when an incoming message can't be
+ * decoded by `parse`/`json` or fails `schema` validation. The message is not delivered.
+ *
+ * @example
+ * ```ts
+ * onError(error) {
+ *   if (error instanceof MessageError) report(error.data, error.issues);
+ * }
+ * ```
+ */
+declare class MessageError extends Error {
+    /** The raw `event.data` that failed. */
+    readonly data: unknown;
+    /** Schema validation issues, when the message failed `schema`. */
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+    }> | undefined;
+    constructor(message: string, data: unknown, options?: {
+        cause?: unknown;
+        issues?: ReadonlyArray<{
+            readonly message: string;
+        }>;
+    });
+}
+/** Events emitted by a client. Subscribe with `client.on(type, listener)` or `useWebSocketEvent`. */
+interface EventMap<In> {
+    /**
+     * The socket opened (initially or after a reconnect). Listeners run before queued
+     * messages are sent, so a handshake sent from here goes out first.
+     */
+    open: (event: Event) => void;
+    /** A message arrived and passed `parse` and `schema`. */
+    message: (message: In, event: MessageEvent) => void;
+    /** A socket closed, whether it will be retried or not. */
+    close: (close: CloseInfo) => void;
+    /**
+     * A socket error `Event`, a {@link MessageError} for an undecodable or invalid message,
+     * or the `Error` thrown by the `WebSocket` constructor or a `url` function.
+     */
+    error: (error: Event | MessageError | Error) => void;
+}
+/**
+ * A WebSocket connection that reconnects, queues, decodes and can be shared.
+ * Create one with `createWebSocket()`.
+ *
+ * The connection is reference-counted: it opens when the first hook mounts (or
+ * `ready` is read) and closes one tick after the last hook unmounts. Calling
+ * `connect()` keeps it open regardless, until `close()`.
+ *
+ * @typeParam In - Type of incoming messages.
+ * @typeParam Out - Type accepted by `send()`.
+ */
+interface WebSocketClient<In = unknown, Out = unknown> {
+    /** The URL (or URL function) the client was created with. */
+    readonly url: UrlSource;
+    /**
+     * A promise that resolves once the socket has opened. Reading it starts an idle client.
+     *
+     * It stays resolved through automatic reconnects, so `use(client.ready)` shows a
+     * Suspense fallback only for the first connection, never on a network blip; use
+     * `status` to show reconnects. It rejects when the client gives up reconnecting, when
+     * `close()` is called, and during a server render. After that, `connect()` or
+     * `reconnect()` make it a new pending promise.
+     *
+     * It is safe to pass to React 19's `use()`: the same promise is returned until its state
+     * changes, and it carries `status`/`value`/`reason` so `use()` doesn't suspend when it is
+     * already settled.
+     */
+    readonly ready: Promise<void>;
+    /** The current underlying `WebSocket`, if any. An escape hatch; prefer the client's methods. */
+    readonly socket: WebSocket | null;
+    /** Subscribe to snapshot changes. Compatible with `useSyncExternalStore`. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** The current {@link Snapshot}. Returns the same object until something changes. */
+    getSnapshot(): Snapshot<In>;
+    /**
+     * Listen to an event. Returns an unsubscribe function. Listener errors are re-thrown
+     * asynchronously, so one failing listener doesn't break the others.
+     */
+    on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
+    /**
+     * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
+     * open, the message is queued and sent on open (see the `queue` option).
+     * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+     */
+    send(message: Out): boolean;
+    /**
+     * Start connecting, and keep the connection open even when no hook is using the
+     * client, until `close()` is called. Does nothing if already connecting or open.
+     */
+    connect(): void;
+    /**
+     * Close the connection and stop reconnecting. The status becomes `closed` and the
+     * send queue is cleared. Mounted hooks stay mounted; call `connect()` or `reconnect()`
+     * to start again.
+     * @param code - Close code. @default 1000
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Drop the current socket (if any) and connect again immediately, resetting the
+     * backoff. Also restarts a `closed` client.
+     */
+    reconnect(): void;
+    /**
+     * Hold the connection open until the returned function is called. This is what the
+     * hooks use; call it yourself to integrate with non-React code.
+     * @returns A release function (safe to call more than once).
+     */
+    acquire(): () => void;
+}
+
+/**
+ * Create a WebSocket client, usually at module level, to share across components.
+ *
+ * Nothing connects until a hook uses it, `ready` is read, or `connect()` is called.
+ * It closes one tick after the last hook unmounts, unless `connect()` was called.
+ *
+ * @param url - A URL, or a function (sync or async) called before every connection
+ *   attempt, e.g. to put a fresh auth token in the URL on each reconnect.
+ * @typeParam In - Type of incoming messages. Inferred from `options.schema` if given.
+ * @typeParam Out - Type accepted by `send()`.
+ *
+ * @example
+ * ```ts
+ * type ChatIn = { user: string; text: string };
+ * type ChatOut = { text: string };
+ *
+ * export const chat = createWebSocket<ChatIn, ChatOut>('wss://api.example.com/chat', { json: true });
+ * ```
+ */
+declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
+
+/**
+ * Per-component event handlers. They always see the component's latest props and
+ * state, and changing them never reconnects.
+ */
+interface WebSocketHandlers<In> {
+    /** The socket opened (initially or after a reconnect). */
+    onOpen?: (event: Event) => void;
+    /** A message arrived and passed `parse`/`json` and `schema`. */
+    onMessage?: (message: In, event: MessageEvent) => void;
+    /** A socket closed. Called whether or not it will be retried. */
+    onClose?: (close: CloseInfo) => void;
+    /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */
+    onError?: (error: Event | Error) => void;
+    /**
+     * `false` releases this component's hold on the connection and stops its handlers.
+     * The connection closes once nothing else holds it.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/** Options for `useWebSocket(url, options)`: connection options plus handlers. */
+interface UseWebSocketOptions<In, Out> extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {
+}
+/** What `useWebSocket` returns: the current {@link Snapshot} plus stable actions. */
+interface UseWebSocketResult<In, Out> extends Snapshot<In> {
+    /** Send now, or queue until open. Returns `true` if sent immediately. Stable identity. */
+    send: (message: Out) => boolean;
+    /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */
+    close: (code?: number, reason?: string) => void;
+    /** Drop the socket and connect again right away. Stable identity. */
+    reconnect: () => void;
+    /** The underlying client, or `null` when the URL is `null`/`undefined`. */
+    client: WebSocketClient<In, Out> | null;
+}
+/**
+ * Connect to a WebSocket and re-render with its status and latest message.
+ *
+ * - With a URL, every component using the same URL (and `protocols`) shares one
+ *   connection. Its options come from whichever component created it first.
+ * - With a client from `createWebSocket()`, options are the client's; only handlers
+ *   and `enabled` apply here.
+ * - With `null` or `undefined`, nothing connects and the status stays `idle`.
+ *
+ * The connection opens on mount and closes one tick after the last component using it
+ * unmounts, so StrictMode and `<Activity>` don't open duplicate sockets.
+ *
+ * Re-renders on status changes and on every message. For high-frequency streams use
+ * `useWebSocketEvent` and `useWebSocketStatus` instead.
+ *
+ * @example
+ * ```tsx
+ * const { status, lastMessage, send } = useWebSocket<Price, Order>('wss://api.example.com/prices', {
+ *   json: true,
+ *   onMessage: price => console.log(price)
+ * });
+ * ```
+ */
+declare function useWebSocket<In = unknown, Out = unknown>(url: string | null | undefined, options?: UseWebSocketOptions<In, Out>): UseWebSocketResult<In, Out>;
+declare function useWebSocket<In, Out>(client: WebSocketClient<In, Out> | null | undefined, options?: WebSocketHandlers<In>): UseWebSocketResult<In, Out>;
+/**
+ * Listen to a client's events without re-rendering the component. The listener always
+ * sees the latest props and state. Keeps the connection open while mounted.
+ *
+ * @example
+ * ```tsx
+ * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));
+ * ```
+ */
+declare function useWebSocketEvent<In, K extends keyof EventMap<In>>(client: WebSocketClient<In, any> | null | undefined, type: K, listener: EventMap<In>[K]): void;
+/**
+ * The connection status of a client. Re-renders only when the status changes, not on
+ * messages. Keeps the connection open while mounted.
+ *
+ * @example
+ * ```tsx
+ * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'
+ * ```
+ */
+declare function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status;
+
+export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketClient, type WebSocketHandlers, type WebSocketOptions, createWebSocket, useWebSocket, useWebSocketEvent, useWebSocketStatus };