motion-master-client 0.0.246 → 0.0.248

package/src/lib/util.d.ts

@@ -1,23 +1,157 @@
 import { SystemLogLine } from './system-log-line';
 import { IMotionMasterMessage, MotionMasterMessage } from './types';
+/**
+ * Parses a single line of 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`.
+ *
+ * **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 {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.
+ */
 export declare function parseSystemLogLine(line: string): SystemLogLine | undefined;
+/**
+ * Parses the content of a system log into an array of `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.
+ *
+ * **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 {string} content - The raw system log content to parse.
+ * @returns {SystemLogLine[]} An array of `SystemLogLine` objects parsed from the log content.
+ */
 export declare function parseSystemLogContent(content: string): SystemLogLine[];
+/**
+ * Differs two system log contents and returns the new content after the last matching line.
+ *
+ * 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 {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`.
+ */
 export declare function diffSystemLogContents(oldContent: string, newContent: string, lineSeparator?: string, lastLineIndex?: number): string;
-export declare function createPlainObjectFromMotionMasterMessage(motionMasterMessage: MotionMasterMessage): {
-    [k: string]: any;
-};
+/**
+ * Converts a `MotionMasterMessage` to a plain JavaScript object with specific field handling options.
+ *
+ * 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.
+ *
+ * **Note:** The function includes a fix for the error `TypeError: Cannot freeze array buffer views with elements in NgRx`.
+ *
+ * @param {MotionMasterMessage} motionMasterMessage - The `MotionMasterMessage` instance to convert.
+ * @returns {object} A plain JavaScript object representing the message with the specified options applied.
+ */
+export declare function createPlainObjectFromMotionMasterMessage(motionMasterMessage: MotionMasterMessage): IMotionMasterMessage;
+/**
+ * Converts a `motionMasterMessage` into a logger context 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 {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).
+ */
 export declare function convertMotionMasterMessageToLoggerContext(motionMasterMessage: IMotionMasterMessage, namespace?: string): {
     namespace: string;
     motionMasterMessage: IMotionMasterMessage;
-    type: string | undefined;
-    name: string | undefined;
+    type: string;
+    name: string;
 };
+/**
+ * Decodes a `Uint8Array` of text content into a string.
+ *
+ * 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.
+ *
+ * @param {Uint8Array} content - The `Uint8Array` containing the encoded text.
+ * @returns {string} The decoded string.
+ */
 export declare function decodeTextContent(content: Uint8Array): string;
-export declare function resolveAfter(ms: number, value?: unknown): Promise<unknown>;
+/**
+ * Resolves a promise after a specified delay.
+ *
+ * This function returns a promise that resolves after the given number of milliseconds (`ms`),
+ * optionally resolving with a provided value.
+ *
+ * @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.
+ */
+export declare function resolveAfter<T>(ms: number, value?: T): Promise<T | undefined>;
+/**
+ * Converts a 24-bit RGB color value to a format used by LED controllers.
+ *
+ * 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.
+ *
+ * @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).
+ */
 export declare function convertRgbToLedColor(value: number): number;
+/**
+ * Generates a random hex color code with a specified 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 {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`.
+ *
+ * @throws {Error} Throws an error if the brightness is not between 0 and 255.
+ */
 export declare function createRandomColor(brightness: number): string;
+/**
+ * Retrieves the first key from a `Map` that matches a given 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`.
+ *
+ * @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.
+ */
 export declare function getMapKeyByValue<K, V>(map: Map<K, V>, searchValue: V): K | undefined;
+/**
+ * Finds and returns the duplicate elements in an 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.
+ *
+ * @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.
+ */
 export declare function findDuplicates<T>(arr: T[]): T[];
+/**
+ * Converts a camelCase 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 {string} str - The camelCase string to convert.
+ * @returns {string} A space-separated, lowercase version of the input string.
+ */
 export declare function camelCaseToWords(str: string): string;
 /**
  * Sets the specified bit in the given number to 0.
@@ -35,6 +169,60 @@ export declare function setBitLow(value: number, position: number): number;
  * @returns {number} The modified number with the specified bit set to 1.
  */
 export declare function setBitHigh(value: number, position: number): number;
