react-websocket 4.0.0 → 4.18.0

package/dist/timeline.d.cts

@@ -1,219 +1,4 @@
-//#region src/types.d.ts
-/**
- * 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 stable connection. A connection that closes
-   * within `reconnect.minUptime` of opening counts as failed. `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;
-}
-/** Per-message options for `send()`. */
-interface SendOptions {
-  /**
-   * Drop the message instead of queueing it when the socket isn't open. For data that
-   * is stale by the time a reconnect finishes, such as player input or cursor positions.
-   * @default false
-   */
-  volatile?: boolean;
-  /**
-   * Keep only the newest queued message with this key. Sending again with the same key
-   * while disconnected replaces the earlier one, which moves to the back of the queue
-   * (or of the `priority` messages, for a priority one).
-   * For state where only the latest value matters, such as "my position is now (x, y)".
-   */
-  key?: string;
-  /**
-   * Queue this message ahead of every message queued without `priority`, after earlier
-   * priority messages. For control messages that must not wait behind a backlog, such as
-   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
-   *
-   * It only matters while the socket isn't open: once a message is handed to the browser,
-   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
-   * @default false
-   */
-  priority?: boolean;
-  /**
-   * Drop the message instead of sending it while more than this many bytes are already
-   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
-   * a slow link, such as audio frames or per-tick input, where a late message is worse than
-   * none. `send()` returns `false`, and `onDrop` isn't called.
-   *
-   * Only checked while the socket is open: a message queued while disconnected is sent on
-   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
-   * it well above one burst of messages.
-   *
-   * @example
-   * ```ts
-   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
-   * ```
-   */
-  maxBuffered?: number;
-  /**
-   * Called if the message is dropped from the queue without being sent: replaced by a
-   * newer message with the same `key`, or evicted by `queue.limit`. Not called when the
-   * queue is cleared because the client closed or gave up, or when `send()` drops the
-   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
-   */
-  onDrop?: () => void;
-}
-/**
- * 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), unless
-   * `options.volatile` is set.
-   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
-   *   (`volatile` while not open, or `maxBuffered` while open).
-   *
-   * @example
-   * ```ts
-   * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
-   * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
-   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
-   * ```
-   */
-  send(message: Out, options?: SendOptions): 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;
-}
-//#endregion
+import { t as WebSocketClient } from "./types-BEecFqIB.cjs";
 //#region src/latency.d.ts
 /** Latest latency measurements. A new object is created on every change. */
 interface Latency {

package/dist/types-BEecFqIB.d.cts

@@ -0,0 +1,268 @@
+//#region src/types.d.ts
+/**
+ * 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. If
+ *   nothing held it when it stopped, the next hook to mount starts it again.
+ */
+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 stable connection. A connection that closes
+   * within `reconnect.minUptime` of opening counts as failed. `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;
+}
+/** Options for `client.migrate()`. */
+interface MigrateOptions {
+  /**
+   * Where to connect instead: a URL, or a function called before the connection, like the
+   * client's own `url`. Later reconnects go there too, until the client is closed, gives up or
+   * is torn down.
+   * @default the client's current URL
+   */
+  url?: UrlSource;
+  /**
+   * Move at a random moment within this many ms, so that clients asked to move together don't
+   * all reconnect at once.
+   * @default 0
+   */
+  within?: number;
+}
+/** Per-message options for `send()`. */
+interface SendOptions {
+  /**
+   * Drop the message instead of queueing it when the socket isn't open. For data that
+   * is stale by the time a reconnect finishes, such as player input or cursor positions.
+   * @default false
+   */
+  volatile?: boolean;
+  /**
+   * Keep only the newest queued message with this key. Sending again with the same key
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (or of the `priority` messages, for a priority one).
+   * For state where only the latest value matters, such as "my position is now (x, y)".
+   */
+  key?: string;
+  /**
+   * Queue this message ahead of every message queued without `priority`, after earlier
+   * priority messages. For control messages that must not wait behind a backlog, such as
+   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
+   *
+   * It only matters while the socket isn't open: once a message is handed to the browser,
+   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
+   * @default false
+   */
+  priority?: boolean;
+  /**
+   * Drop the message instead of sending it while more than this many bytes are already
+   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
+   * a slow link, such as audio frames or per-tick input, where a late message is worse than
+   * none. `send()` returns `false`, and `onDrop` isn't called.
+   *
+   * Only checked while the socket is open: a message queued while disconnected is sent on
+   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
+   * it well above one burst of messages.
+   *
+   * @example
+   * ```ts
+   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
+   * ```
+   */
+  maxBuffered?: number;
+  /**
+   * Drop the message instead of sending it if it has been queued for longer than this many
+   * ms, for messages that go stale during a long outage, such as "typing" or a price quote.
+   * Overrides `queue.maxAge`. Checked when the socket opens and whenever another message is
+   * queued; `onDrop` is called then.
+   */
+  maxAge?: number;
+  /**
+   * Called if the message is dropped from the queue without being sent: replaced by a
+   * newer message with the same `key`, evicted by `queue.limit`, or older than `maxAge`. Not
+   * called when the queue is cleared because the client closed or gave up, or when `send()`
+   * drops the message right away (`volatile` while not open, or `maxBuffered`) and returns
+   * `false`.
+   */
+  onDrop?: () => void;
+}
+/**
+ * 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), unless
+   * `options.volatile` is set.
+   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
+   *   (`volatile` while not open, or `maxBuffered` while open).
+   *
+   * @example
+   * ```ts
+   * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
+   * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
+   * ```
+   */
+  send(message: Out, options?: SendOptions): 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. Closed while no hook holds it, the next hook to mount starts it again.
+   *
+   * Like `WebSocket.close()`, it throws for a code or reason the socket rejects (browsers take
+   * `1000` or `3000`–`4999`, and a reason up to 123 bytes), and then nothing has changed.
+   * @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;
+  /**
+   * Move to a new connection without a gap, for example when the server asks its clients to
+   * before a deploy. At a random moment within `options.within` ms, it opens a new connection
+   * (to `options.url`, if given) and, once that one is open, closes the current one with code
+   * `1000`. Until then the current connection keeps working, so the status stays `open` and
+   * `send()` doesn't queue.
+   *
+   * `open` listeners run for the new connection, as after any reconnect, so handshakes and
+   * topic subscriptions are sent again. Requests the old connection hadn't answered fail as on
+   * a lost connection. If the new connection fails before opening, the current one stays. If
+   * the client isn't open when the moment comes, only the URL changes, for the next attempt.
+   * A later call replaces one that hasn't moved yet.
+   *
+   * @example
+   * ```ts
+   * // The server sends { type: 'reconnect', within: 30000 } before it shuts down.
+   * live.on('message', message => {
+   *   if (message.type === 'reconnect') live.migrate({ within: message.within, url: message.url });
+   * });
+   * ```
+   */
+  migrate(options?: MigrateOptions): 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;
+}
+//#endregion
+export { WebSocketClient as t };
+//# sourceMappingURL=types-BEecFqIB.d.cts.map