albex 0.1.0 → 0.6.0

package/dist/albex-worker.js

@@ -0,0 +1,153 @@
+/*!
+ * albex v0.6.0
+ * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
+ * (c) 2026 RafaCalRob
+ * @license MIT
+ * https://github.com/RafaCalRob/Albex#readme
+ */
+/**
+ * `AlbexEngineWorker` — a main-thread wrapper that runs the engine inside a
+ * Web Worker. Mirrors the surface of `AlbexEngine` so it can be swapped in
+ * without code changes.
+ *
+ * Usage:
+ *
+ *     const engine = new AlbexEngineWorker({
+ *       wasmUrl:    '/assets/albex_wasm_bg.wasm',
+ *       pdfWasmUrl: '/assets/albex_pdf.wasm',
+ *       // Provide the URL to the bundled worker runtime.
+ *       workerUrl:  new URL('./worker-runtime.js', import.meta.url),
+ *     });
+ *     await engine.init();
+ *
+ * Why: a `search()` over 100k chunks can take 10–50 ms. On main thread that
+ * is visible jank for every keystroke. Off-main-thread keeps the UI at 60 fps.
+ *
+ * The runtime is single-threaded WASM, so requests are serialised: only one
+ * call is in flight at a time. This matches the actual `static mut` model
+ * inside the .wasm and is fine for an interactive search UI (each keystroke
+ * replaces the previous query).
+ */
+import { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
+let _workerSearchStreamWarned = false;
+export class AlbexEngineWorker {
+    _opts;
+    _worker;
+    _nextId = 1;
+    _pending = new Map();
+    _docsCache = [];
+    constructor(opts) {
+        this._opts = opts;
+    }
+    async init() {
+        this._worker = new Worker(this._opts.workerUrl, { type: 'module' });
+        this._worker.onmessage = (ev) => {
+            const { id } = ev.data;
+            const p = this._pending.get(id);
+            if (!p)
+                return;
+            this._pending.delete(id);
+            if (ev.data.ok)
+                p.resolve(ev.data.result);
+            else
+                p.reject(rehydrateError(ev.data.error));
+        };
+        this._worker.onerror = (e) => {
+            // Surface the error to every in-flight call.
+            const err = new AlbexInitError(`Worker crashed: ${e.message}`);
+            for (const [, p] of this._pending)
+                p.reject(err);
+            this._pending.clear();
+        };
+        await this._send({ kind: 'init', opts: {
+                wasmUrl: this._opts.wasmUrl,
+                pdfWasmUrl: this._opts.pdfWasmUrl,
+            } });
+    }
+    _send(op, transfer = []) {
+        const id = this._nextId++;
+        const req = { id, op };
+        return new Promise((resolve, reject) => {
+            this._pending.set(id, { resolve: resolve, reject });
+            this._worker.postMessage(req, transfer);
+        });
+    }
+    async indexFile(file) {
+        const buffer = await file.arrayBuffer();
+        // Transfer the buffer to avoid a copy.
+        const doc = await this._send({ kind: 'indexFile', name: file.name, buffer }, [buffer]);
+        this._docsCache.push(doc);
+        return doc;
+    }
+    search(query, opts = {}) {
+        return this._send({ kind: 'search', query, options: opts });
+    }
+    /**
+     * Cooperative variant of `search`. Today the wire still sends a single
+     * batch — the result array is fetched in one round-trip from the worker
+     * and then exposed as an async iterator so callers can `break` early.
+     * A future iteration may use a `MessagePort` to stream individual results
+     * from the worker side; the iterator shape is preserved across that
+     * transition.
+     */
+    async *searchCooperative(query, opts = {}) {
+        const results = await this.search(query, opts);
+        for (const r of results)
+            yield r;
+    }
+    /**
+     * @deprecated Renamed to `searchCooperative` in 0.3.0. Alias removed in 0.4.0.
+     */
+    async *searchStream(query, opts = {}) {
+        if (!_workerSearchStreamWarned) {
+            _workerSearchStreamWarned = true;
+            console.warn('[albex] `AlbexEngineWorker.searchStream` is deprecated; rename to `searchCooperative`. Alias removed in 0.4.0.');
+        }
+        yield* this.searchCooperative(query, opts);
+    }
+    async removeDocument(id) {
+        const ok = await this._send({ kind: 'removeDocument', id });
+        if (ok)
+            this._docsCache = this._docsCache.filter(d => d.name !== id && d.contentHash !== id);
+        return ok;
+    }
+    async compact() { await this._send({ kind: 'compact' }); }
+    async reset() {
+        await this._send({ kind: 'reset' });
+        this._docsCache = [];
+    }
+    getStats() { return this._send({ kind: 'getStats' }); }
+    getLastSearchStats() { return this._send({ kind: 'getLastSearchStats' }); }
+    getDocuments() { return this._send({ kind: 'getDocuments' }); }
+    async setMaxErrors(n) { await this._send({ kind: 'setMaxErrors', n }); }
+    async setThreshold(n) { await this._send({ kind: 'setThreshold', n }); }
+    async setMaxResults(n) { await this._send({ kind: 'setMaxResults', n }); }
+    async setLanguage(lang) { await this._send({ kind: 'setLanguage', lang }); }
+    // Persistence — mirror of AlbexEngine.
+    async save(name) { await this._send({ kind: 'save', name }); }
+    async load(name) { return this._send({ kind: 'load', name }); }
+    async loadOrInit(name) { return this._send({ kind: 'loadOrInit', name }); }
+    async deleteSnapshot(name) { await this._send({ kind: 'deleteSnapshot', name }); }
+    async listSnapshots() { return this._send({ kind: 'listSnapshots' }); }
+    [Symbol.dispose]() {
+        for (const [, p] of this._pending)
+            p.reject(new AlbexError('disposed', 'Engine disposed'));
+        this._pending.clear();
+        this._worker?.terminate();
+        this._docsCache = [];
+    }
+}
+function rehydrateError(e) {
+    switch (e.kind) {
+        case 'init': return new AlbexInitError(e.message);
+        case 'unsupported_format': return new AlbexUnsupportedFormatError(e.message.replace(/^Unsupported format: \./, ''));
+        case 'parse': return new AlbexParseError('unknown', e.message);
+        case 'capacity': return new AlbexCapacityError(e.message);
+        default: {
+            const err = new Error(e.message);
+            err.name = e.name;
+            return err;
+        }
+    }
+}
+//# sourceMappingURL=albex-worker.js.map

package/dist/albex-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"albex-worker.js","sourceRoot":"","sources":["../src/albex-worker.ts"],"names":[],"mappings":"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"}