feat(URL): Support seeking logs by timestamp via URL parameter (resolves #117).

src/components/AppController.tsx

@@ -79,9 +79,10 @@ interface AppControllerProps {
  * @param props.children
  * @return
  */
+// eslint-disable-next-line max-lines-per-function,max-statements
 const AppController = ({children}: AppControllerProps) => {
     const {postPopUp} = useContext(NotificationContext);
-    const {filePath, isPrettified, logEventNum} = useContext(UrlContext);
+    const {filePath, isPrettified, logEventNum, timestamp} = useContext(UrlContext);
 
     // States
     const setLogEventNum = useContextStore((state) => state.setLogEventNum);
@@ -97,6 +98,7 @@ const AppController = ({children}: AppControllerProps) => {
     // Refs
     const isPrettifiedRef = useRef<boolean>(isPrettified ?? false);
     const logEventNumRef = useRef(logEventNum);
+    const timestampRef = useRef(timestamp);
 
     // Synchronize `logEventNumRef` with `logEventNum`.
     useEffect(() => {
@@ -118,6 +120,37 @@ const AppController = ({children}: AppControllerProps) => {
         setIsPrettified,
     ]);
 
+    // On `timestamp` update, findNearestLogEventByTimestamp and clear itself from URL.
+    useEffect(() => {
+        if (null === timestamp) {
+            return;
+        }
+
+        (async () => {
+            const cursor: CursorType = {
+                code: CURSOR_CODE.TIMESTAMP,
+                args: {timestamp: timestamp},
+            };
+
+            const pageData = await logFileManagerProxy.loadPage(cursor, isPrettifiedRef.current);
+            updatePageData(pageData);
+        })().catch((e: unknown) => {
+            console.error(e);
+            postPopUp({
+                level: LOG_LEVEL.ERROR,
+                message: String(e),
+                timeoutMillis: DO_NOT_TIMEOUT_VALUE,
+                title: "Action failed",
+            });
+        });
+        updateWindowUrlHashParams({timestamp: null});
+    }, [
+        logFileManagerProxy,
+        postPopUp,
+        updatePageData,
+        timestamp,
+    ]);
+
     // On `logEventNum` update, clamp it then switch page if necessary or simply update the URL.
     useEffect(() => {
         if (0 === numEvents || URL_HASH_PARAMS_DEFAULT.logEventNum === logEventNum) {
@@ -174,6 +207,12 @@ const AppController = ({children}: AppControllerProps) => {
                 args: {eventNum: logEventNumRef.current},
             };
         }
+        if (URL_HASH_PARAMS_DEFAULT.timestamp !== timestampRef.current) {
+            cursor = {
+                code: CURSOR_CODE.TIMESTAMP,
+                args: {timestamp: timestampRef.current},
+            };
+        }
         loadFile(filePath, cursor);
     }, [
         filePath,

src/contexts/UrlContextProvider.tsx

@@ -32,6 +32,7 @@ const URL_SEARCH_PARAMS_DEFAULT = Object.freeze({
 const URL_HASH_PARAMS_DEFAULT = Object.freeze({
     [HASH_PARAM_NAMES.IS_PRETTIFIED]: false,
     [HASH_PARAM_NAMES.LOG_EVENT_NUM]: null,
+    [HASH_PARAM_NAMES.TIMESTAMP]: null,
 });
 
 /**
@@ -210,12 +211,19 @@ const getWindowUrlHashParams = () => {
         structuredClone(URL_HASH_PARAMS_DEFAULT);
     const hashParams = new URLSearchParams(window.location.hash.substring(1));
 
-    const logEventNum = hashParams.get(HASH_PARAM_NAMES.LOG_EVENT_NUM);
-    if (null !== logEventNum) {
-        const parsed = Number(logEventNum);
-        urlHashParams[HASH_PARAM_NAMES.LOG_EVENT_NUM] = Number.isNaN(parsed) ?
-            null :
-            parsed;
+    const numberHashParamNames = [
+        HASH_PARAM_NAMES.LOG_EVENT_NUM,
+        HASH_PARAM_NAMES.TIMESTAMP,
+    ];
+
+    for (const paramName of numberHashParamNames) {
+        const hashParam = hashParams.get(paramName);
+        if (null !== hashParam) {
+            const parsed = Number(hashParam);
+            urlHashParams[paramName] = Number.isNaN(parsed) ?
+                null :
+                parsed;
+        }
     }
 
     const isPrettified = hashParams.get(HASH_PARAM_NAMES.IS_PRETTIFIED);

src/services/LogFileManager/index.ts

@@ -491,26 +491,32 @@ class LogFileManager {
      */
     #getCursorData (cursor: CursorType, numActiveEvents: number): CursorData {
         const {code, args} = cursor;
-        switch (code) {
-            case CURSOR_CODE.PAGE_NUM:
-                return getPageNumCursorData(
-                    args.pageNum,
-                    args.eventPositionOnPage,
-                    numActiveEvents,
-                    this.#pageSize,
-                );
-            case CURSOR_CODE.LAST_EVENT:
-                return getLastEventCursorData(numActiveEvents, this.#pageSize);
-            case CURSOR_CODE.EVENT_NUM:
-                return getEventNumCursorData(
-                    args.eventNum,
-                    numActiveEvents,
-                    this.#pageSize,
-                    this.#decoder.getFilteredLogEventMap(),
-                );
-            default:
-                throw new Error(`Unsupported cursor type: ${code}`);
+
+        let eventNum: number = 0;
+        if (CURSOR_CODE.PAGE_NUM === code) {
+            return getPageNumCursorData(
+                args.pageNum,
+                args.eventPositionOnPage,
+                numActiveEvents,
+                this.#pageSize,
+            );
+        } else if (CURSOR_CODE.LAST_EVENT === code) {
+            return getLastEventCursorData(numActiveEvents, this.#pageSize);
+        } else if (CURSOR_CODE.EVENT_NUM === code) {
+            ({eventNum} = args);
+        } else {
+            const eventIdx = this.#decoder.findNearestLogEventByTimestamp(args.timestamp);
+            if (null !== eventIdx) {
+                eventNum = eventIdx + 1;
+            }
         }
+
+        return getEventNumCursorData(
+            eventNum,
+            numActiveEvents,
+            this.#pageSize,
+            this.#decoder.getFilteredLogEventMap(),
+        );
     }
 }
 

src/services/decoders/ClpIrDecoder/index.ts

@@ -106,6 +106,10 @@ class ClpIrDecoder implements Decoder {
         return this.#streamReader.getFilteredLogEventMap();
     }
 
+    findNearestLogEventByTimestamp (timestamp: number): Nullable<number> {
+        return this.#streamReader.findNearestLogEventByTimestamp(BigInt(timestamp));
+    }
+
     setLogLevelFilter (logLevelFilter: LogLevelFilter): boolean {
         this.#streamReader.filterLogEvents(logLevelFilter);
 

src/services/decoders/JsonlDecoder/index.ts

@@ -123,6 +123,32 @@ class JsonlDecoder implements Decoder {
         return results;
     }
 
+    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);
+            // 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;
+    }
+
     /**
      * Parses each line from the data array and buffers it internally.
      *

src/typings/decoders.ts

@@ -98,6 +98,25 @@ interface Decoder {
         endIdx: number,
         useFilter: boolean
     ): Nullable<DecodeResult[]>;
+
+    /**
+     * Finds the log event, L, where if we assume:
+     *
+     * - the collection of log events is sorted in chronological order;
+     * - and we insert a marker log event, M, with timestamp `timestamp` into the collection (if log
+     *   events with timestamp `timestamp` already exist in the collection, M should be inserted
+     *   after them).
+     *
+     * L is the event just before M, if M is not the first event in the collection; otherwise L is
+     * the event just after M.
+     *
+     * NOTE: If the collection of log events isn't in chronological order, this method has undefined
+     * behaviour.
+     *
+     * @param timestamp
+     * @return The index of the log event L.
+     */
+    findNearestLogEventByTimestamp(timestamp: number): Nullable<number>;
 }
 
 export type {

src/typings/url.ts

@@ -8,6 +8,7 @@ enum SEARCH_PARAM_NAMES {
 enum HASH_PARAM_NAMES {
     LOG_EVENT_NUM = "logEventNum",
     IS_PRETTIFIED = "isPrettified",
+    TIMESTAMP = "timestamp",
 }
 
 interface UrlSearchParams {
@@ -17,6 +18,7 @@ interface UrlSearchParams {
 interface UrlHashParams {
     [HASH_PARAM_NAMES.IS_PRETTIFIED]: boolean;
     [HASH_PARAM_NAMES.LOG_EVENT_NUM]: number;
+    [HASH_PARAM_NAMES.TIMESTAMP]: number;
 }
 
 type UrlSearchParamUpdatesType = {