@ceeblue/web-utils 2.2.1 → 2.4.0

package/dist/web-utils.d.ts

@@ -130,6 +130,11 @@ type Params = {
      * iceServer to use while connecting to a WebRTC stream
      */
     iceServer?: RTCIceServer;
+    /**
+     * Optional media extension (mp4, flv, ts, rts), usefull for protocol like WebRTS which supports different container type.
+     * When not set, it's also an output parameter to indicate what is the media type selected
+     */
+    mediaExt?: string;
     /**
      * Optional query to add into the generated url of connection
      */
@@ -148,6 +153,14 @@ declare enum Type {
 /**
  * Some connection utility functions
  */
+/**
+ * Defines the {@link Params.mediaExt} based on the type of parameters and its endpoint.
+ * This method always assigns a value to params.mediaExt, defaulting to an empty string if indeterminable,
+ * allowing detection of whether the function has been applied to the parameters.
+ * @param type The type of parameters to define.
+ * @param params The parameters for which the media extension is to be defined
+ */
+declare function defineMediaExt(type: Type, params: Params): void;
 /**
  * Build an URL from {@link Type | type} and {@link Params | params}
  * @param type Type of the connection wanted
@@ -161,15 +174,77 @@ type Connect_Params = Params;
 type Connect_Type = Type;
 declare const Connect_Type: typeof Type;
 declare const Connect_buildURL: typeof buildURL;
+declare const Connect_defineMediaExt: typeof defineMediaExt;
 declare namespace Connect {
-  export { type Connect_Params as Params, Connect_Type as Type, Connect_buildURL as buildURL };
+  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 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.
@@ -211,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
@@ -266,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.
@@ -668,27 +720,58 @@ declare function equal(a: any, b: any): boolean;
  */
 declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 /**
- * Extension parser
+ * Get Extension part from path
  * @param path path to parse
  * @returns the extension
  */
-declare function parseExtension(path: string): string;
+declare function getExtension(path: string): string;
+/**
+ * Get File part from path
+ * @param path path to parse
+ * @returns the file name
+ */
+declare function getFile(path: string): string;
+/**
+ * String Trim function with customizable chars
+ * @param value string to trim
+ * @param chars chars to use to trim
+ * @returns string trimmed
+ */
+declare function trim(value: string, chars?: string): string;
+/**
+ * String Trim Start function with customizable chars
+ * @param value string to trim start
+ * @param chars chars to use to trim start
+ * @returns string trimmed
+ */
+declare function trimStart(value: string, chars?: string): string;
+/**
+ * String Trim End function with customizable chars
+ * @param value string to trim end
+ * @param chars chars to use to trim end
+ * @returns string trimmed
+ */
+declare function trimEnd(value: string, chars?: string): string;
 
 declare const Util_EMPTY_FUNCTION: typeof EMPTY_FUNCTION;
 declare const Util_equal: typeof equal;
 declare const Util_fetch: typeof fetch;
+declare const Util_getExtension: typeof getExtension;
+declare const Util_getFile: typeof getFile;
 declare const Util_objectEntries: typeof objectEntries;
 declare const Util_objectFrom: typeof objectFrom;
 declare const Util_options: typeof options;
-declare const Util_parseExtension: typeof parseExtension;
 declare const Util_safePromise: typeof safePromise;
 declare const Util_sleep: typeof sleep;
 declare const Util_stringify: typeof stringify;
 declare const Util_time: typeof time;
 declare const Util_timeOrigin: typeof timeOrigin;
 declare const Util_toBin: typeof toBin;
+declare const Util_trim: typeof trim;
+declare const Util_trimEnd: typeof trimEnd;
+declare const Util_trimStart: typeof trimStart;
 declare namespace Util {
-  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_equal as equal, Util_fetch as fetch, Util_objectEntries as objectEntries, Util_objectFrom as objectFrom, Util_options as options, Util_parseExtension as parseExtension, Util_safePromise as safePromise, Util_sleep as sleep, Util_stringify as stringify, Util_time as time, Util_timeOrigin as timeOrigin, Util_toBin as toBin };
+  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_equal as equal, Util_fetch as fetch, Util_getExtension as getExtension, Util_getFile as getFile, Util_objectEntries as objectEntries, Util_objectFrom as objectFrom, Util_options as options, Util_safePromise as safePromise, Util_sleep as sleep, Util_stringify as stringify, Util_time as time, Util_timeOrigin as timeOrigin, Util_toBin as toBin, Util_trim as trim, Util_trimEnd as trimEnd, Util_trimStart as trimStart };
 }
 
 /**
@@ -697,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}
@@ -737,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
      */
@@ -809,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;
 }
 
@@ -822,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

@@ -642,15 +642,76 @@ function fetch(input, init) {
     });
 }
 /**
- * Extension parser
+ * Get Extension part from path
  * @param path path to parse
  * @returns the extension
  */
