websocket-ts 1.1.0 → 2.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2020 J. 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) 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
+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,138 +1,211 @@
-# websocket-ts
-A client-websocket written in TypeScript meant to be used from within browsers with focus 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)](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)
-
-## 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
-
-## Installation
-In your project-root:
-```
-$ npm install websocket-ts 
-```
-
-In your project-code:
-```typescript
-import {WebsocketBuilder} from 'websocket-ts';
-```
-
-## Usage
-
-#### Initialization
-New instances are most easily created with the provided `WebsocketBuilder`:
-
-```typescript
-const ws = new WebsocketBuilder('ws://localhost:42421').build();
-```
-
-#### Events & Callbacks
-There are five events which can be subscribed to through callbacks:
-```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
-}
-```
-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();
-```
-
-#### Send & buffer messages
-To send messages, use the websockets `send()`-method:
-```typescript
-let ws: Websocket;
-/* ... */
-ws.send("Hello World!");
-```
-
-If you want to buffer to-be-send messages while the websocket is disconnected, you can provide it with a `Buffer`.
-The websocket will then use the buffer to temporarily keep your messages and send them in correct order once the 
-connection is re-established. There are currently two `Buffer`-implementations. You can also implement your own
- by inheriting from the `Buffer`-interface.
-
-##### 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();
-```
-
-##### 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`:
-```typescript
-const ws = new WebsocketBuilder('ws://localhost:42421')
-    .withBuffer(new TimeBuffer(5 * 60 * 1000))
-    .build();
-```
-
-#### 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.
-
-##### 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`:
-```typescript
-const ws  = new WebsocketBuilder('ws://localhost:42421')
-    .withBackoff(new ConstantBackoff(500))
-    .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:
-```typescript
-const ws  = new WebsocketBuilder('ws://localhost:42421')
-    .withBackoff(new LinearBackoff(0, 1000, 8000))
-    .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]`:
-```typescript
-const ws  = new WebsocketBuilder('ws://localhost:42421')
-    .withBackoff(new ExponentialBackoff(100, 7))
-    .build();
-```
-
-#### Build & Tests
-To build the project run `yarn build`. All provided components are covered with unit-tests. To run the tests run `yarn test`.
+<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`. The codebase includes unit tests for all
+components. To run these tests, use `npm run test`.

package/package.json

@@ -1,33 +1,46 @@
-{
-  "name": "websocket-ts",
-  "version": "1.1.0",
-  "main": "lib/index.js",
-  "types": "lib/",
-  "license": "MIT",
-  "keywords": [
-    "websocket",
-    "browser",
-    "client",
-    "typescript",
-    "reconnecting",
-    "buffered"
-  ],
-  "repository": {
-    "url": "github:jjxxs/websocket-ts"
-  },
-  "scripts": {
-    "build": "tsc -p .",
-    "compile": "tsc",
-    "test": "jest",
-    "coveralls": "jest --coverage && cat ./coverage/lcov.info | coveralls"
-  },
-  "devDependencies": {
-    "@types/jest": "^26.0.13",
-    "@types/ws": "^7.2.6",
-    "coveralls": "^3.1.0",
-    "jest": "^26.4.2",
-    "ts-jest": "^26.3.0",
-    "typescript": "^4.0.2",
-    "ws": "^7.3.1"
-  }
-}
+{
+  "name": "websocket-ts",
+  "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",
+    "browser",
+    "client",
+    "typescript",
+    "reconnecting",
+    "buffered"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "url": "github:jjxxs/websocket-ts"
+  },
+  "scripts": {
+    "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",
+    "test:coverage": "jest --coverage",
+    "coveralls": "cat ./coverage/lcov.info | coveralls",
+    "lint": "cross-env-shell eslint './src/{**/*,*}.{js,ts}' './tests/{**/*,*}.{js,ts}'"
+  },
+  "devDependencies": {
+    "@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.
- */
-export interface Backoff {
-    /**
-     * Provides the callee with the next number in the
-     * series.
-     * @return the next number
-     */
-    next(): number
-
-    /**
-     *  Resets the series to its starting-value.
-     */
-    reset(): void
-}
+/**
+ * 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 {
+  /**
+   * 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;
+
+  /**
+   * 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";
-
-/**
- * ConstantBackoff always returns the same value.
- */
-export class ConstantBackoff implements Backoff {
-    private readonly backoff: number;
-
-    constructor(backoff: number) {
-        this.backoff = backoff;
-    }
-
-    next(): number {
-        return this.backoff;
-    }
-
-    reset = () => {
-        // no-op
-    }
-}
+import { Backoff } from "./backoff";
+
+/**
+ * ConstantBackoff always returns the same backoff-time.
+ */
+export class ConstantBackoff implements Backoff {
+  private readonly backoff: number;
+  private _retries: number = 0;
+
+  /**
+   * 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");
+    }
+
+    this.backoff = backoff;
+  }
+
+  get retries(): number {
+    return this._retries;
+  }
+
+  get current(): number {
+    return this.backoff;
+  }
+
+  next(): number {
+    this._retries++;
+    return this.backoff;
+  }
+
+  reset(): void {
+    this._retries = 0;
+  }
+}