+/**
+ * Returns 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 {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).
+ */
+export declare function getBit(n: number, k: number): number;
+/**
+ * Checks if the bit at the specified position is on (1).
+ *
+ * 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`.
+ *
+ * @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`.
+ */
+export declare function isBitOn(n: number, k: number): boolean;
+/**
+ * Sets the bit at the specified position to 1.
+ *
+ * This function performs a bitwise OR operation to ensure that the bit at the `k`th position is set to `1`.
+ *
+ * @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.
+ */
+export declare function setBit(n: number, k: number): number;
+/**
+ * Clears the bit at the specified position (sets it to 0).
+ *
+ * This function performs a bitwise AND operation with a mask to ensure that the bit at the `k`th position is set to `0`.
+ *
+ * @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).
+ */
+export declare function clearBit(n: number, k: number): number;
+/**
+ * Updates the bit at the specified position with the given value.
+ *
+ * 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 {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.
+ */
+export declare function updateBit(n: number, k: number, value: number | boolean): number;
 /**
  * Converts a number (or string) to a fixed-point format with specified precision.
  *
@@ -44,6 +232,17 @@ export declare function setBitHigh(value: number, position: number): number;
  * @returns The formatted number as a string.
  */
 export declare function toFixedFormat(x: number | string, n?: number, rightTrimZero?: boolean): string;
+/**
+ * Converts a `Blob` 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} 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.
+ */
 export declare function convertBlobToBase64(blob: Blob): Promise<string>;
 /**
  * Checks if the application is running in an Electron environment.
@@ -77,4 +276,56 @@ export declare function parseUnitValue(value: number): {
     denominator: number;
     reserved: number;
 };
+/**
+ * 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 {...Uint8Array[]} ary - An array of `Uint8Array` instances to merge.
+ * @returns {Uint8Array} A new `Uint8Array` containing the concatenated bytes from all input arrays.
+ */
 export declare function mergeUint8Arrays(...ary: Uint8Array[]): Uint8Array;
+/**
+ * Returns an array of unique items by removing duplicates from the given array.
+ *
+ * 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.
+ *
+ * @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.
+ */
+export declare function uniqueItems<T>(items: Array<T>): Array<T>;
+/**
+ * Groups an array of objects by the value of a specified property.
+ *
+ * This function iterates over the array of objects and groups them into a new object,
+ * where the key is the value of the specified property and the value is an array of
+ * objects that have that property value.
+ *
+ * @param {T[]} objects - The array of objects to be grouped.
+ * @param {string} prop - The property name by which the objects will be grouped.
+ * @returns {{ [key: string]: T[] }} An object where the keys are the unique property values and the values are arrays of objects that have that property value.
+ */
+export declare function groupByProperty<T>(objects: T[], prop: keyof T): {
+    [key: string]: T[];
+};
+/**
+ * Maps an array of objects by a specified property, creating a map where the key is
+ * the value of the specified property and the value is an array of objects that have
+ * the same property value.
+ *
+ * @param {V[]} objects - The array of objects to be mapped.
+ * @param {keyof V} prop - The property name by which the objects will be mapped.
+ * @returns {Map<K, V[]>} A map where the keys are the unique property values and the values are arrays of objects that share that property value.
+ */
+export declare function mapByProperty<V, K = string>(objects: V[], prop: keyof V): Map<K, V[]>;
+/**
+ * Converts a C type to its corresponding struct format character.
+ *
+ * @param cType - The C type as a string (e.g., `int8_t`, `uint32_t`, `char[24]`, etc.).
+ * @returns A string representing the struct format equivalent of the given C type.
+ *          For example, `int8_t` becomes `b`, `uint16_t` becomes `H`, `char[24]` becomes `24s`, etc.
+ * @throws Error if the given C type is not recognized.
+ */
+export declare function convertCTypeToStructFormatCharacter(cType: string): string;