@ceeblue/web-utils 7.0.0 → 7.1.0

package/README.md

@@ -14,7 +14,7 @@ Then [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modu
  ```javascript
 import { Util, ILog } from '@ceeblue/web-utils';
 ```
-> 💡 **TIP**
+> [!IMPORTANT]
 > 
 > If your project uses TypeScript, it is recommended that you set target: "ES6" in your configuration to match our use of ES6 features and ensure that your build will succeed (for those requiring a backward-compatible UMD version, a local build is recommended).
 > Then define the "moduleResolution" compiler option: "Node" in tsconfig.json helps with import failures by ensuring that TypeScript uses the correct import resolution strategy based on the targeted Node.js version.
@@ -27,13 +27,11 @@ import { Util, ILog } from '@ceeblue/web-utils';
 >   }
 >   ```
 
-> ⚠️ **REMARKS**
+> [!TIP]
 > 
 > 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
@@ -58,7 +56,12 @@ This monorepo also contains built-in documentation about the APIs in the library
 ```
 npm run build:docs
 ```
-You can access the documentation by opening the index.html file in the docs folder with your browser (`./docs/index.html`).
+
+Once generated, open the `index.html` file located in the `docs` folder (`./docs/index.html`) with your browser.
+
+> [!NOTE]
+>
+>  An online, continuously maintained version of the latest released documentation is available at https://ceebluetv.github.io/web-utils/
 
 ## Contribution
 

package/dist/web-utils.d.ts

@@ -467,7 +467,7 @@ declare class EventEmitter extends Loggable {
      * 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 options.abortSignal Optional `AbortSignal` to stop this or multiple subscriptions in same time
+     * @param options.signal Optional `AbortSignal` to stop this or multiple subscriptions in same time
      */
     once(name: EventKeys<this>, event: Function, options?: {
         signal?: AbortSignal;
@@ -904,6 +904,8 @@ declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Re
  * 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
+ *
+ * WIP => replace the current implementation to use Resource Timing API
  */
 declare function fetchWithRTT(input: RequestInfo | URL, init?: RequestInit): Promise<Response & {
     rtt: number;
@@ -948,8 +950,20 @@ declare function trimStart(value: string, chars?: string): string;
  * @returns string trimmed
  */
 declare function trimEnd(value: string, chars?: string): string;
+/**
+ * Wraps an object with a Proxy that makes property access case-insensitive.
+ *
+ * Property lookup (e.g. `obj.Foo` or `obj.foo`) will resolve to the same underlying key, regardless of casing.
+ * Only affects string-based property access (not symbols).
+ *
+ * @template T
+ * @param {T} obj - The original object.
+ * @returns {T} A proxied object with case-insensitive property access.
+ */
+declare function caseInsensitive<T extends Record<string, any>>(obj: any): T;
 
 declare const Util_EMPTY_FUNCTION: typeof EMPTY_FUNCTION;
+declare const Util_caseInsensitive: typeof caseInsensitive;
 declare const Util_equal: typeof equal;
 declare const Util_fetch: typeof fetch;
 declare const Util_fetchWithRTT: typeof fetchWithRTT;
@@ -969,7 +983,7 @@ 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_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 };
+  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_caseInsensitive as caseInsensitive, 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 };
 }
 
 /**
@@ -1137,24 +1151,22 @@ declare class WebSocketReliable extends EventEmitter {
  * @param {HTMLCanvasElement} canvas
  * @param {CanvasRenderingContext2D} context
  * @param {Date} now current date, new Date() by default
- * @param {Number} blocksPerRow number of blocks in the line, 32 by default
  * @param {Number} tolerance percentage of tolerance for the black and white threshold, 0.2 by default
  * @returns {Number} The latency in millisecond between 'now' and the decoded timestamp, 0 if the timestamp cannot be decoded
  */
-declare function getLatency(sourceEl: HTMLVideoElement, canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, now?: Date, blocksPerRow?: number, tolerance?: number): number;
+declare function getLatency(sourceEl: HTMLVideoElement, canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, now?: Date, tolerance?: number): number;
 /**
  * Decode a previously encoded timestamp from a canvas
  *
  * @param {CanvasRenderingContext2D} context
  * @param {Number} lineWidth width of the line in pixels
- * @param {Number} blocksPerRow number of blocks in the line, 32 by default
  * @param {Number} tolerance percentage of tolerance for the black and white threshold, 0.2 by default
  * @returns {Date|null} The Date object representing the timestamp or null if the timestamp cannot be decoded
  */
-declare function decodeTimestamp(context: CanvasRenderingContext2D, lineWidth: number, blocksPerRow?: number, tolerance?: number): Date | undefined;
+declare function decodeTimestamp(context: CanvasRenderingContext2D, lineWidth: number, tolerance?: number): Date | null;
 /**
- * Encode the current timestamp into a line composed of blocks of black and white pixels
- * written on the top of the canvas.
+ * Encode the given date (excluding year and month) into a line composed of blocks
+ * of black and white pixels written on the top of the canvas.
  *
  * @param {CanvasRenderingContext2D} context
  * @param {Number} lineWidth width of the line in pixels

package/dist/web-utils.js

@@ -476,12 +476,14 @@ function fetch(input, init) {
  * 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
+ *
+ * WIP => replace the current implementation to use Resource Timing API
  */
 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
+        // A first OPTIONS request to establish a connection (keep-alive)
+        yield fetch(input, Object.assign(Object.assign({}, init), { method: 'OPTIONS' }));
+        // Actual RTT measurement
         const startTime = time();
         const response = (yield fetch(input, init));
         response.rtt = time() - startTime;
@@ -584,7 +586,30 @@ 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,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});/**
+}
+/**
+ * Wraps an object with a Proxy that makes property access case-insensitive.
+ *
+ * Property lookup (e.g. `obj.Foo` or `obj.foo`) will resolve to the same underlying key, regardless of casing.
+ * Only affects string-based property access (not symbols).
+ *
+ * @template T
+ * @param {T} obj - The original object.
+ * @returns {T} A proxied object with case-insensitive property access.
+ */
+function caseInsensitive(obj) {
+    return new Proxy(obj, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string') {
+                const key = Object.keys(target).find(k => k.toLowerCase() === prop.toLowerCase());
+                if (key !== undefined) {
+                    return Reflect.get(target, key, receiver);
+                }
+            }
+            return Reflect.get(target, prop, receiver);
+        }
+    });
+}var Util=/*#__PURE__*/Object.freeze({__proto__:null,EMPTY_FUNCTION:EMPTY_FUNCTION,caseInsensitive:caseInsensitive,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.
@@ -1447,7 +1472,7 @@ class EventEmitter extends Loggable {
      * 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 options.abortSignal Optional `AbortSignal` to stop this or multiple subscriptions in same time
+     * @param options.signal Optional `AbortSignal` to stop this or multiple subscriptions in same time
      */
     once(name, event, options) {
         var _a;
@@ -2195,6 +2220,8 @@ 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.
  */
+// Fixed blocks to 32 because timestamp is encoded on 32 bits
+const _blocksPerRow = 32;
 /**
  * Decode the timestamp from a video element and compute the latency between the timestamp and the current date.
  *
@@ -2202,19 +2229,18 @@ class WebSocketReliable extends EventEmitter {
  * @param {HTMLCanvasElement} canvas
  * @param {CanvasRenderingContext2D} context
  * @param {Date} now current date, new Date() by default
- * @param {Number} blocksPerRow number of blocks in the line, 32 by default
  * @param {Number} tolerance percentage of tolerance for the black and white threshold, 0.2 by default
  * @returns {Number} The latency in millisecond between 'now' and the decoded timestamp, 0 if the timestamp cannot be decoded
  */
-function getLatency(sourceEl, canvas, context, now = new Date(), blocksPerRow = 32, tolerance = 0.2) {
+function getLatency(sourceEl, canvas, context, now = new Date(), tolerance = 0.2) {
     canvas.width = sourceEl.videoWidth;
-    canvas.height = Math.floor(canvas.width / blocksPerRow);
+    canvas.height = Math.floor(canvas.width / _blocksPerRow);
     if (!canvas.width || !canvas.height) {
         // No pixel to parse!
         return 0;
     }
     context.drawImage(sourceEl, 0, 0, canvas.width, canvas.height, 0, 0, canvas.width, canvas.height);
-    const timestamp = decodeTimestamp(context, canvas.width, blocksPerRow, tolerance);
+    const timestamp = decodeTimestamp(context, canvas.width, tolerance);
     return timestamp == null ? 0 : now.getTime() - timestamp.getTime();
 }
 /**
@@ -2222,20 +2248,25 @@ function getLatency(sourceEl, canvas, context, now = new Date(), blocksPerRow =
  *
  * @param {CanvasRenderingContext2D} context
  * @param {Number} lineWidth width of the line in pixels
- * @param {Number} blocksPerRow number of blocks in the line, 32 by default
  * @param {Number} tolerance percentage of tolerance for the black and white threshold, 0.2 by default
  * @returns {Date|null} The Date object representing the timestamp or null if the timestamp cannot be decoded
  */
-function decodeTimestamp(context, lineWidth, blocksPerRow = 32, tolerance = 0.2) {
-    const blockSize = lineWidth / blocksPerRow;
+function decodeTimestamp(context, lineWidth, tolerance = 0.2) {
+    // Integer block width and ignore the right-hand remainder.
+    const blockSize = Math.floor(lineWidth / _blocksPerRow);
     let binaryTime = '';
-    let i = blockSize / 2;
-    const data = context.getImageData(0, Math.round(i), lineWidth, 1).data;
+    if (blockSize < 1) {
+        return null;
+    }
+    const effectiveWidth = blockSize * _blocksPerRow;
+    const midBlock = Math.floor(blockSize / 2);
+    const data = context.getImageData(0, midBlock, effectiveWidth, 1).data;
     const pixels = new Uint32Array(data.buffer);
     const blackThreshold = 0xff * tolerance;
     const whiteThreshold = 0xff * (1 - tolerance);
-    while (i < pixels.length) {
-        const pixel = pixels[Math.round(i)] & 0xffffff;
+    // Sample the center pixel of each integer-sized block that the encoder painted.
+    for (let i = 0; i < effectiveWidth; i += blockSize) {
+        const pixel = pixels[i + midBlock] & 0xffffff;
         // Extract luminance from RGB
         const Y = 0.299 * ((pixel >> 16) & 0xff) + 0.587 * ((pixel >> 8) & 0xff) + 0.114 * (pixel & 0xff);
         if (Y < blackThreshold) {
@@ -2247,21 +2278,24 @@ function decodeTimestamp(context, lineWidth, blocksPerRow = 32, tolerance = 0.2)
             binaryTime += '0';
         }
         else {
-            return;
+            return null;
         }
-        i += blockSize;
     }
     const day = parseInt(binaryTime.slice(0, 5), 2);
     const hour = parseInt(binaryTime.slice(5, 10), 2);
     const minute = parseInt(binaryTime.slice(10, 16), 2);
     const second = parseInt(binaryTime.slice(16, 22), 2);
     const millisecond = parseInt(binaryTime.slice(22, 32), 2);
+    // Basic sanity checks (match encoder ranges)
+    if (day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59 || millisecond > 999) {
+        return null;
+    }
     const now = new Date();
     return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), day, hour, minute, second, millisecond));
 }
 /**
- * Encode the current timestamp into a line composed of blocks of black and white pixels
- * written on the top of the canvas.
+ * Encode the given date (excluding year and month) into a line composed of blocks
+ * of black and white pixels written on the top of the canvas.
  *
  * @param {CanvasRenderingContext2D} context
  * @param {Number} lineWidth width of the line in pixels
@@ -2275,11 +2309,11 @@ function encodeTimestamp(context, lineWidth, blocksPerRow = 32, now = new Date()
     const minute = now.getUTCMinutes();
     const second = now.getUTCSeconds();
     const millisecond = now.getUTCMilliseconds();
-    const binaryDay = day.toString(2).padStart(5, '0');
-    const binaryHour = hour.toString(2).padStart(5, '0');
-    const binaryMinute = minute.toString(2).padStart(6, '0');
-    const binarySecond = second.toString(2).padStart(6, '0');
-    const binaryMillisecond = millisecond.toString(2).padStart(10, '0');
+    const binaryDay = day.toString(2).padStart(5, '0'); // 31 possible days/32
+    const binaryHour = hour.toString(2).padStart(5, '0'); // 24 possible hours/32
+    const binaryMinute = minute.toString(2).padStart(6, '0'); // 60 possible minutes/64
+    const binarySecond = second.toString(2).padStart(6, '0'); // 60 possible seconds/64
+    const binaryMillisecond = millisecond.toString(2).padStart(10, '0'); // 1000 possible milliseconds/1024
     const binaryTime = binaryDay + binaryHour + binaryMinute + binarySecond + binaryMillisecond;
     for (let i = 0; i < binaryTime.length; i++) {
         const x = (i % blocksPerRow) * blockSize;
@@ -2546,4 +2580,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 = '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
+const VERSION = '7.1.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