VelesDB WASM

WebAssembly build of VelesDB - vector search in the browser.

Features

• In-browser vector search - No server required
• SIMD optimized - Uses WASM SIMD128 for fast distance calculations
• Multiple metrics - Cosine, Euclidean, Dot Product
• Lightweight - Minimal bundle size

Installation

npm install velesdb-wasm

Usage

import init, { VectorStore } from 'velesdb-wasm';

async function main() {
  // Initialize WASM module
  await init();

  // Create a vector store (768 dimensions, cosine similarity)
  const store = new VectorStore(768, 'cosine');

  // Insert vectors (use BigInt for IDs)
  store.insert(1n, new Float32Array([0.1, 0.2, ...]));
  store.insert(2n, new Float32Array([0.3, 0.4, ...]));

  // Search for similar vectors
  const query = new Float32Array([0.15, 0.25, ...]);
  const results = store.search(query, 5); // Top 5 results

  // Results: [[id, score], [id, score], ...]
  console.log(results);
}

main();

High-Performance Bulk Insert

For optimal performance when inserting many vectors:

// Pre-allocate capacity (avoids repeated memory allocations)
const store = VectorStore.with_capacity(768, 'cosine', 100000);

// Batch insert (much faster than individual inserts)
const batch = [
  [1n, [0.1, 0.2, ...]],
  [2n, [0.3, 0.4, ...]],
  // ... more vectors
];
store.insert_batch(batch);

// Or reserve capacity on existing store
store.reserve(50000);

API

VectorStore

class VectorStore {
  // Create a new store
  constructor(dimension: number, metric: 'cosine' | 'euclidean' | 'dot');
  
  // Create with pre-allocated capacity (performance optimization)
  static with_capacity(dimension: number, metric: string, capacity: number): VectorStore;

  // Properties
  readonly len: number;
  readonly is_empty: boolean;
  readonly dimension: number;

  // Methods
  insert(id: bigint, vector: Float32Array): void;
  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
  search(query: Float32Array, k: number): Array<[bigint, number]>;
  remove(id: bigint): boolean;
  clear(): void;
  reserve(additional: number): void;  // Pre-allocate memory
  memory_usage(): number;
}

Distance Metrics

IndexedDB Persistence

Save and restore your vector store for offline-first applications with built-in async methods:

import init, { VectorStore } from 'velesdb-wasm';

async function main() {
  await init();

  // Create and populate a store
  const store = new VectorStore(768, 'cosine');
  store.insert(1n, new Float32Array(768).fill(0.1));
  store.insert(2n, new Float32Array(768).fill(0.2));

  // Save to IndexedDB (single async call)
  await store.save('my-vectors-db');
  console.log('Saved!', store.len, 'vectors');

  // Later: Load from IndexedDB
  const restored = await VectorStore.load('my-vectors-db');
  console.log('Restored!', restored.len, 'vectors');

  // Clean up: Delete database
  await VectorStore.delete_database('my-vectors-db');
}

main();

Persistence API

class VectorStore {
  // Save to IndexedDB (async)
  save(db_name: string): Promise<void>;
  
  // Load from IndexedDB (async, static)
  static load(db_name: string): Promise<VectorStore>;
  
  // Delete IndexedDB database (async, static)
  static delete_database(db_name: string): Promise<void>;
  
  // Manual binary export/import (for localStorage, file download, etc.)
  export_to_bytes(): Uint8Array;
  static import_from_bytes(bytes: Uint8Array): VectorStore;
}

Binary Format

Performance

Ultra-fast serialization thanks to contiguous memory layout:

Use Cases

• Browser-based RAG - 100% client-side semantic search
• Offline-first apps - Works without internet, persists to IndexedDB
• Privacy-preserving AI - Data never leaves the browser
• Electron/Tauri apps - Desktop AI without a server
• PWA applications - Full offline support with service workers

Building from Source

# Install wasm-pack
cargo install wasm-pack

# Build for browser
wasm-pack build --target web

# Build for Node.js
wasm-pack build --target nodejs

Performance

Typical latencies on modern browsers:

License

Elastic License 2.0 (ELv2)

See LICENSE for details.