react-websocket 2.1.0 → 3.0.0

package/dist/core.d.cts

@@ -0,0 +1,338 @@
+/**
+ * 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>;
+
+export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketOptions, createWebSocket };

package/dist/core.d.ts

@@ -0,0 +1,338 @@
+/**
+ * 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>;
+
+export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type WebSocketClient, type WebSocketOptions, createWebSocket };