api reference

altor-vec API Reference

Complete reference for the altor-vec JavaScript/TypeScript API. All methods are part of the WasmSearchEngine class, which wraps the underlying Rust/WASM HNSW implementation.

Import

// ESM (recommended)
import init, { WasmSearchEngine } from 'altor-vec';

// CommonJS
const { default: init, WasmSearchEngine } = require('altor-vec');

init()

Initialize the altor-vec WebAssembly module. Must be called once before any WasmSearchEngine methods. Returns a promise that resolves when the WASM binary is loaded and ready.

Returns: Promise<void>

import init, { WasmSearchEngine } from 'altor-vec';

// Call once at app startup, before any search operations
await init();
console.log('altor-vec WASM ready');

WasmSearchEngine.from_vectors()

Create a new HNSW index from a Float32Array of pre-computed embeddings. This is the primary way to build an index from scratch.

Returns: WasmSearchEngine instance

const DIM = 384; // embedding dimension
const N = docs.length; // number of documents
const vectors = new Float32Array(N * DIM); // pre-filled with embeddings

const engine = WasmSearchEngine.from_vectors(
  vectors,
  DIM,
  16,   // M
  200,  // ef_construction
  50    // ef_search
);

Tuning guide:

engine.search()

Find the k nearest neighbors to a query embedding using approximate nearest-neighbor search (HNSW). Typically runs in under 1ms for 10,000-vector indexes.

Returns: string — JSON-encoded array of {id: number, score: number} objects, sorted by score descending (most similar first). Parse with JSON.parse().

// Example: search with a query embedding
const queryEmbedding = new Float32Array(384); // your query vector
const k = 5;

const resultsJson = engine.search(queryEmbedding, k);
const results = JSON.parse(resultsJson);
// results: [{id: 3, score: 0.97}, {id: 11, score: 0.94}, ...]

// Map back to your documents
const docs_results = results.map(r => ({
  ...docs[r.id],
  similarity: r.score
}));

Score interpretation: Scores are cosine similarity values in range [0, 1]. A score of 1.0 means identical vectors. Scores above 0.8 are generally strong semantic matches.

WasmSearchEngine.from_json()

Restore a previously serialized HNSW index. Use this to load a pre-built index from a static file, localStorage, or IndexedDB.

Returns: WasmSearchEngine instance — fully restored, ready to search immediately.

// Load pre-built index from a static file (recommended for production)
const resp = await fetch('/search-index.json');
const json = await resp.text();
const engine = WasmSearchEngine.from_json(json);

// Or restore from localStorage
const saved = localStorage.getItem('altor-search-index');
if (saved) {
  const engine = WasmSearchEngine.from_json(saved);
}

engine.to_json()

Serialize the current HNSW index to a JSON string. Use for caching, persistent storage, or shipping as a pre-built static asset.

Returns: string — JSON representation of the index. Size is approximately 4× the raw vector data (due to the HNSW graph structure).

const json = engine.to_json();

// Store in localStorage (small indexes)
localStorage.setItem('altor-search-index', json);
console.log('Index size:', (json.length / 1024).toFixed(1) + 'KB');

// Or write to disk at build time (Node.js)
import { writeFileSync } from 'fs';
writeFileSync('public/search-index.json', json);

engine.add()

Add a single vector to an existing index. Useful for incremental updates when you cannot rebuild the full index.

Returns: void

Note: For bulk additions (100+ vectors), rebuilding the index with from_vectors() is significantly faster than calling add() in a loop. Use add() for truly incremental updates only.

// Add a new document after the index is built
const newEmbedding = new Float32Array(384); // your new vector
engine.add(docs.length, newEmbedding, { title: 'New document', url: '/new' });
docs.push({ title: 'New document', url: '/new' }); // keep docs in sync

engine.delete()

Remove a vector from the index by ID. The HNSW graph is updated to exclude this vector from future search results.

Returns: void

// Remove document with id=3 from search results
engine.delete(3);

TypeScript types

altor-vec ships TypeScript declaration files. All methods are fully typed.

import init, { WasmSearchEngine } from 'altor-vec';

// TypeScript infers: init() returns Promise<void>
await init();

// TypeScript infers: WasmSearchEngine.from_vectors() returns WasmSearchEngine
const engine: WasmSearchEngine = WasmSearchEngine.from_vectors(vectors, 384, 16, 200, 50);

// TypeScript infers: engine.search() returns string (JSON)
const raw: string = engine.search(queryEmbedding, 5);
const results: Array<{id: number, score: number}> = JSON.parse(raw);

Embedding model reference

Error handling

try {
  await init();
  const engine = WasmSearchEngine.from_vectors(vectors, dim, 16, 200, 50);
  const results = JSON.parse(engine.search(queryEmbedding, 5));
} catch (err) {
  if (err.message.includes('dimension mismatch')) {
    // Query embedding dimension doesn't match index dimension
  } else if (err.message.includes('WASM not initialized')) {
    // init() was not called before using WasmSearchEngine
  } else {
    console.error('altor-vec error:', err);
  }
}

Frequently asked questions

Q: What does init() do exactly?
It fetches and instantiates the altor-vec WASM binary. It must resolve before calling any WasmSearchEngine methods.

Q: What does search() return?
JSON.stringify([{id: number, score: number}, ...]) sorted by score descending. Parse with JSON.parse().

Q: Can I run altor-vec in Node.js?
Yes. The WASM binary runs in Node.js 18+ via the native WebAssembly API. Import the same package — no special Node build needed.

Q: What happens if I call search() before init()?
It throws an error. Always await init() before using WasmSearchEngine.