websocket-ts 2.3.0 → 3.0.0

package/dist/cjs/{src/queue → queue}/ring_queue.d.ts

@@ -1,4 +1,4 @@
-import { Queue } from "./queue";
+import { Queue } from "./queue.js";
 /**
  * A ring queue is a queue that has a fixed capacity. When the queue is full, the oldest element is
  * removed to make room for the new element. Reading from a ring queue will return the oldest

package/dist/cjs/queue/ring_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring_queue.d.ts","sourceRoot":"","sources":["../../../src/queue/ring_queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;GAIG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,QAAQ,EAAE,MAAM;IAU5B,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI;IASrB,KAAK;IAML,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO;IAUnC,MAAM,IAAI,MAAM;IAQhB,OAAO,IAAI,OAAO;IAIlB,IAAI,IAAI,CAAC,GAAG,SAAS;IAIrB,IAAI,IAAI,CAAC,GAAG,SAAS;CAStB"}

package/dist/cjs/{src/queue → queue}/ring_queue.js

@@ -6,8 +6,8 @@ exports.RingQueue = void 0;
  * removed to make room for the new element. Reading from a ring queue will return the oldest
  * element and effectively remove it from the queue.
  */
-var RingQueue = /** @class */ (function () {
-    function RingQueue(capacity) {
+class RingQueue {
+    constructor(capacity) {
         if (!Number.isInteger(capacity) || capacity <= 0) {
             throw new Error("Capacity must be a positive integer");
         }
@@ -15,43 +15,46 @@ var RingQueue = /** @class */ (function () {
         this.head = 0;
         this.tail = 0;
     }
-    RingQueue.prototype.add = function (element) {
+    add(element) {
         this.elements[this.head] = element;
         this.head = (this.head + 1) % this.elements.length;
         if (this.head === this.tail) {
+            this.elements[this.tail] = undefined; // drop the reference of the overwritten oldest element
             this.tail = (this.tail + 1) % this.elements.length;
         }
-    };
-    RingQueue.prototype.clear = function () {
+    }
+    clear() {
+        this.elements.fill(undefined); // drop all references so elements can be garbage-collected
         this.head = 0;
         this.tail = 0;
-    };
-    RingQueue.prototype.forEach = function (fn) {
-        for (var i = this.tail; i !== this.head; i = (i + 1) % this.elements.length) {
+    }
+    forEach(fn) {
+        for (let i = this.tail; i !== this.head; i = (i + 1) % this.elements.length) {
             fn(this.elements[i]);
         }
-    };
-    RingQueue.prototype.length = function () {
+    }
+    length() {
         return this.tail === this.head
             ? 0
             : this.tail < this.head
                 ? this.head - this.tail
                 : this.elements.length - this.tail + this.head;
-    };
-    RingQueue.prototype.isEmpty = function () {
+    }
+    isEmpty() {
         return this.head === this.tail;
-    };
-    RingQueue.prototype.peek = function () {
+    }
+    peek() {
         return this.isEmpty() ? undefined : this.elements[this.tail];
-    };
-    RingQueue.prototype.read = function () {
-        var e = this.peek();
-        if (e !== undefined) {
-            this.tail = (this.tail + 1) % this.elements.length;
+    }
+    read() {
+        if (this.isEmpty()) {
+            return undefined; // empty is determined by the indices, so stored 'undefined' elements read correctly
         }
+        const e = this.elements[this.tail];
+        this.elements[this.tail] = undefined; // drop the reference so the element can be garbage-collected
+        this.tail = (this.tail + 1) % this.elements.length;
         return e;
-    };
-    return RingQueue;
-}());
+    }
+}
 exports.RingQueue = RingQueue;
 //# sourceMappingURL=ring_queue.js.map

package/dist/cjs/queue/ring_queue.js.map

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

package/dist/cjs/{src/websocket.d.ts → websocket.d.ts}

@@ -1,10 +1,19 @@
-import { Backoff } from "./backoff/backoff";
-import { WebsocketBuffer } from "./websocket_buffer";
-import { WebsocketEvent, WebsocketEventListener, WebsocketEventListenerOptions } from "./websocket_event";
-import { WebsocketOptions } from "./websocket_options";
+import { Backoff } from "./backoff/backoff.js";
+import { WebsocketBuffer } from "./websocket_buffer.js";
+import { WebsocketEvent, WebsocketEventListener, WebsocketEventListenerOptions } from "./websocket_event.js";
+import { WebsocketOptions } from "./websocket_options.js";
 /**
  * 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.
+ *
+ * The function is called without the websocket as `this` and should only resolve a URL. If, during a
+ * connection attempt after construction, it synchronously calls close() or reconnect() on the websocket, the
+ * attempt that called it is abandoned without creating a socket. It must not call reconnect() on every
+ * invocation, as that recurses indefinitely.
+ *
+ * If it throws during an automatic retry, that attempt fails with an 'error' event (an ErrorEvent whose
+ * 'error' is the thrown value) and retrying continues. During construction and reconnect(), the exception
+ * propagates to the caller instead.
  */
 export type UrlProvider = string | (() => string);
 /**
@@ -16,8 +25,11 @@ export declare class Websocket {
     private readonly _protocols?;
     private _closedByUser;
     private _lastConnection?;
+    private _binaryType?;
     private _underlyingWebsocket;
     private retryTimeout?;
+    private _connectionGeneration;
+    private readonly abortHandlerCleanups;
     private _options;
     /**
      * Creates a new websocket.
@@ -25,10 +37,14 @@ export declare class Websocket {
      * @param url to connect to, or a function that returns a URL.
      * @param protocols optional protocols to use.
      * @param options optional options to use.
+     * @throws Error if retry options (maxRetries, instantReconnect) are set without a backoff.
+     * @throws Error if maxRetries is neither Infinity nor a non-negative integer.
      */
     constructor(url: UrlProvider, protocols?: string | string[], options?: WebsocketOptions);
     /**
-     * Getter for the url.
+     * Getter for the url of the most recently constructed underlying websocket. This is not
+     * necessarily the URL of the last successful connection, and a URL that the WebSocket
+     * constructor rejected, or whose connection attempt was superseded, is not recorded.
      *
      * @return the url.
      */
@@ -70,9 +86,9 @@ export declare class Websocket {
      */
     get closedByUser(): boolean;
     /**
-     * Getter for the last 'open' event, e.g. the last time the websocket was connected.
+     * Getter for the time of the last 'open' event, i.e. the last time the websocket was connected.
      *
-     * @return the last 'open' event, or undefined if the websocket was never connected.
+     * @return the time of the last 'open' event, or undefined if the websocket was never connected.
      */
     get lastConnection(): Date | undefined;
     /**
@@ -111,7 +127,8 @@ export declare class Websocket {
      */
     get binaryType(): BinaryType;
     /**
-     * Setter for the binaryType of the underlying websocket.
+     * Setter for the binaryType of the underlying websocket. The value is remembered
+     * and re-applied whenever a new underlying websocket is created after a reconnect.
      *
      * @param value to set, 'blob' or 'arraybuffer'.
      */
@@ -125,9 +142,10 @@ export declare class Websocket {
      * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
      * @param data to send.
      */
-    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    send(data: string | Blob | BufferSource): void;
     /**
-     * Close the websocket. No connection-retry will be attempted after this.
+     * Close the websocket. No automatic connection-retry will be attempted after this,
+     * until reconnect() is called.
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
      * @param code optional close code.
@@ -135,7 +153,24 @@ export declare class Websocket {
      */
     close(code?: number, reason?: string): void;
     /**
-     * Adds an event listener for the given event-type.
+     * (Re-)connects the websocket immediately, regardless of its current state:
+     * any scheduled retry is cancelled, the backoff and its retry-counter are
+     * reset, the URL provider is resolved again and a new connection is opened.
+     * This also revives a websocket that was closed by the user or that gave up
+     * after exceeding maxRetries (see the 'exhausted' event).
+     *
+     * Typical uses: a "reconnect" button after the 'exhausted' event, reacting to
+     * the browser's 'online' event, or forcing the URL provider to pick up a new
+     * auth token without waiting for the connection to drop.
+     *
+     * @throws whatever the URL provider or the WebSocket constructor throws.
+     */
+    reconnect(): void;
+    /**
+     * Adds an event listener for the given event-type. When an AbortSignal is
+     * provided in the options, aborting it removes exactly this registration;
+     * a listener whose signal is already aborted is never registered, mirroring
+     * the native EventTarget.
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
      * @param type of the event to add the listener for.
@@ -144,18 +179,21 @@ export declare class Websocket {
      */
     addEventListener<K extends WebsocketEvent>(type: K, listener: WebsocketEventListener<K>, options?: WebsocketEventListenerOptions): void;
     /**
-     * Removes one or more event listener for the given event-type that match the given listener and options.
+     * Removes all event listeners for the given event-type that match the given listener.
+     *
+     * Matching is done by listener identity only, mirroring the native EventTarget:
+     * the options a listener was added with are ignored when matching.
      *
      * @param type of the event to remove the listener for.
      * @param listener to remove.
-     * @param options that were used when the listener was added.
+     * @param options ignored when matching, present for backward compatibility.
      */
     removeEventListener<K extends WebsocketEvent>(type: K, listener: WebsocketEventListener<K>, options?: WebsocketEventListenerOptions): void;
     /**
      * Creates a new browser-native websocket and connects it to the given URL with the given protocols
-     * and adds all event listeners to the browser-native websocket.
-     *
-     * @return the created browser-native websocket which is also stored in the '_underlyingWebsocket' property.
+     * and adds all event listeners to the browser-native websocket. The new websocket is stored in the
+     * '_underlyingWebsocket' property, unless the URL provider superseded this attempt by calling close()
+     * or reconnect().
      */
     private tryConnect;
     /**
@@ -189,6 +227,16 @@ export declare class Websocket {
      * @param event to dispatch.
      */
     private dispatchEvent;
+    /**
+     * Reports an exception thrown by a user-provided event listener. Uses
+     * globalThis.reportError where available (browsers); otherwise the exception
+     * is rethrown asynchronously so it still reaches the runtime's global
+     * error handling (e.g. 'uncaughtException' in Node.js) without breaking
+     * the dispatch it escaped from.
+     *
+     * @param error the exception thrown by the listener.
+     */
+    private reportListenerError;
     /**
      * Handles the given event by dispatching it to all listeners of the given event-type.
      *
@@ -197,7 +245,10 @@ export declare class Websocket {
      */
     private handleEvent;
     /**
-     * Sends buffered data if there is a buffer defined.
+     * Sends buffered data if there is a buffer defined. Draining stops as soon as the
+     * websocket is no longer open, e.g. when a listener closed it during the drain;
+     * remaining elements stay buffered for the next successful connection. Without
+     * this guard, send() would re-add each read element to the buffer, cycling forever.
      */
     private sendBufferedData;
     /**
@@ -208,5 +259,12 @@ export declare class Websocket {
      * Cancels the scheduled connection-retry, if there is one.
      */
     private cancelScheduledConnectionRetry;
+    /**
+     * Unhooks the 'abort'-handler that was registered on the AbortSignal of the
+     * given listener-registration, if there is one.
+     *
+     * @param entry the listener-registration to unhook the abort-handler for.
+     */
+    private cleanupAbortHandler;
 }
 //# sourceMappingURL=websocket.d.ts.map

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

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