Add wasm overhead benchmarks

Author: Mik1810

SESSION.md

@@ -862,3 +862,11 @@
 - Decision: Added explicit WASM contract coverage for reachable negative-cycle rejection in Bellman-Ford wrappers.
 - Verified: `bash wasm/scripts/run_wasm_node_contract_tests.sh`; `git diff --check`.
 - Next: Commit, push, and close issue `#157`.
+
+### 2026-05-10 - Issue #80
+
+- Branch/commit:
+- Files: `wasm/benchmarks/native_overhead_bench.cpp`, `wasm/benchmarks/node_overhead_bench.mjs`, `wasm/scripts/run_overhead_benchmarks.sh`, `wasm/package.json`, `wasm/README.md`, `wasm/WASM.md`.
+- Decision: Added a local experimental overhead benchmark path comparing native C++, raw WASM runtime calls, and TypeScript facade calls without storing local results as release claims.
+- Verified: `npm --prefix wasm run build:types`; small `npm --prefix wasm run bench:overhead` smoke; `git diff --check`.
+- Next: Commit, push, and close issue `#80`.

wasm/README.md

@@ -95,6 +95,37 @@ This command builds the wasm module (unless skipped), packs the current
 package, installs that tarball in an isolated fixture consumer, and runs a
 smoke test through the published package entrypoint.
 
+## Local overhead benchmarks
+
+The repository includes a small local benchmark suite for comparing native C++,
+raw WASM runtime calls, and the TypeScript facade on the same machine:
+
+```bash
+cd wasm
+npm run bench:overhead
+```
+
+The runner rebuilds the Node-compatible WASM module, builds a native C++
+benchmark binary, and prints CSV rows for:
+
+- graph construction
+- BFS from one source
+- Dijkstra from one source
+- Floyd-Warshall on a small graph
+- attribute round-trips
+- multigraph edge-ID operations
+
+You can tune the local smoke size with environment variables:
+
+```bash
+NXPP_WASM_BENCH_ITERATIONS=10 NXPP_WASM_BENCH_NODES=500 npm run bench:overhead
+```
+
+These numbers are local diagnostics, not release claims. Small repeated
+operations can be dominated by JS/WASM boundary cost, while larger algorithmic
+calls may amortize that overhead. Publish benchmark results only with the
+exact command, machine context, package version, and reproducible inputs.
+
 ## Publish order (npm first)
 
 Use the package scripts to publish in a deterministic order:

wasm/WASM.md

