albex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RafaCalRob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# Albex
+
+Local full-text search for documents. Runs entirely in the browser — no server, no upload, no network request after the initial load.
+
+Drop a DOCX, PDF, XLSX, TXT or XML file, start typing, get results in milliseconds.
+
+---
+
+## Features
+
+- **Zero server** — all text stays on the user's machine.
+- **Fuzzy matching** — finds "contrato" even if you type "conttrato" (adaptive edit distance).
+- **Accent-insensitive** — "accion" matches "acción", "espana" matches "España".
+- **Multi-format** — DOCX, XLSX, PDF (text-based), TXT, XML.
+- **Phrase search** — `"contrato marco"` requires the words to appear together.
+- **OR search** — `contrato | acuerdo` unions two independent searches.
+- **No dependencies** — one TypeScript file, two WASM binaries, nothing else.
+- **Tiny footprint** — main WASM is ~14 KB on disk; PDF module (~1 MB) loads on demand.
+
+---
+
+## Installation
+
+```bash
+npm install albex
+```
+
+Or copy `dist/albex.js`, `wasm/pkg/albex_wasm_bg.wasm` (and optionally `albex_pdf.wasm`) to your project.
+
+---
+
+## Quick start
+
+```ts
+import { AlbexEngine } from 'albex';
+
+const engine = new AlbexEngine({
+  wasmUrl:    '/assets/albex_wasm_bg.wasm',
+  pdfWasmUrl: '/assets/albex_pdf.wasm',   // only needed for PDFs
+});
+
+await engine.init();
+
+// Index a file from a <input type="file"> or drag-and-drop
+const file = inputElement.files[0];
+const doc  = await engine.indexFile(file);
+console.log(`Indexed ${doc.chunks} chunks in ${doc.indexTimeMs.toFixed(0)} ms`);
+
+// Search
+const results = engine.search('contrato marco');
+for (const r of results) {
+  console.log(`[${r.score}] ${r.documentName} — ${r.snippet}`);
+}
+```
+
+---
+
+## Supported formats
+
+| Extension | How text is extracted |
+|-----------|----------------------|
+| `.docx`   | Native Rust/WASM XML parser — reads `word/document.xml` directly |
+| `.xlsx`   | Native Rust/WASM XML parser — reads shared strings + inline strings |
+| `.pdf`    | Separate `albex_pdf.wasm` (pure Rust, loaded on demand) |
+| `.txt`    | Plain text split on double newlines |
+| `.xml`    | Tag-stripped, entity-decoded |
+
+---
+
+## Query syntax
+
+| Input | Behaviour |
+|-------|-----------|
+| `contrato` | Fuzzy match, accent-insensitive |
+| `contrato marco` | Both words must appear in the same chunk |
+| `"contrato marco"` | Both words AND they must be adjacent (phrase) |
+| `contrato \| acuerdo` | OR: returns results matching either term |
+
+Up to 4 space-separated tokens per simple/phrase query. OR branches are unlimited.
+
+---
+
+## API reference
+
+### `new AlbexEngine(opts)`
+
+```ts
+interface AlbexOptions {
+  wasmUrl:     string;   // required
+  pdfWasmUrl?: string;   // required only for PDF indexing
+}
+```
+
+### `engine.init(): Promise<void>`
+
+Fetches and initialises the main WASM module. Must be called before anything else.
+
+### `engine.indexFile(file: File): Promise<IndexedDocument>`
+
+Detects the file format by extension, extracts text, and adds it to the search index. Throws for unsupported extensions or parse errors.
+
+```ts
+interface IndexedDocument {
+  name:        string;
+  ext:         string;
+  chunks:      number;   // number of indexed text chunks
+  indexTimeMs: number;
+  textBytes:   number;   // raw UTF-8 text indexed
+}
+```
+
+### `engine.search(query: string): SearchResult[]`
+
+Returns results sorted by score (0–1000, descending).
+
+```ts
+interface SearchResult {
+  documentName: string;
+  location:     number;   // paragraph (DOCX/TXT) or page (PDF, 1-based)
+  score:        number;   // 0–1000
+  snippet:      string;   // full chunk text (original, with accents)
+  matchStart:   number;   // byte offset of match in snippet
+  matchEnd:     number;   // exclusive
+}
+```
+
+### `engine.getStats(): EngineStats`
+
+```ts
+interface EngineStats {
+  documents:       number;
+  chunks:          number;
+  textUsed:        number;   // bytes
+  textCapacity:    number;   // 16 MB hard cap
+  wasmMemoryBytes: number;
+}
+```
+
+### `engine.getLastSearchStats(): SearchStats | null`
+
+Bloom/Bitap pipeline counters from the most recent search — useful for debugging and UI dashboards.
+
+```ts
+interface SearchStats {
+  query:        string;
+  timeMs:       number;
+  results:      number;
+  bloomTested:  number;   // chunks tested
+  bloomPassed:  number;   // passed bloom pre-filter
+  bitapMatched: number;   // confirmed by Bitap
+}
+```
+
+### Tuning
+
+```ts
+engine.setMaxErrors(n);     // 0–3  (default 2, auto-scaled by query length)
+engine.setThreshold(n);     // 0–1000 minimum score (default 250)
+engine.setMaxResults(n);    // 1–200 (default 50)
+```
+
+### `engine.reset()`
+
+Clears all indexed documents. The engine is ready to index new files immediately after.
+
+---
+
+## Capacity
+
+| Resource | Limit |
+|----------|-------|
+| Documents | 128 |
+| Chunks | 100 000 |
+| Total text | 16 MB |
+| Query length | 64 characters (longer queries are truncated) |
+| Results | 200 (configurable, default 50) |
+
+These are hard-coded BSS limits in the WASM module. Exceeding them is silent — the engine stops indexing additional content without error.
+
+---
+
+## Browser requirements
+
+- WebAssembly (all modern browsers since 2017)
+- `DecompressionStream` for DOCX/XLSX (Chrome 80+, Firefox 113+, Safari 16.4+)
+- `String.prototype.normalize` for phrase search (all modern browsers)
+
+PDF support additionally requires the `albex_pdf.wasm` module to be served with the correct MIME type (`application/wasm`).
+
+---
+
+## Building from source
+
+```bash
+# Install Rust + wasm-pack
+rustup target add wasm32-unknown-unknown
+
+# Build main WASM
+cd wasm && cargo build --target wasm32-unknown-unknown --release
+cp ../target/wasm32-unknown-unknown/release/albex_wasm.wasm pkg/albex_wasm_bg.wasm
+
+# Build PDF WASM
+cd ../pdf-wasm && cargo build --target wasm32-unknown-unknown --release
+cp ../target/wasm32-unknown-unknown/release/albex_pdf.wasm ../wasm/pkg/albex_pdf.wasm
+
+# Build TypeScript
+cd .. && npm install && npm run build
+```
+
+---
+
+## Privacy
+
+Albex does not transmit any document content. Text extraction, indexing, and search all happen inside the browser's WASM sandbox. The only network requests are the initial fetch of the `.wasm` binary files.
+
+---
+
+## License
+
+MIT

