AlbexEngine API

Constructs the engine. The WASM module is NOT loaded yet — call init() before any other method. The constructor only validates options and stores them.

import { AlbexEngine } from "albex";

// Zero config — the WASM binary ships with the package and your bundler
// (Vite, Webpack 5+, Next, esbuild, Rollup, Parcel 2, Bun) resolves it
// automatically through `import.meta.url`. No assets to copy, no URL to
// configure, no path to remember.
const engine = new AlbexEngine();
await engine.init();

// Optional overrides — only if you want tier auto-selection or a CDN.
// new AlbexEngine({ wasmBaseUrl: "/assets" })  // serve the 6 variants yourself
// new AlbexEngine({ wasmUrl: "https://cdn.example.com/albex_wasm.wasm" })

Resolves the WASM URL (using wasmUrl or wasmBaseUrl + tier auto-detection), fetches the binary, instantiates it, runs initial setup, and subscribes the engine to the global ResourceManager. Throws AlbexInitError on fetch or instantiation failure.

await engine.init();
// engine.tier         → 'mini' | 'std' | 'pro'
// engine.simdEnabled  → boolean
// engine.gpuEngaged   → true after the first search that uses WebGPU

Clears every indexed document and search result. The engine is immediately ready to index a fresh corpus. The WASM module instance is preserved (no re-fetch).

TC39 explicit-resource-management hook. Resets state, unsubscribes from the resource manager, destroys the GPU device (if any), and nulls out internal references so the WASM instance becomes unreachable for GC. Use with using engine = new AlbexEngine(...) when available.

Detects the format from the extension, parses the file, and streams text into the WASM index. Content is hashed (FNV-1a 64-bit) before indexing — if a document with the same hash already exists, the previous entry is returned and no work is done. Throws AlbexUnsupportedFormatError or AlbexParseError on failures.

Supported: .docx, .xlsx, .pdf, .md, .html/.htm, .json, .csv, .eml, .rtf, .txt, .xml.

const input = document.querySelector('input[type=file]');

input.addEventListener('change', async () => {
  for (const file of input.files) {
    const doc = await engine.indexFile(file);
    console.log(`${file.name}: ${doc.chunks} chunks, hash=${doc.contentHash}`);
  }
});

// Idempotent: re-indexing the same file is a no-op and returns the existing
// IndexedDocument (matched by FNV-1a content hash).

Synchronous full-corpus search. Drives the pipeline: parse query → Bloom filter → Bitap fuzzy match → rich scoring → min-heap top-K. Results are returned already sorted by score, descending. May invoke the WebGPU pre-filter automatically when opts.gpu permits and chunk count exceeds gpuThreshold.

// Synchronous fast path — best for small corpora and tests.
const results = engine.search('"contrato marco" | rescisión', { windowed: true });
for (const r of results) {
  console.log(`[${r.score}] ${r.documentName} · ${r.snippet}`);
}

Cooperative variant of search(). The corpus is processed in slices; between slices the engine yields to the browser scheduler via scheduler.yield() (or requestAnimationFrame fallback). UI stays responsive during 50 ms+ scans. Use this in any interactive search box.

// Cooperative streaming search — main thread stays at 60 fps.
for await (const r of engine.searchCooperative('contrato', { frameBudgetMs: 8 })) {
  renderResult(r);   // render incrementally as results arrive
}

Maximum edit distance for fuzzy match. 0 = exact only. Engine auto-shrinks for short queries.

engine.setMaxErrors(1);

Minimum score (0-1000) below which results are dropped. Default 250.

engine.setThreshold(400);

Cap on number of returned results. 1-200. Default 50.

engine.setMaxResults(100);

Enable lightweight Spanish stemming on query tokens. Indexed text is never stemmed, so snippets stay faithful to the source.

engine.setLanguage('es');  // "contratos" now matches "contrato"

Tombstone a document. Subsequent searches skip its chunks. Storage is reclaimed by compact(). `id` accepts the file name or contentHash returned by indexFile.

engine.removeDocument('contract-2024-03.pdf');
engine.removeDocument(doc.contentHash);  // by hash also works

