React Hooks Integration

Relevant source files

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

• pkg/react/useEdgeVec.ts
• wasm/examples/v070_filter_playground.html
• wasm/examples/filter-playground.html
• GATE_1_COMPLETE.md
• wasm/examples/index.html

The React Hooks Integration provides a set of specialized hooks designed to simplify the lifecycle management, initialization, and usage of the EdgeVec vector database within React applications. By leveraging standard React patterns like useEffect, useRef, and useCallback, these hooks abstract the complexities of WebAssembly (WASM) initialization, persistence via IndexedDB, and state synchronization.

This integration serves as the primary bridge between the high-performance Rust/WASM core and modern frontend frameworks. It ensures that database instances remain stable across re-renders while providing reactive state updates for loading status, errors, and index statistics.
Sources: pkg/react/useEdgeVec.ts:1-35, wasm/examples/v070_filter_playground.html:268-283

Core Hook: useEdgeVec

The useEdgeVec hook is the primary entry point for managing an EdgeVec database instance. It handles the asynchronous setup of the WASM module and the creation or restoration of the Hierarchical Navigable Small World (HNSW) index.

Architecture and Data Flow

The hook maintains a stable reference to the EdgeVecIndex using useRef. This prevents the database from being re-initialized unnecessarily during component updates. The initialization logic is encapsulated in a useCallback which is triggered on mount or when critical configuration (like dimensions) changes.

The data flow ensures that if a persistName is provided, the hook attempts to recover the state from IndexedDB before falling back to a clean initialization.
Sources: pkg/react/useEdgeVec.ts:44-98, GATE_1_COMPLETE.md:83-88

Configuration Options

The hook accepts a UseEdgeVecOptions object to configure the HNSW graph and persistence settings.

Parameter	Type	Default	Description
dimensions	number	Required	The dimensionality of vectors stored in the index.
persistName	string	undefined	Key used for IndexedDB persistence.
efConstruction	number	200	Size of the dynamic list for HNSW construction.
m	number	16	Max number of outgoing connections in HNSW graph.

Sources: pkg/react/useEdgeVec.ts:44-50, wasm/examples/index.html:1052-1055

Hook Return Value

The hook returns an object of type UseEdgeVecResult, providing access to the database and utility methods.

• db: The EdgeVecIndex instance (or null if not yet loaded).
• isReady: Boolean indicating if the DB is initialized and ready for operations.
• isLoading: Boolean indicating if WASM or persistence loading is in progress.
• error: Contains any Error encountered during initialization.
• stats: An object containing count (vector total) and dimensions.
• reload: Function to clear the current instance and re-run initialization.
• save: Function to manually persist the current index state to IndexedDB.

Sources: pkg/react/useEdgeVec.ts:52-140

Usage Patterns

Initialization and Metadata Search

Integration with metadata filtering allows for complex queries directly within a functional component. The following implementation pattern demonstrates how the hooks manage the transition from raw vectors to filtered results.

Persistence Management

The hooks expose a save method that bridges the WASM memory state to the browser's persistent storage. This is critical for applications that need to maintain vector indices across page reloads without re-uploading the entire dataset.

const { db, save, stats } = useEdgeVec({
    dimensions: 384,
    persistName: 'my-vector-store'
});

const handleAddData = async (vector, metadata) => {
    db.insertWithMetadata(vector, metadata);
    await save(); // Persists to IndexedDB using 'my-vector-store'
};

Sources: pkg/react/useEdgeVec.ts:114-131, wasm/examples/filter-playground.html:1040-1045

Component Lifecycle & Safety

The integration follows strict lifecycle safety rules to prevent memory leaks and state updates on unmounted components:

1. Mounted Tracking: A mountedRef is used to ensure that setIsLoading and setIsReady are only called if the component is still active in the DOM.
2. Stable References: The dbRef ensures the WASM-backed index survives component re-renders but is properly cleaned up or updated when dependencies like dimensions change.
3. FFI Safety: Hooks wrap underlying WASM calls in try/catch blocks to convert Rust-originated errors into standard JavaScript Error objects for the React error boundary or state.
   Sources: pkg/react/useEdgeVec.ts:57-58, pkg/react/useEdgeVec.ts:92-105, GATE_1_COMPLETE.md:90-95

Summary

The React Hooks Integration abstracts the complexity of WebAssembly and Hierarchical Navigable Small World (HNSW) graph management into a standard React interface. By providing automated initialization, reactive status updates, and simple persistence triggers via IndexedDB, it enables developers to treat EdgeVec as a standard stateful resource. This module ensures that high-performance vector operations are both safe and efficient within the React component lifecycle.