feat(sfa): Add API for decoding all log events.

src/clp_ffi_js/sfa/ClpArchiveReader.ts

@@ -1,3 +1,4 @@
+import {LogEvent} from "./LogEvent.js";
 import {getModule} from "./module.js";
 import type {FileInfo} from "./types.js";
 
@@ -65,6 +66,18 @@ class ClpArchiveReader {
         return this.#getWasmReader().getFileInfos();
     }
 
+    /**
+     * Decodes all log events in global log-event-index order.
+     *
+     * @return Decoded log events.
+     * @throws {Error} If the reader has been closed.
+     */
+    decodeAll (): LogEvent[] {
+        return this.#getWasmReader()
+            .decodeAll()
+            .map((rawEvent) => new LogEvent(rawEvent));
+    }
+
     /**
      * Releases the underlying WASM resources. After calling this method, the reader is no longer
      * usable and any subsequent method calls will throw.

src/clp_ffi_js/sfa/LogEvent.ts

@@ -0,0 +1,55 @@
+import type {
+    JsonObject,
+    JsonValue,
+    RawLogEvent,
+} from "./types.js";
+import {isJsonObject} from "./utils.js";
+
+
+/**
+ * Single log event from a CLP archive.
+ */
+class LogEvent implements RawLogEvent {
+    /**
+     * Global log event index.
+     */
+    declare readonly logEventIdx: bigint;
+
+    /**
+     * Epoch timestamp.
+     */
+    declare readonly timestamp: bigint;
+
+    /**
+     * Serialized message string.
+     */
+    declare readonly message: string;
+
+    /**
+     * @param rawEvent Raw log event interface returned by the WASM binding.
+     */
+    constructor (rawEvent: RawLogEvent) {
+        Object.assign(this, rawEvent);
+    }
+
+    /**
+     * Parses the serialized message as a JSON object.
+     *
+     * @return The parsed object, or null if parsing fails or produces a non-object.
+     */
+    getKvPairs (): Readonly<JsonObject> | null {
+        try {
+            const kvPairs = JSON.parse(this.message) as JsonValue;
+            if (false === isJsonObject(kvPairs)) {
+                return null;
+            }
+
+            return kvPairs;
+        } catch {
+            return null;
+        }
+    }
+}
+
+
+export {LogEvent};

src/clp_ffi_js/sfa/SfaReader.cpp

@@ -66,13 +66,40 @@ auto SfaReader::get_file_infos() const -> FileInfoArrayTsType {
     }
     return FileInfoArrayTsType{file_infos};
 }
