@ceeblue/web-utils 5.0.0 → 7.0.0

package/.codecov.yml

@@ -0,0 +1,21 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 90%
+        threshold: 10%
+    patch:
+      default:
+        target: 90%
+        threshold: 10%
+
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  require_changes: true
+
+ignore:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/__tests__/**"
+  - "**/__mocks__/**"

package/dist/web-utils.d.ts

@@ -273,6 +273,41 @@ declare class ByteRate {
     private updateSamples;
 }
 
+/**
+ * Parameters of a key system for encrypted streams (DRM)
+ *
+ * If the key system is a string, it's the URL of the license server.
+ *
+ * If the key system is an object, it's a key system configuration with more parameters.
+ */
+type KeySystem = string | {
+    /**
+     * The license server URL
+     */
+    licenseUrl: string;
+    /**
+     * The certificate URL if needed (for FairPlay)
+     *
+     * Or directly the certificate
+     */
+    certificate?: string | Uint8Array;
+    /**
+     * The additional HTTP headers to send to the license server
+     */
+    headers?: Record<string, string>;
+    /**
+     * Audio robustness level
+     *
+     * A list of robustness levels, prioritized by the order of the array.
+     */
+    audioRobustness?: string[];
+    /**
+     * Video robustness level
+     *
+     * A list of robustness levels, prioritized by the order of the array.
+     */
+    videoRobustness?: string[];
+};
 /**
  * Parameters of connections
  */
@@ -287,7 +322,7 @@ type Params = {
      * If `endPoint` is a complete URL and `streamName` is not provided, {@link buildURL} will set this parameter automatically
      * using the second part of the URL's path (the first part being the protocol name), or the first path if no other part exists.
      */
-    streamName: string;
+    streamName?: string;
     /**
      * Optional access token to use to join a private stream
      */
@@ -296,6 +331,11 @@ type Params = {
      * iceServer to use while connecting to a WebRTC stream
      */
     iceServer?: RTCIceServer;
+    /**
+     * Map of keys to content protection settings for encrypted streams
+     * The key can be "com.apple.fps" for example for FairPlay
+     */
+    contentProtection?: Record<string, KeySystem>;
     /**
      * 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 for {@link defineMediaExt} to indicate what is the media type selected
@@ -337,13 +377,14 @@ declare function defineMediaExt(type: Type, params: Params): void;
  */
 declare function buildURL(type: Type, params: Params, protocol?: string): URL;
 
+type Connect_KeySystem = KeySystem;
 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, Connect_defineMediaExt as defineMediaExt };
+  export { type Connect_KeySystem as KeySystem, type Connect_Params as Params, Connect_Type as Type, Connect_buildURL as buildURL, Connect_defineMediaExt as defineMediaExt };
 }
 
 /**
@@ -776,13 +817,22 @@ declare const SDP: {
  */
 declare const EMPTY_FUNCTION: () => void;
 /**
- * Efficient and high resolution timestamp in milliseconds elapsed since {@link Util.timeOrigin}
+ * Returns an efficient timestamp in milliseconds elapsed since {@link performance.timeOrigin},
+ * representing the start of the current JavaScript execution context.
+ *
+ * Note: Each Web Worker runs in a separate JS context, so timestamps
+ * are not directly comparable between different workers. Use {@link unixTime}
+ * for comparable timestamps across different Web Workers.
  */
 declare function time(): number;
 /**
- * Time origin represents the time when the application has started
+ * Returns an efficient Unix timestamp in milliseconds.
+ *
+ * Unix timestamps are universally comparable across different JavaScript
+ * contexts (e.g., Web Workers), as they reference the number of milliseconds
+ * elapsed since January 1, 1970 (UNIX epoch).
  */
-declare function timeOrigin(): number;
+declare function unixTime(): number;
 /**
  * Parse query and returns it in an easy-to-use Javascript object form
  * @param urlOrQueryOrSearch string, url, or searchParams containing query. If not set it uses `location.search` to determinate query.
@@ -841,14 +891,24 @@ declare function safePromise<T>(timeout: number, promise: Promise<T>): Promise<u
  */
 declare function sleep(ms: number): Promise<unknown>;
 /**
- * Test equality between two value whatever their type, array included
+ * Test equality between two value whatever their type, object and array included
+ */
+declare function equal(a: any, b: any, seen?: WeakMap<WeakKey, any>): boolean;
+/**
+ * Fetch help method adding an explicit error property when Response is NOK, with the more accurate textual error inside
  */
