API Reference

The WasmSearchEngine class is the primary interface exposed by Altor Vec. It wraps the underlying WebAssembly module and presents a small asynchronous API for creating an index, adding vectors, searching, and optionally persisting state. The API is intentionally narrow so the engine can be embedded in browser code, server-side services, local scripts, and benchmark harnesses without introducing a large dependency surface.

Although the examples below use TypeScript, the same runtime behavior applies in plain JavaScript. All methods that interact with the Wasm module return promises because initialization and large index operations can take noticeable time, especially when the dataset is non-trivial.

Create and Populate an Engine

Use WasmSearchEngine.create() to initialize a new instance. The dimensions option is required. Graph-tuning parameters such as m and efConstruction are optional but recommended when you care about repeatable benchmark behavior.

const engine = await WasmSearchEngine.create({
  dimensions: 768,
  m: 24,
  efConstruction: 200,
});

Once created, you can call add() for single records or addMany() for bulk ingestion. Bulk insertion is typically faster because it reduces JavaScript-to-Wasm boundary overhead.

await engine.add({id: 'doc-1', vector, metadata: {lang: 'en'}});
await engine.addMany(records);

Query and Maintenance Methods

Use search(queryVector, options) to retrieve the nearest neighbors. Common options include limit and efSearch. A higher efSearch usually improves recall but increases per-query work.

const hits = await engine.search(queryVector, {
  limit: 10,
  efSearch: 96,
});

Many applications also rely on helper methods such as count() to report index size, clear() to reset state during tests, and serialize() or save() to persist a built index for later reuse. If your version exposes a load() method, use it only with artifacts created by the same library version unless the release notes explicitly guarantee compatibility.

When handling errors, assume that invalid vector length, corrupted serialized data, and Wasm initialization failures are the most likely causes. Wrap index creation and search calls in your own logging so you can capture the dimension, record count, and search options associated with a failure. That context is far more useful than a generic stack trace when debugging production search behavior.