@ceeblue/web-utils 2.6.1 → 3.0.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;
@@ -179,99 +293,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.
@@ -694,7 +715,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 +726,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
@@ -1020,4 +1041,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, Util, VERSION, WebSocketReliable, type WebSocketReliableError, log };

package/dist/web-utils.js

@@ -275,87 +275,6 @@ class BinaryWriter {
         this._view = undefined; // release view
         return this;
     }
-}/**
- * 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
- */
-class BitReader {
-    constructor(data) {
-        if ('buffer' in data) {
-            this._data = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-        }
-        else {
-            this._data = new Uint8Array(data);
-        }
-        this._size = this._data.byteLength;
-        this._position = 0;
-        this._bit = 0;
-    }
-    data() {
-        return this._data;
-    }
-    size() {
-        return this._size;
-    }
-    available() {
-        return (this._size - this._position) * 8 - this._bit;
-    }
-    next(count = 1) {
-        let gotten = 0;
-        while (this._position !== this._size && count--) {
-            ++gotten;
-            if (++this._bit === 8) {
-                this._bit = 0;
-                ++this._position;
-            }
-        }
-        return gotten;
-    }
-    read(count = 1) {
-        let result = 0;
-        while (this._position !== this._size && count--) {
-            result <<= 1;
-            if (this._data[this._position] & (0x80 >> this._bit++)) {
-                result |= 1;
-            }
-            if (this._bit === 8) {
-                this._bit = 0;
-                ++this._position;
-            }
-        }
-        return result;
-    }
-    read8() {
-        return this.read(8);
-    }
-    read16() {
-        return this.read(16);
-    }
-    read24() {
-        return this.read(24);
-    }
-    read32() {
-        return this.read(32);
-    }
-    readExpGolomb() {
-        let i = 0;
-        while (!this.read()) {
-            if (!this.available()) {
-                return 0;
-            }
-            ++i;
-        }
-        const result = this.read(i);
-        if (i > 15) {
-            console.warn('Exponential-Golomb code exceeding unsigned 16 bits');
-            return 0;
-        }
-        return result + (1 << i) - 1;
-    }
 }/******************************************************************************
 Copyright (c) Microsoft Corporation.
 
@@ -563,12 +482,15 @@ function stringify(obj, params = {}) {
         }
         return (res += space + ']');
     }
-    let res = '';
+    let res = '{';
     for (const name in obj) {
-        res += (res ? ',' : '{') + space + name + ':';
-        res += stringify(obj[name], Object.assign(Object.assign({}, params), { recursion: params.recursion - 1 }));
+        if (res.length > 1) {
+            res += ',';
+        }
+        res += space + name + ':';
+        res += stringify(obj[name], Object.assign(Object.assign({}, params), { recursion: params.recursion - 1 })) + space;
     }
-    return (res += space + '}');
+    return (res += '}');
 }
 /**
  * Encode a string to a binary representation
@@ -727,6 +649,197 @@ function trimEnd(value, chars = ' ') {
  * 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
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "error";
+    LogLevel["WARN"] = "warn";
+    LogLevel["INFO"] = "info";
+    LogLevel["DEBUG"] = "debug";
+})(LogLevel || (LogLevel = {}));
+// check coder issuer: everytime we don't forget to use the built Log
+let _logging = 0;
+setInterval(() => {
+    console.assert(_logging === 0, _logging.toFixed(), 'calls to log was useless');
+}, 10000);
+// !cb-override-log-level
+const _overrideLogLevel = options()['!cb-override-log-level'];
+const _charLevels = new Array(128);
+_charLevels[101] = _charLevels[69] = 1; // error
+_charLevels[119] = _charLevels[87] = 2; // warn
+_charLevels[105] = _charLevels[73] = 3; // info
+_charLevels[100] = _charLevels[68] = 4; // debug
+/**
+ * Log instance
+ */
+class Log {
+    get error() {
+        return this._bind(LogLevel.ERROR);
+    }
+    get warn() {
+        return this._bind(LogLevel.WARN);
+    }
+    get info() {
+        return this._bind(LogLevel.INFO);
+    }
+    get debug() {
+        return this._bind(LogLevel.DEBUG);
+    }
+    constructor(log, ...args) {
+        if (!args.length) {
+            // cannot have 0 args to be called correctly!
+            args.push(undefined);
+        }
+        this._args = args;
+        this._log = log;
+        ++_logging;
+    }
+    _onLog(localLog, level) {
+        var _a, _b;
+        // we take like log-level by priority order:
+        // 1- the overrideLogLevel
+        // 2- the localLog.level
+        // 3- the global log.level
+        // 4- LogLevel.INFO
+        const logLevel = (_b = (_a = _overrideLogLevel !== null && _overrideLogLevel !== void 0 ? _overrideLogLevel : localLog.level) !== null && _a !== void 0 ? _a : log.level) !== null && _b !== void 0 ? _b : LogLevel.INFO;
+        if (logLevel === false) {
+            // explicit null, no log at all!
+            return false;
+        }
+        if (logLevel !== true && _charLevels[level.charCodeAt(0)] > _charLevels[logLevel.charCodeAt(0)]) {
+            return false;
+        }
+        if (localLog.on) {
+            localLog.on(level, this._args);
+        }
+        return this._args.length ? true : false;
+    }
+    _bind(level) {
+        if (!this._done) {
+            this._done = true;
+            --_logging;
+        }
+        // call the global onLog in first (global filter)
+        if (!this._onLog(log, level)) {
+            return EMPTY_FUNCTION;
+        }
+        // call the local onLog (local filter)
+        if (this._log !== log && !this._onLog(this._log, level)) {
+            return EMPTY_FUNCTION;
+        }
+        // if not intercepted display the log
+        return console[level].bind(console, ...this._args);
+    }
+}
+/**
+ * Inherits from this class to use logs
+ */
+class Loggable {
+    constructor() {
+        /**
+         * Start a log
+         * @param args
+         * @returns a Log object with the levels of log to call
+         */
+        this.log = ((...args) => {
+            return new Log(this.log, ...args);
+        });
+    }
+}
+/**
+ * Global log
+ */
+const log = ((...args) => {
+    return new Log(log, ...args);
+});/**
+ * 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
+ */
+class BitReader extends Loggable {
+    constructor(data) {
+        super();
+        if ('buffer' in data) {
+            this._data = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        }
+        else {
+            this._data = new Uint8Array(data);
+        }
+        this._size = this._data.byteLength;
+        this._position = 0;
+        this._bit = 0;
+    }
+    data() {
+        return this._data;
+    }
+    size() {
+        return this._size;
+    }
+    available() {
+        return (this._size - this._position) * 8 - this._bit;
+    }
+    next(count = 1) {
+        let gotten = 0;
+        while (this._position !== this._size && count--) {
+            ++gotten;
+            if (++this._bit === 8) {
+                this._bit = 0;
+                ++this._position;
+            }
+        }
+        return gotten;
+    }
+    read(count = 1) {
+        let result = 0;
+        while (this._position !== this._size && count--) {
+            result <<= 1;
+            if (this._data[this._position] & (0x80 >> this._bit++)) {
+                result |= 1;
+            }
+            if (this._bit === 8) {
+                this._bit = 0;
+                ++this._position;
+            }
+        }
+        return result;
+    }
+    read8() {
+        return this.read(8);
+    }
+    read16() {
+        return this.read(16);
+    }
+    read24() {
+        return this.read(24);
+    }
+    read32() {
+        return this.read(32);
+    }
+    readExpGolomb() {
+        let i = 0;
+        while (!this.read()) {
+            if (!this.available()) {
+                return 0;
+            }
+            ++i;
+        }
+        const result = this.read(i);
+        if (i > 15) {
+            this.log('Exponential-Golomb code exceeding unsigned 16 bits').warn();
+            return 0;
+        }
+        return result + (1 << i) - 1;
+    }
+}/**
+ * 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.
+ */
 /**
  * Compute ByteRate every delta time
  */