package/dist/albex.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Albex — local full-text search engine.
+ *
+ * Zero-dependency TypeScript/ESM wrapper around albex_wasm_bg.wasm and
+ * (optionally) albex_pdf.wasm. All text stays in-browser; nothing is sent
+ * to any server.
+ *
+ * @example
+ * ```ts
+ * const engine = new AlbexEngine({ wasmUrl: './wasm/pkg/albex_wasm_bg.wasm' });
+ * await engine.init();
+ * await engine.indexFile(myFile);
+ * const results = engine.search('contrato marco');
+ * ```
+ */
+export interface AlbexOptions {
+    /** URL to albex_wasm_bg.wasm (required). */
+    wasmUrl: string;
+    /** URL to albex_pdf.wasm. Required only if you call indexFile() with PDFs. */
+    pdfWasmUrl?: string;
+}
+export interface IndexedDocument {
+    name: string;
+    ext: string;
+    chunks: number;
+    indexTimeMs: number;
+    textBytes: number;
+}
+export interface SearchResult {
+    documentName: string;
+    /** Paragraph index (DOCX/TXT) or page number (PDF, 1-based). */
+    location: number;
+    /** Relevance score 0–1000. */
+    score: number;
+    /** Raw snippet text (original, with accents). */
+    snippet: string;
+    /** Match start byte offset within snippet. */
+    matchStart: number;
+    /** Match end byte offset within snippet (exclusive). */
+    matchEnd: number;
+}
+export interface EngineStats {
+    documents: number;
+    chunks: number;
+    textUsed: number;
+    textCapacity: number;
+    wasmMemoryBytes: number;
+}
+export interface SearchStats {
+    query: string;
+    timeMs: number;
+    results: number;
+    bloomTested: number;
+    bloomPassed: number;
+    bitapMatched: number;
+}
+export declare class AlbexEngine {
+    private _wasm;
+    private _mem;
+    private _pdfWasm;
+    private _pdfMem;
+    private _docs;
+    private _lastSearch;
+    private readonly _opts;
+    constructor(opts: AlbexOptions);
+    /** Load and initialise the main WASM module. Must be called before any other method. */
+    init(): Promise<void>;
+    private _u8;
+    private _writePad;
+    private _writeStr;
+    private _readPad;
+    private _feedText;
+    private _feedXmlBytes;
+    private _ensurePdfWasm;
+    private _indexDocx;
+    private _indexXlsx;
+    private _indexPdf;
+    private _indexTxt;
+    private _indexXml;
+    private static readonly _INDEXERS;
+    /**
+     * Index a file. Supported formats: DOCX, XLSX, PDF, TXT, XML.
+     * Throws for unsupported formats or parse errors.
+     */
+    indexFile(file: File): Promise<IndexedDocument>;
+    /**
+     * Search the index. Supports:
+     * - Simple queries:  `contrato`  (AND of tokens, accent-insensitive)
+     * - Phrase queries:  `"contrato marco"`  (must appear as phrase)
+     * - OR queries:      `contrato | acuerdo`  (union of two searches)
+     */
+    search(query: string): SearchResult[];
+    private _searchOr;
+    private _runSearch;
+    /** Returns current engine statistics. */
+    getStats(): EngineStats;
+    /** Returns stats from the most recent search, or null. */
+    getLastSearchStats(): SearchStats | null;
+    /** Returns the list of indexed documents. */
+    get documents(): readonly IndexedDocument[];
+    /** Supported file extensions. */
+    static get supportedExtensions(): string[];
+    /** Configure search sensitivity. */
+    setMaxErrors(errors: 0 | 1 | 2 | 3): void;
+    setThreshold(threshold: number): void;
+    setMaxResults(max: number): void;
+    /** Full reset — clears all indexed documents and chunks. */
+    reset(): void;
+}
+//# sourceMappingURL=albex.d.ts.map

package/dist/albex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"albex.d.ts","sourceRoot":"","sources":["../src/albex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAsLD,qBAAa,WAAW;IAEtB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,IAAI,CAAsB;IAGlC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,OAAO,CAAmC;IAElD,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,IAAI,EAAE,YAAY;IAI9B,wFAAwF;IAClF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,aAAa;YAUP,cAAc;YAad,UAAU;YASV,UAAU;YAqBV,SAAS;YAuCT,SAAS;YAWT,SAAS;IAevB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAM/B;IAIF;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC;IAmBrD;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IAgBrC,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,UAAU;IAiClB,yCAAyC;IACzC,QAAQ,IAAI,WAAW;IAUvB,0DAA0D;IAC1D,kBAAkB,IAAI,WAAW,GAAG,IAAI;IAIxC,6CAA6C;IAC7C,IAAI,SAAS,IAAI,SAAS,eAAe,EAAE,CAE1C;IAED,iCAAiC;IACjC,MAAM,KAAK,mBAAmB,IAAI,MAAM,EAAE,CAEzC;IAED,oCAAoC;IACpC,YAAY,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI;IAIzC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,4DAA4D;IAC5D,KAAK,IAAI,IAAI;CAKd"}