albex 0.1.0 → 0.6.0

package/dist/tiered-store.js

@@ -0,0 +1,238 @@
+/*!
+ * 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
+ */
+/**
+ * Tiered storage layer for Albex.
+ *
+ * The base engine keeps every indexed document in memory inside the BSS
+ * arrays. That works beautifully up to the tier's capacity (4 MB to 128 MB
+ * of indexed text) but breaks when the user wants to search across more.
+ *
+ * `TieredStore` adds two memory tiers behind the engine:
+ *
+ *   HOT  — already-indexed documents living in the WASM arrays.
+ *   WARM — original file blobs serialised in OPFS, NOT in the engine.
+ *
+ * Eviction happens when text capacity climbs above a configurable
+ * threshold (default 85 %). The least-recently-accessed HOT document is
+ * removed from the engine; its blob stays in OPFS so we can promote it
+ * back later without asking the user to re-pick the file.
+ *
+ * Promotion happens explicitly: callers tell the store "I want these
+ * names searchable again" and we re-feed them through `engine.indexFile`.
+ *
+ * **Trade-off vs storing the internal representation in OPFS:** promoting
+ * a doc means re-parsing it (DOCX XML decode, etc.). For typical document
+ * sizes this is 20-200 ms — negligible for an explicit "search across the
+ * archive" action. The win is huge: the persistence format is just the
+ * source files, so it survives engine version bumps without any migration.
+ */
+const OPFS_DIR = 'albex-tiered';
+export class TieredStore {
+    _engine;
+    _entries = new Map();
+    _dir = null;
+    _opts;
+    constructor(engine, opts = {}) {
+        this._engine = engine;
+        this._opts = {
+            evictThreshold: opts.evictThreshold ?? 0.85,
+            hotFloor: opts.hotFloor ?? 1,
+        };
+    }
+    /** Ensure the OPFS directory exists. Idempotent. Tolerated when OPFS is unavailable. */
+    async init() {
+        try {
+            const root = await navigator.storage.getDirectory();
+            this._dir = await root.getDirectoryHandle(OPFS_DIR, { create: true });
+        }
+        catch {
+            // No OPFS — warm tier disabled; everything stays hot.
+            this._dir = null;
+        }
+        await this._rehydrateIndex();
+    }
+    /**
+     * Index a file AND register it in the warm tier so it survives across
+     * sessions. Equivalent to `engine.indexFile(file)` but with the extra
+     * persistence guarantee.
+     */
+    async indexFile(file) {
+        const doc = await this._engine.indexFile(file);
+        // Persist the original blob in OPFS so we can promote it back later
+        // without asking the user to re-pick the file.
+        await this._writeBlob(file);
+        this._entries.set(doc.name, {
+            name: doc.name,
+            ext: doc.ext,
+            lastAccessedMs: Date.now(),
+            hot: true,
+            byteSize: file.size,
+        });
+        await this._enforceCapacity();
+        return doc;
+    }
+    /** Touch an entry to mark it recently used (for LRU). */
+    touch(name) {
+        const e = this._entries.get(name);
+        if (e)
+            e.lastAccessedMs = Date.now();
+    }
+    /**
+     * Evict the least-recently-used HOT documents until `textUsed` falls
+     * below the configured threshold. Respects `hotFloor` (never evicts
+     * the last N docs).
+     */
+    async _enforceCapacity() {
+        const stats = this._engine.getStats();
+        const threshold = stats.textCapacity * this._opts.evictThreshold;
+        if (stats.textUsed <= threshold)
+            return;
+        const hot = [...this._entries.values()]
+            .filter(e => e.hot)
+            .sort((a, b) => a.lastAccessedMs - b.lastAccessedMs);
+        while (hot.length > this._opts.hotFloor) {
+            const victim = hot.shift();
+            this._engine.removeDocument(victim.name);
+            victim.hot = false;
+            // Reclaim storage now so subsequent index calls see real headroom.
+            this._engine.compact();
+            const after = this._engine.getStats();
+            if (after.textUsed <= threshold)
+                break;
+        }
+    }
+    /**
+     * Bring a warm document back into the engine. No-op if already hot.
+     * Returns the resulting `IndexedDocument` or `null` if the doc isn't known.
+     */
+    async promote(name) {
+        const e = this._entries.get(name);
+        if (!e)
+            return null;
+        if (e.hot) {
+            this.touch(name);
+            const stats = this._engine.getStats();
+            void stats;
+            return this._engine.documents.find(d => d.name === name) ?? null;
+        }
+        const blob = await this._readBlob(name);
+        if (!blob)
+            return null;
+        // Re-create the File so `engine.indexFile` sees the original metadata.
+        const file = new File([blob], name);
+        const doc = await this._engine.indexFile(file);
+        e.hot = true;
+        e.lastAccessedMs = Date.now();
+        return doc;
+    }
+    /**
+     * Forget a document entirely: remove from engine and delete its OPFS blob.
+     * Returns whether the entry existed.
+     */
+    async forget(name) {
+        const had = this._entries.has(name);
+        if (this._entries.get(name)?.hot)
+            this._engine.removeDocument(name);
+        this._entries.delete(name);
+        await this._deleteBlob(name);
+        return had;
+    }
+    /** Names of all known documents, hot or warm. */
+    list() {
+        return [...this._entries.values()].map(e => ({
+            name: e.name, hot: e.hot, byteSize: e.byteSize,
+        }));
+    }
+    /** Aggregate storage stats. */
+    getTierStats() {
+        let hot = 0, warm = 0, totalBytes = 0;
+        for (const e of this._entries.values()) {
+            if (e.hot)
+                hot++;
+            else
+                warm++;
+            totalBytes += e.byteSize;
+        }
+        return { hot, warm, totalBytes };
+    }
+    // ── OPFS plumbing ─────────────────────────────────────────────────────
+    _safeName(name) {
+        // Strip path separators just in case; OPFS requires plain file names.
+        return name.replace(/[/\\]/g, '_');
+    }
+    async _writeBlob(file) {
+        if (!this._dir)
+            return;
+        try {
+            const handle = await this._dir.getFileHandle(this._safeName(file.name), { create: true });
+            const w = await handle.createWritable();
+            const bytes = new Uint8Array(await file.arrayBuffer());
+            const plain = new Uint8Array(bytes.byteLength);
+            plain.set(bytes);
+            await w.write(plain);
+            await w.close();
+        }
+        catch (e) {
+            console.warn(`[albex] failed to persist blob for ${file.name}:`, e);
+        }
+    }
+    async _readBlob(name) {
+        if (!this._dir)
+            return null;
+        try {
+            const handle = await this._dir.getFileHandle(this._safeName(name));
+            return await handle.getFile();
+        }
+        catch {
+            return null;
+        }
+    }
+    async _deleteBlob(name) {
+        if (!this._dir)
+            return;
+        try {
+            await this._dir.removeEntry(this._safeName(name));
+        }
+        catch { /* not found */ }
+    }
+    /**
+     * TC39 explicit-resource-management hook. Drops the in-memory index and
+     * the OPFS directory handle. The underlying OPFS blobs are NOT deleted —
+     * disposal only frees JS-side state. Use `forget()` per-doc or
+     * `deleteOpfsAll()` if you want to wipe persisted data.
+     */
+    [Symbol.dispose]() {
+        this._entries.clear();
+        this._dir = null;
+    }
+    async _rehydrateIndex() {
+        if (!this._dir)
+            return;
+        try {
+            // @ts-expect-error async-iterable on FileSystemDirectoryHandle
+            for await (const [name, handle] of this._dir.entries()) {
+                if (handle.kind !== 'file')
+                    continue;
+                const file = await handle.getFile();
+                if (this._entries.has(name))
+                    continue;
+                this._entries.set(name, {
+                    name,
+                    ext: (name.split('.').pop() ?? '').toLowerCase(),
+                    lastAccessedMs: 0, // never accessed in this session yet
+                    hot: false,
+                    byteSize: file.size,
+                });
+            }
+        }
+        catch (e) {
+            console.warn('[albex] could not rehydrate tiered index:', e);
+        }
+    }
+}
+//# sourceMappingURL=tiered-store.js.map

