WebAssembly Boundary

Relevant source files

The following files were used as context for generating this wiki page:

• GATE_1_COMPLETE.md
• Cargo.toml
• README.md
• wasm/examples/index.html
• wasm/examples/filter-playground.html
• wasm/examples/simd_benchmark.html
• CONTRIBUTING.md

The WebAssembly (WASM) Boundary in EdgeVec serves as the critical interface between the high-performance Rust core and the JavaScript/TypeScript environments of the browser and Node.js. It facilitates safe, efficient data exchange, specifically optimized for heavy vector operations, while ensuring that the underlying HNSW index and storage layers remain accessible to web applications without sacrificing performance.

This boundary is characterized by FFI-safe error handling, the use of TypedArray for vector data to minimize serialization overhead, and the exposure of asynchronous operations for I/O tasks like persistence. Sources: GATE_1_COMPLETE.md:154-159, README.md:12-16

Architecture and Data Flow

The WASM boundary is built using wasm-bindgen and js-sys to bridge the gap between Rust and JavaScript. The architecture ensures that complex vector data is passed as Float32Array or Uint8Array to leverage shared memory and SIMD acceleration where available.

The diagram shows the flow of data from the high-level application through the WASM boundary to the hardware-accelerated Rust core. Sources: GATE_1_COMPLETE.md:154-159, Cargo.toml:77-83, wasm/examples/simd_benchmark.html:360-375

Key Boundary Components

Component	Technology	Description
Bindings Generator	wasm-bindgen	Facilitates high-level interactions between WASM and JS.
Type Mapping	serde-wasm-bindgen	Efficiently converts complex Rust structs to JS objects.
Error Handling	thiserror / JsError	Maps internal EdgeVecError to JS exceptions safely.
Memory Buffer	TypedArray	Direct access to WASM linear memory for vector arrays.

Sources: Cargo.toml:50-53, Cargo.toml:77-83, GATE_1_COMPLETE.md:154-156

API Surface and Type Mapping

The WASM boundary exposes several key classes and functions that allow JavaScript developers to interact with the HNSW index. Most notably, the EdgeVec and EdgeVecConfig classes serve as the primary entry points.

Principal Classes

1. EdgeVecConfig: Manages configuration parameters like dimensionality and HNSW hyperparameters (M, ef_construction).
2. EdgeVec: The main index instance providing methods for insertion, search, and deletion.

Sources: wasm/examples/index.html:1034-1040, wasm/examples/filter-playground.html:1320-1325

Function Mapping and Data Exchange

Data is exchanged across the boundary using specific conventions to maximize performance:

• Vectors: Passed as Float32Array to avoid expensive JSON serialization of large numerical arrays.
• Metadata: Handled via serde_json or JsMetadataValue, allowing SQL-like filtering on the Rust side based on JS objects.
• Search Results: Returned as an array of objects containing id and score.

This sequence illustrates the typical data exchange for insertion and filtered search operations. Sources: README.md:130-145, wasm/examples/filter-playground.html:1400-1415

Performance Optimization

The boundary is designed to minimize the cost of cross-environment calls, which is essential for sub-millisecond search latencies.

SIMD Acceleration

EdgeVec utilizes WASM SIMD128 instructions to accelerate vector operations (dot product, L2 distance). On supported browsers (Chrome 91+, Firefox 89+, Safari 16.4+), the boundary enables performance of up to 2.1+ Gelem/s. If SIMD is unavailable, the boundary automatically falls back to scalar implementations. Sources: README.md:78-95, wasm/examples/simd_benchmark.html:360-375

Memory Management

To prevent "out of memory" errors in the browser's restricted environment, the WASM boundary exposes a Memory Pressure API. This allows JavaScript applications to monitor heap usage and trigger compact() operations to reclaim space from soft-deleted vectors. Sources: GATE_1_COMPLETE.md:162-166, README.md:168-175

The flow of the Memory Pressure API monitoring and compaction trigger. Sources: README.md:168-175, GATE_1_COMPLETE.md:162-166

Safety and Invariants

The WASM boundary enforces strict safety rules to prevent panics from crossing into JavaScript, which would lead to unrecoverable states.

• No Panics: All public-facing methods use Result<T, E>. Invariants are verified at the boundary (e.g., dimension checks).
• Safety Proofs: Any unsafe code used for performance (like get_unchecked in hot paths) is documented with safety proofs.
• Compile-Time Verification: Struct layouts (like SectionHeader) are verified with const_assert! to ensure alignment matches the binary data expected by the JS environment.

Sources: CONTRIBUTING.md:46-60, CONTRIBUTING.md:95-125, GATE_1_COMPLETE.md:41-50

Conclusion

The WebAssembly Boundary in EdgeVec is not merely a translation layer but a performance-tuned gateway. By leveraging wasm-bindgen, SIMD128, and efficient TypedArray transfers, it provides web applications with the power of a Rust-based HNSW engine. It balances safety through strict FFI error handling and performance through manual memory management APIs, ensuring a "Nvidia Grade" standard for browser-native vector databases.