Package Exports
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ruvector/wasm) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Ruvector WASM
High-performance vector database running entirely in your browser via WebAssembly.
Bring sub-millisecond vector search to the edge with offline-first capabilities. Perfect for AI applications, semantic search, and recommendation engines that run completely client-side. Built by rUv with Rust and WebAssembly.
π Why Ruvector WASM?
In the age of privacy-first, offline-capable web applications, running AI workloads entirely in the browser is no longer optionalβit's essential.
Ruvector WASM brings enterprise-grade vector search to the browser:
- β‘ Blazing Fast: <1ms query latency with HNSW indexing and SIMD acceleration
- π Privacy First: All data stays in the browserβzero server round-trips
- π΄ Offline Capable: Full functionality without internet via IndexedDB persistence
- π Edge Computing: Deploy to CDNs for ultra-low latency globally
- πΎ Persistent Storage: IndexedDB integration with automatic synchronization
- π§΅ Multi-threaded: Web Workers support for parallel processing
- π¦ Compact: <400KB gzipped with optimizations
- π― Zero Dependencies: Pure Rust compiled to WebAssembly
π Features
Core Capabilities
- Complete VectorDB API: Insert, search, delete, batch operations with familiar patterns
- HNSW Indexing: Hierarchical Navigable Small World for fast approximate nearest neighbor search
- Multiple Distance Metrics: Euclidean, Cosine, Dot Product, Manhattan
- SIMD Acceleration: 2-4x speedup on supported hardware with automatic detection
- Memory Efficient: Optimized memory layouts and zero-copy operations
- Type-Safe: Full TypeScript definitions included
Browser-Specific Features
- IndexedDB Persistence: Save/load database state with progressive loading
- Web Workers Integration: Parallel operations across multiple threads
- Worker Pool Management: Automatic load balancing across 4-8 workers
- Zero-Copy Transfers: Transferable objects for efficient data passing
- Browser Console Debugging: Enhanced error messages and stack traces
- Progressive Web Apps: Perfect for PWA offline scenarios
Performance Optimizations
- Batch Operations: Efficient bulk insert/search for large datasets
- LRU Caching: 1000-entry hot vector cache for frequently accessed data
- Lazy Loading: Progressive data loading with callbacks
- Compressed Storage: Optimized serialization for IndexedDB
- WASM Streaming: Compile WASM modules while downloading
π¦ Installation
NPM
npm install @ruvector/wasmYarn
yarn add @ruvector/wasmCDN (for quick prototyping)
<script type="module">
import init, { VectorDB } from 'https://unpkg.com/@ruvector/wasm/pkg/ruvector_wasm.js';
await init();
const db = new VectorDB(384, 'cosine', true);
</script>β‘ Quick Start
Basic Usage
import init, { VectorDB } from '@ruvector/wasm';
// 1. Initialize WASM module (one-time setup)
await init();
// 2. Create database with 384-dimensional vectors
const db = new VectorDB(
384, // dimensions
'cosine', // distance metric
true // enable HNSW index
);
// 3. Insert vectors with metadata
const embedding = new Float32Array(384).map(() => Math.random());
const id = db.insert(
embedding,
'doc_1', // optional ID
{ title: 'My Document', type: 'article' } // optional metadata
);
// 4. Search for similar vectors
const query = new Float32Array(384).map(() => Math.random());
const results = db.search(query, 10); // top 10 results
// 5. Process results
results.forEach(result => {
console.log(`ID: ${result.id}`);
console.log(`Score: ${result.score}`);
console.log(`Metadata:`, result.metadata);
});React Integration
import { useEffect, useState } from 'react';
import init, { VectorDB } from '@ruvector/wasm';
function SemanticSearch() {
const [db, setDb] = useState<VectorDB | null>(null);
const [results, setResults] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
// Initialize WASM and create database
init().then(() => {
const vectorDB = new VectorDB(384, 'cosine', true);
setDb(vectorDB);
setLoading(false);
});
}, []);
const handleSearch = async (queryEmbedding: Float32Array) => {
if (!db) return;
const searchResults = db.search(queryEmbedding, 10);
setResults(searchResults);
};
if (loading) return <div>Loading vector database...</div>;
return (
<div>
<h1>Semantic Search</h1>
{/* Your search UI */}
</div>
);
}Vue.js Integration
<template>
<div>
<h1>Vector Search</h1>
<div v-if="!dbReady">Initializing...</div>
<div v-else>
<button @click="search">Search</button>
<ul>
<li v-for="result in results" :key="result.id">
{{ result.id }}: {{ result.score }}
</li>
</ul>
</div>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue';
import init, { VectorDB } from '@ruvector/wasm';
const db = ref(null);
const dbReady = ref(false);
const results = ref([]);
onMounted(async () => {
await init();
db.value = new VectorDB(384, 'cosine', true);
dbReady.value = true;
});
const search = () => {
const query = new Float32Array(384).map(() => Math.random());
results.value = db.value.search(query, 10);
};
</script>Svelte Integration
<script>
import { onMount } from 'svelte';
import init, { VectorDB } from '@ruvector/wasm';
let db = null;
let ready = false;
let results = [];
onMount(async () => {
await init();
db = new VectorDB(384, 'cosine', true);
ready = true;
});
function search() {
const query = new Float32Array(384).map(() => Math.random());
results = db.search(query, 10);
}
</script>
{#if !ready}
<p>Loading...</p>
{:else}
<button on:click={search}>Search</button>
{#each results as result}
<div>{result.id}: {result.score}</div>
{/each}
{/if}π₯ Advanced Usage
Web Workers for Background Processing
Offload heavy vector operations to background threads for smooth UI performance:
// main.js
import { WorkerPool } from '@ruvector/wasm/worker-pool';
const pool = new WorkerPool(
'/worker.js',
'/pkg/ruvector_wasm.js',
{
poolSize: navigator.hardwareConcurrency || 4, // Auto-detect CPU cores
dimensions: 384,
metric: 'cosine',
useHnsw: true
}
);
// Initialize worker pool
await pool.init();
// Batch insert in parallel (non-blocking)
const vectors = generateVectors(10000, 384);
const ids = await pool.insertBatch(vectors);
// Parallel search across workers
const query = new Float32Array(384).map(() => Math.random());
const results = await pool.search(query, 100);
// Get pool statistics
const stats = pool.getStats();
console.log(`Workers: ${stats.busyWorkers}/${stats.poolSize} busy`);
console.log(`Queue: ${stats.queuedTasks} tasks waiting`);
// Cleanup when done
pool.terminate();// worker.js - Web Worker implementation
importScripts('/pkg/ruvector_wasm.js');
const { VectorDB } = wasm_bindgen;
let db = null;
self.onmessage = async (e) => {
const { type, data } = e.data;
switch (type) {
case 'init':
await wasm_bindgen('/pkg/ruvector_wasm_bg.wasm');
db = new VectorDB(data.dimensions, data.metric, data.useHnsw);
self.postMessage({ type: 'ready' });
break;
case 'insert':
const id = db.insert(data.vector, data.id, data.metadata);
self.postMessage({ type: 'inserted', id });
break;
case 'search':
const results = db.search(data.query, data.k);
self.postMessage({ type: 'results', results });
break;
}
};IndexedDB Persistence - Offline First
Keep your vector database synchronized across sessions:
import { IndexedDBPersistence } from '@ruvector/wasm/indexeddb';
import init, { VectorDB } from '@ruvector/wasm';
await init();
// Create persistence layer
const persistence = new IndexedDBPersistence('my_vector_db', {
version: 1,
cacheSize: 1000, // LRU cache for hot vectors
batchSize: 100 // Batch size for bulk operations
});
await persistence.open();
// Create or restore VectorDB
const db = new VectorDB(384, 'cosine', true);
// Load existing data from IndexedDB (with progress)
await persistence.loadAll(async (progress) => {
console.log(`Loading: ${progress.loaded}/${progress.total} vectors`);
console.log(`Progress: ${(progress.percent * 100).toFixed(1)}%`);
// Insert batch into VectorDB
if (progress.vectors.length > 0) {
const ids = db.insertBatch(progress.vectors);
console.log(`Inserted ${ids.length} vectors`);
}
if (progress.complete) {
console.log('Database fully loaded!');
}
});
// Insert new vectors and save to IndexedDB
const vector = new Float32Array(384).map(() => Math.random());
const id = db.insert(vector, 'vec_123', { category: 'new' });
await persistence.save({
id,
vector,
metadata: { category: 'new' }
});
// Batch save for better performance
const entries = [...]; // Your vector entries
await persistence.saveBatch(entries);
// Get storage statistics
const stats = await persistence.getStats();
console.log(`Total vectors: ${stats.totalVectors}`);
console.log(`Storage used: ${(stats.storageBytes / 1024 / 1024).toFixed(2)} MB`);
console.log(`Cache size: ${stats.cacheSize}`);
console.log(`Cache hit rate: ${(stats.cacheHitRate * 100).toFixed(2)}%`);
// Clear old data
await persistence.clear();Batch Operations for Performance
Process large datasets efficiently:
import init, { VectorDB } from '@ruvector/wasm';
await init();
const db = new VectorDB(384, 'cosine', true);
// Batch insert (10x faster than individual inserts)
const entries = [];
for (let i = 0; i < 10000; i++) {
entries.push({
vector: new Float32Array(384).map(() => Math.random()),
id: `vec_${i}`,
metadata: { index: i, batch: Math.floor(i / 100) }
});
}
const ids = db.insertBatch(entries);
console.log(`Inserted ${ids.length} vectors in batch`);
// Multiple parallel searches
const queries = Array.from({ length: 100 }, () =>
new Float32Array(384).map(() => Math.random())
);
const allResults = queries.map(query => db.search(query, 10));
console.log(`Completed ${allResults.length} searches`);Memory Management Best Practices
import init, { VectorDB } from '@ruvector/wasm';
await init();
// Reuse Float32Array buffers to reduce GC pressure
const buffer = new Float32Array(384);
// Insert with reused buffer
for (let i = 0; i < 1000; i++) {
// Fill buffer with new data
for (let j = 0; j < 384; j++) {
buffer[j] = Math.random();
}
db.insert(buffer, `vec_${i}`, { index: i });
// Buffer is copied internally, safe to reuse
}
// Check memory usage
const vectorCount = db.len();
const isEmpty = db.isEmpty();
const dimensions = db.dimensions;
console.log(`Vectors: ${vectorCount}, Dims: ${dimensions}`);
// Clean up when done
// JavaScript GC will handle WASM memory automaticallyπ Performance Benchmarks
Browser Performance (Chrome 120 on M1 MacBook Pro)
| Operation | Vectors | Dimensions | Standard | SIMD | Speedup |
|---|---|---|---|---|---|
| Insert (individual) | 10,000 | 384 | 3.2s | 1.1s | 2.9x |
| Insert (batch) | 10,000 | 384 | 1.2s | 0.4s | 3.0x |
| Search (k=10) | 100 queries | 384 | 0.5s | 0.2s | 2.5x |
| Search (k=100) | 100 queries | 384 | 1.8s | 0.7s | 2.6x |
| Delete | 1,000 | 384 | 0.2s | 0.1s | 2.0x |
Throughput Comparison
Operation Ruvector WASM Tensorflow.js ml5.js
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Insert (ops/sec) 25,000 5,000 1,200
Search (queries/sec) 500 80 20
Memory (10K vectors) ~50MB ~200MB ~150MB
Bundle Size (gzipped) 380KB 800KB 450KB
Offline Support β
Partial β
SIMD Acceleration β
β βReal-World Application Performance
Semantic Search (10,000 documents, 384-dim embeddings)
- Cold start: ~800ms (WASM compile + data load)
- Warm query: <5ms (with HNSW index)
- IndexedDB load: ~2s (10,000 vectors)
- Memory footprint: ~60MB
Recommendation Engine (100,000 items, 128-dim embeddings)
- Initial load: ~8s from IndexedDB
- Query latency: <10ms (p50)
- Memory usage: ~180MB
- Bundle impact: +400KB gzipped
π Browser Compatibility
Support Matrix
| Browser | Version | WASM | SIMD | Workers | IndexedDB | Status |
|---|---|---|---|---|---|---|
| Chrome | 91+ | β | β | β | β | Full Support |
| Firefox | 89+ | β | β | β | β | Full Support |
| Safari | 16.4+ | β | Partial | β | β | Limited SIMD |
| Edge | 91+ | β | β | β | β | Full Support |
| Opera | 77+ | β | β | β | β | Full Support |
| Samsung Internet | 15+ | β | β | β | β | No SIMD |
SIMD Support Detection
import { detectSIMD } from '@ruvector/wasm';
if (detectSIMD()) {
console.log('SIMD acceleration available!');
// Load SIMD-optimized build
await import('@ruvector/wasm/pkg-simd/ruvector_wasm.js');
} else {
console.log('Standard build');
// Load standard build
await import('@ruvector/wasm');
}Polyfills and Fallbacks
// Check for required features
const hasWASM = typeof WebAssembly !== 'undefined';
const hasWorkers = typeof Worker !== 'undefined';
const hasIndexedDB = typeof indexedDB !== 'undefined';
if (!hasWASM) {
console.error('WebAssembly not supported');
// Fallback to server-side processing
}
if (!hasWorkers) {
console.warn('Web Workers not available, using main thread');
// Use synchronous API
}
if (!hasIndexedDB) {
console.warn('IndexedDB not available, data will not persist');
// Use in-memory only
}π¦ Bundle Size
Production Build Sizes
Build Type Uncompressed Gzipped Brotli
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Standard WASM 1.2 MB 450 KB 380 KB
SIMD WASM 1.3 MB 480 KB 410 KB
JavaScript Glue 45 KB 12 KB 9 KB
TypeScript Definitions 8 KB 2 KB 1.5 KB
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Total (Standard) 1.25 MB 462 KB 390 KB
Total (SIMD) 1.35 MB 492 KB 420 KBWith Optimizations (wasm-opt)
npm run optimizeOptimized Build Uncompressed Gzipped Brotli
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Standard WASM 900 KB 380 KB 320 KB
SIMD WASM 980 KB 410 KB 350 KBCode Splitting Strategy
// Lazy load WASM module when needed
const loadVectorDB = async () => {
const { default: init, VectorDB } = await import('@ruvector/wasm');
await init();
return VectorDB;
};
// Use in your application
button.addEventListener('click', async () => {
const VectorDB = await loadVectorDB();
const db = new VectorDB(384, 'cosine', true);
// Use db...
});π¨ Building from Source
Prerequisites
- Rust: 1.77 or higher
- wasm-pack: Latest version
- Node.js: 18.0 or higher
# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
# Or via npm
npm install -g wasm-packBuild Commands
# Clone repository
git clone https://github.com/ruvnet/ruvector.git
cd ruvector/crates/ruvector-wasm
# Install dependencies
npm install
# Build for web (ES modules)
npm run build:web
# Build with SIMD optimizations
npm run build:simd
# Build for Node.js
npm run build:node
# Build for bundlers (webpack, rollup, etc.)
npm run build:bundler
# Build all targets
npm run build:all
# Run tests in browser
npm test
# Run tests in Node.js
npm run test:node
# Check bundle size
npm run size
# Optimize with wasm-opt (requires binaryen)
npm run optimize
# Serve examples locally
npm run serveDevelopment Workflow
# Watch mode (requires custom setup)
wasm-pack build --dev --target web -- --features simd
# Run specific browser tests
npm run test:firefox
# Profile WASM performance
wasm-pack build --profiling --target web
# Generate documentation
cargo doc --no-deps --openCustom Build Configuration
# .cargo/config.toml
[target.wasm32-unknown-unknown]
rustflags = [
"-C", "opt-level=z",
"-C", "lto=fat",
"-C", "codegen-units=1"
]π API Reference
VectorDB Class
class VectorDB {
constructor(
dimensions: number,
metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan',
useHnsw?: boolean
);
// Insert operations
insert(vector: Float32Array, id?: string, metadata?: object): string;
insertBatch(entries: VectorEntry[]): string[];
// Search operations
search(query: Float32Array, k: number, filter?: object): SearchResult[];
// Retrieval operations
get(id: string): VectorEntry | null;
len(): number;
isEmpty(): boolean;
// Delete operations
delete(id: string): boolean;
// Persistence (IndexedDB)
saveToIndexedDB(): Promise<void>;
static loadFromIndexedDB(dbName: string): Promise<VectorDB>;
// Properties
readonly dimensions: number;
}Types
interface VectorEntry {
id?: string;
vector: Float32Array;
metadata?: Record<string, any>;
}
interface SearchResult {
id: string;
score: number;
vector?: Float32Array;
metadata?: Record<string, any>;
}Utility Functions
// Detect SIMD support
function detectSIMD(): boolean;
// Get version
function version(): string;
// Array conversion
function arrayToFloat32Array(arr: number[]): Float32Array;
// Benchmarking
function benchmark(name: string, iterations: number, dimensions: number): number;See WASM API Documentation for complete reference.
π― Example Applications
Semantic Search Engine
// Semantic search with OpenAI embeddings
import init, { VectorDB } from '@ruvector/wasm';
import { Configuration, OpenAIApi } from 'openai';
await init();
const openai = new OpenAIApi(new Configuration({
apiKey: process.env.OPENAI_API_KEY
}));
const db = new VectorDB(1536, 'cosine', true); // OpenAI ada-002 = 1536 dims
// Index documents
const documents = [
'The quick brown fox jumps over the lazy dog',
'Machine learning is a subset of artificial intelligence',
'WebAssembly enables high-performance web applications'
];
for (const [i, doc] of documents.entries()) {
const response = await openai.createEmbedding({
model: 'text-embedding-ada-002',
input: doc
});
const embedding = new Float32Array(response.data.data[0].embedding);
db.insert(embedding, `doc_${i}`, { text: doc });
}
// Search
const queryResponse = await openai.createEmbedding({
model: 'text-embedding-ada-002',
input: 'What is AI?'
});
const queryEmbedding = new Float32Array(queryResponse.data.data[0].embedding);
const results = db.search(queryEmbedding, 3);
results.forEach(result => {
console.log(`${result.score.toFixed(4)}: ${result.metadata.text}`);
});Offline Recommendation Engine
// Product recommendations that work offline
import init, { VectorDB } from '@ruvector/wasm';
import { IndexedDBPersistence } from '@ruvector/wasm/indexeddb';
await init();
const db = new VectorDB(128, 'cosine', true);
const persistence = new IndexedDBPersistence('product_recommendations');
await persistence.open();
// Load cached recommendations
await persistence.loadAll(async (progress) => {
if (progress.vectors.length > 0) {
db.insertBatch(progress.vectors);
}
});
// Get recommendations based on user history
function getRecommendations(userHistory, k = 10) {
// Compute user preference vector (average of liked items)
const userVector = computeAverageEmbedding(userHistory);
const recommendations = db.search(userVector, k);
return recommendations.map(r => ({
productId: r.id,
score: r.score,
...r.metadata
}));
}
// Add new products (syncs to IndexedDB)
async function addProduct(productId, embedding, metadata) {
db.insert(embedding, productId, metadata);
await persistence.save({ id: productId, vector: embedding, metadata });
}RAG (Retrieval-Augmented Generation)
// Browser-based RAG system
import init, { VectorDB } from '@ruvector/wasm';
await init();
const db = new VectorDB(768, 'cosine', true); // BERT embeddings
// Index knowledge base
const knowledgeBase = loadKnowledgeBase(); // Your documents
for (const doc of knowledgeBase) {
const embedding = await getBertEmbedding(doc.text);
db.insert(embedding, doc.id, { text: doc.text, source: doc.source });
}
// RAG query function
async function ragQuery(question, llm) {
// 1. Get question embedding
const questionEmbedding = await getBertEmbedding(question);
// 2. Retrieve relevant context
const context = db.search(questionEmbedding, 5);
// 3. Augment prompt with context
const prompt = `
Context:
${context.map(r => r.metadata.text).join('\n\n')}
Question: ${question}
Answer based on the context above:
`;
// 4. Generate response
const response = await llm.generate(prompt);
return {
answer: response,
sources: context.map(r => r.metadata.source)
};
}π Troubleshooting
Common Issues
1. WASM Module Not Loading
// Ensure correct MIME type
// Add to server config (nginx):
// types {
// application/wasm wasm;
// }
// Or use explicit fetch
const wasmUrl = new URL('./pkg/ruvector_wasm_bg.wasm', import.meta.url);
await init(await fetch(wasmUrl));2. CORS Errors
// For local development
// package.json
{
"scripts": {
"serve": "python3 -m http.server 8080 --bind 127.0.0.1"
}
}3. Memory Issues
// Monitor memory usage
const stats = db.len();
const estimatedMemory = stats * dimensions * 4; // bytes
if (estimatedMemory > 100_000_000) { // 100MB
console.warn('High memory usage, consider chunking');
}
// Use batch operations to reduce GC pressure
const BATCH_SIZE = 1000;
for (let i = 0; i < entries.length; i += BATCH_SIZE) {
const batch = entries.slice(i, i + BATCH_SIZE);
db.insertBatch(batch);
}4. Web Worker Issues
// Ensure worker script URL is correct
const workerUrl = new URL('./worker.js', import.meta.url);
const worker = new Worker(workerUrl, { type: 'module' });
// Handle worker errors
worker.onerror = (error) => {
console.error('Worker error:', error);
};See WASM Troubleshooting Guide for more solutions.
π Links & Resources
Documentation
- Getting Started Guide - Complete setup and usage
- WASM API Reference - Full API documentation
- Performance Tuning - Optimization tips
- Main README - Project overview and features
Examples & Demos
- Vanilla JS Example - Basic implementation
- React Demo - React integration with hooks
- Live Demo - Try it in your browser
- CodeSandbox - Interactive playground
Community & Support
- GitHub: github.com/ruvnet/ruvector
- Discord: Join our community
- Twitter: @ruvnet
- Issues: Report bugs
π License
MIT License - see LICENSE for details.
Free to use for commercial and personal projects.
π Acknowledgments
- Built with wasm-pack and wasm-bindgen
- HNSW algorithm implementation from hnsw_rs
- SIMD optimizations powered by Rust's excellent WebAssembly support
- The WebAssembly community for making this possible
Built by rUv β’ Open Source on GitHub
Perfect for: PWAs β’ Offline-First Apps β’ Edge Computing β’ Privacy-First AI
Get Started β’ API Docs β’ Examples