ruvector/docs/wasm-api.md

Ruvector WASM API Documentation

Overview

Ruvector WASM provides a high-performance vector database for browser and Node.js environments. It leverages Rust's speed and safety with WebAssembly for near-native performance.

Features

• ✅ Full VectorDB API: Insert, search, delete, batch operations
• ✅ SIMD Acceleration: Automatic detection and use of SIMD instructions when available
• ✅ Web Workers: Parallel operations across multiple worker threads
• ✅ IndexedDB Persistence: Save and load database state
• ✅ LRU Cache: Efficient caching for hot vectors
• ✅ Zero-Copy Transfers: Transferable objects for optimal performance
• ✅ Multiple Distance Metrics: Euclidean, Cosine, Dot Product, Manhattan

Installation

npm install @ruvector/wasm

Or build from source:

cd crates/ruvector-wasm
npm run build

Basic Usage

Vanilla JavaScript

import init, { VectorDB } from '@ruvector/wasm';

// Initialize WASM module
await init();

// Create database
const db = new VectorDB(384, 'cosine', true);

// Insert vector
const vector = new Float32Array(384).map(() => Math.random());
const id = db.insert(vector, 'vec_1', { label: 'example' });

// Search
const query = new Float32Array(384).map(() => Math.random());
const results = db.search(query, 10);

console.log(results);
// [{ id: 'vec_1', score: 0.123, metadata: { label: 'example' } }, ...]

With Web Workers

import { WorkerPool } from '@ruvector/wasm/worker-pool';

const pool = new WorkerPool(
  '/worker.js',
  '/pkg/ruvector_wasm.js',
  {
    poolSize: 4,
    dimensions: 384,
    metric: 'cosine'
  }
);

await pool.init();

// Parallel insert
const entries = Array(1000).fill(0).map((_, i) => ({
  vector: Array(384).fill(0).map(() => Math.random()),
  id: `vec_${i}`,
  metadata: { index: i }
}));

const ids = await pool.insertBatch(entries);

// Parallel search
const results = await pool.search(query, 10);

// Cleanup
pool.terminate();

With IndexedDB Persistence

import { IndexedDBPersistence } from '@ruvector/wasm/indexeddb';

const persistence = new IndexedDBPersistence('my_database');
await persistence.open();

// Save vectors
await persistence.saveBatch(entries);

// Load with progress callback
await persistence.loadAll((progress) => {
  console.log(`Loaded ${progress.loaded} vectors`);

  // Insert into database
  if (progress.vectors.length > 0) {
    db.insertBatch(progress.vectors);
  }
});

// Get stats
const stats = await persistence.getStats();
console.log(`Total vectors: ${stats.totalVectors}`);
console.log(`Cache size: ${stats.cacheSize}`);

API Reference

VectorDB

Constructor

new VectorDB(
  dimensions: number,
  metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan',
  useHnsw?: boolean
): VectorDB

Creates a new VectorDB instance.

Parameters:

• dimensions: Vector dimensions (required)
• metric: Distance metric (default: 'cosine')
• useHnsw: Use HNSW index for faster search (default: true)

Methods

insert

insert(
  vector: Float32Array,
  id?: string,
  metadata?: object
): string

Insert a single vector.

Returns: Vector ID

insertBatch

insertBatch(entries: Array<{
  vector: Float32Array,
  id?: string,
  metadata?: object
}>): string[]

Insert multiple vectors in a batch (more efficient).

Returns: Array of vector IDs

search

search(
  query: Float32Array,
  k: number,
  filter?: object
): Array<{
  id: string,
  score: number,
  vector?: Float32Array,
  metadata?: object
}>

Search for similar vectors.

Parameters:

• query: Query vector
• k: Number of results to return
• filter: Optional metadata filter

Returns: Array of search results sorted by similarity

delete

delete(id: string): boolean

Delete a vector by ID.

Returns: True if deleted, false if not found

get

get(id: string): {
  id: string,
  vector: Float32Array,
  metadata?: object
} | null

Get a vector by ID.

Returns: Vector entry or null if not found

len

len(): number

Get the number of vectors in the database.

isEmpty

isEmpty(): boolean

Check if the database is empty.

WorkerPool

Constructor

