react-websocket 3.6.0 → 4.0.0

package/dist/core.d.cts

@@ -29,7 +29,10 @@ interface Snapshot<In> {
   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. */
+  /**
+   * 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`. */
@@ -51,6 +54,14 @@ interface ReconnectOptions {
    * @default Infinity
    */
   maxAttempts?: number;
+  /**
+   * How long a connection must stay open, in ms, before the backoff resets. One that closes
+   * sooner counts as a failed attempt, so a server that accepts and then closes right away
+   * (e.g. rejecting the credentials sent on open) is retried with a growing delay, and
+   * `maxAttempts` still applies. `0` resets on every open.
+   * @default 5000
+   */
+  minUptime?: number;
   /**
    * Delay before the first retry, in ms.
    * @default 1000
@@ -68,19 +79,26 @@ interface ReconnectOptions {
   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
+   * dropped at once don't all reconnect at the same moment. The default `1` picks each
+   * delay at random between 0 and the backoff ("full jitter").
+   * @default 1
    */
   jitter?: number;
   /**
    * Called on every unexpected close. Return `false` to stop reconnecting.
    *
+   * The default, `retryableClose`, retries everything except `1002` (protocol error), `1003`
+   * (unsupported data) and `1008` (policy violation). Your own function replaces it; call
+   * `retryableClose` from it to keep that rule, or return `true` to retry every close.
+   *
    * @example
    * ```ts
-   * // Don't retry when the server rejects our credentials.
-   * shouldReconnect: close => close.code !== 4001
+   * import { retryableClose } from 'react-websocket';
+   *
+   * // Also stop when our server rejects the credentials.
+   * shouldReconnect: close => close.code !== 4001 && retryableClose(close)
    * ```
-   * @default () => true
+   * @default retryableClose
    */
   shouldReconnect?: (close: CloseInfo) => boolean;
 }
@@ -155,7 +173,8 @@ interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
    * message is dropped, skipping `priority` messages unless nothing else is queued.
-   * @default Infinity
+   * `Infinity` keeps every message.
+   * @default 100
    */
   limit?: number;
 }
@@ -231,8 +250,8 @@ interface WebSocketOptions<In = unknown, Out = unknown> {
   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.
+   * (right after `open` listeners run). It holds up to 100 messages, dropping the oldest;
+   * `{ limit }` changes that. `false` drops messages instead of queueing them.
    * The queue is cleared by `close()` or when the client gives up.
    * @default true
    */
@@ -374,6 +393,20 @@ interface WebSocketClient<In = unknown, Out = unknown> {
 }
 //#endregion
 //#region src/client.d.ts
+/**
+ * The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+ * `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+ * retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(url, {
+ *   // Also stop on our server's "invalid token" code.
+ *   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+ * });
+ * ```
+ */
+export declare function retryableClose(close: CloseInfo): boolean;
 /**
  * Create a WebSocket client, usually at module level, to share across components.
  *

package/dist/core.d.ts

@@ -29,7 +29,10 @@ interface Snapshot<In> {
   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. */
+  /**
+   * 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`. */
@@ -51,6 +54,14 @@ interface ReconnectOptions {
    * @default Infinity
    */
   maxAttempts?: number;
+  /**
+   * How long a connection must stay open, in ms, before the backoff resets. One that closes
+   * sooner counts as a failed attempt, so a server that accepts and then closes right away
+   * (e.g. rejecting the credentials sent on open) is retried with a growing delay, and
+   * `maxAttempts` still applies. `0` resets on every open.
+   * @default 5000
+   */
+  minUptime?: number;
   /**
    * Delay before the first retry, in ms.
    * @default 1000
@@ -68,19 +79,26 @@ interface ReconnectOptions {
   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
+   * dropped at once don't all reconnect at the same moment. The default `1` picks each
+   * delay at random between 0 and the backoff ("full jitter").
+   * @default 1
    */
   jitter?: number;
   /**
    * Called on every unexpected close. Return `false` to stop reconnecting.
    *
+   * The default, `retryableClose`, retries everything except `1002` (protocol error), `1003`
+   * (unsupported data) and `1008` (policy violation). Your own function replaces it; call
+   * `retryableClose` from it to keep that rule, or return `true` to retry every close.
+   *
    * @example
    * ```ts
-   * // Don't retry when the server rejects our credentials.
-   * shouldReconnect: close => close.code !== 4001
+   * import { retryableClose } from 'react-websocket';
+   *
+   * // Also stop when our server rejects the credentials.
+   * shouldReconnect: close => close.code !== 4001 && retryableClose(close)
    * ```
-   * @default () => true
+   * @default retryableClose
    */
   shouldReconnect?: (close: CloseInfo) => boolean;
 }
@@ -155,7 +173,8 @@ interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
    * message is dropped, skipping `priority` messages unless nothing else is queued.
-   * @default Infinity
+   * `Infinity` keeps every message.
+   * @default 100
    */
   limit?: number;
 }