@@ -996,87 +1109,6 @@ function buildURL(type, params, protocol = 'wss') {
  * 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.
  */
-let _logging = 0;
-setInterval(() => {
-    console.assert(_logging === 0, _logging.toFixed(), 'calls to log was useless');
-}, 10000);
-/**
- * Log types
- */
-var LogType;
-(function (LogType) {
-    LogType["ERROR"] = "error";
-    LogType["WARN"] = "warn";
-    LogType["INFO"] = "info";
-    LogType["DEBUG"] = "debug";
-})(LogType || (LogType = {}));
-/**
- * Log instance
- */
-class Log {
-    get error() {
-        return this._bind(LogType.ERROR);
-    }
-    get warn() {
-        return this._bind(LogType.WARN);
-    }
-    get info() {
-        return this._bind(LogType.INFO);
-    }
-    get debug() {
-        return this._bind(LogType.DEBUG);
-    }
-    constructor(onLog, ...args) {
-        if (!args.length) {
-            // cannot have 0 args to be called correctly!
-            args.push(undefined);
-        }
-        this._args = args;
-        this._onLog = onLog;
-        ++_logging;
-    }
-    _bind(type) {
-        if (!this._done) {
-            this._done = true;
-            --_logging;
-        }
-        // call the local onLog
-        if (this._onLog) {
-            this._onLog(type, this._args);
-        }
-        // call the global onLog
-        if (this._args.length && log.on) {
-            log.on(type, this._args);
-        }
-        // if not intercepted display the log
-        return this._args.length ? console[type].bind(console, ...this._args) : EMPTY_FUNCTION;
-    }
-}
-/**
- * Inherits from this class to use logs
- */
-class Loggable {
-    constructor() {
-        /**
-         * Start a log
-         * @param args
-         * @returns a Log object with the levels of log to call
-         */
-        this.log = ((...args) => {
-            return new Log(this.log.on, ...args);
-        });
-    }
-}
-/**
- * Global log
- */
-const log = ((...args) => {
-    return new Log(() => { }, ...args);
-});/**
- * 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.
- */
 /**
  * A advanced EventEmitter which allows to declare event as natural function in the inheriting children class,
  * function must start by `on` prefix to be recognized as an event.
@@ -2025,4 +2057,4 @@ 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 = '2.6.1';export{BinaryReader,BinaryWriter,BitReader,ByteRate,Connect,EpochTime,EventEmitter,FixMap,Log,LogType,Loggable,NetAddress,Numbers,Queue,SDP,Util,VERSION,WebSocketReliable,log};//# sourceMappingURL=web-utils.js.map
+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