websocket-ts 2.2.1 → 3.0.0

package/dist/{cjs/src → esm}/websocket_builder.d.ts

@@ -1,7 +1,7 @@
-import { Backoff } from "./backoff/backoff";
-import { WebsocketEvent, WebsocketEventListener, WebsocketEventListenerOptions } from "./websocket_event";
-import { Websocket } from "./websocket";
-import { WebsocketBuffer } from "./websocket_buffer";
+import { Backoff } from "./backoff/backoff.js";
+import { WebsocketEvent, WebsocketEventListener, WebsocketEventListenerOptions } from "./websocket_event.js";
+import { UrlProvider, Websocket } from "./websocket.js";
+import { WebsocketBuffer } from "./websocket_buffer.js";
 /**
  * Builder for websockets.
  */
@@ -12,15 +12,15 @@ export declare class WebsocketBuilder {
     /**
      * Creates a new WebsocketBuilder.
      *
-     * @param url the url to connect to
+     * @param url the url to connect to, or a function that returns a URL
      */
-    constructor(url: string);
+    constructor(url: UrlProvider);
     /**
      * Getter for the url.
      *
-     * @returns the url
+     * @returns the url or url provider
      */
-    get url(): string;
+    get url(): UrlProvider;
     /**
      * Adds protocols to the websocket. Subsequent calls to this method will override the previously set protocols.
      *
@@ -34,7 +34,8 @@ export declare class WebsocketBuilder {
      */
     get protocols(): string | string[] | undefined;
     /**
-     * Sets the maximum number of retries before giving up. No limit if undefined.
+     * Sets the maximum number of retries before giving up. No limit if undefined or Infinity.
+     * Must be Infinity or a non-negative integer, otherwise build() will throw.
      *
      * @param maxRetries the maximum number of retries before giving up
      */
@@ -46,15 +47,15 @@ export declare class WebsocketBuilder {
      */
     get maxRetries(): number | undefined;
     /**
-     * Sets wether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
+     * Sets whether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
      *
-     * @param instantReconnect wether to reconnect immediately after a connection has been lost
+     * @param instantReconnect whether to reconnect immediately after a connection has been lost
      */
     withInstantReconnect(instantReconnect: boolean | undefined): WebsocketBuilder;
     /**
-     * Getter for wether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
+     * Getter for whether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
      *
-     * @returns wether to reconnect immediately after a connection has been lost, undefined if no value has been set
+     * @returns whether to reconnect immediately after a connection has been lost, undefined if no value has been set
      */
     get instantReconnect(): boolean | undefined;
     /**
@@ -129,6 +130,14 @@ export declare class WebsocketBuilder {
      * @param options the listener options
      */
     onReconnect(listener: WebsocketEventListener<WebsocketEvent.reconnect>, options?: WebsocketEventListenerOptions): WebsocketBuilder;
+    /**
+     * Adds an 'exhausted' event listener to the websocket. Subsequent calls to this method will add additional listeners that will be
+     * called in the order they were added.
+     *
+     * @param listener the listener to add
+     * @param options the listener options
+     */
+    onExhausted(listener: WebsocketEventListener<WebsocketEvent.exhausted>, options?: WebsocketEventListenerOptions): WebsocketBuilder;
     /**
      * Builds the websocket.
      *

package/dist/esm/websocket_builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_builder.d.ts","sourceRoot":"","sources":["../../src/websocket_builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,6BAA6B,EAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IAEnC,OAAO,CAAC,UAAU,CAAC,CAAoB;IACvC,OAAO,CAAC,QAAQ,CAAC,CAAmB;IAEpC;;;;OAIG;gBACS,GAAG,EAAE,WAAW;IAI5B;;;;OAIG;IACH,IAAI,GAAG,IAAI,WAAW,CAErB;IAED;;;;OAIG;IACI,aAAa,CAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GACvC,gBAAgB;IAKnB;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAE7C;IAED;;;;;OAKG;IACI,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB;IAQvE;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAED;;;;OAIG;IACI,oBAAoB,CACzB,gBAAgB,EAAE,OAAO,GAAG,SAAS,GACpC,gBAAgB;IAQnB;;;;OAIG;IACH,IAAI,gBAAgB,IAAI,OAAO,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACI,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,gBAAgB;IAQlE;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,GAAG,SAAS,CAEjC;IAED;;;;OAIG;IACI,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,gBAAgB;IAKxE;;;;OAIG;IACH,IAAI,MAAM,IAAI,eAAe,GAAG,SAAS,CAExC;IAED;;;;;;OAMG;IACI,MAAM,CACX,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,IAAI,CAAC,EACrD,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,OAAO,CACZ,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,KAAK,CAAC,EACtD,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,OAAO,CACZ,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,KAAK,CAAC,EACtD,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,SAAS,CACd,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,OAAO,CAAC,EACxD,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,OAAO,CACZ,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,KAAK,CAAC,EACtD,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,WAAW,CAChB,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,SAAS,CAAC,EAC1D,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;;;OAMG;IACI,WAAW,CAChB,QAAQ,EAAE,sBAAsB,CAAC,cAAc,CAAC,SAAS,CAAC,EAC1D,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB;IAKnB;;;;OAIG;IACI,KAAK,IAAI,SAAS;IAIzB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;CAiBpB"}

package/dist/esm/{src/websocket_builder.js → websocket_builder.js}

@@ -1,5 +1,5 @@
-import { WebsocketEvent, } from "./websocket_event";
-import { Websocket } from "./websocket";
+import { WebsocketEvent, } from "./websocket_event.js";
+import { Websocket } from "./websocket.js";
 /**
  * Builder for websockets.
  */
@@ -7,7 +7,7 @@ export class WebsocketBuilder {
     /**
      * Creates a new WebsocketBuilder.
      *
-     * @param url the url to connect to
+     * @param url the url to connect to, or a function that returns a URL
      */
     constructor(url) {
         this._url = url;
@@ -15,7 +15,7 @@ export class WebsocketBuilder {
     /**
      * Getter for the url.
      *
-     * @returns the url
+     * @returns the url or url provider
      */
     get url() {
         return this._url;
@@ -38,13 +38,17 @@ export class WebsocketBuilder {
         return this._protocols;
     }
     /**
-     * Sets the maximum number of retries before giving up. No limit if undefined.
+     * Sets the maximum number of retries before giving up. No limit if undefined or Infinity.
+     * Must be Infinity or a non-negative integer, otherwise build() will throw.
      *
      * @param maxRetries the maximum number of retries before giving up
      */
     withMaxRetries(maxRetries) {
         var _a;
-        this._options = Object.assign(Object.assign({}, this._options), { retry: Object.assign(Object.assign({}, (_a = this._options) === null || _a === void 0 ? void 0 : _a.retry), { maxRetries }) });
+        this._options = {
+            ...this._options,
+            retry: { ...(_a = this._options) === null || _a === void 0 ? void 0 : _a.retry, maxRetries },
+        };
         return this;
     }
     /**
@@ -57,19 +61,22 @@ export class WebsocketBuilder {
         return (_b = (_a = this._options) === null || _a === void 0 ? void 0 : _a.retry) === null || _b === void 0 ? void 0 : _b.maxRetries;
     }
     /**
-     * Sets wether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
+     * Sets whether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
      *
-     * @param instantReconnect wether to reconnect immediately after a connection has been lost
+     * @param instantReconnect whether to reconnect immediately after a connection has been lost
      */
     withInstantReconnect(instantReconnect) {
         var _a;
-        this._options = Object.assign(Object.assign({}, this._options), { retry: Object.assign(Object.assign({}, (_a = this._options) === null || _a === void 0 ? void 0 : _a.retry), { instantReconnect }) });
+        this._options = {
+            ...this._options,
+            retry: { ...(_a = this._options) === null || _a === void 0 ? void 0 : _a.retry, instantReconnect },
+        };
         return this;
     }
     /**
-     * Getter for wether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
+     * Getter for whether to reconnect immediately after a connection has been lost, ignoring the backoff strategy for the first retry.
      *
-     * @returns wether to reconnect immediately after a connection has been lost, undefined if no value has been set
+     * @returns whether to reconnect immediately after a connection has been lost, undefined if no value has been set
      */
     get instantReconnect() {
         var _a, _b;
@@ -82,7 +89,10 @@ export class WebsocketBuilder {
      */
     withBackoff(backoff) {
         var _a;
-        this._options = Object.assign(Object.assign({}, this._options), { retry: Object.assign(Object.assign({}, (_a = this._options) === null || _a === void 0 ? void 0 : _a.retry), { backoff }) });
+        this._options = {
+            ...this._options,
+            retry: { ...(_a = this._options) === null || _a === void 0 ? void 0 : _a.retry, backoff },
+        };
         return this;
     }
     /**
@@ -100,7 +110,7 @@ export class WebsocketBuilder {
      * @param buffer the buffer to add
      */
     withBuffer(buffer) {
-        this._options = Object.assign(Object.assign({}, this._options), { buffer });
+        this._options = { ...this._options, buffer };
         return this;
     }
     /**
@@ -178,6 +188,17 @@ export class WebsocketBuilder {
         this.addListener(WebsocketEvent.reconnect, listener, options);
         return this;
     }
+    /**
+     * Adds an 'exhausted' event listener to the websocket. Subsequent calls to this method will add additional listeners that will be
+     * called in the order they were added.
+     *
+     * @param listener the listener to add
+     * @param options the listener options
+     */
+    onExhausted(listener, options) {
+        this.addListener(WebsocketEvent.exhausted, listener, options);
+        return this;
+    }
     /**
      * Builds the websocket.
      *
@@ -194,19 +215,17 @@ export class WebsocketBuilder {
      * @param options the listener options
      */
     addListener(event, listener, options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
-        this._options = Object.assign(Object.assign({}, this._options), { listeners: {
-                open: (_c = (_b = (_a = this._options) === null || _a === void 0 ? void 0 : _a.listeners) === null || _b === void 0 ? void 0 : _b.open) !== null && _c !== void 0 ? _c : [],
-                close: (_f = (_e = (_d = this._options) === null || _d === void 0 ? void 0 : _d.listeners) === null || _e === void 0 ? void 0 : _e.close) !== null && _f !== void 0 ? _f : [],
-                error: (_j = (_h = (_g = this._options) === null || _g === void 0 ? void 0 : _g.listeners) === null || _h === void 0 ? void 0 : _h.error) !== null && _j !== void 0 ? _j : [],
-                message: (_m = (_l = (_k = this._options) === null || _k === void 0 ? void 0 : _k.listeners) === null || _l === void 0 ? void 0 : _l.message) !== null && _m !== void 0 ? _m : [],
-                retry: (_q = (_p = (_o = this._options) === null || _o === void 0 ? void 0 : _o.listeners) === null || _p === void 0 ? void 0 : _p.retry) !== null && _q !== void 0 ? _q : [],
-                reconnect: (_t = (_s = (_r = this._options) === null || _r === void 0 ? void 0 : _r.listeners) === null || _s === void 0 ? void 0 : _s.reconnect) !== null && _t !== void 0 ? _t : [],
+        var _a, _b, _c, _d;
+        this._options = {
+            ...this._options,
+            listeners: {
+                ...(_a = this._options) === null || _a === void 0 ? void 0 : _a.listeners,
                 [event]: [
-                    ...((_w = (_v = (_u = this._options) === null || _u === void 0 ? void 0 : _u.listeners) === null || _v === void 0 ? void 0 : _v[event]) !== null && _w !== void 0 ? _w : []),
+                    ...((_d = (_c = (_b = this._options) === null || _b === void 0 ? void 0 : _b.listeners) === null || _c === void 0 ? void 0 : _c[event]) !== null && _d !== void 0 ? _d : []),
                     { listener, options },
                 ],
-            } });
+            },
+        };
         return this;
     }
 }

package/dist/esm/websocket_builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_builder.js","sourceRoot":"","sources":["../../src/websocket_builder.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,GAGf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAe,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIxD;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAM3B;;;;OAIG;IACH,YAAY,GAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACI,aAAa,CAClB,SAAwC;QAExC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACI,cAAc,CAAC,UAA8B;;QAClD,IAAI,CAAC,QAAQ,GAAG;YACd,GAAG,IAAI,CAAC,QAAQ;YAChB,KAAK,EAAE,EAAE,GAAG,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,EAAE,UAAU,EAAE;SAC/C,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,IAAI,UAAU;;QACZ,OAAO,MAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,0CAAE,UAAU,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACI,oBAAoB,CACzB,gBAAqC;;QAErC,IAAI,CAAC,QAAQ,GAAG;YACd,GAAG,IAAI,CAAC,QAAQ;YAChB,KAAK,EAAE,EAAE,GAAG,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,EAAE,gBAAgB,EAAE;SACrD,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,IAAI,gBAAgB;;QAClB,OAAO,MAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,0CAAE,gBAAgB,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,OAA4B;;QAC7C,IAAI,CAAC,QAAQ,GAAG;YACd,GAAG,IAAI,CAAC,QAAQ;YAChB,KAAK,EAAE,EAAE,GAAG,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,EAAE,OAAO,EAAE;SAC5C,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,IAAI,OAAO;;QACT,OAAO,MAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,KAAK,0CAAE,OAAO,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,MAAmC;QACnD,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,IAAI,MAAM;;QACR,OAAO,MAAA,IAAI,CAAC,QAAQ,0CAAE,MAAM,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CACX,QAAqD,EACrD,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,OAAO,CACZ,QAAsD,EACtD,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,OAAO,CACZ,QAAsD,EACtD,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,SAAS,CACd,QAAwD,EACxD,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,OAAO,CACZ,QAAsD,EACtD,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAChB,QAA0D,EAC1D,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAChB,QAA0D,EAC1D,OAAuC;QAEvC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACI,KAAK;QACV,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,iDAAiD;IACpH,CAAC;IAED;;;;;;OAMG;IACK,WAAW,CACjB,KAAQ,EACR,QAAmC,EACnC,OAAuC;;QAEvC,IAAI,CAAC,QAAQ,GAAG;YACd,GAAG,IAAI,CAAC,QAAQ;YAChB,SAAS,EAAE;gBACT,GAAG,MAAA,IAAI,CAAC,QAAQ,0CAAE,SAAS;gBAC3B,CAAC,KAAK,CAAC,EAAE;oBACP,GAAG,CAAC,MAAA,MAAA,MAAA,IAAI,CAAC,QAAQ,0CAAE,SAAS,0CAAG,KAAK,CAAC,mCAAI,EAAE,CAAC;oBAC5C,EAAE,QAAQ,EAAE,OAAO,EAAE;iBACtB;aACF;SACF,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/esm/websocket_event.d.ts

@@ -0,0 +1,93 @@
+import { Websocket } from "./websocket.js";
+/**
+ * Events that can be fired by the websocket.
+ */
+export declare const WebsocketEvent: {
+    /** Fired when the connection is opened. */
+    readonly open: "open";
+    /** Fired when the connection is closed. */
+    readonly close: "close";
+    /**
+     * Fired when the connection has been closed because of an error, such as when some data couldn't be sent.
+     * Also fired when an automatic retry fails because the URL provider or the WebSocket constructor threw;
+     * that event is an ErrorEvent whose 'error' is the thrown value.
+     */
+    readonly error: "error";
+    /** Fired when a message is received. */
+    readonly message: "message";
+    /** Fired when the websocket tries to reconnect after a connection loss. */
+    readonly retry: "retry";
+    /** Fired when the websocket successfully reconnects after a connection loss. */
+    readonly reconnect: "reconnect";
+    /** Fired when the websocket gives up reconnecting after exceeding maxRetries. */
+    readonly exhausted: "exhausted";
+};
+/** Union of all event type strings, allowing plain strings like "open" as event types. */
+export type WebsocketEvent = (typeof WebsocketEvent)[keyof typeof WebsocketEvent];
+/** Provides member types (e.g. WebsocketEvent.open) for use as generic type arguments. */
+export declare namespace WebsocketEvent {
+    type open = typeof WebsocketEvent.open;
+    type close = typeof WebsocketEvent.close;
+    type error = typeof WebsocketEvent.error;
+    type message = typeof WebsocketEvent.message;
+    type retry = typeof WebsocketEvent.retry;
+    type reconnect = typeof WebsocketEvent.reconnect;
+    type exhausted = typeof WebsocketEvent.exhausted;
+}
+/***
+ * Details/properties of a retry-event.
+ */
+export type RetryEventDetail = {
+    /** Number of retries that have been made since the connection was lost. */
+    readonly retries: number;
+    /** Time (ms) waited since the last connection-retry. */
+    readonly backoff: number;
+    /** Timestamp of the last successful connection ('open' event) or undefined if the connection has never been established. */
+    readonly lastConnection: Date | undefined;
+};
+/**
+ * Properties of a reconnect-event.
+ */
+export type ReconnectEventDetail = Omit<RetryEventDetail, "backoff">;
+/**
+ * Properties of an exhausted-event. The 'retries' field holds the number of
+ * retries that were performed before giving up, i.e. the configured maxRetries.
+ */
+export type ExhaustedEventDetail = Omit<RetryEventDetail, "backoff">;
+/**
+ * Maps websocket events to their corresponding event.
+ */
+export type WebsocketEventMap = {
+    [WebsocketEvent.open]: Event;
+    [WebsocketEvent.close]: CloseEvent;
+    [WebsocketEvent.error]: Event;
+    [WebsocketEvent.message]: MessageEvent;
+    [WebsocketEvent.retry]: CustomEvent<RetryEventDetail>;
+    [WebsocketEvent.reconnect]: CustomEvent<ReconnectEventDetail>;
+    [WebsocketEvent.exhausted]: CustomEvent<ExhaustedEventDetail>;
+};
+/**
+ * Listener for websocket events.
+ * */
+export type WebsocketEventListener<K extends WebsocketEvent> = (instance: Websocket, ev: WebsocketEventMap[K]) => unknown;
+export type WebsocketEventListenerParams<K extends WebsocketEvent> = Parameters<WebsocketEventListener<K>>;
+/**
+ * Options for websocket event listeners. Only 'once' and 'signal' are
+ * supported: a websocket has no capture/bubble phases and its events are not
+ * cancelable, so the remaining AddEventListenerOptions have no meaning here.
+ */
+export type WebsocketEventListenerOptions = Pick<AddEventListenerOptions, "once" | "signal">;
+/**
+ * Listener for websocket events with options.
+ */
+export type WebsocketEventListenerWithOptions<K extends WebsocketEvent> = {
+    readonly listener: WebsocketEventListener<K>;
+    readonly options?: WebsocketEventListenerOptions;
+};
+/**
+ * Maps websocket events to their corresponding event-listeners.
+ */
+export type WebsocketEventListeners = {
+    [K in WebsocketEvent]: WebsocketEventListenerWithOptions<K>[];
+};
+//# sourceMappingURL=websocket_event.d.ts.map

package/dist/esm/websocket_event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_event.d.ts","sourceRoot":"","sources":["../../src/websocket_event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,2CAA2C;;IAG3C,2CAA2C;;IAG3C;;;;OAIG;;IAGH,wCAAwC;;IAGxC,2EAA2E;;IAG3E,gFAAgF;;IAGhF,iFAAiF;;CAEzE,CAAC;AAEX,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,0FAA0F;AAE1F,yBAAiB,cAAc,CAAC;IAC9B,KAAY,IAAI,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;IAC9C,KAAY,KAAK,GAAG,OAAO,cAAc,CAAC,KAAK,CAAC;IAChD,KAAY,KAAK,GAAG,OAAO,cAAc,CAAC,KAAK,CAAC;IAChD,KAAY,OAAO,GAAG,OAAO,cAAc,CAAC,OAAO,CAAC;IACpD,KAAY,KAAK,GAAG,OAAO,cAAc,CAAC,KAAK,CAAC;IAChD,KAAY,SAAS,GAAG,OAAO,cAAc,CAAC,SAAS,CAAC;IACxD,KAAY,SAAS,GAAG,OAAO,cAAc,CAAC,SAAS,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,4HAA4H;IAC5H,QAAQ,CAAC,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAC7B,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnC,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAC9B,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvC,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IACtD,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAC9D,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;CAC/D,CAAC;AAEF;;KAEK;AACL,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,cAAc,IAAI,CAC7D,QAAQ,EAAE,SAAS,EACnB,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC;AAEb,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,cAAc,IAAI,UAAU,CAC7E,sBAAsB,CAAC,CAAC,CAAC,CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAC9C,uBAAuB,EACvB,MAAM,GAAG,QAAQ,CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iCAAiC,CAAC,CAAC,SAAS,cAAc,IAAI;IACxE,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,6BAA6B,CAAC;CAClD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;KACnC,CAAC,IAAI,cAAc,GAAG,iCAAiC,CAAC,CAAC,CAAC,EAAE;CAC9D,CAAC"}

package/dist/esm/websocket_event.js

@@ -0,0 +1,24 @@
+/**
+ * Events that can be fired by the websocket.
+ */
+export const WebsocketEvent = {
+    /** Fired when the connection is opened. */
+    open: "open",
+    /** Fired when the connection is closed. */
+    close: "close",
+    /**
+     * Fired when the connection has been closed because of an error, such as when some data couldn't be sent.
+     * Also fired when an automatic retry fails because the URL provider or the WebSocket constructor threw;
+     * that event is an ErrorEvent whose 'error' is the thrown value.
+     */
+    error: "error",
+    /** Fired when a message is received. */
+    message: "message",
+    /** Fired when the websocket tries to reconnect after a connection loss. */
+    retry: "retry",
+    /** Fired when the websocket successfully reconnects after a connection loss. */
+    reconnect: "reconnect",
+    /** Fired when the websocket gives up reconnecting after exceeding maxRetries. */
+    exhausted: "exhausted",
+};
+//# sourceMappingURL=websocket_event.js.map

package/dist/esm/websocket_event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_event.js","sourceRoot":"","sources":["../../src/websocket_event.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM;IAEZ,2CAA2C;IAC3C,KAAK,EAAE,OAAO;IAEd;;;;OAIG;IACH,KAAK,EAAE,OAAO;IAEd,wCAAwC;IACxC,OAAO,EAAE,SAAS;IAElB,2EAA2E;IAC3E,KAAK,EAAE,OAAO;IAEd,gFAAgF;IAChF,SAAS,EAAE,WAAW;IAEtB,iFAAiF;IACjF,SAAS,EAAE,WAAW;CACd,CAAC"}

package/dist/{cjs/src → esm}/websocket_options.d.ts

@@ -1,6 +1,6 @@
-import { WebsocketBuffer } from "./websocket_buffer";
-import { WebsocketConnectionRetryOptions } from "./websocket_retry_options";
-import { WebsocketEventListeners } from "./websocket_event";
+import { WebsocketBuffer } from "./websocket_buffer.js";
+import { WebsocketConnectionRetryOptions } from "./websocket_retry_options.js";
+import { WebsocketEventListeners } from "./websocket_event.js";
 /**
  * Options that can be passed to the Websocket constructor.
  */
@@ -14,8 +14,9 @@ export interface WebsocketOptions {
      */
     readonly retry?: WebsocketConnectionRetryOptions;
     /**
-     * The initial listeners to add to the websocket.
+     * The initial listeners to add to the websocket. Event-types without
+     * listeners can be omitted.
      */
-    readonly listeners?: WebsocketEventListeners;
+    readonly listeners?: Partial<WebsocketEventListeners>;
 }
 //# sourceMappingURL=websocket_options.d.ts.map

package/dist/esm/websocket_options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_options.d.ts","sourceRoot":"","sources":["../../src/websocket_options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,+BAA+B,CAAC;IAEjD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACvD"}

package/dist/esm/websocket_options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_options.js","sourceRoot":"","sources":["../../src/websocket_options.ts"],"names":[],"mappings":""}

package/dist/{cjs/src → esm}/websocket_retry_options.d.ts

@@ -1,14 +1,15 @@
-import { Backoff } from "./backoff/backoff";
+import { Backoff } from "./backoff/backoff.js";
 /**
  * Options for the websockets retry-strategy.
  */
 export interface WebsocketConnectionRetryOptions {
     /**
-     * The maximum number of retries before giving up. No limit if undefined.
+     * The maximum number of retries before giving up. No limit if undefined or Infinity.
+     * Must be Infinity or a non-negative integer; zero means no retry is ever made.
      */
     readonly maxRetries?: number;
     /**
-     * Wether to reconnect immediately after a connection has been lost,
+     * Whether to reconnect immediately after a connection has been lost,
      * ignoring the backoff strategy for the first retry.
      */
     readonly instantReconnect?: boolean;

package/dist/esm/websocket_retry_options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_retry_options.d.ts","sourceRoot":"","sources":["../../src/websocket_retry_options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/esm/websocket_retry_options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket_retry_options.js","sourceRoot":"","sources":["../../src/websocket_retry_options.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,9 +1,27 @@
 {
   "name": "websocket-ts",
-  "version": "2.2.1",
-  "main": "dist/cjs/src/index.js",
-  "types": "dist/cjs/src/index.d.ts",
-  "module": "dist/esm/src/index.js",
+  "description": "A WebSocket client library with optional reconnecting and buffering capabilities.",
+  "version": "3.0.0",
+  "main": "dist/cjs/index.js",
+  "types": "dist/cjs/index.d.ts",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "MIT",
   "keywords": [
     "websocket",
@@ -18,31 +36,32 @@
     "url": "github:jjxxs/websocket-ts"
   },
   "scripts": {
-    "build": "npm run build:cjs && npm run build:esm",
+    "build": "npm run typecheck && npm run build:cjs && npm run build:esm && npm run build:finalize",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json",
-    "coveralls": "cat ./coverage/lcov.info | coveralls",
-    "lint": "cross-env-shell eslint './src/{**/*,*}.{js,ts}' './tests/{**/*,*}.{js,ts}'",
+    "build:finalize": "node -e \"const fs=require('fs');fs.writeFileSync('dist/esm/package.json',JSON.stringify({type:'module'}));fs.writeFileSync('dist/cjs/package.json',JSON.stringify({type:'commonjs'}))\"",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint \"./src/**/*.ts\" \"./tests/**/*.ts\"",
     "test": "vitest",
-    "test:coverage": "vitest --coverage"
+    "test:coverage": "vitest --coverage",
+    "docs": "typedoc"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.20.0",
-    "@types/ws": "^8.5.14",
-    "@typescript-eslint/eslint-plugin": "^8.24.0",
-    "@typescript-eslint/parser": "^8.24.0",
-    "@vitest/coverage-v8": "^3.0.5",
-    "coveralls": "^3.1.1",
-    "cross-env": "^7.0.3",
-    "eslint": "^9.20.1",
-    "eslint-config-prettier": "^10.0.1",
-    "eslint-plugin-prettier": "^5.2.3",
-    "globals": "^15.15.0",
-    "jsdom": "^26.0.0",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5",
-    "ws": "^8.18.0"
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.7.0",
+    "jsdom": "^26.1.0",
+    "prettier": "^3.9.4",
+    "typedoc": "^0.28.20",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11",
+    "ws": "^8.20.0"
   }
 }

package/src/backoff/backoff.ts

@@ -1,6 +1,9 @@
 /**
  * A Backoff produces a series of numbers that are used to determine
  * the delay between connection-retries. Values are expected to be in milliseconds.
+ *
+ * Implementations must not call back into the websocket (e.g. close() or reconnect()):
+ * the websocket calls them in the middle of its lifecycle transitions.
  */
 export interface Backoff {
   /**
@@ -9,13 +12,13 @@ export interface Backoff {
   readonly retries: number;
 
   /**
-   * Current number in the series.
+   * Current number in the series, i.e. the value that the next call to next() will return.
    */
   readonly current: number;
 
   /**
-   * Advances the series to the next number and returns it.
-   * @return the next number in the series
+   * Returns the current number in the series and advances the series by one step.
+   * @return the current number in the series
    */
   next(): number;
 

package/src/backoff/constantbackoff.ts

@@ -1,4 +1,4 @@
-import { Backoff } from "./backoff";
+import { Backoff } from "./backoff.js";
 
 /**
  * ConstantBackoff always returns the same backoff-time.
@@ -9,11 +9,11 @@ export class ConstantBackoff implements Backoff {
 
   /**
    * Creates a new ConstantBackoff.
-   * @param backoff the backoff-time to return
+   * @param backoff the backoff-time (in milliseconds) to return
    */
   constructor(backoff: number) {
-    if (!Number.isInteger(backoff) || backoff < 0) {
-      throw new Error("Backoff must be a positive integer");
+    if (!Number.isFinite(backoff) || backoff < 0) {
+      throw new Error("Backoff must be a finite, non-negative number");
     }
 
     this.backoff = backoff;

package/src/backoff/exponentialbackoff.ts

@@ -1,4 +1,4 @@
-import { Backoff } from "./backoff";
+import { Backoff } from "./backoff.js";
 
 /**
  * ExponentialBackoff increases the backoff-time exponentially.
@@ -38,15 +38,15 @@ export class ExponentialBackoff implements Backoff {
 
   /**
    * Creates a new ExponentialBackoff.
-   * @param base the base of the exponentiation
+   * @param base the base of the exponentiation (in milliseconds)
    * @param expMax the maximum exponent, no bound if undefined
    */
   constructor(base: number, expMax?: number) {
-    if (!Number.isInteger(base) || base < 0) {
-      throw new Error("Base must be a positive integer or zero");
+    if (!Number.isFinite(base) || base < 0) {
+      throw new Error("Base must be a finite, non-negative number");
     }
     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 or a non-negative integer");
     }
 
     this.base = base;
@@ -63,12 +63,13 @@ export class ExponentialBackoff implements Backoff {
   }
 
   next(): number {
+    const backoff = this.current;
     this._retries++;
     this.i =
       this.expMax === undefined
         ? this.i + 1
         : Math.min(this.i + 1, this.expMax);
-    return this.current;
+    return backoff;
   }
 
   reset(): void {

package/src/backoff/linearbackoff.ts

@@ -1,4 +1,4 @@
-import { Backoff } from "./backoff";
+import { Backoff } from "./backoff.js";
 
 /**
  * LinearBackoff returns a backoff-time that is incremented by a fixed amount
@@ -45,14 +45,14 @@ export class LinearBackoff implements Backoff {
    * @param max the maximum backoff-time (in milliseconds), no bound if undefined
    */
   constructor(initial: number, increment: number, max?: number) {
-    if (initial < 0) {
-      throw new Error("Initial must be a positive number or zero");
+    if (!Number.isFinite(initial) || initial < 0) {
+      throw new Error("Initial must be a finite, non-negative number");
     }
-    if (increment < 0) {
-      throw new Error("Increment must be a positive number or zero");
+    if (!Number.isFinite(increment) || increment < 0) {
+      throw new Error("Increment must be a finite, non-negative number");
     }
-    if (max !== undefined && max < 0) {
-      throw new Error("Max must be undefined, a positive number or zero");
+    if (max !== undefined && (!Number.isFinite(max) || max < 0)) {
+      throw new Error("Max must be undefined or a finite, non-negative number");
     }
     if (max !== undefined && max < initial) {
       throw new Error(
@@ -76,9 +76,10 @@ export class LinearBackoff implements Backoff {
   }
 
   next(): number {
+    const backoff = this.current;
     this._retries++;
     this.i++;
-    return this.current;
+    return backoff;
   }
 
   reset(): void {