@@ -231,8 +250,8 @@ interface WebSocketOptions<In = unknown, Out = unknown> {
   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.
+   * (right after `open` listeners run). It holds up to 100 messages, dropping the oldest;
+   * `{ limit }` changes that. `false` drops messages instead of queueing them.
    * The queue is cleared by `close()` or when the client gives up.
    * @default true
    */
@@ -374,6 +393,20 @@ interface WebSocketClient<In = unknown, Out = unknown> {
 }
 //#endregion
 //#region src/client.d.ts
+/**
+ * The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+ * `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+ * retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(url, {
+ *   // Also stop on our server's "invalid token" code.
+ *   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+ * });
+ * ```
+ */
+export declare function retryableClose(close: CloseInfo): boolean;
 /**
  * Create a WebSocket client, usually at module level, to share across components.
  *

package/dist/core.js

@@ -30,8 +30,26 @@ const RECONNECT_DEFAULTS = {
 	minDelay: 1e3,
 	maxDelay: 3e4,
 	factor: 2,
-	jitter: .5
+	jitter: 1,
+	minUptime: 5e3
 };
+const QUEUE_LIMIT = 100;
+/**
+* The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+* `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+* retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+*
+* @example
+* ```ts
+* createWebSocket(url, {
+*   // Also stop on our server's "invalid token" code.
+*   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+* });
+* ```
+*/
+function retryableClose(close) {
+	return close.code !== 1002 && close.code !== 1003 && close.code !== 1008;
+}
 const READY_GRACE = 5e3;
 function createDeferred() {
 	let resolve;
@@ -83,7 +101,7 @@ function createClient(url, options = {}) {
 		...RECONNECT_DEFAULTS,
 		...typeof options.reconnect === "object" ? options.reconnect : {}
 	};
-	const queueLimit = options.queue === false ? 0 : typeof options.queue === "object" ? Math.max(0, options.queue.limit ?? Infinity) : Infinity;
+	const queueLimit = options.queue === false ? 0 : Math.max(0, (typeof options.queue === "object" ? options.queue.limit : void 0) ?? QUEUE_LIMIT);
 	let snapshot = {
 		status: "idle",
 		lastMessage: void 0,
@@ -108,8 +126,10 @@ function createClient(url, options = {}) {
 	let inbox = null;
 	let generation = 0;
 	let windowBound = false;
+	let failures = 0;
 	let retryTimer;
 	let teardownTimer;
+	let stableTimer;
 	let heartbeatTimer;
 	let pongTimer;
 	function set(patch) {
@@ -176,10 +196,12 @@ function createClient(url, options = {}) {
 			}, heartbeat.timeout);
 		}, heartbeat.interval);
 	}
-	function stopHeartbeat() {
+	/** Stop the timers that belong to the current open socket. */
+	function stopSocketTimers() {
 		clearInterval(heartbeatTimer);
 		clearTimeout(pongTimer);
-		heartbeatTimer = pongTimer = void 0;
+		clearTimeout(stableTimer);
+		heartbeatTimer = pongTimer = stableTimer = void 0;
 	}
 	/** Stop tracking `socket`. Its eventual close event is still reported unless `reportClose` is false. */
 	function detach(socket, reportClose) {
@@ -250,6 +272,7 @@ function createClient(url, options = {}) {
 				status: "open",
 				attempt: 0
 			});
+			if (retry) stableTimer = setTimeout(() => failures = 0, retry.minUptime);
 			startHeartbeat(socket);
 			ready?.resolve();
 			if (refs === 0 && !pinned) {
@@ -274,14 +297,14 @@ function createClient(url, options = {}) {
 		};
 	}
 	function handleClose(info) {
-		stopHeartbeat();
+		stopSocketTimers();
 		log("closed", info);
 		retryOrFail(info);
 		emit("close", info);
 	}
 	function retryOrFail(info, error) {
-		if (wanted && retry && snapshot.attempt < retry.maxAttempts && (retry.shouldReconnect?.(info) ?? true)) {
-			const attempt = snapshot.attempt + 1;
+		if (wanted && retry && failures < retry.maxAttempts && (retry.shouldReconnect ?? retryableClose)(info)) {
+			const attempt = ++failures;
 			const delay = backoff(attempt);
 			set({
 				status: "reconnecting",
@@ -296,7 +319,10 @@ function createClient(url, options = {}) {
 		opened = false;
 		unbindWindow();
 		pending = [];
-		set({ status: "closed" });
+		set({
+			status: "closed",
+			attempt: failures
+		});
 		rejectReady(reason);
 	}
 	function receive(event, socket) {
@@ -401,6 +427,7 @@ function createClient(url, options = {}) {
 			opened = false;
 			if (ready?.settled) ready = null;
 		}
+		failures = 0;
 		snapshot = {
 			...snapshot,
 			attempt: 0
@@ -422,7 +449,8 @@ function createClient(url, options = {}) {
 		generation++;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		failures = 0;
+		stopSocketTimers();
 		unbindWindow();
 		pending = [];
 		if (ws) {
@@ -445,7 +473,7 @@ function createClient(url, options = {}) {
 		if (!getImpl()) return;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		stopSocketTimers();
 		if (ws) {
 			const socket = ws;
 			detach(socket, true);
@@ -1223,6 +1251,6 @@ function createWebSocketTopics(client, options) {
 	};
 }
 //#endregion
-export { MessageError, createWebSocket, createWebSocketLatency, createWebSocketRequests, createWebSocketResponder, createWebSocketSendRate, createWebSocketState, createWebSocketTopics };
+export { MessageError, createWebSocket, createWebSocketLatency, createWebSocketRequests, createWebSocketResponder, createWebSocketSendRate, createWebSocketState, createWebSocketTopics, retryableClose };
 
 //# sourceMappingURL=core.js.map