Atomic remove + re-index. Bypasses dedup so re-indexing the same bytes after a remove works.

await engine.replaceDocument('contract.pdf', newVersionFile);

Reclaim storage from tombstoned documents. Rewrites internal arrays in place. Doc IDs of survivors are preserved.

engine.removeDocument('old.pdf');
engine.compact();  // bytes freed; subsequent indexFile sees real headroom

Serialise the index to a binary snapshot in OPFS (preferred) or IndexedDB.

await engine.save('my-corpus');

Restore a previously saved snapshot. Returns true on success, false if missing or header mismatched.

if (!await engine.load('my-corpus')) {
  console.log('No snapshot yet; starting fresh');
}

Convenience wrapper: load if it exists, otherwise reset() and start clean.

await engine.loadOrInit('my-corpus');

Remove a snapshot from storage.

await engine.deleteSnapshot('old-corpus');

List the names of all snapshots saved in the current origin.

const names = await engine.listSnapshots();

Snapshot of current engine state: document count, chunk count, memory usage, loaded tier, capacity caps.

Bloom/Bitap pipeline counters from the most recent search call. Useful for debugging relevance and detecting performance regressions.

Probe the host capabilities (cores, memory, WASM features, WebGPU, storage budget, network, battery). Result cached in sessionStorage. Pass `fresh: true` to bypass the cache.

import { detectProfile } from 'albex';
const profile = await detectProfile();
console.log(profile.memoryGB, profile.wasm.simd);

Pure heuristic: <=1 GB → mini, 2-4 GB → std, >=8 GB → pro, null (Safari) → std.

const tier = pickTier(profile);

cores/2 clamped [1, 8]. Falls to 1 when battery is reported below 20 % and discharging.

const workers = pickWorkerCount(profile);

true when WebGPU is available AND chunk count crosses the threshold (default 20 000).

if (shouldUseGpu(profile, engine.getStats().chunks)) { /* … */ }

Drop-in replacement for AlbexEngine that runs the entire engine inside a Web Worker. Surface is identical except every method returns a Promise. Files are transferred via postMessage with transferable ArrayBuffers — no copy.

Import from albex/worker. The runtime script is exported separately as albex/worker-runtime and must be referenced via new URL(..., import.meta.url).

import { AlbexEngineWorker } from 'albex/worker';

// Same zero-config pattern as the main engine — the worker runtime URL is
// the only thing you must point at (so the bundler can spawn it).
const engine = new AlbexEngineWorker({
  workerUrl: new URL('albex/worker-runtime', import.meta.url),
});

await engine.init();
const results = await engine.search('contrato', { windowed: true });

Orchestrates N worker shards. Documents are sharded round-robin across workers. Searches broadcast to every shard and the coordinator merges top-K results preserving the global descending score order. Default worker count is half of hardwareConcurrency clamped to [1, 8]; battery-aware (drops to 1 on low battery).

Import from albex/pool.

import { AlbexPool } from 'albex/pool';

const pool = new AlbexPool({
  workerUrl: new URL('albex/worker-runtime', import.meta.url),
  workers: 'auto',   // cores/2 clamped [1, 8]
});
await pool.init();

await pool.indexFile(fileA);                   // sharded round-robin
await pool.indexFile(fileB);
const results = await pool.search('contrato'); // map-reduce across shards

Adds hot/warm tiers behind the engine. When the engine reaches evictThreshold of capacity, the LRU document is removed and its original blob remains in OPFS. promote(name) brings it back by re-indexing from the persisted blob.

Import from albex/tiered.

import { AlbexEngine, TieredStore } from 'albex';

const engine = new AlbexEngine();
await engine.init();

const store = new TieredStore(engine, { evictThreshold: 0.85, hotFloor: 4 });
await store.init();

await store.indexFile(file);          // persists original blob in OPFS
await store.promote('older-doc.pdf'); // brings warm doc back to engine

Standalone WebGPU Bloom-scan accelerator. AlbexEngine instantiates one automatically when opts.gpu permits and the corpus exceeds gpuThreshold (default 20 000 chunks). You only need to touch this class directly to integrate the WGSL shader into a non-Albex pipeline.

Import from albex/gpu.