motion-master-client 0.0.339 → 0.0.341

package/src/lib/util.js

@@ -1,21 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeNormalizeTimestampFn = exports.analyzeTimeDurations = exports.withTimeDifference = exports.fromQ = exports.convertIpv4 = exports.convertValueToHexString = exports.hexDecValueToNumber = exports.convertCTypeToStructFormatCharacter = exports.mapByProperty = exports.groupByProperty = exports.uniqueItems = exports.mergeUint8Arrays = exports.parseUnitValue = exports.isElectronContext = exports.isElectronApp = exports.convertBlobToBase64 = exports.toFixedFormat = exports.updateBit = exports.clearBit = exports.setBit = exports.isBitOn = exports.getBit = exports.setBitHigh = exports.setBitLow = exports.camelCaseToWords = exports.findDuplicates = exports.getMapKeyByValue = exports.createRandomColor = exports.convertRgbToLedColor = exports.resolveAfter = exports.decodeTextContent = exports.convertMotionMasterMessageToLoggerContext = exports.createPlainObjectFromMotionMasterMessage = exports.diffSystemLogContents = exports.parseSystemLogContent = exports.parseSystemLogLine = void 0;
+exports.makeNormalizeTimestampFn = exports.analyzeTimeDurations = exports.fromQ = exports.convertIpv4 = exports.convertValueToHexString = exports.hexDecValueToNumber = exports.convertCTypeToStructFormatCharacter = exports.mapByProperty = exports.groupByProperty = exports.uniqueItems = exports.mergeUint8Arrays = exports.parseUnitValue = exports.isElectronContext = exports.isElectronApp = exports.convertBlobToBase64 = exports.toFixedFormat = exports.updateBit = exports.clearBit = exports.setBit = exports.isBitOn = exports.getBit = exports.setBitHigh = exports.setBitLow = exports.camelCaseToWords = exports.findDuplicates = exports.getMapKeyByValue = exports.createRandomColor = exports.convertRgbToLedColor = exports.resolveAfter = exports.decodeTextContent = exports.convertMotionMasterMessageToLoggerContext = exports.createPlainObjectFromMotionMasterMessage = exports.diffSystemLogContents = exports.parseSystemLogContent = exports.parseSystemLogLine = void 0;
 const tslib_1 = require("tslib");