-declare function equal(a: any, b: any): boolean;
+declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response & {
+    error?: string;
+}>;
 /**
- * fetch help method with few usefull fix:
- * - throw an string exception if response code is not 200 with the text of the response or uses statusText
+ * Fetch help method adding an explicit error property when Response is NOK, with the more accurate textual error inside
+ * Also measure the rtt of fetching and returns it in the property Response.rtt (guaranteed to be ≥ 1),
+ * supports subtracting server processing time using either the Response-Delay or CMSD-rd header when available
  */
-declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+declare function fetchWithRTT(input: RequestInfo | URL, init?: RequestInit): Promise<Response & {
+    rtt: number;
+    error?: string;
+}>;
 /**
  * Get Extension part from path
  * @param path path to parse
@@ -892,6 +952,7 @@ 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_fetchWithRTT: typeof fetchWithRTT;
 declare const Util_getBaseFile: typeof getBaseFile;
 declare const Util_getExtension: typeof getExtension;
 declare const Util_getFile: typeof getFile;
@@ -902,13 +963,13 @@ 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 const Util_unixTime: typeof unixTime;
 declare namespace Util {
-  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_equal as equal, Util_fetch as fetch, Util_getBaseFile as getBaseFile, Util_getExtension as getExtension, Util_getFile as getFile, Util_iterableEntries as iterableEntries, 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 };
+  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_equal as equal, Util_fetch as fetch, Util_fetchWithRTT as fetchWithRTT, Util_getBaseFile as getBaseFile, Util_getExtension as getExtension, Util_getFile as getFile, Util_iterableEntries as iterableEntries, 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_toBin as toBin, Util_trim as trim, Util_trimEnd as trimEnd, Util_trimStart as trimStart, Util_unixTime as unixTime };
 }
 
 /**
@@ -1183,6 +1244,7 @@ declare class UIMetrics {
     private _legendFontSize;
     private _stepSize;
     private _ranges;
+    private _mouseX?;
     constructor(ui: HTMLElement);
     /**
      * Reset metrics stats, essentially rescaling the metrics

package/dist/web-utils.js

@@ -164,16 +164,25 @@ const _perf = performance; // to increase x10 now performance!
  */
 const EMPTY_FUNCTION = () => { };
 /**
- * Efficient and high resolution timestamp in milliseconds elapsed since {@link Util.timeOrigin}
+ * Returns an efficient timestamp in milliseconds elapsed since {@link performance.timeOrigin},
+ * representing the start of the current JavaScript execution context.
+ *
+ * Note: Each Web Worker runs in a separate JS context, so timestamps
+ * are not directly comparable between different workers. Use {@link unixTime}
+ * for comparable timestamps across different Web Workers.
  */
 function time() {
     return Math.floor(_perf.now());
 }
 /**
- * Time origin represents the time when the application has started
+ * Returns an efficient Unix timestamp in milliseconds.
+ *
+ * Unix timestamps are universally comparable across different JavaScript
+ * contexts (e.g., Web Workers), as they reference the number of milliseconds
+ * elapsed since January 1, 1970 (UNIX epoch).
  */
