@ceeblue/web-utils 2.3.0 → 2.4.0

package/dist/web-utils.d.ts

@@ -184,6 +184,67 @@ declare namespace Connect {
  * 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 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;
+}
+/**
+ * ILog interface used by log methods
+ */
+interface ILog {
+    /**
+     * Build a log
+     */
+    (...args: unknown[]): Log;
+    /**
+     * Intercept or redefine any log
+     * @param type log level
+     * @param args args
+     * @returns
+     */
+    on: (type: LogType, args: unknown[]) => void;
+}
+/**
+ * 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.
+ */
+
 /**
  * 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.
@@ -225,7 +286,7 @@ declare namespace Connect {
  * controller.abort();
  * logger.test(); // displays nothing
  */
-declare class EventEmitter {
+declare class EventEmitter extends Loggable {
     private _events;
     /**
      * Build our EventEmitter, usually call from children class
@@ -280,29 +341,6 @@ declare class FixMap<KeyType, ValueType> {
     forEach(callbackfn: (value: ValueType, key: KeyType, map: Map<KeyType, ValueType>) => void, thisArg?: any): void;
 }
 
-/**
- * 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.
- */
-/**
- * Implement this interface to throw log and error
- */
-interface ILog {
-    /**
-     * Call to distribute log message, default implementation is usually `onLog(log:string) { console.log(log); }`
-     * @param log log string message
-     * @event
-     */
-    onLog(log: string): void;
-    /**
-     * Call to distribute error message, default implementation is usually `onError(error:string) { console.error(error); }`
-     * @param error error string message
-     * @event
-     */
-    onError(error: string): void;
-}
-
 /**
  * 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.
@@ -742,6 +780,33 @@ declare namespace Util {
  * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
  */
 
+type WebSocketReliableError = 
+/**
+ * Represents a WebSocket disconnection error.
+ */
+{
+    type: 'WebSocketReliableError';
+    name: 'Socket disconnection';
+    url: string;
+    reason: string;
+}
+/**
+ * Represents a server shutdown error.
+ */
+ | {
+    type: 'WebSocketReliableError';
+    name: 'Server shutdown';
+    url: string;
+}
+/**
+ * Represents a connection failure error.
+ */
+ | {
+    type: 'WebSocketReliableError';
+    name: 'Connection failed';
+    url: string;
+    reason: string;
+};
 /**
  * The WebSocketReliable class extends WebSocket to bring up the following improvements:
  * - Fix all possible unintentional closing ways to get always a related error message, {@link onClose | onClose(error?) event}
@@ -782,7 +847,7 @@ declare class WebSocketReliable extends EventEmitter {
      * @event `close` fired on websocket close
      * @param error error description on an improper closure
      */
-    onClose(error?: string): void;
+    onClose(error?: WebSocketReliableError): void;
     /**
      * binaryType, fix binary type to arrayBuffer
      */
@@ -854,8 +919,9 @@ declare class WebSocketReliable extends EventEmitter {
     /**
      * Close websocket
      * @param error the error reason if is not a proper close
+     * @param detail detail of the error
      */
-    close(error?: string): void;
+    close(error?: WebSocketReliableError): void;
     private _send;
 }
 
@@ -867,4 +933,4 @@ declare class WebSocketReliable extends EventEmitter {
 
 declare const VERSION: string;
 
-export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EventEmitter, FixMap, type ILog, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable };
+export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EventEmitter, FixMap, type ILog, Log, LogType, Loggable, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable, type WebSocketReliableError, log };

package/dist/web-utils.js

@@ -987,6 +987,87 @@ 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.
@@ -1028,11 +1109,12 @@ function buildURL(type, params, protocol = 'wss') {
  * controller.abort();
  * logger.test(); // displays nothing
  */
-class EventEmitter {
+class EventEmitter extends Loggable {
     /**
      * Build our EventEmitter, usually call from children class
      */
     constructor() {
+        super();
         this._events = new Map();
         // Fill events with events as defined!
         let proto = Object.getPrototypeOf(this);
@@ -1633,11 +1715,7 @@ class WebSocketReliable extends EventEmitter {
      * @event `close` fired on websocket close
      * @param error error description on an improper closure
      */
-    onClose(error) {
-        if (error) {
-            console.error(error);
-        }
-    }
+    onClose(error) { }
     /**
      * binaryType, fix binary type to arrayBuffer
      */
@@ -1736,18 +1814,30 @@ class WebSocketReliable extends EventEmitter {
         // Add details and fix close ways
         ws.onclose = (e) => {
             if (!this._opened) {
-                // close during connection
-                // the caller can differentiate this case of one server shutdown by looking if onOpen was op
-                this.close(url.toString() + ' connection failed, ' + String(e.reason || e.code));
+                // close during connection!
+                this.close({
+                    type: 'WebSocketReliableError',
+                    name: 'Connection failed',
+                    url: url.toString(),
+                    reason: String(e.reason || e.code)
+                });
             }
             else if (e.code === 1000 || e.code === 1005) {
-                // normal disconnection from server, no error to indicate that a reconnection is possible!
-                // the caller can differentiate this case of one explicit websocket.close() call in the encpasulating class
-                this.close(url.toString() + ' shutdown');
+                // normal disconnection from server
+                this.close({
+                    type: 'WebSocketReliableError',
+                    name: 'Server shutdown',
+                    url: url.toString()
+                });
             }
             else {
                 // abnormal disconnection from server
-                this.close(url.toString() + ' disconnection, ' + String(e.reason || e.code));
+                this.close({
+                    type: 'WebSocketReliableError',
+                    name: 'Socket disconnection',
+                    url: url.toString(),
+                    reason: String(e.reason || e.code)
+                });
             }
         };
         // Wrap send method to queue messages until connection is established.
@@ -1792,6 +1882,7 @@ class WebSocketReliable extends EventEmitter {
     /**
      * Close websocket
      * @param error the error reason if is not a proper close
+     * @param detail detail of the error
      */
     close(error) {
         if (!this._ws || this._closed) {
@@ -1803,9 +1894,11 @@ class WebSocketReliable extends EventEmitter {
         // release resources!
         this._queueing.length = 0;
         this._queueingBytes = 0;
+        if (error) {
+            this.log(error).error();
+        }
         this.onClose(error);
         // Reset _opened in last to allow to differenciate in onClose an error while connecting OR while connected
-        // Is welcome to attempt a reconnection when no error OR when error on connection!
         this._opened = false;
     }
     _send(message) {
@@ -1820,4 +1913,4 @@ class WebSocketReliable extends EventEmitter {
  * 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.3.0';export{BinaryReader,BinaryWriter,BitReader,ByteRate,Connect,EventEmitter,FixMap,NetAddress,Numbers,Queue,SDP,Util,VERSION,WebSocketReliable};//# sourceMappingURL=web-utils.js.map
+const VERSION = '2.4.0';export{BinaryReader,BinaryWriter,BitReader,ByteRate,Connect,EventEmitter,FixMap,Log,LogType,Loggable,NetAddress,Numbers,Queue,SDP,Util,VERSION,WebSocketReliable,log};//# sourceMappingURL=web-utils.js.map