@@ -104,6 +104,18 @@ Run Node API contract tests:
 bash wasm/scripts/run_wasm_node_contract_tests.sh
 ```
 
+Run local native-vs-WASM overhead benchmarks:
+
+```bash
+bash wasm/scripts/run_overhead_benchmarks.sh
+```
+
+This benchmark path is intentionally local and experimental. It compares native
+C++, raw WASM runtime calls, and the TypeScript facade for representative graph
+construction, traversal, shortest-path, all-pairs, attribute, and multigraph
+edge-ID workloads. Treat its output as reproducible diagnostics only; do not use
+ad hoc local numbers as marketing or release claims.
+
 ## CI behavior
 
 The experimental wasm workflow runs:

wasm/benchmarks/native_overhead_bench.cpp

@@ -0,0 +1,155 @@
+#include <chrono>
+#include <cstddef>
+#include <cstdlib>
+#include <functional>
+#include <iomanip>
+#include <iostream>
+#include <string>
+#include <vector>
+
+#include "include/nxpp.hpp"
+
+namespace {
+
+struct Config {
+    int nodes = 300;
+    int edges = 900;
+    int floyd_nodes = 35;
+    int attr_ops = 1000;
+    int multigraph_edges = 600;
+    int iterations = 5;
+};
+
+template <typename T>
+void consume(const T& value) {
+#if defined(__GNUC__) || defined(__clang__)
+    asm volatile("" : : "g"(&value) : "memory");
+#else
+    (void)value;
+#endif
+}
+
+int read_int_arg(int argc, char** argv, const std::string& name, int fallback) {
+    for (int i = 1; i + 1 < argc; ++i) {
+        if (argv[i] == name) {
+            return std::atoi(argv[i + 1]);
+        }
+    }
+    return fallback;
+}
+
+Config read_config(int argc, char** argv) {
+    Config config;
+    config.nodes = read_int_arg(argc, argv, "--nodes", config.nodes);
+    config.edges = read_int_arg(argc, argv, "--edges", config.edges);
+    config.floyd_nodes = read_int_arg(argc, argv, "--floyd-nodes", config.floyd_nodes);
+    config.attr_ops = read_int_arg(argc, argv, "--attr-ops", config.attr_ops);
+    config.multigraph_edges = read_int_arg(argc, argv, "--multigraph-edges", config.multigraph_edges);
+    config.iterations = read_int_arg(argc, argv, "--iterations", config.iterations);
+    return config;
+}
+
+nxpp::DiGraphInt make_digraph(int nodes, int edges) {
+    nxpp::DiGraphInt graph;
+    for (int node = 0; node < nodes; ++node) {
+        graph.add_node(node);
+    }
+    for (int edge = 0; edge < edges; ++edge) {
+        const int source = edge % nodes;
+        int target = (edge * 37 + 11) % nodes;
+        if (target == source) {
+            target = (target + 1) % nodes;
+        }
+        graph.add_edge(source, target, static_cast<double>((edge % 17) + 1));
+    }
+    return graph;
+}
+
+nxpp::DiGraphInt make_floyd_graph(int nodes) {
+    nxpp::DiGraphInt graph;
+    for (int node = 0; node < nodes; ++node) {
+        graph.add_node(node);
+    }
+    for (int node = 0; node + 1 < nodes; ++node) {
+        graph.add_edge(node, node + 1, 1.0);
+        if (node + 3 < nodes) {
+            graph.add_edge(node, node + 3, 4.0);
+        }
+    }
+    return graph;
+}
+
+template <typename Fn>
+double measure_ms(int iterations, Fn&& fn) {
+    const auto start = std::chrono::steady_clock::now();
+    for (int i = 0; i < iterations; ++i) {
+        fn();
+    }
+    const auto stop = std::chrono::steady_clock::now();
+    return std::chrono::duration<double, std::milli>(stop - start).count();
+}
+
+void print_row(const std::string& workload, int iterations, double total_ms, const std::string& notes) {
+    const double ops_per_second = total_ms > 0.0 ? (static_cast<double>(iterations) * 1000.0 / total_ms) : 0.0;
+    std::cout << "native_cpp," << workload << "," << iterations << ","
+              << std::fixed << std::setprecision(3) << total_ms << ","
+              << std::fixed << std::setprecision(3) << ops_per_second << ","
+              << notes << "\n";
+}
+
+} // namespace
+
+int main(int argc, char** argv) {
+    const Config config = read_config(argc, argv);
+    std::cout << "layer,workload,iterations,total_ms,ops_per_second,notes\n";
+
+    const double construction_ms = measure_ms(config.iterations, [&] {
+        auto graph = make_digraph(config.nodes, config.edges);
+        consume(graph.num_edges());
+    });
+    print_row("construct_digraph", config.iterations, construction_ms, "nodes=" + std::to_string(config.nodes) + ";edges=" + std::to_string(config.edges));
+
+    auto graph = make_digraph(config.nodes, config.edges);
+    const double bfs_ms = measure_ms(config.iterations, [&] {
+        const auto edges = graph.bfs_edges(0);
+        consume(edges.size());
+    });
+    print_row("bfs_edges", config.iterations, bfs_ms, "source=0");
+
+    const double dijkstra_ms = measure_ms(config.iterations, [&] {
+        const auto result = graph.dijkstra_shortest_paths(0);
+        consume(result.distance.size());
+    });
+    print_row("dijkstra_shortest_paths", config.iterations, dijkstra_ms, "source=0");
+
+    auto floyd_graph = make_floyd_graph(config.floyd_nodes);
+    const double floyd_ms = measure_ms(config.iterations, [&] {
+        const auto matrix = floyd_graph.floyd_warshall_all_pairs_shortest_paths();
+        consume(matrix.size());
+    });
+    print_row("floyd_warshall_all_pairs", config.iterations, floyd_ms, "nodes=" + std::to_string(config.floyd_nodes));
+
+    nxpp::DiGraphInt attr_graph;
+    const double attr_ms = measure_ms(config.iterations, [&] {
+        for (int i = 0; i < config.attr_ops; ++i) {
+            const int node = i % config.nodes;
+            attr_graph.node(node)["label"] = std::string("node-") + std::to_string(node);
+            const auto value = attr_graph.get_node_attr<std::string>(node, "label");
+            consume(value);
+        }
+    });
+    print_row("attribute_roundtrip", config.iterations, attr_ms, "ops_per_iteration=" + std::to_string(config.attr_ops));
+
+    const double multigraph_ms = measure_ms(config.iterations, [&] {
+        nxpp::MultiDiGraphInt multigraph;
+        for (int i = 0; i < config.multigraph_edges; ++i) {
+            const auto id = multigraph.add_edge_with_id(i % config.nodes, (i + 1) % config.nodes, 1.0);
+            multigraph.set_edge_attr(id, "capacity", i + 1);
+        }
+        const auto ids = multigraph.edge_ids(0, 1);
+        consume(ids.size());
+    });
+    print_row("multigraph_edge_ids", config.iterations, multigraph_ms, "edges=" + std::to_string(config.multigraph_edges));
+
+    return 0;
+}

wasm/benchmarks/node_overhead_bench.mjs

@@ -0,0 +1,152 @@
+import { performance } from "node:perf_hooks";
+
+import nxpp from "../dist/index.js";
+
+function readIntArg(name, fallback) {
+    const index = process.argv.indexOf(name);
+    if (index === -1 || index + 1 >= process.argv.length) {
+        return fallback;
+    }
+    const value = Number.parseInt(process.argv[index + 1], 10);
+    return Number.isFinite(value) ? value : fallback;
+}
+
+const config = {
+    nodes: readIntArg("--nodes", 300),
+    edges: readIntArg("--edges", 900),
+    floydNodes: readIntArg("--floyd-nodes", 35),
+    attrOps: readIntArg("--attr-ops", 1000),
+    multigraphEdges: readIntArg("--multigraph-edges", 600),
+    iterations: readIntArg("--iterations", 5),
+};
+
+function consume(value) {
+    globalThis.__nxppBenchmarkSink = value;
+}
+
+function toArray(value) {
+    return Array.from(value);
+}
+
+function measureMs(iterations, fn) {
+    const start = performance.now();
+    for (let i = 0; i < iterations; i += 1) {
+        fn();
+    }
+    return performance.now() - start;
+}
+
+function printHeader() {
+    console.log("layer,workload,iterations,total_ms,ops_per_second,notes");
+}
+
+function printRow(layer, workload, iterations, totalMs, notes) {
+    const opsPerSecond = totalMs > 0 ? (iterations * 1000) / totalMs : 0;
+    console.log([
+        layer,
+        workload,
+        iterations,
+        totalMs.toFixed(3),
+        opsPerSecond.toFixed(3),
+        notes,
+    ].join(","));
+}
+
+function makeDiGraph(GraphCtor, nodes = config.nodes, edges = config.edges) {
+    const graph = new GraphCtor();
+    for (let node = 0; node < nodes; node += 1) {
+        graph.addNode(node);
+    }
+    for (let edge = 0; edge < edges; edge += 1) {
+        const source = edge % nodes;
+        let target = (edge * 37 + 11) % nodes;
+        if (target === source) {
+            target = (target + 1) % nodes;
+        }
+        graph.addEdge(source, target, (edge % 17) + 1);
+    }
+    return graph;
+}
+
+function makeFloydGraph(GraphCtor) {
+    const graph = new GraphCtor();
+    for (let node = 0; node < config.floydNodes; node += 1) {
+        graph.addNode(node);
+    }
+    for (let node = 0; node + 1 < config.floydNodes; node += 1) {
+        graph.addEdge(node, node + 1, 1);
+        if (node + 3 < config.floydNodes) {
+            graph.addEdge(node, node + 3, 4);
+        }
+    }
+    return graph;
+}
+
+function dispose(graph) {
+    if (typeof graph.dispose === "function") {
+        graph.dispose();
+        return;
+    }
+    if (typeof graph.delete === "function") {
+        graph.delete();
+    }
+}
+
+function runLayer(layer, constructors) {
+    const constructionMs = measureMs(config.iterations, () => {
+        const graph = makeDiGraph(constructors.DiGraphInt);
+        consume(toArray(graph.nodes()).length);
+        dispose(graph);
+    });
+    printRow(layer, "construct_digraph", config.iterations, constructionMs, `nodes=${config.nodes};edges=${config.edges}`);
+
+    const graph = makeDiGraph(constructors.DiGraphInt);
+    const bfsMs = measureMs(config.iterations, () => {
+        consume(toArray(graph.bfsEdges(0)).length);
+    });
+    printRow(layer, "bfs_edges", config.iterations, bfsMs, "source=0");
+
+    const dijkstraMs = measureMs(config.iterations, () => {
+        const result = graph.dijkstraShortestPaths(0);
+        consume(toArray(result.distance).length);
+    });
+    printRow(layer, "dijkstra_shortest_paths", config.iterations, dijkstraMs, "source=0");
+    dispose(graph);
+
+    const floydGraph = makeFloydGraph(constructors.DiGraphInt);
+    const floydMs = measureMs(config.iterations, () => {
+        consume(toArray(floydGraph.floydWarshallAllPairsShortestPaths()).length);
+    });
+    printRow(layer, "floyd_warshall_all_pairs", config.iterations, floydMs, `nodes=${config.floydNodes}`);
+    dispose(floydGraph);
+
+    const attrGraph = new constructors.DiGraphInt();
+    const attrMs = measureMs(config.iterations, () => {
+        for (let i = 0; i < config.attrOps; i += 1) {
+            const node = i % config.nodes;
+            attrGraph.setNodeAttr(node, "label", `node-${node}`);
+            consume(attrGraph.getNodeAttr(node, "label"));
+        }
+    });
+    printRow(layer, "attribute_roundtrip", config.iterations, attrMs, `ops_per_iteration=${config.attrOps}`);
+    dispose(attrGraph);
+
+    const multigraphMs = measureMs(config.iterations, () => {
+        const multigraph = new constructors.MultiDiGraphInt();
+        for (let i = 0; i < config.multigraphEdges; i += 1) {
+            multigraph.addEdge(i % config.nodes, (i + 1) % config.nodes, 1);
+        }
+        const ids = toArray(multigraph.edgeIdsBetween(0, 1));
+        for (const id of ids) {
+            multigraph.setEdgeAttrById(id, "capacity", id + 1);
+        }
+        consume(ids.length);
+        dispose(multigraph);
+    });
+    printRow(layer, "multigraph_edge_ids", config.iterations, multigraphMs, `edges=${config.multigraphEdges}`);
+}
+
+printHeader();
+const rawRuntime = await nxpp.createNxpp();
+runLayer("raw_wasm", rawRuntime);
+runLayer("facade_ts", nxpp);

wasm/package.json

@@ -34,6 +34,7 @@
   },
   "scripts": {
     "build:types": "tsc -p tsconfig.json",
+    "bench:overhead": "bash scripts/run_overhead_benchmarks.sh",
     "check:node-contract": "bash scripts/run_wasm_node_contract_tests.sh",
     "check:npm-pack-consumer": "bash scripts/run_npm_pack_consumer_test.sh",
     "publish:npm": "npm publish --registry=https://registry.npmjs.org/",