websocket-ts 1.1.1 → 2.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 J. Behrmann
+Copyright (c) 2023 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

package/README.md

@@ -1,147 +1,211 @@
-# websocket-ts
-A client-websocket written in TypeScript for browser-applications. Focus is on simplicity, reliability and extensibility. It provides convenient features to automatically reconnect and buffer pending messages.
-
-[![Build Status](https://travis-ci.org/jjxxs/websocket-ts.svg?branch=master)](https://travis-ci.org/jjxxs/websocket-ts)
-[![Coverage Status](https://coveralls.io/repos/github/jjxxs/websocket-ts/badge.svg?branch=master&service=github)](https://coveralls.io/github/jjxxs/websocket-ts?branch=master)
-[![Release](https://img.shields.io/github/v/release/jjxxs/websocket-ts)](https://github.com/jjxxs/websocket-ts/releases/latest)
-[![License](https://img.shields.io/github/license/jjxxs/websocket-ts)](/LICENSE)
+<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
-- Dependency-free and small in size
-- Uses the browser-native WebSocket-functionality
-   - Copies the event-based WebSocket-API
-   - Provides access to the underlying WebSocket
-- When the connection is lost, it can optionally be configured to
-   - Automatically try to reconnect in a smart way
-   - Buffer messages that are sent when the connection is re-established
-- Builder-class for easy initialization and configuration
-- High test-coverage and in-code documentation
-    - Enables you to easily modify and extend the code
+
+- **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
-In your project-root:
-```
+
+Install `websocket-ts` with npm:
+
+```bash
 $ npm install websocket-ts 
 ```
 
-In your project-code:
+## 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 {WebsocketBuilder} from 'websocket-ts';
+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 provided `WebsocketBuilder`:
+
+Create a new instance with the `WebsocketBuilder`:
 
 ```typescript
-const ws = new WebsocketBuilder('ws://localhost:42421').build();
+const ws = new WebsocketBuilder("ws://localhost:42421").build();
 ```
 
-#### Events & Callbacks
-There are five events which can be subscribed to through callbacks:
+#### Events
+
+There are six events which can be subscribed to through with event listeners:
+
 ```typescript
-export enum WebsocketEvents {
-    open = 'open',          // Connection is opened or re-opened
-    close = 'close',        // Connection is closed
-    error = 'error',        // An error occurred
-    message = 'message',    // A message was received
-    retry = 'retry'         // A try to re-connect is made
+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
 }
 ```
-The callbacks are called with the issuing websocket-instance and the causing event 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") })
-    .build();
-```
 
-You can register multiple callbacks for the same event. They will be called in stack-order:
-```typescript
-const ws = new WebsocketBuilder('ws://localhost:42421')
-    .onMessage((i, e) => { console.log("echo sent") })
-    .onMessage((i, e) => { i.send(e.data) })
-    .onMessage((i, e) => { console.log("message received") })
-    .build();
-```
+#### 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`:
 
-You can remove event-listener with `removeEventListener`:
 ```typescript
 let ws: Websocket
 /* ... */
-ws.removeEventListener(WebsocketEvents.open, openEventListener);
+ws.removeEventListener(WebsocketEvent.open, openEventListener);
 ```
 
-#### Send
-To send messages, use the websockets `send()`-method:
+#### Send Message
+
+Use the `send` method to send a message to the server:
+
 ```typescript
 let ws: Websocket;
 /* ... */
 ws.send("Hello World!");
 ```
 
-#### Reconnect & Backoff
-If you want the websocket to automatically try to re-connect when the connection is lost, you can provide it with a `Backoff`.
-The websocket will use the `Backoff` to determine how long it should wait between re-tries. There are currently three
-`Backoff`-implementations. You can also implement your own by inheriting from the `Backoff`-interface.
+#### 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` will make the websocket wait a constant time between each connection retry. To use the `ConstantBackoff`
-with a wait-time of `1 second`:
+
+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();
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new ConstantBackoff(1000)) // 1000ms = 1s
+  .build();
 ```
 
 ##### LinearBackoff
-The `LinearBackoff` linearly increases the wait-time between connection-retries until an optional maximum is reached.
-To use the `LinearBackoff` to initially wait `0 seconds` and increase the wait-time by `1 second` with every retry until
-a maximum of `8 seconds` is reached:
+
+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, 1000, 8000))
-    .build();
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new LinearBackoff(0, 10000, 60000)) // 0ms, 10s, 20s, 30s, 40s, 50s, 60s
+  .build();
 ```
 
 ##### ExponentialBackoff
-The `ExponentialBackoff` doubles the backoff with every retry until a maximum is reached. This is modelled after the binary
-exponential-backoff algorithm used in computer-networking. To use the `ExponentialBackoff` that will produce the series
-`[100, 200, 400, 800, 1600, 3200, 6400]`:
+
+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(100, 7))
-    .build();
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBackoff(new ExponentialBackoff(1000, 6)) // 1s, 2s, 4s, 8s, 16s, 32s, 64s
+  .build();
 ```
 
-#### Buffer
+#### 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
 
-If you want to buffer to-be-send messages while the websocket is disconnected, you can provide it with a `Buffer`.
-The websocket will use the buffer to temporarily keep your messages and send them in order once the websocket
-(re-)connects. There are currently two `Buffer`-implementations. You can also implement your own
- by inheriting from the `Buffer`-interface.
+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:
 
-##### LRUBuffer
-The `LRUBuffer` keeps the last `n` messages. When the buffer is full, the oldest message in the buffer will be replaced.
-It uses an array as a circular-buffer for linear space- and time-requirements. To use the `LRUBuffer` with a capacity of `1000`:
 ```typescript
-const ws = new WebsocketBuilder('ws://localhost:42421')
-    .withBuffer(new LRUBuffer(1000))
-    .build();
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBuffer(new RingQueue(100))
+  .build();
 ```
 
-##### TimeBuffer
-The `TimeBuffer` will keep all messages that were written within the last `n` milliseconds. It will drop messages that are
-older than the specified amount. To use the `TimeBuffer` that keeps messages from the last `5 minutes`:
+##### 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 TimeBuffer(5 * 60 * 1000))
-    .build();
+const ws = new WebsocketBuilder("ws://localhost:42421")
+  .withBuffer(new ArrayQueue())
+  .build();
 ```
 
-#### Build & Tests
-To build the project run `yarn build`. All provided components are covered with unit-tests. Run the tests with `yarn test`.
+## Build & Tests
+
+To compile the project, execute `npm run build`. The codebase includes unit tests for all
+components. To run these tests, use `npm run test`.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "websocket-ts",
-  "version": "1.1.1",
-  "main": "lib/index.js",
-  "types": "lib/",
+  "version": "2.1.1",
+  "main": "dist/cjs/src/index.js",
+  "types": "dist/cjs/src/index.d.ts",
+  "module": "dist/esm/src/index.js",
   "license": "MIT",
   "keywords": [
     "websocket",
@@ -12,22 +13,34 @@
     "reconnecting",
     "buffered"
   ],
+  "sideEffects": false,
   "repository": {
     "url": "github:jjxxs/websocket-ts"
   },
   "scripts": {
-    "build": "tsc -p .",
-    "compile": "tsc",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build": "npm run build:cjs && npm run build:esm",
     "test": "jest",
-    "coveralls": "jest --coverage && cat ./coverage/lcov.info | coveralls"
+    "test:coverage": "jest --coverage",
+    "coveralls": "cat ./coverage/lcov.info | coveralls",
+    "lint": "cross-env-shell eslint './src/{**/*,*}.{js,ts}' './tests/{**/*,*}.{js,ts}'"
   },
   "devDependencies": {
-    "@types/jest": "^26.0.23",
-    "@types/ws": "^7.4.4",
-    "coveralls": "^3.1.0",
-    "jest": "^27.0.4",
-    "ts-jest": "^27.0.2",
-    "typescript": "^4.3.2",
-    "ws": "^7.4.6"
+    "@typescript-eslint/eslint-plugin": "^6.6.0",
+    "@typescript-eslint/parser": "^6.6.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "coveralls": "^3.1.1",
+    "eslint": "^8.49.0",
+    "@types/jest": "^29.5.4",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.2.2",
+    "@types/ws": "^8.5.5",
+    "ws": "^7.0.0",
+    "cross-env": "^7.0.3"
   }
-}
+}

package/src/backoff/backoff.ts

@@ -1,18 +1,26 @@
 /**
- * Backoff provides a series of numbers. This series follows
- * a concrete pattern, e.g. be constant, linearly increasing,
- * exponentially increasing etc.
+ * A Backoff produces a series of numbers that are used to determine
+ * the delay between connection-retries. Values are expected to be in milliseconds.
  */
 export interface Backoff {
-    /**
-     * Provides the callee with the next number in the
-     * series.
-     * @return the next number
-     */
-    next(): number
+  /**
+   * The number of retries. Starts at 0, increases by 1 for each call to next(). Resets to 0 when reset() is called.
+   */
+  readonly retries: number;
 
-    /**
-     *  Resets the series to its starting-value.
-     */
-    reset(): void
+  /**
+   * Current number in the series.
+   */
+  readonly current: number;
+
+  /**
+   * Advances the series to the next number and returns it.
+   * @return the next number in the series
+   */
+  next(): number;
+
+  /**
+   * Resets the series to its initial state.
+   */
+  reset(): void;
 }

package/src/backoff/constantbackoff.ts

@@ -1,20 +1,38 @@
-import {Backoff} from "./backoff";
+import { Backoff } from "./backoff";
 
 /**
- * ConstantBackoff always returns the same value.
+ * ConstantBackoff always returns the same backoff-time.
  */
 export class ConstantBackoff implements Backoff {
-    private readonly backoff: number;
+  private readonly backoff: number;
+  private _retries: number = 0;
 
-    constructor(backoff: number) {
-        this.backoff = backoff;
+  /**
+   * Creates a new ConstantBackoff.
+   * @param backoff the backoff-time to return
+   */
+  constructor(backoff: number) {
+    if (!Number.isInteger(backoff) || backoff < 0) {
+      throw new Error("Backoff must be a positive integer");
     }
 
-    next(): number {
-        return this.backoff;
-    }
+    this.backoff = backoff;
+  }
 
-    reset = () => {
-        // no-op
-    }
+  get retries(): number {
+    return this._retries;
+  }
+
+  get current(): number {
+    return this.backoff;
+  }
+
+  next(): number {
+    this._retries++;
+    return this.backoff;
+  }
+
+  reset(): void {
+    this._retries = 0;
+  }
 }

package/src/backoff/exponentialbackoff.ts

@@ -1,38 +1,78 @@
-import {Backoff} from "./backoff";
+import { Backoff } from "./backoff";
 
 /**
- * ExponentialBackoff doubles the backoff with every step until a maximum
- * is reached. This is modelled after the binary exponential-backoff algo-
- * rithm used in computer-networking.
+ * ExponentialBackoff increases the backoff-time exponentially.
+ * An optional maximum can be provided as an upper bound to the
+ * exponent and thus to the returned backoff.
  *
- * The calculation-specification is:
- *          backoff = k * 2^s with s in [1, expMax].
+ * The series can be described as ('i' is the current step/retry):
+ *    backoff = base * 2^i                | without bound
+ *    backoff = base * 2^min(i, expMax)   | with bound
  *
- * Example: for initial=100, expMax=7 the ExponentialBackoff will pro-
- * duce the backoff-series [100, 200, 400, 800, 1600, 3200, 6400].
+ * Example:
+ *
+ * 1) Without bound:
+ *   base = 1000, expMax = undefined
+ *   backoff = 1000 * 2^0 = 1000 // first retry
+ *   backoff = 1000 * 2^1 = 2000 // second retry
+ *   backoff = 1000 * 2^2 = 4000 // ...doubles with every retry
+ *   backoff = 1000 * 2^3 = 8000
+ *   backoff = 1000 * 2^4 = 16000
+ *   ... // and so on
+ *
+ * 2) With bound:
+ *  base = 1000, expMax = 3
+ *  backoff = 1000 * 2^0 = 1000 // first retry
+ *  backoff = 1000 * 2^1 = 2000 // second retry
+ *  backoff = 1000 * 2^2 = 4000 // third retry
+ *  backoff = 1000 * 2^3 = 8000 // maximum reached, don't increase further
+ *  backoff = 1000 * 2^3 = 8000
+ *  backoff = 1000 * 2^3 = 8000
+ *  ... // and so on
  */
 export class ExponentialBackoff implements Backoff {
-    private readonly initial: number;
-    private readonly expMax: number;
-    private expCurrent: number;
-    private current: number;
+  private readonly base: number;
+  private readonly expMax?: number;
+  private i: number;
+  private _retries: number = 0;
 
-    constructor(initial: number, expMax: number) {
-        this.initial = initial;
-        this.expMax = expMax;
-        this.expCurrent = 1;
-        this.current = this.initial;
+  /**
+   * Creates a new ExponentialBackoff.
+   * @param base the base of the exponentiation
+   * @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");
     }
-
-    next(): number {
-        const backoff = this.current;
-        if (this.expMax > this.expCurrent++)
-            this.current = this.current * 2;
-        return backoff;
+    if (expMax !== undefined && (!Number.isInteger(expMax) || expMax < 0)) {
+      throw new Error("ExpMax must be a undefined, a positive integer or zero");
     }
 
-    reset() {
-        this.expCurrent = 1;
-        this.current = this.initial;
-    }
-}
+    this.base = base;
+    this.expMax = expMax;
+    this.i = 0;
+  }
+
+  get retries() {
+    return this._retries;
+  }
+
+  get current(): number {
+    return this.base * Math.pow(2, this.i);
+  }
+
+  next(): number {
+    this._retries++;
+    this.i =
+      this.expMax === undefined
+        ? this.i + 1
+        : Math.min(this.i + 1, this.expMax);
+    return this.current;
+  }
+
+  reset(): void {
+    this._retries = 0;
+    this.i = 0;
+  }
+}