-const rxjs_1 = require("rxjs");
 const types_1 = require("./types");
 /**
- * Parses a single line of system log into a structured `SystemLogLine` object.
+ * Parses a single line of a system log into a structured `SystemLogLine` object.
  *
- * This function uses a regular expression to extract key parts of a log line: the timestamp, uptime, ID,
- * file, log level, and message. If the line matches the expected format, it returns an object with these
- * extracted properties. If the line doesn't match the format, it returns `undefined`.
+ * The function expects the log line to follow the format:
+ * ```
+ * YYYY-MM-DD HH:MM:SS.sss (uptime) [id]file:linelevel|message
+ * ```
+ * where the `id` part is optional.
  *
- * **Note:** The regular expression uses the `s` flag (dot-all mode), which may not be supported in all browsers.
- * This is suppressed with `@ts-ignore`.
+ * @param line - A single system log line as a string.
+ * @returns A `SystemLogLine` object with parsed fields, or `undefined` if the line cannot be parsed.
  *
- * @param {string} line - A single log line to parse.
- * @returns {SystemLogLine | undefined} A `SystemLogLine` object with the parsed data, or `undefined` if the line doesn't match the expected format.
+ * @example
+ * const line = '2025-12-05 10:01:23.123 (12:34:56) [device1]main.ts:123INFO|Started';
+ * const parsed = parseSystemLogLine(line);
+ * console.log(parsed?.date);    // → Date object for '2025-12-05 10:01:23.123'
+ * console.log(parsed?.uptime);  // → '12:34:56'
+ * console.log(parsed?.id);      // → 'device1'
+ * console.log(parsed?.message); // → 'Started'
+ *
+ * @remarks
+ * - Uses a regular expression with the `s` (dotAll) flag; this may not be supported in all browsers.
+ * - If parsing fails, the function returns `undefined`.
+ * - The returned object includes the original line for reference.
  */
 function parseSystemLogLine(line) {
     // @ts-ignore - The 's' flag is not supported in all browsers.
@@ -36,17 +47,24 @@ function parseSystemLogLine(line) {
 }
 exports.parseSystemLogLine = parseSystemLogLine;
 /**
- * Parses the content of a system log into an array of `SystemLogLine` objects.
+ * Parses a system log string into an array of structured `SystemLogLine` objects.
  *
- * This function uses a regular expression to split the log content into individual log lines. It then parses
- * each log line into a structured `SystemLogLine` object. The function also filters out any empty lines
- * and ensures only valid `SystemLogLine` objects are returned.
+ * Each log entry is expected to start with a timestamp in the format `YYYY-MM-DD HH:MM:SS.sss`.
+ * The function uses a regular expression to split the content into individual log entries,
+ * then parses each entry into a `SystemLogLine` using `parseSystemLogLine`.
  *
- * **Note:** The regular expression uses the `s` flag, which may not be supported in all browsers. This is suppressed
- * with `@ts-ignore` to allow the use of dot-all mode in the regex.
+ * @param content - The full system log content as a string.
+ * @returns An array of `SystemLogLine` objects representing each parsed log entry.
  *
- * @param {string} content - The raw system log content to parse.
- * @returns {SystemLogLine[]} An array of `SystemLogLine` objects parsed from the log content.
+ * @example
+ * const logContent = '2025-12-05 10:01:23.123 Info: started\n2025-12-05 10:01:24.456 Error: failed';
+ * const lines = parseSystemLogContent(logContent);
+ * console.log(lines[0].timestamp); // → Date object for '2025-12-05 10:01:23.123'
+ *
+ * @remarks
+ * - Entries that cannot be parsed by `parseSystemLogLine` are ignored.
+ * - The regular expression uses the `s` (dotAll) flag, which may not be supported in all browsers;
+ *   a `@ts-ignore` is used to suppress TypeScript warnings.
  */
 function parseSystemLogContent(content) {
     // @ts-ignore - The 's' flag is not supported in all browsers.
@@ -59,17 +77,26 @@ function parseSystemLogContent(content) {
 }
 exports.parseSystemLogContent = parseSystemLogContent;
 /**
- * Differs two system log contents and returns the new content after the last matching line.
+ * Computes the difference between two system log contents by returning only the new lines
+ * added after the last known line from the old content.
  *
- * This function compares two log contents, `oldContent` and `newContent`, and returns the portion of
- * the `newContent` that appears after the last matching line in the `oldContent`. It splits the content
- * based on the provided `lineSeparator` and uses the `lastLineIndex` to find the line to compare.
+ * @param oldContent - The previous log content.
+ * @param newContent - The current log content.
+ * @param lineSeparator - Optional string used to split lines (default: `'\n'`).
+ * @param lastLineIndex - Optional index of the line in `oldContent` to use as the reference point
+ *                        (default: `-2`, i.e., the second-to-last line).
+ * @returns A string containing only the new lines from `newContent` that come after the reference
+ *          line from `oldContent`. If the reference line is not found, returns the entire `newContent`.
  *
- * @param {string} oldContent - The original system log content to compare against.
- * @param {string} newContent - The new system log content to find the difference from the old content.
- * @param {string} [lineSeparator='\n'] - The character(s) used to separate lines in the content (default is newline).
- * @param {number} [lastLineIndex=-2] - The index of the last line to compare, negative index can be used (default is -2, the second-to-last line).
- * @returns {string} The portion of `newContent` after the last matching line in `oldContent`. If no match is found, returns the entire `newContent`.
+ * @example
+ * const oldLog = 'line1\nline2\nline3';
+ * const newLog = 'line1\nline2\nline3\nline4\nline5';
+ * const diff = diffSystemLogContents(oldLog, newLog);
+ * console.log(diff); // → 'line4\nline5'
+ *
+ * @remarks
+ * - Useful for incremental log processing where only newly appended lines need to be handled.
+ * - Handles negative indexing for selecting the reference line from the end of `oldContent`.
  */
 function diffSystemLogContents(oldContent, newContent, lineSeparator = '\n', lastLineIndex = -2) {
     const oldLines = oldContent.split(lineSeparator);
@@ -91,16 +118,26 @@ function diffSystemLogContents(oldContent, newContent, lineSeparator = '\n', las
 }
 exports.diffSystemLogContents = diffSystemLogContents;
 /**
- * Converts a `MotionMasterMessage` to a plain JavaScript object with specific field handling options.
+ * Converts a `MotionMasterMessage` instance into a plain JavaScript object with full defaults
+ * and JSON-compatible values.
+ *
+ * The conversion uses `MotionMasterMessage.toObject` with options that:
+ * - Convert bytes fields to standard arrays.
+ * - Include default values for missing fields.
+ * - Initialize empty arrays for repeated fields and empty objects for map fields.
+ * - Include virtual `oneof` properties indicating which field is set.
+ * - Apply JSON-compatible conversions (e.g., NaN and Infinity to strings).
  *
- * This function utilizes the `MotionMasterMessage.toObject()` method to create a plain object
- * from the provided `MotionMasterMessage`. It includes various options for how fields are processed,
- * such as handling arrays, default values, and JSON compatibility.
+ * @param motionMasterMessage - The `MotionMasterMessage` instance to convert.
+ * @returns A plain object representation of the message with all fields populated and JSON-safe.
  *
- * **Note:** The function includes a fix for the error `TypeError: Cannot freeze array buffer views with elements in NgRx`.
+ * @example
+ * const plainObject = createPlainObjectFromMotionMasterMessage(message);
+ * console.log(plainObject.status); // → fully populated status object
  *
- * @param {MotionMasterMessage} motionMasterMessage - The `MotionMasterMessage` instance to convert.
- * @returns {object} A plain JavaScript object representing the message with the specified options applied.
+ * @remarks
+ * - Useful for logging, serialization, or transferring messages over standard JSON APIs.
+ * - Ensures that all optional, repeated, and map fields are represented in the resulting object.
  */
 function createPlainObjectFromMotionMasterMessage(motionMasterMessage) {
     return types_1.MotionMasterMessage.toObject(motionMasterMessage, {
@@ -114,16 +151,27 @@ function createPlainObjectFromMotionMasterMessage(motionMasterMessage) {
 }
 exports.createPlainObjectFromMotionMasterMessage = createPlainObjectFromMotionMasterMessage;
 /**
- * Converts a `motionMasterMessage` into a logger context object.
+ * Converts a `IMotionMasterMessage` into a structured context object suitable for logging.
+ *
+ * The resulting object includes:
+ * - `namespace`: a string identifying the logging context (default: `'reqResMessage'`),
+ * - `motionMasterMessage`: the original message,
+ * - `type`: either `'request'` or `'status'` depending on the message content,
+ * - `name`: a comma-separated string of the keys in the request or status object.
  *
- * This function extracts relevant details from the provided `motionMasterMessage` and
- * constructs an object to be used as context in logging. It determines whether the message
- * is a request or status type and stores the associated keys from the respective properties.
+ * @param motionMasterMessage - The Motion Master message to convert.
+ * @param namespace - Optional namespace for the logging context (default is `'reqResMessage'`).
+ * @returns An object containing the logging context with type, name, namespace, and original message.
  *
- * @param {IMotionMasterMessage} motionMasterMessage - The message to convert into a logger context.
- * @param {string} [namespace='reqResMessage'] - The namespace to associate with the context (default is 'reqResMessage').
- * @returns {object} An object containing the `namespace`, the original `motionMasterMessage`, the `type` of message
- *                   (either 'request' or 'status'), and the `name` (a string of keys from the request or status).
+ * @example
+ * const context = convertMotionMasterMessageToLoggerContext(message, 'motion');
+ * console.log(context.namespace); // → 'motion'
+ * console.log(context.type);      // → 'request' or 'status'
+ * console.log(context.name);      // → comma-separated keys of the message content
+ *
+ * @remarks
+ * - Determines type by checking the presence of `request` or `status` in the message.
+ * - Useful for structured logging or telemetry where message metadata is required.
  */
 function convertMotionMasterMessageToLoggerContext(motionMasterMessage, namespace = 'reqResMessage') {
     let type = '';
@@ -140,13 +188,18 @@ function convertMotionMasterMessageToLoggerContext(motionMasterMessage, namespac
 }
 exports.convertMotionMasterMessageToLoggerContext = convertMotionMasterMessageToLoggerContext;
 /**
- * Decodes a `Uint8Array` of text content into a string.
+ * Decodes a `Uint8Array` of bytes into a string using UTF-8 encoding.
+ *
+ * @param content - The byte array to decode.
+ * @returns The decoded string representation of the input bytes.
  *
- * This function uses the `TextDecoder` API to decode the given `Uint8Array` (representing
- * text encoded in a specific encoding, such as UTF-8) into a readable string.
+ * @example
+ * const bytes = new Uint8Array([72, 101, 108, 108, 111]);
+ * const text = decodeTextContent(bytes); // → "Hello"
  *
- * @param {Uint8Array} content - The `Uint8Array` containing the encoded text.
- * @returns {string} The decoded string.
+ * @remarks
+ * - Uses the standard `TextDecoder` API with UTF-8 encoding.
+ * - Creates a copy of the input array before decoding, so the original `Uint8Array` is not modified.
  */
 function decodeTextContent(content) {
     const decoder = new TextDecoder();
@@ -155,14 +208,20 @@ function decodeTextContent(content) {
 }
 exports.decodeTextContent = decodeTextContent;
 /**
- * Resolves a promise after a specified delay.
+ * Returns a promise that resolves with the specified value after a given delay.
  *
- * This function returns a promise that resolves after the given number of milliseconds (`ms`),
- * optionally resolving with a provided value.
+ * @typeParam T - The type of the value to resolve.
+ * @param ms - The delay in milliseconds before the promise resolves.
+ * @param value - Optional value to resolve the promise with (defaults to `undefined` if not provided).
+ * @returns A `Promise` that resolves to `value` after `ms` milliseconds.
  *
- * @param {number} ms - The number of milliseconds to wait before resolving the promise.
- * @param {unknown} [value] - The value to resolve with once the delay has passed. Default is `undefined`.
- * @returns {Promise<unknown>} A promise that resolves with the specified value after the delay.
+ * @example
+ * await resolveAfter(1000, 'hello'); // resolves with 'hello' after 1 second
+ * await resolveAfter(500);           // resolves with undefined after 0.5 seconds
+ *
+ * @remarks
+ * - Useful for simulating delays or asynchronous timing in tests or animations.
+ * - The function does not reject; it always resolves after the specified timeout.
  */
 function resolveAfter(ms, value) {
     return new Promise(function (resolve) {
@@ -171,14 +230,23 @@ function resolveAfter(ms, value) {
 }
 exports.resolveAfter = resolveAfter;
 /**
- * Converts a 24-bit RGB color value to a format used by LED controllers.
+ * Converts a standard 24-bit RGB color value into a format suitable for certain LED controllers.
+ *
+ * The conversion swaps the red and green channels, producing a new 24-bit integer where:
+ * - Original green becomes the most significant byte,
+ * - Original red becomes the middle byte,
+ * - Original blue remains the least significant byte.
+ *
+ * @param value - A 24-bit RGB color represented as a number (0xRRGGBB).
+ * @returns The converted 24-bit LED color value with swapped red and green channels.
  *
- * This function takes an RGB color value (represented as a single 24-bit number)
- * and rearranges the color channels to match a typical LED color format, which may
- * require swapping the red and green channels.
+ * @example
+ * const rgb = 0x112233;
+ * const ledColor = convertRgbToLedColor(rgb); // → 0x221133
  *
- * @param {number} value - A 24-bit integer representing the RGB color value (0xRRGGBB).
- * @returns {number} A new integer representing the color in the LED format (0xGRB).
+ * @remarks
+ * - Useful when interfacing with LED hardware that expects a different channel ordering.
+ * - Input and output are standard JavaScript numbers representing 24-bit colors.
  */
 function convertRgbToLedColor(value) {
     const r = (value >> 16) & 0xff;
@@ -189,16 +257,19 @@ function convertRgbToLedColor(value) {
 }
 exports.convertRgbToLedColor = convertRgbToLedColor;
 /**
- * Generates a random hex color code with a specified brightness.
+ * Generates a random hexadecimal color string with a specified minimum brightness.
  *
- * This function creates a random color by generating random values for the red, green, and blue
- * color channels. The brightness parameter ensures the generated color is not too dark by
- * limiting the possible range for each channel.
+ * @param brightness - Minimum value for each RGB channel (0–255). Higher values produce lighter colors.
+ * @returns A random color string in `#RRGGBB` format.
  *
- * @param {number} brightness - The minimum brightness of the generated color. Should be between 0 and 255.
- * @returns {string} A random hex color code, in the form of `#RRGGBB`.
+ * @example
+ * createRandomColor(100); // → '#c48f7a' (example output)
+ * createRandomColor(200); // → '#e5f0ff' (example output)
  *
- * @throws {Error} Throws an error if the brightness is not between 0 and 255.
+ * @remarks
+ * - Each color channel (red, green, blue) is independently randomized between `brightness` and 255.
+ * - Ensures that no channel is darker than the specified brightness.
+ * - Useful for generating visually distinct colors while avoiding very dark shades.
  */
 function createRandomColor(brightness) {
     function randomChannel(brightness) {
@@ -211,17 +282,22 @@ function createRandomColor(brightness) {
 }
 exports.createRandomColor = createRandomColor;
 /**
- * Retrieves the first key from a `Map` that matches a given value.
+ * Finds the first key in a `Map` that corresponds to the specified value.
  *
- * This function iterates over the entries of the map and returns the first key
- * whose corresponding value strictly equals (`===`) the provided `searchValue`.
- * If no matching value is found, it returns `undefined`.
+ * @typeParam K - The type of keys in the map.
+ * @typeParam V - The type of values in the map.
+ * @param map - The map to search.
+ * @param searchValue - The value to find the corresponding key for.
+ * @returns The first key whose value strictly equals (`===`) the searchValue, or `undefined` if no match is found.
+ *
+ * @example
+ * const myMap = new Map<string, number>([['a', 1], ['b', 2], ['c', 1]]);
+ * getMapKeyByValue(myMap, 1); // → 'a'
+ * getMapKeyByValue(myMap, 3); // → undefined
  *
- * @template K - The type of the map's keys.
- * @template V - The type of the map's values.
- * @param {Map<K, V>} map - The map to search through.
- * @param {V} searchValue - The value to find the corresponding key for.
- * @returns {K | undefined} The key associated with the given value, or `undefined` if not found.
+ * @remarks
+ * - Only the first matching key is returned; subsequent keys with the same value are ignored.
+ * - Comparison uses strict equality (`===`).
  */
 function getMapKeyByValue(map, searchValue) {
     for (let [key, value] of map.entries()) {
@@ -233,14 +309,20 @@ function getMapKeyByValue(map, searchValue) {
 }
 exports.getMapKeyByValue = getMapKeyByValue;
 /**
- * Finds and returns the duplicate elements in an array.
+ * Identifies duplicate elements in an array and returns them as a new array.
  *
- * This function iterates through the array and identifies elements that appear more than once.
- * It preserves only one instance of each duplicate in the output.
+ * @typeParam T - The type of elements in the array.
+ * @param arr - The array to check for duplicate values.
+ * @returns An array containing all elements that appear more than once in the input array.
+ *          Each duplicate element appears only once in the returned array, regardless of how many times it occurs.
  *
- * @template T - The type of elements in the array.
- * @param {T[]} arr - The input array to search for duplicates.
- * @returns {T[]} An array of the duplicate elements, without repetition.
+ * @example
+ * findDuplicates([1, 2, 3, 2, 4, 3, 5]); // → [2, 3]
+ * findDuplicates(['a', 'b', 'a', 'c']);   // → ['a']
+ *
+ * @remarks
+ * - Uses `Set` internally for efficient duplicate detection.
+ * - Preserves the insertion order of first detected duplicates.
  */
 function findDuplicates(arr) {
     const uniqueElements = new Set();
@@ -257,89 +339,136 @@ function findDuplicates(arr) {
 }
 exports.findDuplicates = findDuplicates;
 /**
- * Converts a camelCase string into a space-separated lowercase string.
+ * Converts a camelCase or PascalCase string into a space-separated, lowercase string.
  *
- * This function inserts spaces before each uppercase letter in the string (except the first one)
- * and converts the entire string to lowercase.
+ * @param str - The input string in camelCase or PascalCase format.
+ * @returns A new string where each uppercase letter is preceded by a space and all letters are lowercase.
+ *
+ * @example
+ * camelCaseToWords('camelCaseString'); // → 'camel case string'
+ * camelCaseToWords('PascalCase');      // → 'pascal case'
  *
- * @param {string} str - The camelCase string to convert.
- * @returns {string} A space-separated, lowercase version of the input string.
+ * @remarks
+ * - Useful for converting identifiers into human-readable words.
+ * - Leading spaces are preserved if the string starts with an uppercase letter.
  */
 function camelCaseToWords(str) {
     return str.replace(/([A-Z])/g, ' $1').toLowerCase();
 }
 exports.camelCaseToWords = camelCaseToWords;
 /**
- * Sets the specified bit in the given number to 0.
+ * Clears (sets to 0) the bit at the specified position in a number.
  *
- * @param {number} value - The original number whose bit will be modified.
- * @param {number} position - The position of the bit to set to 0 (0-based index).
- * @returns {number} The modified number with the specified bit set to 0.
+ * @param value - The original number whose bit is to be cleared.
+ * @param position - Zero-based bit position to clear (0 = least-significant bit).
+ * @returns A new number with the bit at the specified position cleared to 0.
+ *
+ * @example
+ * setBitLow(0b1011, 1); // → 0b1001 (clears bit 1)
+ * setBitLow(0b1111, 3); // → 0b0111 (clears bit 3)
+ *
+ * @remarks
+ * - Only the bit at the given position is affected; all other bits remain unchanged.
+ * - Works with any 32-bit integer representable in JavaScript.
  */
 function setBitLow(value, position) {
     return value & ~(1 << position);
 }
 exports.setBitLow = setBitLow;
 /**
- * Sets the specified bit in the given number to 1.
+ * Sets (changes to 1) the bit at the specified position in a number.
+ *
+ * @param value - The original number whose bit is to be set.
+ * @param position - Zero-based bit position to set (0 = least-significant bit).
+ * @returns A new number with the bit at the specified position set to 1.
  *
- * @param {number} value - The original number whose bit will be modified.
- * @param {number} position - The position of the bit to set to 1 (0-based index).
- * @returns {number} The modified number with the specified bit set to 1.
+ * @example
+ * setBitHigh(0b1001, 1); // → 0b1011 (sets bit 1)
+ * setBitHigh(0b0111, 3); // → 0b1111 (sets bit 3)
+ *
+ * @remarks
+ * - Only the bit at the given position is affected; all other bits remain unchanged.
+ * - Works with any 32-bit integer representable in JavaScript.
  */
 function setBitHigh(value, position) {
     return value | (1 << position);
 }
 exports.setBitHigh = setBitHigh;
 /**
- * Returns the bit at the specified position in a number.
+ * Retrieves the value of the bit at the specified position in a number.
  *
- * This function performs a bitwise AND operation to isolate the bit at the `k`th position.
- * If the bit is 0, it returns `0`; otherwise, it returns `1`.
+ * @param n - The number from which to retrieve the bit.
+ * @param k - Zero-based bit position to retrieve (0 = least-significant bit).
+ * @returns `1` if the bit at position `k` is set, otherwise `0`.
  *
- * @param {number} n - The number whose bit will be retrieved.
- * @param {number} k - The position of the bit to retrieve (0-indexed).
- * @returns {number} The bit at position `k` (either 0 or 1).
+ * @example
+ * getBit(0b1010, 1); // → 1 (bit 1 is set)
+ * getBit(0b1010, 0); // → 0 (bit 0 is clear)
+ *
+ * @remarks
+ * - Works with any 32-bit integer representable in JavaScript.
+ * - Does not modify the original number.
  */
 function getBit(n, k) {
     return (n & (1 << k)) === 0 ? 0 : 1;
 }
 exports.getBit = getBit;
 /**
- * Checks if the bit at the specified position is on (1).
+ * Checks whether the bit at the specified position in a number is set (1).
+ *
+ * @param n - The number to check.
+ * @param k - Zero-based bit position to check (0 = least-significant bit).
+ * @returns `true` if the bit at position `k` is 1, otherwise `false`.
  *
- * This function performs a bitwise AND operation to check if the bit at the `k`th position is set to `1`.
- * It returns `true` if the bit is set, otherwise `false`.
+ * @example
+ * isBitOn(0b1010, 1); // → true  (bit 1 is set)
+ * isBitOn(0b1010, 0); // → false (bit 0 is clear)
  *
- * @param {number} n - The number to check.
- * @param {number} k - The position of the bit to check (0-indexed).
- * @returns {boolean} `true` if the bit is on (1), otherwise `false`.
+ * @remarks
+ * - Works with any 32-bit integer representable in JavaScript.
+ * - Does not modify the original number.
  */
 function isBitOn(n, k) {
     return (n & (1 << k)) > 0;
 }
 exports.isBitOn = isBitOn;
 /**
- * Sets the bit at the specified position to 1.
+ * Sets (changes to 1) the bit at the specified position in a number.
+ *
+ * The original number is not mutated; a new number is returned with the bit set.
  *
- * This function performs a bitwise OR operation to ensure that the bit at the `k`th position is set to `1`.
+ * @param n - The original number whose bit is to be set.
+ * @param k - Zero-based bit position to set (0 = least-significant bit).
+ * @returns A new number equal to `n` with bit `k` set.
  *
- * @param {number} n - The number in which the bit will be set.
- * @param {number} k - The position of the bit to set (0-indexed).
- * @returns {number} The new number with the bit at position `k` set to 1.
+ * @example
+ * setBit(0b1001, 1); // → 0b1011 (sets bit 1)
+ * setBit(0b0111, 3); // → 0b1111 (sets bit 3)
+ *
+ * @remarks
+ * - Only the bit at position `k` is affected; all other bits remain unchanged.
+ * - Works with any 32-bit integer representable in JavaScript.
  */
 function setBit(n, k) {
     return n | (1 << k);
 }
 exports.setBit = setBit;
 /**
- * Clears the bit at the specified position (sets it to 0).
+ * Clears (sets to 0) the bit at the specified position in a number.
  *
- * This function performs a bitwise AND operation with a mask to ensure that the bit at the `k`th position is set to `0`.
+ * The original number is not mutated; a new number is returned with the bit cleared.
  *
- * @param {number} n - The number in which the bit will be cleared.
- * @param {number} k - The position of the bit to clear (0-indexed).
- * @returns {number} The new number with the bit at position `k` cleared (set to 0).
+ * @param n - The original number whose bit is to be cleared.
+ * @param k - Zero-based bit position to clear (0 = least-significant bit).
+ * @returns A new number equal to `n` with bit `k` cleared.
+ *
+ * @example
+ * clearBit(0b1011, 1); // → 0b1001 (clears bit 1)
+ * clearBit(0b1111, 3); // → 0b0111 (clears bit 3)
+ *
+ * @remarks
+ * - Only the bit at position `k` is affected; all other bits remain unchanged.
+ * - Works with any 32-bit integer representable in JavaScript.
  */
 function clearBit(n, k) {
     const mask = ~(1 << k);
@@ -347,15 +476,23 @@ function clearBit(n, k) {
 }
 exports.clearBit = clearBit;
 /**
- * Updates the bit at the specified position with the given value.
+ * Updates the bit at position `k` in the given number `n` to the specified value.
+ *
+ * The original number is not mutated; instead, a new number is returned with the bit updated.
  *
- * This function updates the bit at the `k`th position to either `1` or `0` depending on the provided value.
- * If the value is a boolean, it will be normalized to `1` (true) or `0` (false).
+ * @param n - The original number whose bit is being modified.
+ * @param k - Zero-based bit position to update (0 = least-significant bit).
+ * @param value - Boolean or numeric value indicating whether the bit should be set (`true` / `1`)
+ *                or cleared (`false` / `0`).
+ * @returns A new number equal to `n` with bit `k` updated.
+ *
+ * @example
+ * updateBit(0b1010, 1, true);   // → 0b1011 (set bit 1)
+ * updateBit(0b1011, 3, false);  // → 0b0011 (clear bit 3)
  *
- * @param {number} n - The number in which the bit will be updated.
- * @param {number} k - The position of the bit to update (0-indexed).
- * @param {number | boolean} value - The value to set the bit to (1 or 0, or `true`/`false`).
- * @returns {number} The new number with the bit at position `k` updated.
+ * @remarks
+ * - Values other than `0` or `false` result in bit being set to `1`.
+ * - Works with any 32-bit integer representable in JavaScript.
  */
 function updateBit(n, k, value) {
     const normalizedValue = value ? 1 : 0;
@@ -394,15 +531,20 @@ function toFixedFormat(x, n = 6, rightTrimZero = true) {
 }
 exports.toFixedFormat = toFixedFormat;
 /**
- * Converts a `Blob` into a Base64-encoded string.
+ * Converts a `Blob` object into a Base64-encoded string.
  *
- * This function reads the provided `Blob` using `FileReader` and extracts the Base64 content
- * from the resulting data URL.
+ * @param blob - The `Blob` to convert.
+ * @returns A `Promise` that resolves to the Base64 string representation of the blob.
  *
- * @param {Blob} blob - The `Blob` to convert into a Base64 string.
- * @returns {Promise<string>} A promise that resolves with the Base64 string representation of the blob.
- *
- * @throws {string} If the blob cannot be read (e.g., due to an error), the promise rejects with an error message.
+ * @example
+ * const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
+ * const base64 = await convertBlobToBase64(blob);
+ * console.log(base64); // → 'SGVsbG8sIHdvcmxkIQ=='
+ *
+ * @remarks
+ * - Internally uses `FileReader.readAsDataURL` to serialize the blob.
+ * - The returned Base64 string excludes the data URL prefix (e.g., `data:text/plain;base64,`).
+ * - The promise is rejected if the blob cannot be read.
  */
 function convertBlobToBase64(blob) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -483,12 +625,17 @@ exports.isElectronContext = isElectronContext;
  *
  * The function uses bitwise operations to isolate each byte from the 32-bit integer.
  *
- * @param {number} value - The 32-bit integer to be parsed.
- * @returns {Object} An object containing the extracted components:
+ * @param value - The 32-bit integer to be parsed.
+ * @returns An object containing the extracted components:
  *   - `prefix`: The extracted prefix byte (8 bits).
  *   - `numerator`: The extracted numerator byte (8 bits).
  *   - `denominator`: The extracted denominator byte (8 bits).
  *   - `reserved`: The extracted reserved byte (8 bits).
+ *
+ * @example
+ * const parsed = parseUnitValue(0x12345678);
+ * console.log(parsed);
+ * // → { prefix: 0x12, numerator: 0x34, denominator: 0x56, reserved: 0x78 }
  */
 function parseUnitValue(value) {
     // Convert a value to a 32-bit signed integer using bitwise OR
@@ -505,11 +652,18 @@ exports.parseUnitValue = parseUnitValue;
 /**
  * Merges multiple `Uint8Array` instances into a single `Uint8Array`.
  *
- * This function concatenates all provided `Uint8Array` instances in the order they are given,
- * producing a new array containing all their bytes sequentially.
+ * @param ary - One or more `Uint8Array` instances to merge.
+ * @returns A new `Uint8Array` containing all elements from the input arrays in order.
  *
- * @param {...Uint8Array[]} ary - An array of `Uint8Array` instances to merge.
- * @returns {Uint8Array} A new `Uint8Array` containing the concatenated bytes from all input arrays.
+ * @example
+ * const a = new Uint8Array([1, 2]);
+ * const b = new Uint8Array([3, 4]);
+ * const merged = mergeUint8Arrays(a, b); // → Uint8Array [1, 2, 3, 4]
+ *
+ * @remarks
+ * - Preserves the order of elements from each input array.
+ * - Efficiently concatenates arrays without creating intermediate arrays for each element.
+ * - Returns a new `Uint8Array`; the input arrays are not modified.
  */
 function mergeUint8Arrays(...ary) {
     const elements = ary.map((v) => v.length).reduce((a, b) => a + b, 0);
@@ -523,13 +677,19 @@ function mergeUint8Arrays(...ary) {
 }
 exports.mergeUint8Arrays = mergeUint8Arrays;
 /**
- * Returns an array of unique items by removing duplicates from the given array.
+ * Returns a new array containing only the unique elements from the input array, preserving their order.
  *
- * This function utilizes the `Set` object to remove duplicate values, ensuring that only unique items
- * remain in the returned array. The order of items in the resulting array is preserved as in the input.
+ * @typeParam T - The type of elements in the array.
+ * @param items - The array from which to remove duplicates.
+ * @returns A new array with duplicate elements removed.
+ *
+ * @example
+ * uniqueItems([1, 2, 2, 3, 1]); // → [1, 2, 3]
+ * uniqueItems(['a', 'b', 'a']); // → ['a', 'b']
  *
- * @param {Array<T>} items - The array from which duplicates will be removed.
- * @returns {Array<T>} A new array containing only the unique items from the input array.
+ * @remarks
+ * - Uses a `Set` internally for efficient duplicate removal.
+ * - Original array is not modified.
  */
 function uniqueItems(items) {
     return [...new Set(items)];
@@ -804,35 +964,6 @@ function fromQ(rawValue, qFractionalBits = 15, round = false) {
     return round ? Math.round(value) : value;
 }
 exports.fromQ = fromQ;
-/**
- * Custom RxJS operator that accumulates notifications with their
- * elapsed time relative to a provided start time.
- *
- * Each emitted notification string is converted into a `NotificationEntry`
- * object, and the operator maintains an array of all previous entries.
- *
- * @param startTime - The timestamp (in milliseconds) to use as the reference
- *   point for calculating elapsed time. Typically obtained via `performance.now()`.
- * @returns An OperatorFunction that transforms an Observable of strings into
- *   an Observable of `NotificationEntry[]`.
- *
- * @example
- * ```ts
- * const startTime = performance.now();
- * notifications$.pipe(withTimeDifference(startTime)).subscribe(entries => {
- *   console.log(entries); // Array of NotificationEntry objects with elapsed time
- * });
- * ```
- */
-function withTimeDifference(startTime) {
-    return (source) => source.pipe((0, rxjs_1.scan)((acc, message) => {
-        const endTime = performance.now();
-        const timeDifference = endTime - startTime;
-        acc.push({ message, timeDifference });
-        return acc;
-    }, []));
-}
-exports.withTimeDifference = withTimeDifference;
 /**
  * Analyzes an array of measured time durations and returns useful statistics
  * both for the full dataset and for outlier-filtered data.