new-log-viewer: Add bounds checking and search methods to support log filtering around a specific log event.

new-log-viewer/src/utils/data.ts

@@ -1,6 +1,87 @@
 import {Nullable} from "../typings/common";
 
 
+/**
+ * Checks if 'target' is bounded by the first and last value in a sorted array of numbers.
+ *
+ * @param data A number array sorted in ascending order.
+ * @param target
+ * @return `true` if is `target` is within bounds; `false` otherwise or when the array is empty.
+ */
+const isWithinBounds = (data: number[], target: number): boolean => {
+    const {length} = data;
+    if (0 === length) {
+        return false;
+    }
+
+    return (target >= (data[0] as number)) && (target <= (data[length - 1] as number));
+};
+
+/**
+ * Performs binary search to find the smallest index `i` in the range [0, length) where the
+ * `conditionFn` is true. Assumes that the `conditionFn` is false for some prefix of the input
+ * range and true for the remainder. The most common use is to find the index `i` of a target
+ * value in a sorted array.
+ *
+ * @param length The length of the range to search.
+ * @param conditionFn A function that takes an index and returns `true` or `false`.
+ * @return The smallest index where `conditionFn(i)` is true. If no such index exists, returns
+ * `length`.
+ * @example
+ * const arr = [1, 3, 5, 7, 10, 15, 20];
+ * const result = binarySearch(arr.length, (i) => arr[i] >= 10);
+ * console.log(result); // Output: 4 (since arr[4] is 10).
+ */
+const binarySearch = (length: number, conditionFn: (index: number) => boolean): number => {
+    // Generic implementation based on Go standard library implementation.
+    // Reference: https://pkg.go.dev/sort#Search
+    let i = 0;
+    let j = length;
+
+    while (i < j) {
+        const mid = Math.floor((i + j) / 2);
+
+        if (false === conditionFn(mid)) {
+            i = mid + 1;
+        } else {
+            j = mid;
+        }
+    }
+
+    return i;
+};
+
+/**
+ * Finds the largest index `i` in a sorted array `data` such that `data[i] <= target`. Uses binary
+ * search for efficiency.
+ *
+ * @param data A number array sorted in ascending order.
+ * @param target
+ * @return The largest index where `data[i] <= target`. There are 2 edge cases where returns:
+ * - 0 if `target` is less than `data[0]`.
+ * - `null` if array is empty.
+ * @example
+ * const arr = [2, 3, 5, 7, 10, 15, 20];
+ * const result = getLargestIdxLte(arr, 8);
+ * console.log(result); // Output: 3 (since arr[3] is 7).
+ */
+const getLargestIdxLte = (data: number[], target: number): Nullable<number> => {
+    const {length} = data;
+
+    if (0 === length) {
+        return null;
+    }
+
+    // Binary search to find the first index where data[i] > target.
+    const firstGreaterIdx: number = binarySearch(length, (i) => data[i] as number > target);
+
+    if (0 === firstGreaterIdx) {
+        return 0;
+    }
+
+    return firstGreaterIdx - 1;
+};
+
 /**
  * Finds the key in a map based on the provided value.
  *
@@ -38,7 +119,10 @@ const getMapValueWithNearestLessThanOrEqualKey = <T>(
         map.get(lowerBoundKey) as T;
 };
 
+
 export {
+    getLargestIdxLte,
     getMapKeyByValue,
     getMapValueWithNearestLessThanOrEqualKey,
+    isWithinBounds,
 };