websocket-ts 2.2.0 → 2.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Joscha Behrmann
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2020 Joscha Behrmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,212 +1,225 @@
-<div>
-  <div align="center">
-    <img src="https://raw.githubusercontent.com/jjxxs/websocket-ts/gh-pages/websocket-ts-logo.svg" alt="websocket-ts" width="300" height="65" />
-  </div>
-  <p align="center">
-    <img src="https://github.com/jjxxs/websocket-ts/actions/workflows/build.yml/badge.svg" alt="Build Status" />
-    <img src="https://github.com/jjxxs/websocket-ts/actions/workflows/test.yml/badge.svg" alt="Build Status" />
-    <a href="https://coveralls.io/github/jjxxs/websocket-ts?branch=master">
-      <img src="https://coveralls.io/repos/github/jjxxs/websocket-ts/badge.svg?branch=master&service=github" alt="Coverage Status" />
-    </a>
-    <a href="https://github.com/jjxxs/websocket-ts/releases/latest">
-      <img src="https://img.shields.io/github/v/release/jjxxs/websocket-ts" alt="Release" />
-    </a>
-    <a href="/LICENSE">
-      <img src="https://img.shields.io/github/license/jjxxs/websocket-ts" alt="License" />
-    </a>
-  </p>
-</div>
-
-<div align="center">
-A <b>WebSocket</b> for browsers with <b>auto-reconnect</b> and <b>message buffering</b> written in <b>TypeScript</b>.
-</div>
-
-## Features
-
-- **Lightweight & Standalone**: No dependencies, 2.1 kB minified & gzipped.
-- **Browser-native**: Utilizes WebSocket API, offers direct access.
-- **Smart Reconnect**: Optional auto-reconnect and message buffering.
-- **Easy Setup**: Optional builder class for quick initialization.
-- **Well-Tested**: High test coverage, well-documented for extensibility.
-- **Module Support**: Supports CommonJS and ES6 modules.
-
-## Installation
-
-Install `websocket-ts` with npm:
-
-```bash
-$ npm install websocket-ts 
-```
-
-## Quickstart
-This example shows how to use the package, complete with message buffering and automatic reconnection.
-The created websocket will echo back any received messages. It will buffer messages when disconnected
-and attempt to reconnect every 1 second.
-
-```typescript
-import {
-  ArrayQueue,
-  ConstantBackoff,
-  Websocket,
-  WebsocketBuilder,
-  WebsocketEvent,
-} from "websocket-ts";
-
-// Initialize WebSocket with buffering and 1s reconnection delay
-const ws = new WebsocketBuilder("ws://localhost:8080")
-  .withBuffer(new ArrayQueue())           // buffer messages when disconnected
-  .withBackoff(new ConstantBackoff(1000)) // retry every 1s
-  .build();
-
-// Function to output & echo received messages
-const echoOnMessage = (i: Websocket, ev: MessageEvent) => {
-  console.log(`received message: ${ev.data}`);
-  i.send(`echo: ${ev.data}`);
-};
-
-// Add event listeners
-ws.addEventListener(WebsocketEvent.open, () => console.log("opened!"));
-ws.addEventListener(WebsocketEvent.close, () => console.log("closed!"));
-ws.addEventListener(WebsocketEvent.message, echoOnMessage);
-```
-
-## Usage
-This will demonstrate how to use `websocket-ts` in your project using the provided `WebsocketBuild`-class.
-
-For a more detailed description of the API, please refer to the [API Documentation](https://jjxxs.github.io/websocket-ts/).
-
-#### Initialization
-
-Create a new instance with the `WebsocketBuilder`:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421").build();
-```
-
-#### Events
-
-There are six events which can be subscribed to through with event listeners:
-
-```typescript
-export enum WebsocketEvent {
-  open = "open",          // Connection opened
-  close = "close",        // Connection closed
-  error = "error",        // Error-induced closure
-  message = "message",    // Message received
-  retry = "retry",        // Reconnect attempt
-  reconnect = "reconnect" // Successful reconnect
-}
-```
-
-#### Add Event Listeners
-Event listeners receive the websocket instance (`i`) and the triggering event (`ev`) as arguments.
-
- ```typescript
- const ws = new WebsocketBuilder("ws://localhost:42421")
-   .onOpen((i, ev) => console.log("opened"))
-   .onClose((i, ev) => console.log("closed"))
-   .onError((i, ev) => console.log("error"))
-   .onMessage((i, ev) => console.log("message"))
-   .onRetry((i, ev) => console.log("retry"))
-   .onReconnect((i, ev) => console.log("reconnect"))
-   .build();
- ```
-
-#### Remove Event Listeners
-
-To unregister a specific event listener, use `removeEventListener`:
-
-```typescript
-let ws: Websocket
-/* ... */
-ws.removeEventListener(WebsocketEvent.open, openEventListener);
-```
-
-#### Send Message
-
-Use the `send` method to send a message to the server:
-
-```typescript
-let ws: Websocket;
-/* ... */
-ws.send("Hello World!");
-```
-
-#### Reconnect & Backoff (Optional)
-
-If you'd like the websocket to automatically reconnect upon disconnection, you can optionally provide a `Backoff` strategy. 
-This sets the delay between reconnection attempts. There are three built-in `Backoff` implementations, or you can create 
-your own by implementing the `Backoff` interface. If no Backoff is provided, the websocket will not attempt to reconnect.
-
-##### ConstantBackoff
-
-The `ConstantBackoff` strategy enforces a fixed delay between each reconnection attempt. 
-To set a constant 1-second wait time, use:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421")
-  .withBackoff(new ConstantBackoff(1000)) // 1000ms = 1s
-  .build();
-```
-
-##### LinearBackoff
-
-The `LinearBackoff` strategy increases the delay between reconnection attempts linearly,
-up to an optional maximum. For example, to start with a 0-second delay and increase by
-10 second for each retry, capping at 60 seconds, use:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421")
-  .withBackoff(new LinearBackoff(0, 10000, 60000)) // 0ms, 10s, 20s, 30s, 40s, 50s, 60s
-  .build();
-```
-
-##### ExponentialBackoff
-
-The `ExponentialBackoff` strategy doubles the delay between each reconnection attempt, up
-to a specified maximum. This approach is inspired by the binary exponential backoff algorithm
-commonly used in networking. For example, to generate a backoff series like `[1s, 2s, 4s, 8s]`, use:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421")
-  .withBackoff(new ExponentialBackoff(1000, 6)) // 1s, 2s, 4s, 8s, 16s, 32s, 64s
-  .build();
-```
-
-#### Buffer (Optional)
-
-To buffer outgoing messages when the websocket is disconnected, you can optionally specify
-a `Queue`. This queue will temporarily store your messages and send them in sequence when
-the websocket (re)connects. Two built-in `Queue` implementations are available, or you can
-create your own by implementing the `Queue` interface. If no queue is provided, messages 
-won't be buffered.
-
-##### RingQueue
-
-The `RingQueue` is a fixed-capacity, first-in-first-out (FIFO) queue. When it reaches capacity, 
-the oldest element is removed to accommodate new ones. Reading from the queue returns and
-removes the oldest element. For instance, to set up a `RingQueue` with a 100-element capacity,
-use:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421")
-  .withBuffer(new RingQueue(100))
-  .build();
-```
-
-##### ArrayQueue
-
-The ArrayQueue offers an unbounded capacity, functioning as a first-in-first-out (FIFO) queue. 
-Reading from this queue returns and removes the oldest element. To use an `ArrayQueue`, use:
-
-```typescript
-const ws = new WebsocketBuilder("ws://localhost:42421")
-  .withBuffer(new ArrayQueue())
-  .build();
-```
-
-## Build & Tests
-
-To compile the project, execute `npm run build`. 
-
-To run tests, use `npm run test`.
+<div align="center">
+<img src="https://raw.githubusercontent.com/jjxxs/websocket-ts/gh-pages/websocket-ts-logo.svg" alt="websocket-ts" width="300" height="65" />
+</div>
+&nbsp;
+<div align="center">
+A <b>WebSocket</b> for browsers with <b>auto-reconnect</b> and <b>message buffering</b> written in <b>TypeScript</b>.
+</div>
+&nbsp;
+<div align="center">
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/jjxxs/websocket-ts/build.yml)](https://github.com/jjxxs/websocket-ts/actions/workflows/build.yml)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/jjxxs/websocket-ts/test.yml?label=tests)](https://github.com/jjxxs/websocket-ts/actions/workflows/test.yml)
+[![Coverage Status](https://img.shields.io/coveralls/github/jjxxs/websocket-ts/master)](https://coveralls.io/github/jjxxs/websocket-ts?branch=master)
+[![npm downloads](https://img.shields.io/npm/dm/websocket-ts.svg)](https://npm-stat.com/charts.html?package=websocket-ts)
+
+</div>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/websocket-ts.svg)](https://www.npmjs.org/package/websocket-ts)
+[![Bundle Size](https://deno.bundlejs.com/badge?q=websocket-ts@2.2.1)](https://bundlejs.com/?q=websocket-ts)
+[![Known Vulnerabilities](https://snyk.io/test/npm/websocket-ts/badge.svg)](https://snyk.io/test/npm/websocket-ts)
+[![License](https://img.shields.io/github/license/jjxxs/websocket-ts)](/LICENSE)
+
+</div>
+
+## Features
+
+- **Lightweight & Standalone**: No dependencies, 2.5 kB minified & gzipped.
+- **Browser-native**: Utilizes native WebSocket API, offers direct access to the underlying connection.
+- **Smart Reconnect**: Optional auto-reconnect and message buffering.
+- **Easy Setup**: Optional builder class for quick initialization.
+- **Well-Tested**: High test coverage, well-documented for extensibility.
+- **Module Support**: Supports CommonJS and ES6 modules.
+
+## Installation
+
+Install `websocket-ts` with npm:
+
+```bash
+npm install websocket-ts
+```
+
+## Quickstart
+This example creates a WebSocket with message buffering and automatic reconnection.
+The created websocket will echo back any received messages. It will buffer messages when disconnected
+and attempt to reconnect every 1 second.
+
+```typescript
+import {
+  ArrayQueue,
+  ConstantBackoff,
+  Websocket,
+  WebsocketBuilder,
+  WebsocketEvent,
+} from "websocket-ts";
+
+// Initialize WebSocket with buffering and 1s reconnection delay
+const ws = new WebsocketBuilder("ws://localhost:8080")
+  .withBuffer(new ArrayQueue())           // buffer messages when disconnected
+  .withBackoff(new ConstantBackoff(1000)) // retry every 1s
+  .build();
+
+// Function to output & echo received messages
+const echoOnMessage = (i: Websocket, ev: MessageEvent) => {
+  console.log(`received message: ${ev.data}`);
+  i.send(`echo: ${ev.data}`);
+};
+
+// Add event listeners
+ws.addEventListener(WebsocketEvent.open, () => console.log("opened!"));
+ws.addEventListener(WebsocketEvent.close, () => console.log("closed!"));
+ws.addEventListener(WebsocketEvent.message, echoOnMessage);
+```
+
+## Usage
+This section demonstrates how to use `websocket-ts` in your project using the provided `WebsocketBuilder` class.
+
+For a more detailed description of the API, please refer to the [API Documentation](https://jjxxs.github.io/websocket-ts/).
+
+#### Initialization
+
+Create a new instance with the `WebsocketBuilder`:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421").build();
+```
+
+#### Events
+
+There are six events you can listen for:
+
+| Event | Description |
+|---|---|
+| `open` | Connection opened |
+| `close` | Connection closed |
+| `error` | An error occurred |
+| `message` | Message received |
+| `retry` | Reconnect attempt |
+| `reconnect` | Successful reconnect |
+
+You can use either `WebsocketEvent.open` or the string `"open"` when registering listeners.
+
+#### Add Event Listeners
+Event listeners receive the websocket instance (`i`) and the triggering event (`ev`) as arguments.
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .onOpen((i, ev) => console.log("opened"))
+  .onClose((i, ev) => console.log("closed"))
+  .onError((i, ev) => console.log("error"))
+  .onMessage((i, ev) => console.log("message"))
+  .onRetry((i, ev) => console.log("retry"))
+  .onReconnect((i, ev) => console.log("reconnect"))
+  .build();
+```
+
+#### Remove Event Listeners
+
+To unregister a specific event listener, use `removeEventListener`:
+
+```typescript
+let ws: Websocket
+/* ... */
+ws.removeEventListener(WebsocketEvent.open, openEventListener);
+```
+
+#### Send Message
+
+Use the `send` method to send a message to the server:
+
+```typescript
+let ws: Websocket;
+/* ... */
+ws.send("Hello World!");
+```
+
+#### Reconnect & Backoff (Optional)
+
+To automatically reconnect after a disconnection, provide a `Backoff` strategy.
+This controls the delay between reconnection attempts. There are three built-in `Backoff` implementations, or you can create
+your own by implementing the `Backoff` interface. If no backoff is provided, the websocket will not attempt to reconnect.
+
+##### ConstantBackoff
+
+`ConstantBackoff` uses a fixed delay between each reconnection attempt.
+To set a constant 1-second wait time, use:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new ConstantBackoff(1000)) // 1000ms = 1s
+  .build();
+```
+
+#### LinearBackoff
+
+`LinearBackoff` increases the delay between reconnection attempts linearly,
+up to an optional maximum. For example, to start with a 0-second delay and increase by
+10 seconds for each retry, capping at 60 seconds, use:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new LinearBackoff(0, 10000, 60000)) // 0ms, 10s, 20s, 30s, 40s, 50s, 60s
+  .build();
+```
+
+##### ExponentialBackoff
+
+`ExponentialBackoff` doubles the delay between each reconnection attempt, up
+to a specified maximum. This approach is inspired by the binary exponential backoff algorithm
+commonly used in networking. For example, to use a base of 1000ms with a maximum exponent of 6:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new ExponentialBackoff(1000, 6)) // 1s, 2s, 4s, 8s, 16s, 32s, 64s
+  .build();
+```
+
+#### Buffer (Optional)
+
+To buffer outgoing messages when the websocket is disconnected, provide a `Queue`.
+The queue temporarily stores messages and sends them in order when
+the websocket (re)connects. Two built-in `Queue` implementations are available, or you can
+create your own by implementing the `Queue` interface. If no queue is provided, messages
+won't be buffered.
+
+##### RingQueue
+
+`RingQueue` is a fixed-capacity, first-in-first-out (FIFO) queue. When it reaches capacity,
+the oldest element is removed to make room for new ones. For instance, to set up a `RingQueue` with a 100-element capacity:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBuffer(new RingQueue(100))
+  .build();
+```
+
+##### ArrayQueue
+
+`ArrayQueue` is an unbounded first-in-first-out (FIFO) queue.
+To use an `ArrayQueue`:
+
+```typescript
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBuffer(new ArrayQueue())
+  .build();
+```
+
+#### URL Provider (Optional)
+
+By default, the URL is a static string. To use a different URL between connection attempts, provide
+a function instead. The function is called on each connection attempt, including the initial one and
+any retries. This enables use cases like load balancing, auth token rotation, and failover.
+
+```typescript
+const ws = new WebsocketBuilder(() => `ws://localhost:42421?token=${getToken()}`)
+  .withBackoff(new ConstantBackoff(1000))
+  .build();
+```
+
+## Build & Tests
+
+To compile the project, run `npm run build`.
+
+To run tests, use `npm run test`.

package/dist/cjs/src/backoff/exponentialbackoff.js

@@ -43,7 +43,7 @@ var ExponentialBackoff = /** @class */ (function () {
             throw new Error("Base must be a positive integer or zero");
         }
         if (expMax !== undefined && (!Number.isInteger(expMax) || expMax < 0)) {
-            throw new Error("ExpMax must be a undefined, a positive integer or zero");
+            throw new Error("ExpMax must be undefined, a positive integer, or zero");
         }
         this.base = base;
         this.expMax = expMax;

package/dist/cjs/src/backoff/exponentialbackoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"exponentialbackoff.js","sourceRoot":"","sources":["../../../../src/backoff/exponentialbackoff.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAME;;;;OAIG;IACH,4BAAY,IAAY,EAAE,MAAe;QAPjC,aAAQ,GAAW,CAAC,CAAC;QAQ3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IAED,sBAAI,uCAAO;aAAX;YACE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;;;OAAA;IAED,sBAAI,uCAAO;aAAX;YACE,OAAO,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;;;OAAA;IAED,iCAAI,GAAJ;QACE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC;YACJ,IAAI,CAAC,MAAM,KAAK,SAAS;gBACvB,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;gBACZ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kCAAK,GAAL;QACE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACH,yBAAC;AAAD,CAAC,AA7CD,IA6CC;AA7CY,gDAAkB"}
+{"version":3,"file":"exponentialbackoff.js","sourceRoot":"","sources":["../../../../src/backoff/exponentialbackoff.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAME;;;;OAIG;IACH,4BAAY,IAAY,EAAE,MAAe;QAPjC,aAAQ,GAAW,CAAC,CAAC;QAQ3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IAED,sBAAI,uCAAO;aAAX;YACE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;;;OAAA;IAED,sBAAI,uCAAO;aAAX;YACE,OAAO,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;;;OAAA;IAED,iCAAI,GAAJ;QACE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC;YACJ,IAAI,CAAC,MAAM,KAAK,SAAS;gBACvB,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;gBACZ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kCAAK,GAAL;QACE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACH,yBAAC;AAAD,CAAC,AA7CD,IA6CC;AA7CY,gDAAkB"}

package/dist/cjs/src/index.d.ts

@@ -5,7 +5,7 @@ export { LinearBackoff } from "./backoff/linearbackoff";
 export { Queue } from "./queue/queue";
 export { ArrayQueue } from "./queue/array_queue";
 export { RingQueue } from "./queue/ring_queue";
-export { Websocket } from "./websocket";
+export { UrlProvider, Websocket } from "./websocket";
 export { WebsocketBuffer } from "./websocket_buffer";
 export { WebsocketBuilder } from "./websocket_builder";
 export { WebsocketEvent, RetryEventDetail, ReconnectEventDetail, WebsocketEventMap, WebsocketEventListener, WebsocketEventListenerParams, WebsocketEventListenerOptions, WebsocketEventListenerWithOptions, WebsocketEventListeners, } from "./websocket_event";

package/dist/cjs/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,4BAA4B,EAC5B,6BAA6B,EAC7B,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,4BAA4B,EAC5B,6BAA6B,EAC7B,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/cjs/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";;;AACA,6DAA4D;AAAnD,kHAAA,eAAe,OAAA;AACxB,mEAAkE;AAAzD,wHAAA,kBAAkB,OAAA;AAC3B,yDAAwD;AAA/C,8GAAA,aAAa,OAAA;AAEtB,mDAAiD;AAAxC,yGAAA,UAAU,OAAA;AACnB,iDAA+C;AAAtC,uGAAA,SAAS,OAAA;AAClB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAElB,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA;AACzB,qDAU2B;AATzB,iHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";;;AACA,6DAA4D;AAAnD,kHAAA,eAAe,OAAA;AACxB,mEAAkE;AAAzD,wHAAA,kBAAkB,OAAA;AAC3B,yDAAwD;AAA/C,8GAAA,aAAa,OAAA;AAEtB,mDAAiD;AAAxC,yGAAA,UAAU,OAAA;AACnB,iDAA+C;AAAtC,uGAAA,SAAS,OAAA;AAClB,yCAAqD;AAA/B,sGAAA,SAAS,OAAA;AAE/B,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA;AACzB,qDAU2B;AATzB,iHAAA,cAAc,OAAA"}

package/dist/cjs/src/websocket.d.ts

@@ -2,11 +2,17 @@ import { Backoff } from "./backoff/backoff";
 import { WebsocketBuffer } from "./websocket_buffer";
 import { WebsocketEvent, WebsocketEventListener, WebsocketEventListenerOptions } from "./websocket_event";
 import { WebsocketOptions } from "./websocket_options";
+/**
+ * A URL or a function that returns a URL. When a function is provided, it is called on each connection attempt,
+ * enabling use cases like load balancing, auth token rotation, and failover.
+ */
+export type UrlProvider = string | (() => string);
 /**
  * A websocket wrapper that can be configured to reconnect automatically and buffer messages when the websocket is not connected.
  */
 export declare class Websocket {
-    private readonly _url;
+    private readonly _urlProvider;
+    private _url;
     private readonly _protocols?;
     private _closedByUser;
     private _lastConnection?;
@@ -16,11 +22,11 @@ export declare class Websocket {
     /**
      * Creates a new websocket.
      *
-     * @param url to connect to.
+     * @param url to connect to, or a function that returns a URL.
      * @param protocols optional protocols to use.
      * @param options optional options to use.
      */
-    constructor(url: string, protocols?: string | string[], options?: WebsocketOptions);
+    constructor(url: UrlProvider, protocols?: string | string[], options?: WebsocketOptions);
     /**
      * Getter for the url.
      *

package/dist/cjs/src/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/websocket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/websocket.ts"],"names":[],"mappings":"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"}

package/dist/cjs/src/websocket.js

@@ -18,7 +18,7 @@ var Websocket = /** @class */ (function () {
     /**
      * Creates a new websocket.
      *
-     * @param url to connect to.
+     * @param url to connect to, or a function that returns a URL.
      * @param protocols optional protocols to use.
      * @param options optional options to use.
      */
@@ -54,7 +54,7 @@ var Websocket = /** @class */ (function () {
         this.handleMessageEvent = function (event) {
             return _this.handleEvent(websocket_event_1.WebsocketEvent.message, event);
         };
-        this._url = url;
+        this._urlProvider = url;
         this._protocols = protocols;
         // make a copy of the options to prevent the user from changing them
         this._options = {
@@ -305,7 +305,11 @@ var Websocket = /** @class */ (function () {
      * @return the created browser-native websocket which is also stored in the '_underlyingWebsocket' property.
      */
     Websocket.prototype.tryConnect = function () {
-        this._underlyingWebsocket = new WebSocket(this.url, this.protocols); // create new browser-native websocket and add all event listeners
+        this._url =
+            typeof this._urlProvider === "function"
+                ? this._urlProvider()
+                : this._urlProvider;
+        this._underlyingWebsocket = new WebSocket(this._url, this.protocols); // create new browser-native websocket and add all event listeners
         this._underlyingWebsocket.addEventListener(websocket_event_1.WebsocketEvent.open, this.handleOpenEvent);
         this._underlyingWebsocket.addEventListener(websocket_event_1.WebsocketEvent.close, this.handleCloseEvent);
         this._underlyingWebsocket.addEventListener(websocket_event_1.WebsocketEvent.error, this.handleErrorEvent);