feat: Add support for finding the log event that's closest to a target timestamp.

src/clp_ffi_js/ir/StreamReader.cpp

@@ -129,6 +129,7 @@ EMSCRIPTEN_BINDINGS(ClpStreamReader) {
             "Array<[string, bigint, number, number]>"
     );
     emscripten::register_type<clp_ffi_js::ir::FilteredLogEventMapTsType>("number[] | null");
+    emscripten::register_type<clp_ffi_js::ir::LogEventIdxTsType>("number | null");
     emscripten::class_<clp_ffi_js::ir::StreamReader>("ClpStreamReader")
             .constructor(
                     &clp_ffi_js::ir::StreamReader::create,
@@ -145,7 +146,11 @@ EMSCRIPTEN_BINDINGS(ClpStreamReader) {
             )
             .function("filterLogEvents", &clp_ffi_js::ir::StreamReader::filter_log_events)
             .function("deserializeStream", &clp_ffi_js::ir::StreamReader::deserialize_stream)
-            .function("decodeRange", &clp_ffi_js::ir::StreamReader::decode_range);
+            .function("decodeRange", &clp_ffi_js::ir::StreamReader::decode_range)
+            .function(
+                    "getLogEventIdxByTimestamp",
+                    &clp_ffi_js::ir::StreamReader::get_log_event_idx_by_timestamp
+            );
 }
 }  // namespace
 

src/clp_ffi_js/ir/StreamReader.hpp

@@ -11,6 +11,7 @@
 #include <type_traits>
 #include <vector>
 
+#include <clp/ir/types.hpp>
 #include <clp/streaming_compression/zstd/Decompressor.hpp>
 #include <clp/type_utils.hpp>
 #include <emscripten/em_asm.h>
@@ -29,6 +30,7 @@ EMSCRIPTEN_DECLARE_VAL_TYPE(ReaderOptions);
 // JS types used as outputs
 EMSCRIPTEN_DECLARE_VAL_TYPE(DecodedResultsTsType);
 EMSCRIPTEN_DECLARE_VAL_TYPE(FilteredLogEventMapTsType);
+EMSCRIPTEN_DECLARE_VAL_TYPE(LogEventIdxTsType);
 
 enum class StreamType : uint8_t {
     Structured,
@@ -123,6 +125,17 @@ class StreamReader {
      */
     [[nodiscard]] virtual auto decode_range(size_t begin_idx, size_t end_idx, bool use_filter) const
             -> DecodedResultsTsType = 0;
+    /**
+     * Finds the index of the last log event that matches or next to the given timestamp.
+     *
+     * @param timestamp The timestamp to search for, in milliseconds since the Unix epoch.
+     * @return The last index of the log event whose timestamp is smaller than or equal to the
+     * `timestamp`.
+     * @return `0` if all log event timestamps are larger than the target.
+     * @return null if no log event exists in the stream.
+     */
+    [[nodiscard]] virtual auto get_log_event_idx_by_timestamp(clp::ir::epoch_time_ms_t timestamp
+    ) -> LogEventIdxTsType = 0;
 
 protected:
     explicit StreamReader() = default;
@@ -172,6 +185,20 @@ class StreamReader {
             LogLevelFilterTsType const& log_level_filter,
             LogEvents<LogEvent> const& log_events
     ) -> void;
+
+    /**
+     * Templated implementation of `get_log_event_idx_by_timestamp`.
+     *
+     * @tparam LogEvent
+     * @param log_events
+     * @param timestamp
+     * @return the best matched log event index.
+     */
+    template <typename LogEvent>
+    auto generic_get_log_event_idx_by_timestamp(
+            LogEvents<LogEvent> const& log_events,
+            clp::ir::epoch_time_ms_t timestamp
+    ) -> LogEventIdxTsType;
 };
 
 template <typename LogEvent, typename ToStringFunc>
@@ -258,6 +285,33 @@ auto StreamReader::generic_filter_log_events(
         }
     }
 }
