refactor: Extract upper-bound binary search from findNearestLogEventByTimestamp into a function (resolves #343).

src/services/decoders/JsonlDecoder/index.ts

@@ -18,6 +18,7 @@ import {
     LogLevelFilter,
 } from "../../../typings/logs";
 import {getNestedJsonValue} from "../../../utils/js";
+import {upperBoundBinarySearch} from "../../../utils/math";
 import YscopeFormatter from "../../formatters/YscopeFormatter";
 import {parseFilterKeys} from "../utils";
 import {
@@ -139,31 +140,11 @@ class JsonlDecoder implements Decoder {
     }
 
     findNearestLogEventByTimestamp (timestamp: number): Nullable<number> {
-        let low = 0;
-        let high = this.#logEvents.length - 1;
-        if (high < low) {
-            return null;
-        }
-
-        while (low <= high) {
-            const mid = Math.floor((low + high) / 2);
-
-            // `mid` is guaranteed to be within bounds since `low <= high`.
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const midTimestamp = this.#logEvents[mid]!.timestamp.valueOf();
-            if (midTimestamp <= timestamp) {
-                low = mid + 1;
-            } else {
-                high = mid - 1;
-            }
-        }
-
-        // corner case: all log events have timestamps >= timestamp
-        if (0 > high) {
-            return 0;
-        }
-
-        return high;
+        return upperBoundBinarySearch(
+            this.#logEvents,
+            timestamp,
+            (logEvent) => logEvent.timestamp.valueOf()
+        );
     }
 
     /**

src/typings/decoders.ts

@@ -128,7 +128,7 @@ interface Decoder {
      * behaviour.
      *
      * @param timestamp
-     * @return The index of the log event L.
+     * @return The index of the log event L, or null if there are no log events.
      */
     findNearestLogEventByTimestamp(timestamp: number): Nullable<number>;
 }

src/utils/math.ts

@@ -1,3 +1,6 @@
+import {Nullable} from "../typings/common";
+
+
 /**
  * Clamps a number to the given range. E.g. If the number is greater than the range's upper bound,
  * the range's upper bound is returned.
@@ -20,7 +23,50 @@ const clamp = (num: number, min: number, max: number) => Math.min(Math.max(num,
 const getChunkNum =
     (itemNum: number, chunkSize: number) => Math.max(1, Math.ceil(itemNum / chunkSize));
 
+/**
+ * Finds the last element in a sorted collection that is less than or equal to `upperBoundValue`. If
+ * all elements in the collection are greater than `upperBoundValue`, returns the first index of the
+ * collection (i.e., `0`).
+ *
+ * @param array The entire collection in ascending order.
+ * @param upperBoundValue
+ * @param get Function to access an element (or its property) in the collection.
+ * @return The index of the last element less than or equal to `upperBoundValue`, `0` if all
+ * elements are greater, or `null` if the collection is empty.
+ */
+const upperBoundBinarySearch = <T, U>(
+    array: U[],
+    upperBoundValue: T,
+    get: (arrayElement: U) => T,
+): Nullable<number> => {
+    if (0 === array.length) {
+        return null;
+    }
+    let lowIdx = 0;
+    let highIdx = array.length - 1;
+
+    while (lowIdx <= highIdx) {
+        const mid = Math.floor((lowIdx + highIdx) / 2);
+
+        // `mid` is guaranteed to be within bounds since `lowIdx <= highIdx`.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        if (get(array[mid]!) <= upperBoundValue) {
+            lowIdx = mid + 1;
+        } else {
+            highIdx = mid - 1;
+        }
+    }
+
+    // corner case: all values >= upperboundValue
+    if (0 > highIdx) {
+        return 0;
+    }
+
+    return highIdx;
+};
+
 export {
     clamp,
     getChunkNum,
+    upperBoundBinarySearch,
 };

test/utils/math.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable @stylistic/array-element-newline */
 import {
     clamp,
     getChunkNum,
+    upperBoundBinarySearch,
 } from "../../src/utils/math";
 
 
@@ -49,3 +51,59 @@ describe("getChunkNum", () => {
         expect(getChunkNum(20, 4)).toBe(5);
     });
 });
+
+describe("upperBoundBinarySearch", () => {
+    const emptyArray: number[] = [];
+    const singleElementArray = [3];
+    const array = [-5, -3, 0, 1, 1, 8, 8, 8, 100];
+    test("returns null if collection is empty", () => {
+        const result = upperBoundBinarySearch(emptyArray, 5, (arrayElement) => arrayElement);
+        expect(result).toBeNull();
+    });
+    test("returns the first index if upperboundValue < all elements in array", () => {
+        const result = upperBoundBinarySearch(array, -10, (arrayElement) => arrayElement);
+        expect(result).toBe(0);
+    });
+    test("returns the first index if upperboundValue < element in singleElementArray", () => {
+        const result = upperBoundBinarySearch(
+            singleElementArray,
+            -10,
+            (arrayElement) => arrayElement
+        );
+
+        expect(result).toBe(0);
+    });
+    test("returns the last index if upperboundValue > all elements in array", () => {
+        const result = upperBoundBinarySearch(array, 200, (arrayElement) => arrayElement);
+        expect(result).toBe(array.length - 1);
+    });
+    test("returns the last index if upperboundValue > element in singleElementArray", () => {
+        const result = upperBoundBinarySearch(
+            singleElementArray,
+            200,
+            (arrayElement) => arrayElement
+        );
+
+        expect(result).toBe(0);
+    });
+    test("returns the correct index if upperboundValue doesn't match any elements", () => {
+        const result = upperBoundBinarySearch(array, 2, (arrayElement) => arrayElement);
+        expect(result).toBe(4);
+    });
+    test("returns the correct index if upperboundValue matches a unique element", () => {
+        const result = upperBoundBinarySearch(array, 0, (arrayElement) => arrayElement);
+        expect(result).toBe(2);
+    });
+    test("returns the last matched index if upperboundValue matches a duplicated element", () => {
+        const result = upperBoundBinarySearch(array, 8, (arrayElement) => arrayElement);
+        expect(result).toBe(7);
+    });
+    test("returns index 0 if upperboundValue matches the first element", () => {
+        const result = upperBoundBinarySearch(array, -5, (arrayElement) => arrayElement);
+        expect(result).toBe(0);
+    });
+    test("returns the last index if upperboundValue matches the last element", () => {
+        const result = upperBoundBinarySearch(array, 100, (arrayElement) => arrayElement);
+        expect(result).toBe(array.length - 1);
+    });
+});