@ceeblue/web-utils 3.0.0 → 3.2.0

package/commitlint.config.js

@@ -0,0 +1,9 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+export default {
+    extends: ['@commitlint/config-conventional'],
+    ignores: [commit => /^[^\r\n]*\[skip ci\]/.test(commit)]
+};

package/dist/web-utils.d.ts

@@ -53,7 +53,7 @@ declare class BinaryWriter {
      * Write binary data
      * @param data
      */
-    write(data: ArrayLike<number>): BinaryWriter;
+    write(data: ArrayLike<number> | BufferSource | string): BinaryWriter;
     write8(value: number): BinaryWriter;
     write16(value: number): BinaryWriter;
     write24(value: number): BinaryWriter;
@@ -208,19 +208,69 @@ declare class BitReader extends Loggable {
 }
 
 /**
- * Compute ByteRate every delta time
+ * Class to compute a weighted average byte rate over a specified time interval.
+ *
+ * This class continuously tracks data transmission and computes the byte rate
+ * based on a weighted average, considering both the duration and the number of
+ * bytes in each sample. It allows for real-time monitoring of bandwidth usage
+ * and provides mechanisms to dynamically adjust the measurement interval.
+ *
+ * Features:
+ * - Computes the byte rate using a **weighted average** approach.
+ * - Allows setting a custom interval for tracking.
+ * - Supports dynamic clipping to manually shrink the observation window.
  */
 declare class ByteRate {
+    /**
+     * Raised when new bytes are added
+     */
     onBytes(bytes: number): void;
-    get delta(): number;
+    /**
+     * Returns the interval used for computing the byte rate
+     */
+    get interval(): number;
+    /**
+     * Sets a new interval for computing the average byte rate
+     */
+    set interval(value: number);
+    private _interval;
     private _bytes;
     private _time;
-    private _delta;
-    private _value;
-    constructor(delta?: number);
+    private _samples;
+    private _clip;
+    /**
+     * Constructor initializes the ByteRate object with a specified interval (default: 1000ms).
+     * It sets up necessary variables to track byte rate over time.
+     *
+     * @param interval - Time interval in milliseconds to compute the byte rate.
+     */
+    constructor(interval?: number);
+    /**
+     * Returns the computed byte rate rounded to the nearest integer
+     */
     value(): number;
+    /**
+     * Computes the exact byte rate in bytes per second
+     */
     exact(): number;
-    addBytes(bytes: number): this;
+    /**
+     * Adds a new byte sample to the tracking system.
+     * Updates the list of samples and recomputes the byte rate
+     *
+     * @param bytes - Number of bytes added in this interval
+     */
+    addBytes(bytes: number): ByteRate;
+    /**
+     * Clears all recorded byte rate data.
+     */
+    clear(): ByteRate;
+    /**
+     * Clips the byte rate tracking by marking the last sample as clipped.
+     * If a previous clip exists, removes the clipped sample and all preceding samples.
+     * Allows to shrink the interval manually between two positions.
+     */
+    clip(): ByteRate;
+    private updateSamples;
 }
 
 /**
@@ -350,16 +400,20 @@ declare class EventEmitter extends Loggable {
      * Event subscription
      * @param name Name of event without the `on` prefix (ex: `log` to `onLog` event declared)
      * @param event Subscriber Function
-     * @param abort Optional `AbortController` to stop this or multiple subscriptions in same time
+     * @param options.signal Optional `AbortSignal` to stop this or multiple subscriptions in same time
      */
-    on(name: string, event: Function, abort?: AbortController): void;
+    on(name: string, event: Function, options?: {
+        signal?: AbortSignal;
+    }): void;
     /**
      * Event subscription only one time, once time fired it's automatically unsubscribe
      * @param name Name of event without the `on` prefix (ex: `log` to `onLog` event declared)
      * @param event Subscriber Function
-     * @param abort Optional `AbortController` to stop this or multiple subscriptions in same time
+     * @param options.abortSignal Optional `AbortSignal` to stop this or multiple subscriptions in same time
      */
-    once(name: string, event: Function, abort?: AbortController): void;
+    once(name: string, event: Function, options?: {
+        signal?: AbortSignal;
+    }): void;
     /**
      * Event unsubscription
      * @param name Name of event without the 'on' prefix (ex: 'log' to 'onLog' event declared)
@@ -1033,6 +1087,86 @@ declare namespace EpochTime {
   export { EpochTime_decodeTimestamp as decodeTimestamp, EpochTime_encodeTimestamp as encodeTimestamp, EpochTime_getLatency as getLatency };
 }
 
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+/**
+ * An user-interface compoment to vizualize real-time metrics
+ */
+declare class UIMetrics {
+    /**
+     * get graph margin in pixels
+     */
+    get graphMargin(): number;
+    /**
+     * set graph margin in pixels
+     */
+    set graphMargin(value: number);
+    /**
+     * get text margin in pixels
+     */
+    get textMargin(): number;
+    /**
+     * set text margin in pixels
+     */
+    set textMargin(value: number);
+    /**
+     * get metric line height in pixels
+     */
+    get lineHeight(): number;
+    /**
+     * set metric line height in pixels
+     */
+    set lineHeight(value: number);
+    /**
+     * get label width in pixels
+     */
+    get labelWidth(): number;
+    /**
+     * set label width in pixels
+     */
+    set labelWidth(value: number);
+    /**
+     * get legend font size in pixels
+     */
+    get legendFontSize(): number;
+    /**
+     * set legend font size in pixels
+     */
+    set legendFontSize(value: number);
+    /**
+     * get the metric unit-step in pixels
+     */
+    get stepSize(): number;
+    /**
+     * set the metric unit-step in pixels
+     */
+    set stepSize(value: number);
+    private _ui;
+    private _html?;
+    private _lineHeight;
+    private _labelWidth;
+    private _graphMargin;
+    private _textMargin;
+    private _legendFontSize;
+    private _stepSize;
+    private _ranges;
+    constructor(ui: HTMLElement);
+    /**
+     * Reset metrics stats, essentially rescaling the metrics
+     */
+    reset(): void;
+    /**
+     * build metric from stats
+     * @param stats Map with stats per entry
+     * @returns
+     */
+    display(stats: Map<string, Array<string | number>>): void;
+    private _drawCircle;
+}
+
 /**
  * Copyright 2024 Ceeblue B.V.
  * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
@@ -1041,4 +1175,4 @@ declare namespace EpochTime {
 
 declare const VERSION: string;
 
-export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EpochTime, EventEmitter, FixMap, type ILog, Log, LogLevel, Loggable, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable, type WebSocketReliableError, log };
+export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EpochTime, EventEmitter, FixMap, type ILog, Log, LogLevel, Loggable, NetAddress, Numbers, Queue, SDP, UIMetrics, Util, VERSION, WebSocketReliable, type WebSocketReliableError, log };