+
+auto SfaReader::decode_all() -> LogEventArrayTsType {
+    auto decoded_result{m_reader.decode_all()};
+    if (decoded_result.has_error()) {
+        auto const error{decoded_result.error()};
+        auto const err_msg{fmt::format(
+                "Failed to decode SFA archive: {} - {}.",
+                error.category().name(),
+                error.message()
+        )};
+        SPDLOG_ERROR("{}", err_msg);
+        throw std::runtime_error{err_msg};
+    }
+
+    auto decoded_events{emscripten::val::array()};
+    for (auto const& event : decoded_result.value()) {
+        auto entry{emscripten::val::object()};
+        entry.set("logEventIdx", emscripten::val(event.get_log_event_idx()));
+        entry.set("timestamp", emscripten::val(event.get_timestamp()));
+        entry.set("message", emscripten::val(event.get_message()));
+        decoded_events.call<void>("push", entry);
+    }
+    return LogEventArrayTsType{decoded_events};
+}
 }  // namespace clp_ffi_js::sfa
 
 EMSCRIPTEN_BINDINGS(SfaReader) {
     emscripten::register_type<clp_ffi_js::sfa::FileInfoArrayTsType>(
             "Array<{fileName: string, logEventIdxStart: bigint, logEventIdxEnd: bigint, "
             "logEventCount: bigint}>"
     );
+    emscripten::register_type<clp_ffi_js::sfa::LogEventArrayTsType>(
+            "Array<{logEventIdx: bigint, timestamp: bigint, message: string}>"
+    );
 
     emscripten::class_<clp_ffi_js::sfa::SfaReader>("ClpSfaReader")
             .constructor(
@@ -81,5 +108,6 @@ EMSCRIPTEN_BINDINGS(SfaReader) {
             )
             .function("getEventCount", &clp_ffi_js::sfa::SfaReader::get_event_count)
             .function("getFileNames", &clp_ffi_js::sfa::SfaReader::get_file_names)
-            .function("getFileInfos", &clp_ffi_js::sfa::SfaReader::get_file_infos);
+            .function("getFileInfos", &clp_ffi_js::sfa::SfaReader::get_file_infos)
+            .function("decodeAll", &clp_ffi_js::sfa::SfaReader::decode_all);
 }

src/clp_ffi_js/sfa/SfaReader.hpp

@@ -12,6 +12,7 @@
 
 namespace clp_ffi_js::sfa {
 EMSCRIPTEN_DECLARE_VAL_TYPE(FileInfoArrayTsType);
+EMSCRIPTEN_DECLARE_VAL_TYPE(LogEventArrayTsType);
 
 class SfaReader {
 public:
@@ -31,6 +32,8 @@ class SfaReader {
 
     [[nodiscard]] auto get_file_infos() const -> FileInfoArrayTsType;
 
+    [[nodiscard]] auto decode_all() -> LogEventArrayTsType;
+
 private:
     explicit SfaReader(clp_s::ffi::sfa::ClpArchiveReader&& reader) : m_reader(std::move(reader)) {}
 

src/clp_ffi_js/sfa/index.ts

@@ -1,5 +1,8 @@
 export {ClpArchiveReader} from "./ClpArchiveReader.js";
-export type {FileInfo} from "./types.js";
+export {LogEvent} from "./LogEvent.js";
+export type {
+    FileInfo, JsonObject, JsonValue,
+} from "./types.js";
 export {
     CLP_SFA_MAGIC_BYTES,
     isClpJsonSingleFileArchive,

src/clp_ffi_js/sfa/types.ts

@@ -8,4 +8,39 @@ interface FileInfo {
     logEventCount: bigint;
 }
 
-export type {FileInfo};
+/**
+ * Data used to construct a `LogEvent`.
+ */
+interface RawLogEvent {
+    logEventIdx: bigint;
+    timestamp: bigint;
+    message: string;
+}
+
+/**
+ * Type for values in a JSON object/array.
+ * Reference: https://www.json.org/json-en.html
+ */
+type JsonValue = null |
+    string |
+    number |
+    boolean |
+    {
+        [key: string]: JsonValue;
+    } |
+    Array<JsonValue>;
+
+/**
+ * JSON object type.
+ * Reference: https://www.json.org/json-en.html
+ */
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+
+export type {
+    FileInfo,
+    JsonObject,
+    JsonValue,
+    RawLogEvent,
+};

src/clp_ffi_js/sfa/utils.ts

@@ -1,3 +1,9 @@
+import type {
+    JsonObject,
+    JsonValue,
+} from "./types.js";
+
+
 /**
  * Starting byte sequence that identifies a CLP JSON single-file archive (SFA).
  */
@@ -24,7 +30,19 @@ const isClpJsonSingleFileArchive = (input: ArrayBuffer | ArrayBufferView): boole
     return CLP_SFA_MAGIC_BYTES.every((value, index) => bytes[index] === value);
 };
 
+/**
+ * Determines whether the given value is a `JsonObject` and applies a TypeScript narrowing
+ * conversion if so.
+ *
+ * @param value
+ * @return A TypeScript type predicate indicating whether `value` is a `JsonObject`.
+ */
+const isJsonObject = (value: JsonValue): value is JsonObject => {
+    return "object" === typeof value && null !== value && false === Array.isArray(value);
+};
+
 export {
     CLP_SFA_MAGIC_BYTES,
     isClpJsonSingleFileArchive,
+    isJsonObject,
 };