package/dist/tiered-store.js.map

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

package/dist/wasm-bindings.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Typed interfaces for the two WASM modules Albex ships with.
+ *
+ * These types replace ad-hoc `as Function` casts and give us:
+ *  - argument/return type checking at call sites,
+ *  - autocompletion in IDEs,
+ *  - safe refactors when an export name or signature changes.
+ *
+ * The interfaces mirror the `#[no_mangle] pub extern "C" fn` exports
+ * in `wasm/src/lib.rs` and `pdf-wasm/src/lib.rs`.
+ */
+export interface AlbexWasmExports {
+    readonly memory: WebAssembly.Memory;
+    abiVersion(): number;
+    getBuffer(size: number): number;
+    init(): void;
+    /** Reset the streaming FNV-1a 64-bit hash state. Optional on the first
+     * hash of a session because the static initialiser is also FNV_OFFSET. */
+    hashBegin(): void;
+    /** Fold `len` bytes of scratchpad into the streaming hash. May be
+     * called repeatedly for files larger than SCRATCHPAD_SIZE. */
+    hashFeed(len: number): void;
+    /** Write the final 8 raw big-endian bytes at scratchpad[0..8] and
+     * reset the state so the next hash can start without an explicit Begin. */
+    hashFinish(): void;
+    setDocumentName(len: number): void;
+    beginDocument(): number;
+    feedXmlBytes(len: number): void;
+    endDocument(): number;
+    beginXlsx(): number;
+    feedXlsxBytes(len: number): void;
+    feedText(len: number): void;
+    flushParagraph(): void;
+    setMaxErrors(errors: number): void;
+    setThreshold(threshold: number): void;
+    setMaxResults(max: number): void;
+    prepareQuery(len: number): number;
+    getQueryKind(): number;
+    getQueryBranchCount(): number;
+    getQueryBranchPattern(i: number): number;
+    selectQueryBranch(i: number): number;
+    setPattern(len: number): number;
+    search(): number;
+    searchBegin(): number;
+    searchSlice(maxChunks: number): number;
+    getSearchCursor(): number;
+    getSearchTotal(): number;
+    getResultCount(): number;
+    getResultDocId(i: number): number;
+    getResultLocation(i: number): number;
+    getResultScore(i: number): number;
+    getResultStart(i: number): number;
+    getResultEnd(i: number): number;
+    getResultChunkIdx(i: number): number;
+    getResultDocName(i: number): number;
+    getResultMatchCount(i: number): number;
+    getResultMatchStartAt(i: number, k: number): number;
+    getResultMatchEndAt(i: number, k: number): number;
+    getSnippet(i: number): number;
+    getSnippetWindow(i: number, before: number, after: number): number;
+    getSnippetWindowOffset(): number;
+    getStatBloomTested(): number;
+    getStatBloomPassed(): number;
+    getStatBitapMatched(): number;
+    getChunkCount(): number;
+    getDocCount(): number;
+    getTextUsed(): number;
+    getTextCapacity(): number;
+    /** Bitflags of capacity limits hit during the most recent
+     * begin..endDocument cycle: 1 = chunks, 2 = text, 4 = docs, 8 = names.
+     * 0 = everything fit. Read by the host right after endDocument to raise a
+     * typed AlbexCapacityError instead of silently truncating the corpus. */
+    getLastIndexOverflow(): number;
+    snapshotSize(): number;
+    snapshotChunk(offset: number, maxLen: number): number;
+    /** Validate header. For v3 also reserves the staging buffer; state is
+     * NOT touched until restoreCommit succeeds. For v1/v2 (legacy) state is
+     * reset and counters are written immediately. */
+    restoreBegin(): number;
+    /** Feed payload bytes. For v3 they accumulate into staging; for v1/v2
+     * they are written straight to the state arrays as before. */
+    restoreFeed(len: number): number;
+    /** Atomic commit for v3 snapshots. Returns 1 if the staged payload was
+     * complete and decoded successfully; 0 otherwise — and in the 0 case
+     * the previous engine state is preserved. For v1/v2 this is a no-op
+     * that always returns 1. */
+    restoreCommit(): number;
+    getDocId(index: number): number;
+    getDocChunkCount(index: number): number;
+    getDocName(index: number): number;
+    isDocDeleted(index: number): number;
+    removeDocument(docId: number): number;
+    compact(): void;
+    /**
+     * Per-document content hash (snapshot v2). Returns a pointer to 8 bytes
+     * holding the FNV-1a 64-bit hash of the original file bytes, or 0 if the
+     * doc index is out of range. All-zero bytes mean "hash not available"
+     * — either the host never called setDocumentContentHash for this doc
+     * (legacy code path) or it was restored from a v1 snapshot.
+     */
+    getDocContentHashPtr(index: number): number;
+    /** Always returns 8. Useful as a runtime feature-detect: older binaries
+     * without snapshot v2 will not export this function at all. */
+    getDocContentHashLen(): number;
+    /** Copy a content hash (up to 8 bytes from the scratchpad) into the
+     * pending slot. endDocument() then writes it into doc_hashes[]. */
+    setDocumentContentHash(len: number): void;
+    setLanguage(lang: number): void;
+    getTier(): number;
+    getMaxChunks(): number;
+    getMaxDocs(): number;
+    getNameCapacity(): number;
+    getChunksPtr(): number;
+    getChunkStructSize(): number;
+    setCandidateMask(byteLen: number): void;
+    clearCandidateMask(): void;
+}
+export interface AlbexPdfExports {
+    readonly memory: WebAssembly.Memory;
+    /** ABI version of the PDF module. The host loader refuses any binary
+     * whose abiVersion is outside the supported range. */
+    abiVersion(): number;
+    /** Reserve `len` bytes inside the PDF module and return a pointer. */
+    allocInput(len: number): number;
+    /**
+     * Parse the PDF. Returns:
+     *   N ≥ 0 — page count,
+     *   -1    — parse error (read with getErrorPtr/getErrorLen),
+     *   -2    — image-only / no extractable text.
+     *
+     * When `-2` is returned, the host can fall through to the scanned-PDF
+     * path via `getPageCount` + `extractPageImages`.
+     */
+    extractPdf(len: number): number;
+    getPageLen(page: number): number;
+    getPagePtr(page: number): number;
+    getErrorLen(): number;
+    getErrorPtr(): number;
+    /** Total page count of the loaded PDF; 0 if the input cannot be parsed. */
+    getPageCount(): number;
+    /**
+     * Extract every supported image XObject on page `page` (0-based) into the
+     * module's internal buffer.
+     *
+     * Returns:
+     *   N ≥ 0 — number of images extracted on this page,
+     *   -1    — parse error or page index out of range.
+     *
+     * Each extracted image is one of:
+     *   * JPEG (kind = 1, from a `/DCTDecode` filter), or
+     *   * JPEG2000 (kind = 2, from a `/JPXDecode` filter).
+     *
+     * Filters that require Rust-side reconstruction (`FlateDecode`,
+     * `CCITTFaxDecode`, `JBIG2Decode`) are intentionally skipped — they
+     * would roughly double the binary size for ~5 % more coverage.
+     */
+    extractPageImages(page: number): number;
+    /** Byte length of extracted image `i` (from the last `extractPageImages`). */
+    getPageImageLen(i: number): number;
+    /** Pointer to extracted image `i`'s raw bytes. */
+    getPageImagePtr(i: number): number;
+    /** Format tag for extracted image `i`: 1 = JPEG, 2 = JPEG2000, 0 = none. */
+    getPageImageKind(i: number): number;
+}
+/** Thrown when an instantiated WASM module fails the ABI contract. */
+export declare class AlbexAbiMismatchError extends Error {
+    readonly module: 'main' | 'pdf';
+    readonly missing?: readonly string[];
+    readonly version?: number;
+    constructor(module: 'main' | 'pdf', message: string, opts?: {
+        missing?: readonly string[];
+        version?: number;
+    });
+}
+/** Validate and narrow `WebAssembly.Exports` to the typed Albex main
+ * interface. Throws `AlbexAbiMismatchError` if the contract is broken. */
+export declare function asAlbexExports(exports: WebAssembly.Exports): AlbexWasmExports;
+/** Validate and narrow `WebAssembly.Exports` to the typed PDF interface. */
+export declare function asAlbexPdfExports(exports: WebAssembly.Exports): AlbexPdfExports;
+//# sourceMappingURL=wasm-bindings.d.ts.map

