Vue 3 Composables

Relevant source files

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

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

EdgeVec provides a set of reactive Vue 3 composables designed to integrate high-performance vector search and metadata filtering into Vue applications. These composables abstract the complexities of WebAssembly (WASM) initialization, index management, and asynchronous search operations, providing a native Vue developer experience using the Composition API.

The primary purpose of these tools is to manage the lifecycle of the EdgeVecIndex, including initialization from scratch or loading from persistent storage like IndexedDB, and providing reactive state for search results, loading statuses, and performance metrics.

Sources: pkg/vue/index.ts:1-12, pkg/vue/useEdgeVec.ts:1-15

Core Composables and Module Structure

The Vue integration is organized as a modular package that exports reactive hooks and TypeScript types. It specifically targets Vue 3.3+ to utilize modern reactive features.

Module Exports

Export	Type	Description
useEdgeVec	Function	Manages WASM initialization and EdgeVecIndex lifecycle.
useSearch	Function	Handles reactive search queries with support for debouncing and filters.
UseEdgeVecOptions	Type	Configuration for database initialization.
UseSearchOptions	Type	Configuration for search parameters including k and debounceMs.

Sources: pkg/vue/index.ts:10-53, pkg/vue/useEdgeVec.ts:32-37

Database Initialization: useEdgeVec

The useEdgeVec composable is responsible for the setup and persistence of the vector database. It handles the asynchronous transition of the database from a loading state to a ready state.

Architecture and Data Flow

The composable utilizes shallowRef for the database instance to prevent unnecessary deep reactivity overhead on the complex EdgeVecIndex class. It manages internal state regarding the number of vectors (stats) and error tracking during the WASM boundary transition.

Functionality Table

Feature	Implementation	Source
Persistence	Automatically attempts to load from IndexedDB if persistName is provided.	useEdgeVec.ts:64-70
Reactivity	Uses Ref and shallowRef to provide isLoading, isReady, and error.	useEdgeVec.ts:43-46
Manual Save	Provides a save(name?) function to persist the current index state.	useEdgeVec.ts:111-125
Lifecycle	Cleans up and tracks mount status to prevent memory leaks or state updates on unmounted components.	useEdgeVec.ts:128-136

Reactive Searching

While useEdgeVec manages the instance, search operations are abstracted to handle the high-frequency nature of user queries, such as those found in the Filter Playground.

Search Logic and Filtering

Search composables support metadata filtering using SQL-like syntax. This is integrated into the Vue reactivity system, allowing search results to update automatically when dependencies like the query vector or filter string change.

Implementation Example

The following snippet demonstrates a typical implementation combining database initialization and search results in a Vue 3 template.

// Initializing the database with 384 dimensions
const { db, isReady, isLoading, error, stats } = useEdgeVec({
  dimensions: 384,
  persistName: 'my-index',
});

// Setting up a reactive search with a 300ms debounce
const { results, isSearching, searchTime } = useSearch(db, {
  vector: queryVector,
  k: 10,
  enabled: computed(() => isReady.value && queryVector.value !== null),
  debounceMs: 300,
});

Sources: pkg/vue/index.ts:13-30

Performance Budgets and Constraints

Within the architecture approved in Phase 1, the Vue composables are designed to operate within specific performance and memory budgets:

• Search Latency: Target < 10ms P99 for 100k vectors.
• Initialization: Index load target < 500ms.
• Memory Overhead: ~82 bytes per vector.
• Persistence: Writes larger than 50MB are chunked at the application layer to avoid IndexedDB limits.

Sources: GATE_1_COMPLETE.md:120-143, pkg/vue/useEdgeVec.ts:111-125

Conclusion

The Vue 3 Composables for EdgeVec provide a robust, reactive interface for vector operations. By managing WASM lifecycle and index persistence automatically, they allow developers to focus on UI implementation while maintaining "Nvidia Grade" performance standards. The integration of filtering and debouncing ensures that search interfaces remain responsive even with large datasets and complex metadata queries.