-function parseExtension(path) {
+function getExtension(path) {
     const dot = path.lastIndexOf('.');
     const ext = dot >= 0 && dot > path.lastIndexOf('/') ? path.substring(dot) : '';
     return ext;
-}var Util=/*#__PURE__*/Object.freeze({__proto__:null,EMPTY_FUNCTION:EMPTY_FUNCTION,equal:equal,fetch:fetch,objectEntries:objectEntries,objectFrom:objectFrom,options:options,parseExtension:parseExtension,safePromise:safePromise,sleep:sleep,stringify:stringify,time:time,timeOrigin:timeOrigin,toBin:toBin});/**
+}
+/**
+ * Get File part from path
+ * @param path path to parse
+ * @returns the file name
+ */
+function getFile(path) {
+    return path.substring(path.lastIndexOf('/') + 1);
+}
+function codesFromString(value) {
+    const codes = [];
+    for (let i = 0; i < value.length; ++i) {
+        codes.push(value.charCodeAt(i));
+    }
+    return codes;
+}
+/**
+ * String Trim function with customizable chars
+ * @param value string to trim
+ * @param chars chars to use to trim
+ * @returns string trimmed
+ */
+function trim(value, chars = ' ') {
+    const codes = codesFromString(chars);
+    let start = 0;
+    while (start < value.length && codes.includes(value.charCodeAt(start))) {
+        ++start;
+    }
+    let end = value.length;
+    while (end > 0 && codes.includes(value.charCodeAt(end - 1))) {
+        --end;
+    }
+    return value.substring(start, end);
+}
+/**
+ * String Trim Start function with customizable chars
+ * @param value string to trim start
+ * @param chars chars to use to trim start
+ * @returns string trimmed
+ */
+function trimStart(value, chars = ' ') {
+    const codes = codesFromString(chars);
+    let i = 0;
+    while (i < value.length && codes.includes(value.charCodeAt(i))) {
+        ++i;
+    }
+    return value.substring(i);
+}
+/**
+ * String Trim End function with customizable chars
+ * @param value string to trim end
+ * @param chars chars to use to trim end
+ * @returns string trimmed
+ */
+function trimEnd(value, chars = ' ') {
+    const codes = codesFromString(chars);
+    let i = value.length;
+    while (i > 0 && codes.includes(value.charCodeAt(i - 1))) {
+        --i;
+    }
+    return value.substring(0, i);
+}var Util=/*#__PURE__*/Object.freeze({__proto__:null,EMPTY_FUNCTION:EMPTY_FUNCTION,equal:equal,fetch:fetch,getExtension:getExtension,getFile:getFile,objectEntries:objectEntries,objectFrom:objectFrom,options:options,safePromise:safePromise,sleep:sleep,stringify:stringify,time:time,timeOrigin:timeOrigin,toBin:toBin,trim:trim,trimEnd:trimEnd,trimStart:trimStart});/**
  * 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.
@@ -831,6 +892,56 @@ var Type;
 /**
  * Some connection utility functions
  */
+/**
+ * Defines the {@link Params.mediaExt} based on the type of parameters and its endpoint.
+ * This method always assigns a value to params.mediaExt, defaulting to an empty string if indeterminable,
+ * allowing detection of whether the function has been applied to the parameters.
+ * @param type The type of parameters to define.
+ * @param params The parameters for which the media extension is to be defined
+ */
+function defineMediaExt(type, params) {
+    // Fix mediaExt in removing the possible '.' prefix
+    if (params.mediaExt) {
+        params.mediaExt = trimStart(params.mediaExt, '.');
+    }
+    // Compute appropriate mediaExt out parameter
+    switch (type) {
+        case Type.HESP:
+            params.mediaExt = 'mp4';
+            break;
+        case Type.WEBRTC:
+            params.mediaExt = 'rtp';
+            break;
+        case Type.WRTS: {
+            try {
+                const url = new URL(params.endPoint);
+                const ext = getExtension(getFile(url.pathname));
+                // set extension just if not json, json means a manifest file endPoint
+                if (ext && ext !== 'json') {
+                    params.mediaExt = ext;
+                }
+            }
+            catch (_) {
+                // not an URL, it's only a host => keep mediaExt unchanged to build the URL
+            }
+            if (!params.mediaExt) {
+                // set to its default rts value => always set for WRTS!
+                params.mediaExt = 'rts';
+            }
+            break;
+        }
+        case Type.META:
+            params.mediaExt = 'js';
+            break;
+        case Type.DATA:
+            params.mediaExt = 'json';
+            break;
+        default:
+            params.mediaExt = ''; // set always a value to know that the parameters have been fixed
+            console.warn('Unknown params type ' + type);
+            break;
+    }
+}
 /**
  * Build an URL from {@link Type | type} and {@link Params | params}
  * @param type Type of the connection wanted
@@ -839,10 +950,8 @@ var Type;
  * @returns The URL of connection
  */
 function buildURL(type, params, protocol = 'wss') {
+    defineMediaExt(type, params);
     const url = new URL(NetAddress.fixProtocol(protocol, params.endPoint));
-    // Remove possible extension of streamName put sometimes to decide format when multiple choices are possible like with WRTS
-    const ext = parseExtension(params.streamName);
-    params.streamName = params.streamName.substring(0, params.streamName.length - ext.length);
     if (url.pathname.length <= 1) {
         // build ceeblue path!
         switch (type) {
@@ -853,7 +962,7 @@ function buildURL(type, params, protocol = 'wss') {
                 url.pathname = '/webrtc/' + params.streamName;
                 break;
             case Type.WRTS:
-                url.pathname = '/wrts/' + params.streamName + ext;
+                url.pathname = '/wrts/' + params.streamName;
                 break;
             case Type.META:
                 url.pathname = '/json_' + params.streamName + '.js';
@@ -873,7 +982,88 @@ function buildURL(type, params, protocol = 'wss') {
         url.searchParams.set(key, params.query[key]);
     }
     return url;
-}var Connect=/*#__PURE__*/Object.freeze({__proto__:null,get Type(){return Type},buildURL:buildURL});/**
+}var Connect=/*#__PURE__*/Object.freeze({__proto__:null,get Type(){return Type},buildURL:buildURL,defineMediaExt: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.
+ */
+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.
@@ -919,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);
@@ -1524,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
      */
@@ -1627,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.
@@ -1683,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) {
@@ -1694,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) {
@@ -1711,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.2.1';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