@ceeblue/web-utils 3.0.0 → 3.1.0

package/dist/web-utils.d.ts

@@ -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 };

package/dist/web-utils.js

@@ -841,38 +841,146 @@ class BitReader extends Loggable {
  * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
  */
 /**
- * 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.
  */
 class ByteRate {
+    /**
+     * Raised when new bytes are added
+     */
     onBytes(bytes) { }
-    get delta() {
-        return this._delta;
+    /**
+     * Returns the interval used for computing the byte rate
+     */
+    get interval() {
+        return this._interval;
     }
-    constructor(delta = 1000) {
-        this._time = time();
-        this._value = NaN;
-        this._delta = delta;
-        this._bytes = 0;
+    /**
+     * Sets a new interval for computing the average byte rate
+     */
+    set interval(value) {
+        this._interval = value;
+        this.updateSamples();
     }
+    /**
+     * 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 = 1000) {
+        this._interval = interval;
+        this.clear();
+    }
+    /**
+     * Returns the computed byte rate rounded to the nearest integer
+     */
     value() {
         return Math.round(this.exact());
     }
+    /**
+     * Computes the exact byte rate in bytes per second
+     */
     exact() {
-        const now = time();
-        const elapsed = now - this._time;
-        if (elapsed > this._delta || isNaN(this._value)) {
-            // wait "_delta" before next compute rate
-            this._value = (this._bytes * 1000) / elapsed;
-            this._bytes = 0;
-            this._time = now;
-        }
-        return this._value;
+        // compute rate/s
+        this.updateSamples();
+        const duration = time() - this._time;
+        return duration ? (this._bytes / duration) * 1000 : 0;
     }
+    /**
+     * 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) {
+        var _a;
+        const time$1 = time();
+        const lastSample = this.updateSamples(time$1)[this._samples.length - 1];
+        const lastTime = (_a = lastSample === null || lastSample === void 0 ? void 0 : lastSample.time) !== null && _a !== void 0 ? _a : this._time;
+        if (time$1 > lastTime) {
+            this._samples.push({ bytes, time: time$1, clip: false });
+        }
+        else {
+            // no new duration => attach byte to last-one
+            if (!lastSample) {
+                // Ignore, was before our ByteRate scope !
+                return this;
+            }
+            lastSample.bytes += bytes;
+        }
         this._bytes += bytes;
         this.onBytes(bytes);
         return this;
     }
+    /**
+     * Clears all recorded byte rate data.
+     */
+    clear() {
+        this._bytes = 0;
+        this._time = time();
+        this._samples = [];
+        this._clip = false;
+        return this;
+    }
+    /**
+     * 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() {
+        if (this._clip) {
+            this._clip = false;
+            let removes = 0;
+            for (const sample of this._samples) {
+                this._bytes -= sample.bytes;
+                ++removes;
+                this._time = sample.time;
+                if (sample.clip) {
+                    break;
+                }
+            }
+            this._samples.splice(0, removes);
+        }
+        const lastSample = this._samples[this._samples.length - 1];
+        if (lastSample) {
+            lastSample.clip = true;
+            this._clip = true;
+        }
+        return this;
+    }
+    updateSamples(now = time()) {
+        // Remove obsolete sample
+        const timeOK = now - this._interval;
+        let removes = 0;
+        let sample;
+        while (this._time < timeOK && (sample = this._samples[removes])) {
+            this._bytes -= sample.bytes;
+            if (sample.clip) {
+                this._clip = sample.clip = false;
+            }
+            if (sample.time > timeOK) {
+                // only a part of the sample to delete !
+                sample.bytes *= (sample.time - timeOK) / (sample.time - this._time);
+                this._time = timeOK;
+                this._bytes += sample.bytes;
+                break;
+            }
+            ++removes;
+            this._time = sample.time;
+        }
+        this._samples.splice(0, removes);
+        return this._samples;
+    }
 }/**
  * 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.
@@ -1062,7 +1170,7 @@ function defineMediaExt(type, params) {
             break;
     }
     // Fix mediaExt in removing the possible '.' prefix
-    trimStart(params.mediaExt, '.');
+    params.mediaExt = trimStart(params.mediaExt, '.');
 }
 /**
  * Build an URL from {@link Type | type} and {@link Params | params}
@@ -1196,25 +1304,25 @@ 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, event, abort) {
+    on(name, event, options) {
+        var _a;
         if (!event) {
             throw Error('event to subscribe cannot be null');
         }
         const events = this._event(name);
         events.add(event);
-        if (abort) {
-            abort.signal.addEventListener('abort', () => events.delete(event), { once: true });
-        }
+        (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', () => events.delete(event), { once: true });
     }
     /**
      * 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, event, abort) {
+    once(name, event, options) {
+        var _a;
         if (!event) {
             throw Error('event to subscribe cannot be null');
         }
@@ -1223,9 +1331,7 @@ class EventEmitter extends Loggable {
             events.delete(event); // delete from events
             event(...args); // execute event
         });
-        if (abort) {
-            abort.signal.addEventListener('abort', () => events.delete(event), { once: true });
-        }
+        (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', () => events.delete(event), { once: true });
     }
     /**
      * Event unsubscription
@@ -2057,4 +2163,230 @@ function encodeTimestamp(context, lineWidth, blocksPerRow = 32, now = new Date()
  * 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.
  */
-const VERSION = '3.0.0';export{BinaryReader,BinaryWriter,BitReader,ByteRate,Connect,EpochTime,EventEmitter,FixMap,Log,LogLevel,Loggable,NetAddress,Numbers,Queue,SDP,Util,VERSION,WebSocketReliable,log};//# sourceMappingURL=web-utils.js.map
+/**
+ * An user-interface compoment to vizualize real-time metrics
+ */
+class UIMetrics {
+    /**
+     * get graph margin in pixels
+     */
+    get graphMargin() {
+        return this._graphMargin;
+    }
+    /**
+     * set graph margin in pixels
+     */
+    set graphMargin(value) {
+        this._graphMargin = value;
+    }
+    /**
+     * get text margin in pixels
+     */
+    get textMargin() {
+        return this._textMargin;
+    }
+    /**
+     * set text margin in pixels
+     */
+    set textMargin(value) {
+        this._textMargin = value;
+    }
+    /**
+     * get metric line height in pixels
+     */
+    get lineHeight() {
+        return this._lineHeight;
+    }
+    /**
+     * set metric line height in pixels
+     */
+    set lineHeight(value) {
+        this._lineHeight = value;
+    }
+    /**
+     * get label width in pixels
+     */
+    get labelWidth() {
+        return this._labelWidth;
+    }
+    /**
+     * set label width in pixels
+     */
+    set labelWidth(value) {
+        this._labelWidth = value;
+    }
+    /**
+     * get legend font size in pixels
+     */
+    get legendFontSize() {
+        return this._legendFontSize;
+    }
+    /**
+     * set legend font size in pixels
+     */
+    set legendFontSize(value) {
+        this._legendFontSize = value;
+    }
+    /**
+     * get the metric unit-step in pixels
+     */
+    get stepSize() {
+        return this._stepSize;
+    }
+    /**
+     * set the metric unit-step in pixels
+     */
+    set stepSize(value) {
+        this._stepSize = value;
+    }
+    constructor(ui) {
+        this._ui = ui;
+        // default values in pixels
+        this._lineHeight = 40;
+        this._labelWidth = 170;
+        this._graphMargin = 5;
+        this._textMargin = 5;
+        this._legendFontSize = 13;
+        this._stepSize = 10;
+        this._ranges = {};
+    }
+    /**
+     * Reset metrics stats, essentially rescaling the metrics
+     */
+    reset() {
+        this._ranges = {};
+    }
+    /**
+     * build metric from stats
+     * @param stats Map with stats per entry
+     * @returns
+     */
+    display(stats) {
+        if (this._html != null) {
+            // CPU processing, skip one stats!
+            return;
+        }
+        this._html = '';
+        const averageWidth = (this._legendFontSize / 2) * 7; // 7 chars (1 char width ≈ fontSize/2)
+        const width = this._ui.clientWidth - averageWidth;
+        const graphHeight = this._lineHeight - 2 * this._graphMargin;
+        const graphMiddle = Math.round(this._lineHeight / 2);
+        const textY = Math.round(this._lineHeight / 2 + this._textMargin);
+        const titleWidth = this._labelWidth - 2 * this._textMargin;
+        const averageCenter = averageWidth / 2;
+        for (const [key, values] of stats) {
+            let x = this._labelWidth + values.length * this._stepSize;
+            if (x >= width) {
+                x -= values.splice(0, Math.ceil((x - width) / this._stepSize)).length * this._stepSize;
+            }
+            if (!values.length) {
+                continue;
+            }
+            /*
+            <svg class="list-group-item p-0" style="height: 40px;" xmlns="http://www.w3.org/2000/svg">
+                <text x="5" y="22">M text</text>
+                <path fill="none" d="M100 0 110 22 120 0 130 20" stroke-width="1" stroke="brown"/>
+            </svg>
+            */
+            this._html +=
+                '<svg class="list-group-item p-0" style="height: ' +
+                    this._lineHeight +
+                    'px" xmlns="http://www.w3.org/2000/svg">';
+            this._html += '<text x="' + this._textMargin + '" y="' + textY + '">' + key + '</text>';
+            this._html +=
+                '<text x="' +
+                    titleWidth +
+                    '" y="' +
+                    textY +
+                    '" text-anchor="end">' +
+                    values[values.length - 1].toString() +
+                    '</text>';
+            this._html += '<path fill="none" d="M' + this._labelWidth + ' ' + graphMiddle;
+            this._html += 'H' + (width + averageCenter);
+            this._html += '" stroke-width="1" stroke="lightgray" stroke-dasharray="10,10"/>';
+            this._html += '<path fill="none" stroke-width="1" stroke="brown" d="M';
+            let min = Number.POSITIVE_INFINITY;
+            let max = Number.NEGATIVE_INFINITY;
+            for (let i = 0; i < values.length; ++i) {
+                const value = parseFloat(values[i].toString());
+                if (value < min) {
+                    min = value;
+                }
+                if (value > max) {
+                    max = value;
+                }
+            }
+            let range = this._ranges[key];
+            if (!range) {
+                this._ranges[key] = range = { min: Number.POSITIVE_INFINITY, max: Number.NEGATIVE_INFINITY };
+            }
+            range.min = Math.min(range.min, min);
+            range.max = Math.max(range.max, max);
+            const delta = range.max - range.min;
+            let minCircle = '';
+            let maxCircle = '';
+            for (let i = 0; i < values.length; ++i) {
+                x -= this._stepSize;
+                const value = parseFloat(values[i].toString());
+                const y = graphMiddle + (delta ? Math.round((0.5 - (value - range.min) / delta) * graphHeight) : 0);
+                this._html += x + ' ' + y + ' ';
+                if (value === min) {
+                    maxCircle = maxCircle || this._drawCircle(x, y, value);
+                }
+                else if (value === max) {
+                    minCircle = minCircle || this._drawCircle(x, y, value);
+                }
+            }
+            this._html += '" />'; // end path
+            // Average
+            const average = Math.round((max - min) / 2);
+            this._html += '<text text-anchor="middle" font-size="' + this._legendFontSize + '" y="' + textY + '">';
+            this._html +=
+                '<tspan x="' +
+                    (width + averageCenter) +
+                    '" dy="-0.5em">' +
+                    (min !== max ? '≈' : '=') +
+                    (min + average) +
+                    '</tspan>';
+            this._html += '<tspan x="' + (width + averageCenter) + '" dy="1em">±' + average + '</tspan>';
+            this._html += '</text>';
+            this._html += minCircle + maxCircle;
+            this._html += '</svg>';
+        }
+        requestAnimationFrame(() => {
+            if (this._html != null) {
+                this._ui.innerHTML = this._html;
+                this._html = undefined;
+            }
+        });
+    }
+    _drawCircle(x, y, value) {
+        let circle = '<circle cx="' + x + '" cy="' + y + '" r="2" fill="green" />';
+        const legendFontHeight = 0.7 * this._legendFontSize;
+        const graphMiddle = Math.round(this._lineHeight / 2);
+        if (y < graphMiddle) {
+            // legend below
+            y += this.textMargin + legendFontHeight;
+        }
+        else {
+            // legend above
+            y -= this.textMargin;
+        }
+        circle +=
+            '<text font-style="italic" font-size="' +
+                this._legendFontSize +
+                '" x="' +
+                (x - this._legendFontSize) +
+                '" y="' +
+                y +
+                '">' +
+                value +
+                '</text>';
+        return circle;
+    }
+}/**
+ * 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.
+ */
+const VERSION = '3.1.0';export{BinaryReader,BinaryWriter,BitReader,ByteRate,Connect,EpochTime,EventEmitter,FixMap,Log,LogLevel,Loggable,NetAddress,Numbers,Queue,SDP,UIMetrics,Util,VERSION,WebSocketReliable,log};//# sourceMappingURL=web-utils.js.map