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

package.json

@@ -30,7 +30,7 @@
     "@mui/icons-material": "^6.4.1",
     "@mui/joy": "^5.0.0-beta.51",
     "axios": "^1.7.9",
-    "clp-ffi-js": "^0.3.4",
+    "clp-ffi-js": "^0.3.5",
     "dayjs": "^1.11.13",
     "monaco-editor": "0.50.0",
     "react": "^19.0.0",

src/contexts/StateContextProvider.tsx

@@ -247,7 +247,7 @@ const updateUrlIfEventOnPage = (
 // eslint-disable-next-line max-lines-per-function, max-statements
 const StateContextProvider = ({children}: StateContextProviderProps) => {
     const {postPopUp} = useContext(NotificationContext);
-    const {filePath, logEventNum} = useContext(UrlContext);
+    const {filePath, logEventNum, timestamp} = useContext(UrlContext);
 
     // States
     const [exportProgress, setExportProgress] =
@@ -273,6 +273,7 @@ const StateContextProvider = ({children}: StateContextProviderProps) => {
     const mainWorkerRef = useRef<null | Worker>(null);
     const numPagesRef = useRef<number>(numPages);
     const pageNumRef = useRef<number>(pageNum);
+    const timestampRef = useRef(timestamp);
     const uiStateRef = useRef<UI_STATE>(uiState);
 
     const handleMainWorkerResp = useCallback((ev: MessageEvent<MainWorkerRespMessage>) => {
@@ -460,6 +461,11 @@ const StateContextProvider = ({children}: StateContextProviderProps) => {
         logEventNumRef.current = logEventNum;
     }, [logEventNum]);
 
+    // Synchronize `timestampRef` with `timestamp`.
+    useEffect(() => {
+        timestampRef.current = timestamp;
+    }, [timestamp]);
+
     // Synchronize `pageNumRef` with `pageNum`.
     useEffect(() => {
         pageNumRef.current = pageNum;
@@ -479,13 +485,21 @@ const StateContextProvider = ({children}: StateContextProviderProps) => {
         }
     }, [uiState]);
 
-    // On `logEventNum` update, clamp it then switch page if necessary or simply update the URL.
     useEffect(() => {
-        if (null === mainWorkerRef.current) {
+        if (null === mainWorkerRef.current || null === timestamp) {
             return;
         }
 
-        if (URL_HASH_PARAMS_DEFAULT.logEventNum === logEventNum) {
+        loadPageByCursor(mainWorkerRef.current, {
+            code: CURSOR_CODE.TIMESTAMP,
+            args: {timestamp: timestamp},
+        });
+        updateWindowUrlHashParams({timestamp: null});
+    }, [timestamp]);
+
+    // On `logEventNum` update, clamp it then switch page if necessary or simply update the URL.
+    useEffect(() => {
+        if (null === mainWorkerRef.current || URL_HASH_PARAMS_DEFAULT.logEventNum === logEventNum) {
             return;
         }
 
@@ -524,6 +538,12 @@ const StateContextProvider = ({children}: StateContextProviderProps) => {
                 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

@@ -31,6 +31,7 @@ const URL_SEARCH_PARAMS_DEFAULT = Object.freeze({
  */
 const URL_HASH_PARAMS_DEFAULT = Object.freeze({
     [HASH_PARAM_NAMES.LOG_EVENT_NUM]: null,
+    [HASH_PARAM_NAMES.TIMESTAMP]: null,
 });
 
 /**
@@ -204,12 +205,17 @@ const getWindowUrlHashParams = () => {
     );
     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;
+        }
     }
 
     return urlHashParams;

src/services/LogFileManager/index.ts

@@ -433,26 +433,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.ts

@@ -77,6 +77,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

@@ -122,6 +122,27 @@ 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;
+            }
+        }
+
+        return high;
+    }
+
     /**
      * Parses each line from the data array and buffers it internally.
      *
@@ -214,7 +235,7 @@ class JsonlDecoder implements Decoder {
      * @return The decoded log event.
      */
     #decodeLogEvent = (logEventIdx: number): DecodeResult => {
-        let timestamp: number;
+        let timestamp: bigint;
         let message: string;
         let logLevel: LOG_LEVEL;
 
@@ -231,7 +252,7 @@ class JsonlDecoder implements Decoder {
             const logEvent = this.#logEvents[logEventIdx] as LogEvent;
             logLevel = logEvent.level;
             message = this.#formatter.formatLogEvent(logEvent);
-            timestamp = logEvent.timestamp.valueOf();
+            timestamp = BigInt(logEvent.timestamp.valueOf());
         }
 
         return [

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/logs.ts

@@ -43,7 +43,7 @@ const LOG_LEVEL_VALUES = Object.freeze(
 
 const MAX_LOG_LEVEL = Math.max(...LOG_LEVEL_VALUES);
 
-const INVALID_TIMESTAMP_VALUE = 0;
+const INVALID_TIMESTAMP_VALUE = 0n;
 
 
 export type {

src/typings/url.ts

@@ -7,6 +7,7 @@ enum SEARCH_PARAM_NAMES {
 
 enum HASH_PARAM_NAMES {
     LOG_EVENT_NUM = "logEventNum",
+    TIMESTAMP = "timestamp",
 }
 
 interface UrlSearchParams {
@@ -15,6 +16,7 @@ interface UrlSearchParams {
 
 interface UrlHashParams {
     logEventNum: number;
+    timestamp: number;
 }
 
 type UrlSearchParamUpdatesType = {