package/dist/wasm-bindings.d.ts.map

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

package/dist/wasm-bindings.js

@@ -0,0 +1,128 @@
+/*!
+ * 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
+ */
+/**
+ * Typed interfaces for the two WASM modules Albex ships with.
+ *
+ * These types replace ad-hoc `as Function` casts and give us:
+ *  - argument/return type checking at call sites,
+ *  - autocompletion in IDEs,
+ *  - safe refactors when an export name or signature changes.
+ *
+ * The interfaces mirror the `#[no_mangle] pub extern "C" fn` exports
+ * in `wasm/src/lib.rs` and `pdf-wasm/src/lib.rs`.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Runtime validators
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// These replace the pre-0.5.0 `as unknown as` casts. They check three
+// things at instantiation time:
+//   1. memory is a WebAssembly.Memory instance.
+//   2. abiVersion() returns a number inside the supported range.
+//   3. every required export exists and is a function.
+//
+// If any of these fails, the loader throws a typed error before the
+// engine returns from init(). This eliminates the audit 3.2 issue:
+// previously a missing export only surfaced when its call site ran.
+/** Range of ABI versions this host code understands for the main module.
+ * Update both ends together with the Rust `abiVersion()` constant when
+ * the export surface changes. */
+// 0.6.0 requires ABI 3 (trigram pre-filter + getLastIndexOverflow). The
+// required-exports list below already makes any older binary fail the
+// missing-exports check, so a tolerant lower bound was dead code — the range
+// is pinned to the one ABI this host actually speaks (audit 0.6.0, finding #7).
+const MAIN_ABI_MIN = 3;
+const MAIN_ABI_MAX = 3;
+/** Range of ABI versions for the PDF module. */
+const PDF_ABI_MIN = 1;
+const PDF_ABI_MAX = 3;
+/** Required function names on the main WASM. Adding a new one here forces
+ * the validator to check it; removing one is a breaking ABI bump. */
+const MAIN_REQUIRED = [
+    'abiVersion', 'getBuffer', 'init',
+    'setDocumentName', 'beginDocument', 'feedXmlBytes', 'endDocument',
+    'beginXlsx', 'feedXlsxBytes',
+    'feedText', 'flushParagraph',
+    'setMaxErrors', 'setThreshold', 'setMaxResults',
+    'prepareQuery', 'getQueryKind', 'getQueryBranchCount',
+    'getQueryBranchPattern', 'selectQueryBranch',
+    'setPattern', 'search',
+    'searchBegin', 'searchSlice', 'getSearchCursor', 'getSearchTotal',
+    'getResultCount',
+    'getResultDocId', 'getResultLocation', 'getResultScore',
+    'getResultStart', 'getResultEnd', 'getResultChunkIdx',
+    'getResultDocName', 'getResultMatchCount',
+    'getResultMatchStartAt', 'getResultMatchEndAt',
+    'getSnippet', 'getSnippetWindow', 'getSnippetWindowOffset',
+    'getStatBloomTested', 'getStatBloomPassed', 'getStatBitapMatched',
+    'getChunkCount', 'getDocCount', 'getTextUsed', 'getTextCapacity',
+    'getLastIndexOverflow',
+    'snapshotSize', 'snapshotChunk',
+    'restoreBegin', 'restoreFeed', 'restoreCommit',
+    'getDocId', 'getDocChunkCount', 'getDocName', 'isDocDeleted',
+    'removeDocument', 'compact',
+    'setLanguage',
+    'getTier', 'getMaxChunks', 'getMaxDocs', 'getNameCapacity',
+    'getChunksPtr', 'getChunkStructSize',
+    'setCandidateMask', 'clearCandidateMask',
+    'getDocContentHashPtr', 'getDocContentHashLen', 'setDocumentContentHash',
+    'hashBegin', 'hashFeed', 'hashFinish',
+];
+const PDF_REQUIRED = [
+    'abiVersion', 'allocInput', 'extractPdf',
+    'getPageLen', 'getPagePtr', 'getErrorLen', 'getErrorPtr',
+    'getPageCount', 'extractPageImages',
+    'getPageImageLen', 'getPageImagePtr', 'getPageImageKind',
+];
+/** Thrown when an instantiated WASM module fails the ABI contract. */
+export class AlbexAbiMismatchError extends Error {
+    module;
+    missing;
+    version;
+    constructor(module, message, opts) {
+        super(message);
+        this.name = 'AlbexAbiMismatchError';
+        this.module = module;
+        if (opts?.missing)
+            this.missing = opts.missing;
+        if (opts?.version !== undefined)
+            this.version = opts.version;
+    }
+}
+function validateExports(exports, required, module, abiMin, abiMax) {
+    const mem = exports['memory'];
+    if (!(mem instanceof WebAssembly.Memory)) {
+        throw new AlbexAbiMismatchError(module, `${module}: \`memory\` is missing or not a WebAssembly.Memory instance.`);
+    }
+    const missing = [];
+    for (const name of required) {
+        if (typeof exports[name] !== 'function')
+            missing.push(name);
+    }
+    if (missing.length) {
+        throw new AlbexAbiMismatchError(module, `${module}: WASM binary missing required exports: ${missing.join(', ')}. ` +
+            `The .wasm was built with an incompatible source — rebuild with the current toolchain.`, { missing });
+    }
+    const version = exports['abiVersion']();
+    if (version < abiMin || version > abiMax) {
+        throw new AlbexAbiMismatchError(module, `${module}: abiVersion ${version} outside supported range [${abiMin}..${abiMax}]. ` +
+            `The host TypeScript expects a different binary — upgrade albex or rebuild the WASM.`, { version });
+    }
+}
+/** Validate and narrow `WebAssembly.Exports` to the typed Albex main
+ * interface. Throws `AlbexAbiMismatchError` if the contract is broken. */
+export function asAlbexExports(exports) {
+    validateExports(exports, MAIN_REQUIRED, 'main', MAIN_ABI_MIN, MAIN_ABI_MAX);
+    return exports;
+}
+/** Validate and narrow `WebAssembly.Exports` to the typed PDF interface. */
+export function asAlbexPdfExports(exports) {
+    validateExports(exports, PDF_REQUIRED, 'pdf', PDF_ABI_MIN, PDF_ABI_MAX);
+    return exports;
+}
+//# sourceMappingURL=wasm-bindings.js.map

