@ruvector/wasm

@ruvector/wasm

WebAssembly bindings for the RuVector vector database, enabling high-performance HNSW vector search in browsers, edge workers (Cloudflare Workers, Deno Deploy), and any WASM-compatible runtime.

Quick Command Reference

Installation

Hub install (recommended): npx ruvector@latest includes this package. Standalone: npx @ruvector/wasm@latest See Installation Guide for the full ecosystem.

Core API

Initialization

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

// Must initialize WASM module before use
await init();
const db = new WasmVectorDB(384); // dimensions

Constructor

const db = new WasmVectorDB(dimensions: number, metric?: string);

Insert Operations

// Single insert
db.insert(id: string, vector: Float32Array, metadata?: string);

// Example
db.insert('doc-1', new Float32Array([0.1, 0.2, 0.3]), JSON.stringify({ title: 'Hello' }));

// Batch insert
db.batchInsert(items: Array<[string, Float32Array, string?]>);

Search Operations

// Basic search
const results = db.search(query: Float32Array, topK: number): SearchResult[];

// Search with filter
const results = db.searchWithFilter(
  query: Float32Array,
  topK: number,
  filter: string  // JSON filter expression
): SearchResult[];

SearchResult (WASM):

interface SearchResult {
  id: string;
  score: number;
  metadata?: string; // JSON string
}

Serialization

// Serialize to bytes (for IndexedDB, localStorage, network transfer)
const bytes: Uint8Array = db.serialize();

// Deserialize from bytes
const db = WasmVectorDB.deserialize(bytes: Uint8Array);

Browser Usage

<script type="module">
  import init, { WasmVectorDB } from '@ruvector/wasm';

  async function main() {
    await init();
    const db = new WasmVectorDB(384);
    db.insert('doc-1', new Float32Array(384).fill(0.1));
    db.buildIndex();
    const results = db.search(new Float32Array(384).fill(0.2), 5);
    console.log(results);
  }
  main();
</script>

Common Patterns

Client-Side Semantic Search

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

await init();
const db = new WasmVectorDB(384);
// Load pre-computed embeddings
const embeddings = await fetch('/embeddings.json').then(r => r.json());
for (const item of embeddings) {
  db.insert(item.id, new Float32Array(item.vector), JSON.stringify(item.meta));
}
db.buildIndex();
// Search on user query
const queryVec = await embedText(userQuery);
const results = db.search(queryVec, 10);

Persist to IndexedDB

// Save
const bytes = db.serialize();
await idb.put('vectors', bytes);
// Restore
const stored = await idb.get('vectors');
const db = WasmVectorDB.deserialize(stored);

Edge Worker (Cloudflare Workers)

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

export default {
  async fetch(request) {
    await init();
    const db = WasmVectorDB.deserialize(await VECTORS_KV.get('index', 'arrayBuffer'));
    const query = await request.json();
    const results = db.search(new Float32Array(query.vector), 5);
    return Response.json(results);
  }
};

Key Options

RAN DDD Context

Bounded Context: Data Infrastructure

References

• API reference: See references/commands.md
• Full README
• npm