-function timeOrigin() {
-    return Math.floor(_perf.now() + _perf.timeOrigin);
+function unixTime() {
+    return Math.floor(_perf.timeOrigin + _perf.now());
 }
 /**
  * Parse query and returns it in an easy-to-use Javascript object form
@@ -362,52 +371,136 @@ function safePromise(timeout, promise) {
  * Wait in milliseconds, requires a call with await keyword!
  */
 function sleep(ms) {
-    return new Promise(resolve => {
-        setTimeout(resolve, ms);
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise(resolve => {
+            setTimeout(resolve, ms);
+        });
     });
 }
 /**
- * Test equality between two value whatever their type, array included
+ * Test equality between two value whatever their type, object and array included
  */
-function equal(a, b) {
-    if (Object(a) !== a) {
-        if (Object(b) === b) {
-            return false;
-        }
-        // both primitive (null and undefined included)
-        return a === b;
+function equal(a, b, seen = new WeakMap()) {
+    // 1. Check primitve identiy or NaN
+    if (a === b) {
+        return true;
     }
-    // complexe object
-    if (a[Symbol.iterator]) {
-        if (!b[Symbol.iterator]) {
-            return false;
+    if (Number.isNaN(a) && Number.isNaN(b)) {
+        return true;
+    }
+    // 2. Check the both are complexe object
+    if (Object(a) !== a || Object(b) !== b) {
+        return false;
+    }
+    // 3. Catch circular reference
+    if (seen.has(a)) {
+        return seen.get(a) === b;
+    }
+    seen.set(a, b);
+    // 4. Check « toStringTag » (Date, RegExp, Map, Set…)
+    const tagA = Object.prototype.toString.call(a);
+    if (tagA !== Object.prototype.toString.call(b)) {
+        return false;
+    }
+    // 5. Special Case
+    switch (tagA) {
+        case '[object Date]':
+            return a.getTime() === b.getTime();
+        case '[object RegExp]':
+            return a.source === b.source && a.flags === b.flags;
+        case '[object Set]':
+        case '[object Map]': {
+            if (a.size !== b.size) {
+                return false;
+            }
+            const aKeys = a.keys();
+            const bKeys = a.keys();
+            const aValues = a.values();
+            const bValues = b.values();
+            let aKey;
+            while (!(aKey = aKeys.next()).done) {
+                if (!equal(aKey.value, bKeys.next().value)) {
+                    return false;
+                }
+                const aValue = aValues.next().value;
+                const bValue = bValues.next().value;
+                if (aValue !== aKey && !equal(aValue, bValue)) {
+                    return false;
+                }
+            }
+            return true;
         }
-        if (a.length !== b.length) {
+    }
+    // 6. Arrays
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length) {
             return false;
         }
-        for (let i = 0; i !== a.length; ++i) {
-            if (a[i] !== b[i]) {
+        for (let i = 0; i < a.length; i++) {
+            if (!equal(a[i], b[i], seen)) {
                 return false;
             }
         }
         return true;
     }
-    return a === b;
+    // 7. Generic object : keys + symbols
+    const keysA = [...Object.keys(a), ...Object.getOwnPropertySymbols(a)];
+    if (keysA.length !== Object.keys(b).length + Object.getOwnPropertySymbols(b).length) {
+        return false;
+    }
+    for (const key of keysA) {
+        if (!equal(a[key], b[key], seen)) {
+            return false;
+        }
+    }
+    return true;
 }
 /**
- * fetch help method with few usefull fix:
- * - throw an string exception if response code is not 200 with the text of the response or uses statusText
+ * Fetch help method adding an explicit error property when Response is NOK, with the more accurate textual error inside
  */
 function fetch(input, init) {
     return __awaiter(this, void 0, void 0, function* () {
-        const response = yield self.fetch(input, init);
-        if (response.status >= 300) {
-            let error;
+        const response = (yield self.fetch(input, init));
+        if (!response.ok) {
             if (response.body) {
-                error = yield response.text();
+                response.error = yield response.text();
+            }
+            if (!response.error) {
+                response.error = response.statusText || response.status.toString() || 'Unknown error';
+            }
+        }
+        return response;
+    });
+}
+/**
+ * Fetch help method adding an explicit error property when Response is NOK, with the more accurate textual error inside
+ * Also measure the rtt of fetching and returns it in the property Response.rtt (guaranteed to be ≥ 1),
+ * supports subtracting server processing time using either the Response-Delay or CMSD-rd header when available
+ */
+function fetchWithRTT(input, init) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // a first HEAD request to try to ensure a connection
+        yield fetch(input, Object.assign(Object.assign({}, init), { method: 'HEAD' }));
+        // the true request
+        const startTime = time();
+        const response = (yield fetch(input, init));
+        response.rtt = time() - startTime;
+        // remove the ResponseDelay if indicated by the server
+        let responseDelay = Number(response.headers.get('Response-Delay')) || 0;
+        if (!responseDelay) {
+            // search if we have a CMSD info?
+            // cmsd-dynamic "fly";rd=1
+            const cmsd = response.headers.get('cmsd-dynamic');
+            if (cmsd) {
+                for (const param of cmsd.split(';')) {
+                    const [name, value] = param.split('=');
+                    if (name.trim().toLowerCase() === 'rd') {
+                        responseDelay = Number(value) || responseDelay;
+                    }
+                }
             }
-            throw (error || response.statusText || response.status).toString();
         }
+        response.rtt = Math.max(1, response.rtt - responseDelay);
         return response;
     });
 }
@@ -491,7 +584,7 @@ function trimEnd(value, chars = ' ') {
         --i;
     }
     return value.substring(0, i);
-}var Util=/*#__PURE__*/Object.freeze({__proto__:null,EMPTY_FUNCTION:EMPTY_FUNCTION,equal:equal,fetch:fetch,getBaseFile:getBaseFile,getExtension:getExtension,getFile:getFile,iterableEntries:iterableEntries,objectFrom:objectFrom,options:options,safePromise:safePromise,sleep:sleep,stringify:stringify,time:time,timeOrigin:timeOrigin,toBin:toBin,trim:trim,trimEnd:trimEnd,trimStart:trimStart});/**
+}var Util=/*#__PURE__*/Object.freeze({__proto__:null,EMPTY_FUNCTION:EMPTY_FUNCTION,equal:equal,fetch:fetch,fetchWithRTT:fetchWithRTT,getBaseFile:getBaseFile,getExtension:getExtension,getFile:getFile,iterableEntries:iterableEntries,objectFrom:objectFrom,options:options,safePromise:safePromise,sleep:sleep,stringify:stringify,time:time,toBin:toBin,trim:trim,trimEnd:trimEnd,trimStart:trimStart,unixTime:unixTime});/**
  * 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.
@@ -1032,6 +1125,8 @@ class NetAddress {
      * console.log(NetAddress.fixProtocol('wss','http://domain/path')) // 'ws://domain/path'
      */
     static fixProtocol(protocol, address) {
+        // Remove leading slashes for absolute pathes!
+        address = address.replace(/^[\/]+/, '');
         const found = address.indexOf('://');
         // isolate protocol is present in address
         if (found >= 0) {
@@ -1118,14 +1213,14 @@ class NetAddress {
         this._host = address;
         this._domain = address;
         this._port = defaultPort;
-        // Parse Port
-        pos = this._host.lastIndexOf(':');
-        const endOfBrace = this._host.lastIndexOf(']'); // to support IPv6
-        if (pos > endOfBrace) {
-            const port = parseInt(address.substring(pos + 1));
-            if (port >= 0 && port <= 0xffff) {
-                this._port = port;
-                this._domain = address.substring(0, pos);
+        const domainPortMatch = this._host.match(/^(?:\[([0-9a-fA-F:]+)\]|([^:/?#]+))(?::(\d+))?(?=[/#?]|$)/);
+        if (domainPortMatch) {
+            this._domain = domainPortMatch[1] || domainPortMatch[2];
+            if (domainPortMatch[3]) {
+                const port = parseInt(domainPortMatch[3]);
+                if (port >= 0 && port <= 0xffff) {
+                    this._port = port;
+                }
             }
         }
     }
@@ -1156,7 +1251,21 @@ var Type;
  * @param params The parameters for which the media extension is to be defined
  */
 function defineMediaExt(type, params) {
+    var _a;
     // Compute appropriate mediaExt out parameter
+    if (!params.mediaExt) {
+        try {
+            const url = new URL(params.endPoint);
+            // Set mediaExt with ?ext= param when set OR url extension
+            params.mediaExt = (_a = url.searchParams.get('ext')) !== null && _a !== void 0 ? _a : getExtension(getFile(url.pathname));
+        }
+        catch (_) {
+            // not an URL, it's only a host
+            params.mediaExt = '';
+        }
+    }
+    // Normalize mediaExt in removing the possible '.' prefix and change it to lower case
+    params.mediaExt = trimStart(params.mediaExt, '.').toLowerCase();
     switch (type) {
         case Type.HESP:
             params.mediaExt = 'mp4';
@@ -1165,19 +1274,8 @@ function defineMediaExt(type, params) {
             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.toLowerCase() !== '.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!
+            // json means a manifest file endPoint, replace with default rts media extension
+            if (!params.mediaExt || params.mediaExt === 'json') {
                 params.mediaExt = 'rts';
             }
             break;
@@ -1189,12 +1287,9 @@ function defineMediaExt(type, params) {
             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);
+            log('Unknown params type ' + type).warn();
             break;
     }
-    // Fix mediaExt in removing the possible '.' prefix
-    params.mediaExt = trimStart(params.mediaExt, '.');
 }
 /**
  * Build an URL from {@link Type | type} and {@link Params | params}
@@ -1227,7 +1322,7 @@ function buildURL(type, params, protocol = 'wss') {
                 url.pathname = '/' + params.streamName + '.json';
                 break;
             default:
-                console.warn('Unknown url type ' + type);
+                log('Unknown url type ' + type).warn();
                 break;
         }
     }
@@ -1360,11 +1455,12 @@ class EventEmitter extends Loggable {
             throw Error('event callback must be a function');
         }
         const events = this._event(name);
-        events.add((...args) => {
-            events.delete(event); // delete from events
+        const wrapper = (...args) => {
+            events.delete(wrapper); // delete the wrapper from events
             event(...args); // execute event
-        });
-        (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', () => events.delete(event), { once: true });
+        };
+        events.add(wrapper);
+        (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', () => events.delete(wrapper), { once: true });
     }
     /**
      * Event unsubscription
@@ -2288,6 +2384,12 @@ class UIMetrics {
     }
     constructor(ui) {
         this._ui = ui;
+        ui.addEventListener('mousemove', (event) => {
+            this._mouseX = event.offsetX;
+        });
+        ui.addEventListener('mouseleave', (event) => {
+            this._mouseX = undefined;
+        });
         // default values in pixels
         this._lineHeight = 40;
         this._labelWidth = 170;
@@ -2371,6 +2473,7 @@ class UIMetrics {
             const delta = range.max - range.min;
             let minCircle = '';
             let maxCircle = '';
+            let mouseCircle = this._mouseX == null || this._mouseX > x ? null : '';
             for (let i = 0; i < values.length; ++i) {
                 x -= this._stepSize;
                 const value = parseFloat(values[i].toString());
@@ -2382,6 +2485,9 @@ class UIMetrics {
                 else if (value === max) {
                     minCircle = minCircle || this._drawCircle(x, y, value);
                 }
+                if (mouseCircle === '' && x <= (this._mouseX || 0)) {
+                    mouseCircle = this._drawCircle(x, y, value, 'blue', '');
+                }
             }
             this._html += '" />'; // end path
             // Average
@@ -2396,7 +2502,10 @@ class UIMetrics {
                     '</tspan>';
             this._html += '<tspan x="' + (width + averageCenter) + '" dy="1em">±' + average + '</tspan>';
             this._html += '</text>';
-            this._html += minCircle + maxCircle;
+            this._html += minCircle + maxCircle + (mouseCircle !== null && mouseCircle !== void 0 ? mouseCircle : '');
+            if (mouseCircle) {
+                this._html += mouseCircle;
+            }
             this._html += '</svg>';
         }
         requestAnimationFrame(() => {
@@ -2406,8 +2515,8 @@ class UIMetrics {
             }
         });
     }
-    _drawCircle(x, y, value) {
-        let circle = '<circle cx="' + x + '" cy="' + y + '" r="2" fill="green" />';
+    _drawCircle(x, y, value, color = 'green', fontStyle = 'italic') {
+        let circle = '<circle cx="' + x + '" cy="' + y + '" r="2" fill="' + color + '" />';
         const legendFontHeight = 0.7 * this._legendFontSize;
         const graphMiddle = Math.round(this._lineHeight / 2);
         if (y < graphMiddle) {
@@ -2419,7 +2528,9 @@ class UIMetrics {
             y -= this.textMargin;
         }
         circle +=
-            '<text font-style="italic" font-size="' +
+            '<text font-style="' +
+                fontStyle +
+                '" font-size="' +
                 this._legendFontSize +
                 '" x="' +
                 (x - this._legendFontSize) +
@@ -2435,4 +2546,4 @@ class UIMetrics {
  * 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 = '5.0.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
+const VERSION = '7.0.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