feat(sfa): ClpArchiveReader prototype.

CMakeLists.txt

@@ -18,7 +18,7 @@ if("${CLP_FFI_JS_PACKAGE_JSON_CONTENT}" MATCHES "\"name\":[ ]*\"([^\"]+)\"")
 else()
     set(CLP_FFI_JS_PROJECT_NAME "clp-ffi-js")
 endif()
-if("${CLP_FFI_JS_PACKAGE_JSON_CONTENT}" MATCHES "\"version\":[ ]*\"([^\"]+)\"")
+if("${CLP_FFI_JS_PACKAGE_JSON_CONTENT}" MATCHES "\"version\":[ ]*\"([0-9]+\\.[0-9]+\\.[0-9]+)")
     set(CLP_FFI_JS_VERSION "${CMAKE_MATCH_1}")
 else()
     set(CLP_FFI_JS_VERSION "0.0.0")

eslint.config.mjs

@@ -8,7 +8,9 @@ const EslintConfig = [
         ignores: [
             "build/",
             "dist/",
+            "docs/",
             "node_modules/",
+            "test/",
         ],
     },
     CommonConfig,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clp-ffi-js",
-  "version": "0.6.1",
+  "version": "0.7.0-beta.1",
   "description": "clp-ffi-js is a JavaScript FFI library for CLP.",
   "author": "YScope Inc. <dev@yscope.com>",
   "license": "Apache-2.0",
@@ -55,7 +55,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.19.9",
+    "@types/node": "^22.19.15",
     "@vitest/browser-playwright": "^4.0.18",
     "eslint": "^9.39.2",
     "eslint-config-yscope": "^1.1.2",

src/clp_ffi_js/constants.hpp

@@ -4,7 +4,8 @@
 #include <array>
 #include <cstdint>
 #include <string_view>
-#include <type_utils.hpp>
+
+#include <clp/type_utils.hpp>
 
 namespace clp_ffi_js {
 /**

src/clp_ffi_js/ir/StructuredIrUnitHandler.cpp

@@ -8,14 +8,14 @@
 #include <optional>
 #include <string>
 #include <string_view>
-#include <type_utils.hpp>
 #include <utility>
 
 #include <clp/ffi/ir_stream/decoding_methods.hpp>
 #include <clp/ffi/SchemaTree.hpp>
 #include <clp/ffi/Value.hpp>
 #include <clp/ir/types.hpp>
 #include <clp/time_types.hpp>
+#include <clp/type_utils.hpp>
 #include <emscripten/val.h>
 #include <spdlog/spdlog.h>
 

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,26 @@ 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() as Array<{
+            logEventIdx: bigint;
+            message: string;
+            timestamp: bigint;
+        }>).map((rawEvent) => {
+            return new LogEvent(
+                rawEvent.logEventIdx,
+                rawEvent.timestamp,
+                rawEvent.message
+            );
+        });
+    }
+
     /**
      * 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,39 @@
+import type {FieldValue} from "./types.js";
+
+
+/**
+ * Single log event from a CLP archive.
+ */
+class LogEvent {
+    readonly logEventIdx: bigint;
+
+    readonly timestamp: bigint;
+
+    readonly message: string;
+
+    /**
+     * @param logEventIdx Global log event index.
+     * @param timestamp Epoch timestamp.
+     * @param message Serialized message string.
+     */
+    constructor (logEventIdx: bigint, timestamp: bigint, message: string) {
+        this.logEventIdx = logEventIdx;
+        this.timestamp = timestamp;
+        this.message = message;
+    }
+
+    /**
+     * Returns the key-value pairs of this log event by parsing the message as JSON.
+     *
+     * @return The key-value pairs, or null if the message is not valid JSON.
+     */
+    getKvPairs (): Readonly<{[key: string]: FieldValue}> | null {
+        try {
+            return JSON.parse(this.message) as {[key: string]: FieldValue};
+        } 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,2 +1,3 @@
 export {ClpArchiveReader} from "./ClpArchiveReader.js";
-export type {FileInfo} from "./types.js";
+export {LogEvent} from "./LogEvent.js";
+export type {FieldValue, FileInfo} from "./types.js";

src/clp_ffi_js/sfa/types.ts

@@ -8,4 +8,15 @@ interface FileInfo {
     logEventCount: bigint;
 }
 
-export type {FileInfo};
+type FieldValue =
+    number |
+    string |
+    boolean |
+    null |
+    {[key: string]: FieldValue} |
+    FieldValue[];
+
+export type {
+    FieldValue,
+    FileInfo,
+};

src/clp_ffi_js/utils.ts

@@ -0,0 +1,43 @@
+import NodeModuleFactory, {type MainModule} from "#clp-ffi-js/node";
+import WorkerModuleFactory from "#clp-ffi-js/worker";
+
+
+/**
+ * Detects whether the current runtime is Node.js.
+ *
+ * @return True if running in Node.js.
+ */
+const isNodeRuntime = (): boolean => {
+    const maybeWindow = (globalThis as {window?: unknown}).window;
+    if ("undefined" !== typeof maybeWindow) {
+        return false;
+    }
+
+    const maybeProcess = (globalThis as {process?: {versions?: {node?: unknown}}}).process;
+    return "string" === typeof maybeProcess?.versions?.node;
+};
+
+let mainModulePromise: Promise<MainModule> | null = null;
+
+/**
+ * Returns the shared CLP FFI module instance, initializing it lazily once.
+ *
+ * @return A cached `MainModule` promise.
+ */
+const getMainModule = (): Promise<MainModule> => {
+    if (null !== mainModulePromise) {
+        return mainModulePromise;
+    }
+
+    const moduleFactory = (
+        true === isNodeRuntime() ?
+            NodeModuleFactory :
+            WorkerModuleFactory
+    ) as () => Promise<MainModule>;
+
+    mainModulePromise = moduleFactory();
+
+    return mainModulePromise;
+};
+
+export {getMainModule};

taskfile.yaml

@@ -117,6 +117,7 @@ tasks:
     deps: ["deps"]
     cmd: |-
       cmake \
+      -DCLP_FFI_JS_ENABLE_SFA_READER_BINDING=ON \
       -DCLP_FFI_JS_SUPPORTED_ENVIRONMENTS="{{.G_CLP_FFI_JS_ENV_NAMES | join ";"}}" \
       -DCMAKE_TOOLCHAIN_FILE="{{.G_EMSCRIPTEN_CMAKE_TOOLCHAIN_FILE}}" \
       -S "{{.ROOT_DIR}}" \

taskfiles/deps.yaml

@@ -134,9 +134,9 @@ tasks:
     cmds:
       - task: ":utils:remote:download-and-extract-tar"
         vars:
-          FILE_SHA256: "aedfc75767a4b5fe3a970e3c8398fc909bec27f6b6f8e62a78d8344625e3f66e"
+          FILE_SHA256: "248ea1fc4d54cad6433126ff39be649ba40968ef0042a6c977b4a447ca4bf684"
           OUTPUT_DIR: "{{.OUTPUT_DIR}}"
-          URL: "https://github.com/y-scope/clp/archive/f9b9cc0.tar.gz"
+          URL: "https://github.com/y-scope/clp/archive/ec74acc.tar.gz"
       - >-
         echo "set(
         CLP_FFI_JS_CLP_SOURCE_DIRECTORY \"{{.OUTPUT_DIR}}\"