package/dist/wasm-bindings.js.map

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

package/dist/worker-protocol.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Wire protocol between the main thread and the AlbexEngineWorker runtime.
+ *
+ * One request/response pair per call, identified by `id`. The runtime is
+ * single-threaded so we serialise requests on the main side (one in-flight
+ * call at a time per worker) — keeps the protocol trivial and matches the
+ * actual constraint of `static mut` WASM state.
+ *
+ * `Transferable` is opt-in per op; we use it for `indexFile` to avoid
+ * copying the file bytes into the worker.
+ */
+import type { AlbexOptions, IndexedDocument, SearchOptions, SearchResult, EngineStats, SearchStats } from './albex.js';
+export type WorkerOp = {
+    kind: 'init';
+    opts: AlbexOptions;
+} | {
+    kind: 'indexFile';
+    name: string;
+    buffer: ArrayBuffer;
+} | {
+    kind: 'search';
+    query: string;
+    options: SearchOptions;
+} | {
+    kind: 'removeDocument';
+    id: string;
+} | {
+    kind: 'compact';
+} | {
+    kind: 'reset';
+} | {
+    kind: 'getStats';
+} | {
+    kind: 'getLastSearchStats';
+} | {
+    kind: 'getDocuments';
+} | {
+    kind: 'setMaxErrors';
+    n: 0 | 1 | 2 | 3;
+} | {
+    kind: 'setThreshold';
+    n: number;
+} | {
+    kind: 'setMaxResults';
+    n: number;
+} | {
+    kind: 'setLanguage';
+    lang: 'off' | 'es';
+} | {
+    kind: 'save';
+    name: string;
+} | {
+    kind: 'load';
+    name: string;
+} | {
+    kind: 'loadOrInit';
+    name: string;
+} | {
+    kind: 'deleteSnapshot';
+    name: string;
+} | {
+    kind: 'listSnapshots';
+};
+export interface WorkerRequest {
+    id: number;
+    op: WorkerOp;
+}
+export type WorkerResponse = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: {
+        name: string;
+        kind?: string;
+        message: string;
+    };
+};
+export type IndexFileResult = IndexedDocument;
+export type SearchResultArr = SearchResult[];
+export type StatsResult = EngineStats;
+export type SearchStatsRes = SearchStats | null;
+export type DocsResult = readonly IndexedDocument[];
+//# sourceMappingURL=worker-protocol.d.ts.map

package/dist/worker-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["../src/worker-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAY,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAQ,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAW,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAG,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAM,IAAI,EAAE,KAAK,GAAG,IAAI,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAa,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAa,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAO,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAG,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG,eAAe,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,YAAY,EAAE,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAO,WAAW,CAAC;AAC1C,MAAM,MAAM,cAAc,GAAI,WAAW,GAAG,IAAI,CAAC;AACjD,MAAM,MAAM,UAAU,GAAQ,SAAS,eAAe,EAAE,CAAC"}