new WorkerPool(
  workerUrl: string,
  wasmUrl: string,
  options: {
    poolSize?: number,
    dimensions: number,
    metric?: string,
    useHnsw?: boolean
  }
): WorkerPool

Creates a worker pool for parallel operations.

Parameters:

• workerUrl: URL to worker.js
• wasmUrl: URL to WASM module
• options.poolSize: Number of workers (default: CPU cores)
• options.dimensions: Vector dimensions
• options.metric: Distance metric
• options.useHnsw: Use HNSW index

Methods

init

async init(): Promise<void>

Initialize the worker pool.

insert

async insert(
  vector: number[],
  id?: string,
  metadata?: object
): Promise<string>

Insert vector via worker pool.

insertBatch

async insertBatch(entries: Array<{
  vector: number[],
  id?: string,
  metadata?: object
}>): Promise<string[]>

Insert batch via worker pool (distributed across workers).

search

async search(
  query: number[],
  k?: number,
  filter?: object
): Promise<Array<{
  id: string,
  score: number,
  metadata?: object
}>>

Search via worker pool.

searchBatch

async searchBatch(
  queries: number[][],
  k?: number,
  filter?: object
): Promise<Array<Array<SearchResult>>>

Parallel search across multiple queries.

terminate

terminate(): void

Terminate all workers.

getStats

getStats(): {
  poolSize: number,
  busyWorkers: number,
  idleWorkers: number,
  pendingRequests: number
}

Get pool statistics.

IndexedDBPersistence

Constructor

new IndexedDBPersistence(dbName?: string): IndexedDBPersistence

Creates IndexedDB persistence manager.

Methods

open

async open(): Promise<IDBDatabase>

Open IndexedDB connection.

saveVector

async saveVector(
  id: string,
  vector: Float32Array,
  metadata?: object
): Promise<string>

Save a single vector.

saveBatch

async saveBatch(
  entries: Array<{
    id: string,
    vector: Float32Array,
    metadata?: object
  }>,
  batchSize?: number
): Promise<number>

Save vectors in batch.

loadVector

async loadVector(id: string): Promise<{
  id: string,
  vector: Float32Array,
  metadata?: object,
  timestamp: number
} | null>

Load a single vector.

loadAll

async loadAll(
  onProgress?: (progress: {
    loaded: number,
    vectors: Array<any>,
    complete?: boolean
  }) => void,
  batchSize?: number
): Promise<{ count: number, complete: boolean }>

Load all vectors with progressive loading.

deleteVector

async deleteVector(id: string): Promise<boolean>

Delete a vector.

clear

async clear(): Promise<void>

Clear all vectors.

getStats

async getStats(): Promise<{
  totalVectors: number,
  cacheSize: number,
  cacheHitRate: number
}>

Get database statistics.

Utility Functions

detectSIMD

detectSIMD(): boolean

Detect if SIMD is supported in the current environment.

version

version(): string

Get Ruvector version.

benchmark

benchmark(
  name: string,
  iterations: number,
  dimensions: number
): number

Run performance benchmark.

Returns: Operations per second

Performance Tips

1. Use Batch Operations: insertBatch is significantly faster than multiple insert calls
2. Enable SIMD: Build with SIMD feature for 2-4x speedup on supported hardware
3. Use Web Workers: Distribute operations across workers for parallel processing
4. Use LRU Cache: Keep hot vectors in memory via IndexedDB cache
5. Optimize Vector Size: Smaller dimensions = faster operations
6. Use Appropriate Metric: Dot product is fastest, Euclidean is slowest

Browser Support

• Chrome 91+ (with SIMD)
• Firefox 89+ (with SIMD)
• Safari 16.4+ (limited SIMD)
• Edge 91+

Size Optimization

The WASM binary is optimized for size:

• Base build: ~450KB gzipped
• With SIMD: ~480KB gzipped

Build size can be further reduced with:

npm run optimize

Examples

See:

• /examples/wasm-vanilla/ - Vanilla JavaScript example
• /examples/wasm-react/ - React with Web Workers example

Troubleshooting

SIMD not working

Ensure your browser supports SIMD and you're using the SIMD build:

import init from '@ruvector/wasm-simd';

Workers not starting

Check CORS headers and ensure worker.js is served from the same origin.

IndexedDB errors

Ensure your browser supports IndexedDB and you have sufficient storage quota.

License

MIT