+
+template <typename LogEvent>
+auto StreamReader::generic_get_log_event_idx_by_timestamp(
+        LogEvents<LogEvent> const& log_events,
+        clp::ir::epoch_time_ms_t timestamp
+) -> LogEventIdxTsType {
+    if (log_events.empty()) {
+        return LogEventIdxTsType{emscripten::val::null()};
+    }
+
+    auto first_greater_it{std::upper_bound(
+            log_events.begin(),
+            log_events.end(),
+            timestamp,
+            [](clp::ir::epoch_time_ms_t ts, LogEventWithFilterData<LogEvent> const& log_event) {
+                return ts < log_event.get_timestamp();
+            }
+    )};
+
+    if (first_greater_it == log_events.begin()) {
+        return LogEventIdxTsType{emscripten::val(0)};
+    }
+
+    auto const first_greater_idx{std::distance(log_events.begin(), first_greater_it)};
+
+    return LogEventIdxTsType{emscripten::val(first_greater_idx - 1)};
+}
 }  // namespace clp_ffi_js::ir
 
 #endif  // CLP_FFI_JS_IR_STREAMREADER_HPP

src/clp_ffi_js/ir/StructuredIrStreamReader.cpp

@@ -11,6 +11,7 @@
 #include <clp/Array.hpp>
 #include <clp/ErrorCode.hpp>
 #include <clp/ffi/ir_stream/Deserializer.hpp>
+#include <clp/ir/types.hpp>
 #include <clp/TraceableException.hpp>
 #include <emscripten/val.h>
 #include <spdlog/spdlog.h>
@@ -147,6 +148,15 @@ auto StructuredIrStreamReader::decode_range(size_t begin_idx, size_t end_idx, bo
     );
 }
 
+auto StructuredIrStreamReader::get_log_event_idx_by_timestamp(
+        clp::ir::epoch_time_ms_t const timestamp
+) -> LogEventIdxTsType {
+    return generic_get_log_event_idx_by_timestamp(
+            *m_deserialized_log_events,
+            timestamp
+    );
+}
+
 StructuredIrStreamReader::StructuredIrStreamReader(
         StreamReaderDataContext<StructuredIrDeserializer>&& stream_reader_data_context,
         std::shared_ptr<StructuredLogEvents> deserialized_log_events

src/clp_ffi_js/ir/StructuredIrStreamReader.hpp

@@ -8,6 +8,7 @@
 #include <clp/Array.hpp>
 #include <clp/ffi/ir_stream/Deserializer.hpp>
 #include <clp/ffi/SchemaTree.hpp>
+#include <clp/ir/types.hpp>
 #include <emscripten/val.h>
 
 #include <clp_ffi_js/ir/LogEventWithFilterData.hpp>
@@ -74,6 +75,9 @@ class StructuredIrStreamReader : public StreamReader {
     [[nodiscard]] auto decode_range(size_t begin_idx, size_t end_idx, bool use_filter) const
             -> DecodedResultsTsType override;
 
+    [[nodiscard]] auto get_log_event_idx_by_timestamp(clp::ir::epoch_time_ms_t timestamp
+    ) -> LogEventIdxTsType override;
+
 private:
     // Constructor
     explicit StructuredIrStreamReader(

src/clp_ffi_js/ir/UnstructuredIrStreamReader.cpp

@@ -158,6 +158,15 @@ auto UnstructuredIrStreamReader::decode_range(size_t begin_idx, size_t end_idx,
     );
 }
 
+auto UnstructuredIrStreamReader::get_log_event_idx_by_timestamp(
+        clp::ir::epoch_time_ms_t const timestamp
+) -> LogEventIdxTsType {
+    return generic_get_log_event_idx_by_timestamp(
+            m_encoded_log_events,
+            timestamp
+    );
+}
+
 UnstructuredIrStreamReader::UnstructuredIrStreamReader(
         StreamReaderDataContext<UnstructuredIrDeserializer>&& stream_reader_data_context
 )

src/clp_ffi_js/ir/UnstructuredIrStreamReader.hpp

@@ -71,6 +71,9 @@ class UnstructuredIrStreamReader : public StreamReader {
     [[nodiscard]] auto decode_range(size_t begin_idx, size_t end_idx, bool use_filter) const
             -> DecodedResultsTsType override;
 
+    [[nodiscard]] auto get_log_event_idx_by_timestamp(clp::ir::epoch_time_ms_t timestamp
+    ) -> LogEventIdxTsType override;
+
 private:
     // Constructor
     explicit UnstructuredIrStreamReader(