@ceeblue/web-utils 2.6.1 → 3.1.0

package/README.md

@@ -27,6 +27,13 @@ import { Util, ILog } from '@ceeblue/web-utils';
 >   }
 >   ```
 
+> ⚠️ **REMARKS**
+> 
+> To debug production code without modifying it, the library can use special query parameter of the main page's URL:
+> - __!cb-override-log-level__ : allows to override the log level for the entire library, see [Log.ts](./src/Log.ts) for details on handling log levels.
+
+
+
 ## Building locally
 
 1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this repository

package/dist/web-utils.d.ts

@@ -72,10 +72,124 @@ declare class BinaryWriter {
  * 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.
  */
+/**
+ * Log levels
+ */
+declare enum LogLevel {
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    DEBUG = "debug"
+}
+/**
+ * Log interface to deal with log everywhere:
+ * - filter log level: filter log level independantly of the browser
+ * - subscribe logs: listen logs to effectuate some specific job related logs
+ * - intercept logs: intercept logs to change the default behavior
+ * - redirect logs: redirect logs to one other logger engine
+ * - redefine logs: change log text like adding a prefix
+ *
+ * You have 4 {@link LogLevel} 'error','warn','info',and 'debug', as commonly managed by browsers.
+ * You can use {@link ILog.level} or {@link ILog.on} to customer log level and behavior.
+ *
+ * @example
+ * // filter log level globally, independantly of the browser
+ * import { log } from '@ceeblue/web-utils';
+ * log.level = LogLevel.WARN; // displays errors and warns
+ *
+ * // filter log level only for Player compoment
+ * player.log.level = false; // no logs at all for player compoment
+ *
+ * // Intercept and redirect all the logs to the console (default behavior)
+ * import { log } from '@ceeblue/web-utils';
+ * log.on = (level:LogLevel,args:unknown[]) => {
+ *    console[level](...args.splice(0)); // args is empty after this call = final interception
+ * }
+ *
+ * // Intercept the logs from Player compoment and displays only WARN logs
+ * player.log.on = (level:LogLevel,args:unknown[]) => {
+ *    if (level !== LogLevel.WARN) {
+ *       args.length = 0; // args is empty after this call = final interception
+ *    }
+ * }
+ *
+ * // Subscribe and redirect all the logs to a file logger
+ * import { log } from '@ceeblue/web-utils';
+ * log.on = (level:LogLevel,args:unknown[]) => {
+ *    fileLogger[level](...args); // args stays unchanged to let's continue the default behavior
+ * }
+ *
+ * // Redefine the log to add some prefix indication
+ * class Player {
+ *    connector = new Connector();
+ *    constructor() {
+ *       connector.log = this.log.bind(this,"Connector log:");
+ *    }
+ * }
+ *
+ */
+interface ILog {
+    /**
+     * Build a log
+     */
+    (...args: unknown[]): Log;
+    /**
+     * Intercept,redefine or redirect any log
+     * If you clear args you intercept the log and nothing happen more after this call.
+     * @param type log level
+     * @param args args
+     * @returns
+     */
+    on: (level: LogLevel, args: unknown[]) => void;
+    /**
+     * Change log level, default log level is {@link LogLevel.INFO},
+     * Boolean can be user to lets pass all the logs with `true` or disables all the logs with `false`.
+     * @note To debug production code without modifying it you can use a special query parameter
+     * called !cb-override-log-level to override this configuration.
+     */
+    level?: LogLevel | boolean;
+}
+/**
+ * Log instance
+ */
+declare class Log {
+    get error(): (...args: any[]) => void;
+    get warn(): (...args: any[]) => void;
+    get info(): (...args: any[]) => void;
+    get debug(): (...args: any[]) => void;
+    private _args;
+    private _done?;
+    private _log;
+    constructor(log: ILog, ...args: unknown[]);
+    private _onLog;
+    private _bind;
+}
+/**
+ * Inherits from this class to use logs
+ */
+declare class Loggable {
+    /**
+     * Start a log
+     * @param args
+     * @returns a Log object with the levels of log to call
+     */
+    log: ILog;
+}
+/**
+ * Global log
+ */
+declare const log: ILog;
+
+/**
+ * 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.
+ */
+
 /**
  * BitReader allows to read binary data bit by bit
  */
-declare class BitReader {
+declare class BitReader extends Loggable {
     private _data;
     private _size;
     private _position;
@@ -94,19 +208,69 @@ declare class BitReader {
 }
 
 /**
- * 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;
 }
 
 /**
@@ -179,99 +343,6 @@ declare namespace Connect {
   export { type Connect_Params as Params, Connect_Type as Type, Connect_buildURL as buildURL, Connect_defineMediaExt as defineMediaExt };
 }
 
-/**
- * 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.
- */
-/**
- * Log interface to deal with log everywhere:
- * - subscribe logs: listen logs to effectuate some specific job related logs
- * - intercept logs: intercept logs to change the default behavior
- * - redirect logs: redirect logs to one other logger engine
- * - redefine logs: change log text like adding a prefix
- *
- * You have 4 {@link LogType} 'error', 'warn', 'info', and 'debug', as commonly managed by browsers.
- *
- * @example
- * // Intercept and redirect all the logs to the console (default behavior)
- * import { log } from '@ceeblue/web-utils';
- * log.on(type:LogType, args:uknown[]) => {
- *    console[type](...args.splice(0)); // args is empty after this call = final interception
- * }
- *
- * // Intercept and redirect the logs from Player compoment to the console
- * player.log.on(type:LogType, args:uknown[]) => {
- *    console[type](...args.splice(0)); // args is empty after this call = final interception
- * }
- *
- * // Subscribe and redirect all the logs to a file logger
- * log.on(type:LogType, args:uknown[]) => {
- *    fileLogger[type](...args); // args stays unchanged to let's continue the default behavior
- * }
- *
- * // Redefine the log to add some prefix indication
- * class Player {
- *    connector = new Connector();
- *    constructor() {
- *       connector.log = this.log.bind(this, "Connector log:");
- *    }
- * }
- *
- */
-interface ILog {
-    /**
-     * Build a log
-     */
-    (...args: unknown[]): Log;
-    /**
-     * Intercept, redefine or redirect any log
-     * If you clear args you intercept the log and nothing happen more after this call.
-     * @param type log level
-     * @param args args
-     * @returns
-     */
-    on: (type: LogType, args: unknown[]) => void;
-}
-/**
- * Log types
- */
-declare enum LogType {
-    ERROR = "error",
-    WARN = "warn",
-    INFO = "info",
-    DEBUG = "debug"
-}
-/**
- * Log instance
- */
-declare class Log {
-    get error(): (...args: any[]) => void;
-    get warn(): (...args: any[]) => void;
-    get info(): (...args: any[]) => void;
-    get debug(): (...args: any[]) => void;
-    private _args;
-    private _done?;
-    private _onLog;
-    constructor(onLog: Function, ...args: unknown[]);
-    private _bind;
-}
-/**
- * Inherits from this class to use logs
- */
-declare class Loggable {
-    /**
-     * Start a log
-     * @param args
-     * @returns a Log object with the levels of log to call
-     */
-    log: ILog;
-}
-/**
- * Global log
- */
-declare const log: ILog;
-
 /**
  * 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.
@@ -329,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)
@@ -694,7 +769,7 @@ declare function timeOrigin(): number;
  * @param urlOrQueryOrSearch string, url, or searchParams containing query. If not set it uses `location.search` to determinate query.
  * @returns An javascript object containing each option
  */
-declare function options(urlOrQueryOrSearch?: URL | URLSearchParams | string | object | undefined): object;
+declare function options(urlOrQueryOrSearch?: URL | URLSearchParams | string | object | undefined): any;
 /**
  * Returns an easy-to-use Javascript object something iterable, such as a Map, Set, or Array
  * @param value iterable input
@@ -705,7 +780,7 @@ declare function options(urlOrQueryOrSearch?: URL | URLSearchParams | string | o
 declare function objectFrom(value: any, params: {
     withType: boolean;
     noEmptyString: boolean;
-}): object;
+}): any;
 /**
  * Returns entries from something iterable, such as a Map, Set, or Array
  * @param value iterable input
@@ -1012,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.
@@ -1020,4 +1175,4 @@ declare namespace EpochTime {
 
 declare const VERSION: string;
 
-export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EpochTime, EventEmitter, FixMap, type ILog, Log, LogType, 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 };