websocket-ts 1.1.0 → 2.1.1

package/src/backoff/exponentialbackoff.ts

@@ -1,38 +1,78 @@
-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.
- *
- * The calculation-specification is:
- *          backoff = k * 2^s with s in [1, expMax].
- *
- * Example: for initial=100, expMax=7 the ExponentialBackoff will pro-
- * duce the backoff-series [100, 200, 400, 800, 1600, 3200, 6400].
- */
-export class ExponentialBackoff implements Backoff {
-    private readonly initial: number;
-    private readonly expMax: number;
-    private expCurrent: number;
-    private current: number;
-
-    constructor(initial: number, expMax: number) {
-        this.initial = initial;
-        this.expMax = expMax;
-        this.expCurrent = 1;
-        this.current = this.initial;
-    }
-
-    next(): number {
-        const backoff = this.current;
-        if (this.expMax > this.expCurrent++)
-            this.current = this.current * 2;
-        return backoff;
-    }
-
-    reset() {
-        this.expCurrent = 1;
-        this.current = this.initial;
-    }
-}
+import { Backoff } from "./backoff";
+
+/**
+ * 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 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:
+ *
+ * 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 base: number;
+  private readonly expMax?: number;
+  private i: number;
+  private _retries: number = 0;
+
+  /**
+   * 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");
+    }
+    if (expMax !== undefined && (!Number.isInteger(expMax) || expMax < 0)) {
+      throw new Error("ExpMax must be a undefined, a positive integer or zero");
+    }
+
+    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;
+  }
+}

package/src/backoff/linearbackoff.ts

@@ -1,37 +1,88 @@
-import {Backoff} from "./backoff";
-
-/**
- * LinearBackoff increases the backoff-time by a constant number with
- * every step. An optional maximum can be provided as an upper bound
- * to the returned backoff.
- *
- * Example: for initial=0, increment=2000, maximum=8000 the Linear-
- * Backoff will produce the series [0, 2000, 4000, 6000, 8000].
- */
-export class LinearBackoff implements Backoff {
-    private readonly initial: number;
-    private readonly increment: number;
-    private readonly maximum?: number;
-    private current: number;
-
-    constructor(initial: number, increment: number, maximum?: number) {
-        this.initial = initial;
-        this.increment = increment;
-        this.maximum = maximum;
-        this.current = this.initial;
-    }
-
-    next() {
-        const backoff = this.current;
-        const next = this.current + this.increment;
-        if (this.maximum === undefined)
-            this.current = next;
-        else if (next <= this.maximum)
-            this.current = next;
-        return backoff;
-    }
-
-    reset() {
-        this.current = this.initial;
-    }
-}
+import { Backoff } from "./backoff";
+
+/**
+ * LinearBackoff returns a backoff-time that is incremented by a fixed amount
+ * with every step/retry. An optional maximum can be provided as an upper bound
+ * to the returned backoff.
+ *
+ * The series can be described as ('i' is the current step/retry):
+ *   backoff = initial + increment * i                | without bound
+ *   backoff = initial + increment * min(i, max)      | with bound
+ *
+ * Example:
+ *
+ * 1) Without bound:
+ *  initial = 1000, increment = 1000
+ *  backoff = 1000 + 1000 * 0 = 1000 // first retry
+ *  backoff = 1000 + 1000 * 1 = 2000 // second retry
+ *  backoff = 1000 + 1000 * 2 = 3000 // ...increases by 'increment' with every retry
+ *  backoff = 1000 + 1000 * 3 = 4000
+ *  backoff = 1000 + 1000 * 4 = 5000
+ *  ... // and so on
+ *
+ *  2) With bound:
+ *  initial = 1000, increment = 1000, max = 5000
+ *  backoff = 1000 + 1000 * 0 = 1000 // first retry
+ *  backoff = 1000 + 1000 * 1 = 2000 // second retry
+ *  backoff = 1000 + 1000 * 2 = 3000 // third retry
+ *  backoff = 1000 + 1000 * 3 = 4000 // fourth retry
+ *  backoff = 1000 + 1000 * 4 = 5000 // maximum reached, don't increase further
+ *  backoff = 1000 + 1000 * 4 = 5000
+ *  backoff = 1000 + 1000 * 4 = 5000
+ *  ... // and so on
+ */
+export class LinearBackoff implements Backoff {
+  private readonly initial: number;
+  private readonly increment: number;
+  private readonly max?: number;
+  private i: number = 0;
+  private _retries: number = 0;
+
+  /**
+   * Creates a new LinearBackoff.
+   * @param initial the initial backoff-time in milliseconds
+   * @param increment the amount to increment the backoff-time with every step (in milliseconds)
+   * @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 (increment < 0) {
+      throw new Error("Increment must be a positive number or zero");
+    }
+    if (max !== undefined && max < 0) {
+      throw new Error("Max must be undefined, a positive number or zero");
+    }
+    if (max !== undefined && max < initial) {
+      throw new Error(
+        "Max must be undefined or greater than or equal to initial",
+      );
+    }
+
+    this.initial = initial;
+    this.increment = increment;
+    this.max = max;
+  }
+
+  get retries() {
+    return this._retries;
+  }
+
+  get current(): number {
+    return this.max === undefined
+      ? this.initial + this.increment * this.i
+      : Math.min(this.initial + this.increment * this.i, this.max);
+  }
+
+  next(): number {
+    this._retries++;
+    this.i++;
+    return this.current;
+  }
+
+  reset(): void {
+    this._retries = 0;
+    this.i = 0;
+  }
+}

package/src/index.ts

@@ -1,9 +1,23 @@
-export * from './backoff/backoff';
-export * from './backoff/constantbackoff'
-export * from './backoff/exponentialbackoff'
-export * from './backoff/linearbackoff'
-export * from './buffer/buffer';
-export * from './buffer/lrubuffer'
-export * from './buffer/timebuffer'
-export * from './websocket';
-export * from './websocketBuilder';
+export { Backoff } from "./backoff/backoff";
+export { ConstantBackoff } from "./backoff/constantbackoff";
+export { ExponentialBackoff } from "./backoff/exponentialbackoff";
+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 { WebsocketBuffer } from "./websocket_buffer";
+export { WebsocketBuilder } from "./websocket_builder";
+export {
+  WebsocketEvent,
+  RetryEventDetail,
+  ReconnectEventDetail,
+  WebsocketEventMap,
+  WebsocketEventListener,
+  WebsocketEventListenerParams,
+  WebsocketEventListenerOptions,
+  WebsocketEventListenerWithOptions,
+  WebsocketEventListeners,
+} from "./websocket_event";
+export { WebsocketOptions } from "./websocket_options";
+export { WebsocketConnectionRetryOptions } from "./websocket_retry_options";

package/src/queue/array_queue.ts

@@ -0,0 +1,41 @@
+import { Queue } from "./queue";
+
+/**
+ * An array queue is a queue that has an unbounded capacity. Reading from an array queue
+ * will return the oldest element and effectively remove it from the queue.
+ */
+export class ArrayQueue<E> implements Queue<E> {
+  private readonly elements: E[];
+
+  constructor() {
+    this.elements = [];
+  }
+
+  add(element: E): void {
+    this.elements.push(element);
+  }
+
+  clear() {
+    this.elements.length = 0;
+  }
+
+  forEach(fn: (element: E) => unknown) {
+    this.elements.forEach(fn);
+  }
+
+  length(): number {
+    return this.elements.length;
+  }
+
+  isEmpty(): boolean {
+    return this.elements.length === 0;
+  }
+
+  peek(): E | undefined {
+    return this.elements[0];
+  }
+
+  read(): E | undefined {
+    return this.elements.shift();
+  }
+}

package/src/queue/queue.ts

@@ -0,0 +1,46 @@
+/**
+ * A queue holds elements until they are read. The order in which elements are
+ * read is determined by the implementation of the queue.
+ */
+export interface Queue<E> {
+  /**
+   * Adds an element to the queue.
+   * @param element the element to add
+   */
+  add(element: E): void;
+
+  /**
+   * Clears the queue, removing all elements.
+   */
+  clear(): void;
+
+  /**
+   * Calls the given function for each element in the queue.
+   * @param fn the function to call
+   */
+  forEach(fn: (element: E) => unknown): void;
+
+  /**
+   * Number of elements in the queue.
+   * @return the number of elements in the queue
+   */
+  length(): number;
+
+  /**
+   * Whether the queue is empty.
+   * @return true if the queue is empty, false otherwise
+   */
+  isEmpty(): boolean;
+
+  /**
+   * Returns the next element in the queue without removing it.
+   * @return the next element in the queue, or undefined if the queue is empty
+   */
+  peek(): E | undefined;
+
+  /**
+   * Removes and returns the next element in the queue.
+   * @return the next element in the queue, or undefined if the queue is empty
+   */
+  read(): E | undefined;
+}

package/src/queue/ring_queue.ts

@@ -0,0 +1,69 @@
+import { Queue } from "./queue";
+
+/**
+ * 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
+ * element and effectively remove it from the queue.
+ */
+export class RingQueue<E> implements Queue<E> {
+  private readonly elements: E[];
+  private head: number; // index of the next position to write to
+  private tail: number; // index of the next position to read from
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error("Capacity must be a positive integer");
+    }
+
+    this.elements = new Array<E>(capacity + 1); // +1 to distinguish between full and empty
+    this.head = 0;
+    this.tail = 0;
+  }
+
+  add(element: E): void {
+    this.elements[this.head] = element;
+    this.head = (this.head + 1) % this.elements.length;
+    if (this.head === this.tail) {
+      this.tail = (this.tail + 1) % this.elements.length;
+    }
+  }
+
+  clear() {
+    this.head = 0;
+    this.tail = 0;
+  }
+
+  forEach(fn: (element: E) => unknown) {
+    for (
+      let i = this.tail;
+      i !== this.head;
+      i = (i + 1) % this.elements.length
+    ) {
+      fn(this.elements[i]);
+    }
+  }
+
+  length(): number {
+    return this.tail === this.head
+      ? 0
+      : this.tail < this.head
+      ? this.head - this.tail
+      : this.elements.length - this.tail + this.head;
+  }
+
+  isEmpty(): boolean {
+    return this.head === this.tail;
+  }
+
+  peek(): E | undefined {
+    return this.isEmpty() ? undefined : this.elements[this.tail];
+  }
+
+  read(): E | undefined {
+    const e = this.peek();
+    if (e !== undefined) {
+      this.tail = (this.tail + 1) % this.elements.length;
+    }
+    return e;
+  }
+}