hermes-wasm 1.8.28 → 1.8.29

package/README.md

@@ -0,0 +1,236 @@
+# hermes-wasm
+
+WebAssembly bindings for the [Hermes](https://github.com/SpaceFrontiers/hermes) search engine. Run a full-text search engine entirely in the browser — including indexing, BM25 ranking, and document storage.
+
+## Features
+
+- **Local indexing** — create indexes, add documents, commit, and search entirely in WASM
+- **IndexedDB persistence** — indexes survive page refreshes via per-file IDB records
+- **Remote search** — load pre-built indexes over HTTP with slice caching
+- **IPFS support** — load indexes from IPFS via JavaScript fetch callbacks
+- **15+ language stemmers** — English, German, French, Spanish, Russian, Arabic, and more
+- **Query language** — `field:term`, `AND`, `OR`, `NOT`, grouping with parentheses
+- **~3 MB** WASM binary (gzipped ~1.2 MB)
+
+## Quick Start
+
+```bash
+npm install hermes-wasm
+```
+
+### In-Memory Index
+
+```js
+import init, { LocalIndex } from "hermes-wasm";
+
+await init();
+
+// Define schema using SDL
+const index = await LocalIndex.create(`
+  index articles {
+    field title: text<en_stem> [indexed, stored]
+    field body:  text<en_stem> [indexed, stored]
+    field views: u64 [indexed, stored]
+  }
+`);
+
+// Add documents
+await index.addDocuments([
+  {
+    title: "Rust Programming",
+    body: "Rust is a systems language.",
+    views: 1500,
+  },
+  { title: "Search Engines", body: "BM25 is a ranking function.", views: 800 },
+]);
+
+// Commit (builds the segment)
+await index.commit();
+
+// Search
+const results = await index.search("rust", 10);
+// { hits: [{ address: { segment_id, doc_id }, score }], total_hits: 1 }
+
+// Get document
+const doc = await index.getDocument(
+  results.hits[0].address.segment_id,
+  results.hits[0].address.doc_id,
+);
+// { title: "Rust Programming", body: "Rust is a systems language.", views: 1500 }
+```
+
+### Persistent Index (IndexedDB)
+
+```js
+// Create — auto-saves changed files to IDB on each commit
+const index = await LocalIndex.createPersistent("my-index", schema);
+await index.addDocuments(docs);
+await index.commit(); // only new segment files written to IDB
+
+// Later, on page reload:
+const index = await LocalIndex.open("my-index");
+const results = await index.search("rust", 10); // works immediately
+
+// Management
+await LocalIndex.exists("my-index"); // true
+await LocalIndex.deleteIndex("my-index");
+```
+
+### Remote Index (HTTP)
+
+```js
+import init, { RemoteIndex } from "hermes-wasm";
+
+await init();
+
+const index = new RemoteIndex("https://example.com/my-index/");
+await index.load_with_idb_cache(); // loads with IndexedDB cache for fast reload
+
+const results = await index.search("query", 10);
+
+// Fetch a document
+const doc = await index.get_document(
+  results.hits[0].address.segment_id,
+  results.hits[0].address.doc_id,
+);
+```
+
+## API Reference
+
+### `LocalIndex`
+
+| Method                                     | Description                             |
+| ------------------------------------------ | --------------------------------------- |
+| `LocalIndex.create(sdl)`                   | Create in-memory index from SDL schema  |
+| `LocalIndex.createPersistent(name, sdl)`   | Create IndexedDB-backed index           |
+| `LocalIndex.open(name)`                    | Open existing persistent index from IDB |
+| `LocalIndex.deleteIndex(name)`             | Delete persistent index from IDB        |
+| `LocalIndex.exists(name)`                  | Check if persistent index exists in IDB |
+| `index.addDocument(json)`                  | Add a single document                   |
+| `index.addDocuments(jsonArray)`            | Add multiple documents, returns count   |
+| `index.commit()`                           | Commit pending docs (builds segments)   |
+| `index.search(query, limit)`               | Search with BM25 ranking                |
+| `index.searchOffset(query, limit, offset)` | Search with pagination                  |
+| `index.getDocument(segmentId, docId)`      | Retrieve stored document                |
+| `index.numDocs()`                          | Count of committed documents            |
+| `index.pendingDocs()`                      | Count of uncommitted documents          |
+| `index.fieldNames()`                       | List of field names                     |
+
+### `RemoteIndex`
+
+| Method                                      | Description                         |
+| ------------------------------------------- | ----------------------------------- |
+| `new RemoteIndex(url)`                      | Create remote index pointing to URL |
+| `RemoteIndex.with_cache_size(url, bytes)`   | Create with custom cache size       |
+| `index.load()`                              | Load index metadata and segments    |
+| `index.load_with_idb_cache()`               | Load with IndexedDB cache pre-fill  |
+| `index.search(query, limit)`                | Search                              |
+| `index.search_offset(query, limit, offset)` | Search with pagination              |
+| `index.get_document(segmentId, docId)`      | Retrieve document                   |
+| `index.num_docs()`                          | Document count                      |
+| `index.num_segments()`                      | Segment count                       |
+| `index.field_names()`                       | Field names                         |
+| `index.default_fields()`                    | Default search fields               |
+| `index.export_cache()`                      | Export slice cache as `Uint8Array`  |
+| `index.import_cache(data)`                  | Import previously exported cache    |
+| `index.save_cache_to_idb()`                 | Persist slice cache to IndexedDB    |
+| `index.load_cache_from_idb()`               | Restore cache from IndexedDB        |
+| `index.clear_idb_cache()`                   | Remove persisted cache              |
+| `index.cache_stats()`                       | Cache utilization info              |
+| `index.network_stats()`                     | HTTP request statistics             |
+| `index.reset_network_stats()`               | Clear network statistics            |
+
+### `IpfsIndex`
+
+Same API as `RemoteIndex` but loaded via JavaScript callbacks instead of HTTP:
+
+| Method                                       | Description                              |
+| -------------------------------------------- | ---------------------------------------- |
+| `new IpfsIndex(basePath)`                    | Create with IPFS path (e.g. `/ipfs/Qm…`) |
+| `IpfsIndex.with_cache_size(path, bytes)`     | Create with custom cache size            |
+| `index.load(fetchFn, sizeFn)`                | Load using JS callbacks                  |
+| `index.load_with_idb_cache(fetchFn, sizeFn)` | Load with IDB cache + JS callbacks       |
+
+`fetchFn`: `(path: string, rangeStart?: number, rangeEnd?: number) => Promise<Uint8Array>`
+`sizeFn`: `(path: string) => Promise<number>`
+
+All other methods (`search`, `get_document`, `cache_stats`, etc.) are identical to `RemoteIndex`.
+
+### `IndexRegistry`
+
+Manages multiple named remote indexes:
+
+| Method                                | Description                    |
+| ------------------------------------- | ------------------------------ |
+| `new IndexRegistry()`                 | Create empty registry          |
+| `registry.add_remote(name, url)`      | Load and register remote index |
+| `registry.remove(name)`               | Remove index                   |
+| `registry.list()`                     | List index names               |
+| `registry.search(name, query, limit)` | Search a specific index        |
+
+### Schema Definition Language (SDL)
+
+```
+index <name> {
+    field <name>: <type> [attributes]
+}
+```
+
+**Types:** `text`, `u64`, `i64`, `f64`, `bytes`
+
+**Tokenizers:** `text<en_stem>`, `text<de_stem>`, `text<fr_stem>`, `text<es_stem>`, `text<it_stem>`, `text<pt_stem>`, `text<ru_stem>`, `text<ar_stem>`, `text<simple>`, etc.
+
+**Attributes:** `indexed` (searchable), `stored` (retrievable), `fast` (columnar access)
+
+### Query Language
+
+| Syntax | Example                | Description                 |
+| ------ | ---------------------- | --------------------------- |
+| Term   | `rust`                 | Match across default fields |
+| Field  | `title:rust`           | Match in specific field     |
+| AND    | `rust AND web`         | Both terms required         |
+| OR     | `rust OR python`       | Either term                 |
+| NOT    | `rust NOT unsafe`      | Exclude term                |
+| Group  | `(rust OR go) AND web` | Grouping                    |
+| Phrase | `"search engine"`      | Exact phrase                |
+
+## Building
+
+```bash
+cd hermes-wasm
+bash build.sh  # requires Homebrew LLVM on macOS
+```
+
+The build script sets `CC` and `AR` to Homebrew LLVM binaries for zstd cross-compilation to `wasm32-unknown-unknown`.
+
+## Example
+
+Open `examples/index.html` in a browser (needs to be served, not opened as file):
+
+```bash
+cd hermes-wasm
+bash build.sh
+cp pkg/hermes_wasm.js pkg/hermes_wasm_bg.wasm examples/
+cd examples && python3 -m http.server 8080
+# Open http://localhost:8080
+```
+
+## Architecture
+
+```
+Browser JS
+    │
+    ├── LocalIndex (create/index/search in WASM)
+    │       └── WasmIndexWriter → SegmentBuilder → RamDirectory
+    │                                                   │
+    │                                         [per-file IndexedDB records]
+    │
+    ├── RemoteIndex (HTTP range requests)
+    │       └── Searcher → SliceCachingDirectory → HttpDirectory
+    │
+    ├── IpfsIndex (JS fetch callbacks)
+    │       └── Searcher → SliceCachingDirectory → JsFetchDirectory
+    │
+    └── IndexRegistry (multi-index management)
+            └── Map<name, RemoteIndex>
+```

package/hermes_wasm.d.ts

@@ -113,6 +113,9 @@ export class IpfsIndex {
     save_cache_to_idb(): Promise<void>;
     /**
      * Search the index
+     *
+     * Returns `{ hits: [{ address: { segment_id: string, doc_id: number }, score: number }], total_hits: number }`.
+     * Use `get_document(hit.address.segment_id, hit.address.doc_id)` to fetch document content.
      */
     search(query_str: string, limit: number): Promise<any>;
     /**
@@ -125,6 +128,93 @@ export class IpfsIndex {
     static with_cache_size(base_path: string, cache_size: number): IpfsIndex;
 }
 
+/**
+ * In-browser local index — create, index documents, search, all in WASM.
+ *
+ * ```js
+ * // In-memory (ephemeral)
+ * const index = await LocalIndex.create("index articles { field title: text<en_stem> [indexed, stored] }");
+ *
+ * // Persistent (IndexedDB-backed)
+ * const index = await LocalIndex.createPersistent("my-index", "index articles { ... }");
+ * // ... later, on page reload:
+ * const index = await LocalIndex.open("my-index");
+ * ```
+ */
+export class LocalIndex {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add a single document (JSON object with field names matching the schema).
+     */
+    addDocument(doc_json: any): Promise<void>;
+    /**
+     * Add multiple documents at once (array of JSON objects).
+     */
+    addDocuments(docs_json: any): Promise<number>;
+    /**
+     * Commit pending documents — builds segments and updates metadata.
+     *
+     * For persistent indexes, only writes new/changed files to IndexedDB.
+     */
+    commit(): Promise<boolean>;
+    /**
+     * Create a new in-memory index from an SDL schema string.
+     *
+     * Data is lost on page refresh. Use `createPersistent()` for IndexedDB-backed storage.
+     */
+    static create(schema_sdl: string): Promise<LocalIndex>;
+    /**
+     * Create a new persistent index backed by IndexedDB.
+     *
+     * Each file in the index gets its own IDB record — commits only write
+     * new/changed files, not the entire index.
+     * Use `LocalIndex.open(name)` to reopen it after page refresh.
+     */
+    static createPersistent(name: string, schema_sdl: string): Promise<LocalIndex>;
+    /**
+     * Delete a persistent index from IndexedDB.
+     */
+    static deleteIndex(name: string): Promise<void>;
+    /**
+     * Check if a persistent index exists in IndexedDB.
+     */
+    static exists(name: string): Promise<boolean>;
+    /**
+     * Get field names from the schema.
+     */
+    fieldNames(): any;
+    /**
+     * Get a document by its address.
+     */
+    getDocument(segment_id: string, doc_id: number): Promise<any>;
+    /**
+     * Number of indexed documents (across all committed segments).
+     */
+    numDocs(): number;
+    /**
+     * Open an existing persistent index from IndexedDB.
+     *
+     * Loads the file manifest and all index files into a RamDirectory.
+     */
+    static open(name: string): Promise<LocalIndex>;
+    /**
+     * Number of documents pending (not yet committed).
+     */
+    pendingDocs(): number;
+    /**
+     * Search the index.
+     *
+     * Returns `{ hits: [{ address: { segment_id, doc_id }, score }], total_hits }`.
+     */
+    search(query_str: string, limit: number): Promise<any>;
+    /**
+     * Search with offset for pagination.
+     */
+    searchOffset(query_str: string, limit: number, offset: number): Promise<any>;
+}
+
 /**
  * Remote index that loads data via HTTP with slice caching
  */
@@ -219,7 +309,9 @@ export class RemoteIndex {
      *
      * Accepts both query language syntax (field:term, AND, OR, NOT, grouping)
      * and simple text (tokenized and searched across default fields).
-     * Returns document addresses (segment_id + doc_id) without document content.
+     *
+     * Returns `{ hits: [{ address: { segment_id: string, doc_id: number }, score: number }], total_hits: number }`.
+     * Use `get_document(hit.address.segment_id, hit.address.doc_id)` to fetch document content.
      */
     search(query_str: string, limit: number): Promise<any>;
     /**
@@ -246,30 +338,9 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
-    readonly __wbg_remoteindex_free: (a: number, b: number) => void;
-    readonly remoteindex_cache_stats: (a: number) => any;
-    readonly remoteindex_clear_idb_cache: (a: number) => any;
-    readonly remoteindex_default_fields: (a: number) => any;
-    readonly remoteindex_export_cache: (a: number) => [number, number];
-    readonly remoteindex_field_names: (a: number) => any;
-    readonly remoteindex_get_document: (a: number, b: number, c: number, d: number) => any;
-    readonly remoteindex_import_cache: (a: number, b: number, c: number) => [number, number];
-    readonly remoteindex_load: (a: number) => any;
-    readonly remoteindex_load_cache_from_idb: (a: number) => any;
-    readonly remoteindex_load_with_idb_cache: (a: number) => any;
-    readonly remoteindex_network_stats: (a: number) => any;
-    readonly remoteindex_new: (a: number, b: number) => number;
-    readonly remoteindex_num_docs: (a: number) => number;
-    readonly remoteindex_num_segments: (a: number) => number;
-    readonly remoteindex_reset_network_stats: (a: number) => void;
-    readonly remoteindex_save_cache_to_idb: (a: number) => any;
-    readonly remoteindex_search: (a: number, b: number, c: number, d: number) => any;
-    readonly remoteindex_search_offset: (a: number, b: number, c: number, d: number, e: number) => any;
-    readonly remoteindex_with_cache_size: (a: number, b: number, c: number) => number;
-    readonly init: () => void;
-    readonly setup_logging: () => void;
     readonly __wbg_indexregistry_free: (a: number, b: number) => void;
     readonly __wbg_ipfsindex_free: (a: number, b: number) => void;
+    readonly __wbg_remoteindex_free: (a: number, b: number) => void;
     readonly indexregistry_add_remote: (a: number, b: number, c: number, d: number, e: number) => any;
     readonly indexregistry_list: (a: number) => any;
     readonly indexregistry_new: () => number;
@@ -294,6 +365,42 @@ export interface InitOutput {
     readonly ipfsindex_search: (a: number, b: number, c: number, d: number) => any;
     readonly ipfsindex_search_offset: (a: number, b: number, c: number, d: number, e: number) => any;
     readonly ipfsindex_with_cache_size: (a: number, b: number, c: number) => number;
+    readonly remoteindex_cache_stats: (a: number) => any;
+    readonly remoteindex_clear_idb_cache: (a: number) => any;
+    readonly remoteindex_default_fields: (a: number) => any;
+    readonly remoteindex_export_cache: (a: number) => [number, number];
+    readonly remoteindex_field_names: (a: number) => any;
+    readonly remoteindex_get_document: (a: number, b: number, c: number, d: number) => any;
+    readonly remoteindex_import_cache: (a: number, b: number, c: number) => [number, number];
+    readonly remoteindex_load: (a: number) => any;
+    readonly remoteindex_load_cache_from_idb: (a: number) => any;
+    readonly remoteindex_load_with_idb_cache: (a: number) => any;
+    readonly remoteindex_network_stats: (a: number) => any;
+    readonly remoteindex_new: (a: number, b: number) => number;
+    readonly remoteindex_reset_network_stats: (a: number) => void;
+    readonly remoteindex_save_cache_to_idb: (a: number) => any;
+    readonly remoteindex_search: (a: number, b: number, c: number, d: number) => any;
+    readonly remoteindex_search_offset: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly remoteindex_with_cache_size: (a: number, b: number, c: number) => number;
+    readonly init: () => void;
+    readonly setup_logging: () => void;
+    readonly remoteindex_num_docs: (a: number) => number;
+    readonly remoteindex_num_segments: (a: number) => number;
+    readonly __wbg_localindex_free: (a: number, b: number) => void;
+    readonly localindex_addDocument: (a: number, b: any) => any;
+    readonly localindex_addDocuments: (a: number, b: any) => any;
+    readonly localindex_commit: (a: number) => any;
+    readonly localindex_create: (a: number, b: number) => any;
+    readonly localindex_createPersistent: (a: number, b: number, c: number, d: number) => any;
+    readonly localindex_deleteIndex: (a: number, b: number) => any;
+    readonly localindex_exists: (a: number, b: number) => any;
+    readonly localindex_fieldNames: (a: number) => any;
+    readonly localindex_getDocument: (a: number, b: number, c: number, d: number) => any;
+    readonly localindex_numDocs: (a: number) => number;
+    readonly localindex_open: (a: number, b: number) => any;
+    readonly localindex_pendingDocs: (a: number) => number;
+    readonly localindex_search: (a: number, b: number, c: number, d: number) => any;
+    readonly localindex_searchOffset: (a: number, b: number, c: number, d: number, e: number) => any;
     readonly rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
     readonly rust_zstd_wasm_shim_free: (a: number) => void;
     readonly rust_zstd_wasm_shim_malloc: (a: number) => number;

package/hermes_wasm.js

@@ -254,6 +254,9 @@ export class IpfsIndex {
     }
     /**
      * Search the index
+     *
+     * Returns `{ hits: [{ address: { segment_id: string, doc_id: number }, score: number }], total_hits: number }`.
+     * Use `get_document(hit.address.segment_id, hit.address.doc_id)` to fetch document content.
      * @param {string} query_str
      * @param {number} limit
      * @returns {Promise<any>}
@@ -292,6 +295,197 @@ export class IpfsIndex {
 }
 if (Symbol.dispose) IpfsIndex.prototype[Symbol.dispose] = IpfsIndex.prototype.free;
 
+/**
+ * In-browser local index — create, index documents, search, all in WASM.
+ *
+ * ```js
+ * // In-memory (ephemeral)
+ * const index = await LocalIndex.create("index articles { field title: text<en_stem> [indexed, stored] }");
+ *
+ * // Persistent (IndexedDB-backed)
+ * const index = await LocalIndex.createPersistent("my-index", "index articles { ... }");
+ * // ... later, on page reload:
+ * const index = await LocalIndex.open("my-index");
+ * ```
+ */
+export class LocalIndex {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(LocalIndex.prototype);
+        obj.__wbg_ptr = ptr;
+        LocalIndexFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        LocalIndexFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_localindex_free(ptr, 0);
+    }
+    /**
+     * Add a single document (JSON object with field names matching the schema).
+     * @param {any} doc_json
+     * @returns {Promise<void>}
+     */
+    addDocument(doc_json) {
+        const ret = wasm.localindex_addDocument(this.__wbg_ptr, doc_json);
+        return ret;
+    }
+    /**
+     * Add multiple documents at once (array of JSON objects).
+     * @param {any} docs_json
+     * @returns {Promise<number>}
+     */
+    addDocuments(docs_json) {
+        const ret = wasm.localindex_addDocuments(this.__wbg_ptr, docs_json);
+        return ret;
+    }
+    /**
+     * Commit pending documents — builds segments and updates metadata.
+     *
+     * For persistent indexes, only writes new/changed files to IndexedDB.
+     * @returns {Promise<boolean>}
+     */
+    commit() {
+        const ret = wasm.localindex_commit(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Create a new in-memory index from an SDL schema string.
+     *
+     * Data is lost on page refresh. Use `createPersistent()` for IndexedDB-backed storage.
+     * @param {string} schema_sdl
+     * @returns {Promise<LocalIndex>}
+     */
+    static create(schema_sdl) {
+        const ptr0 = passStringToWasm0(schema_sdl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_create(ptr0, len0);
+        return ret;
+    }
+    /**
+     * Create a new persistent index backed by IndexedDB.
+     *
+     * Each file in the index gets its own IDB record — commits only write
+     * new/changed files, not the entire index.
+     * Use `LocalIndex.open(name)` to reopen it after page refresh.
+     * @param {string} name
+     * @param {string} schema_sdl
+     * @returns {Promise<LocalIndex>}
+     */
+    static createPersistent(name, schema_sdl) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(schema_sdl, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_createPersistent(ptr0, len0, ptr1, len1);
+        return ret;
+    }
+    /**
+     * Delete a persistent index from IndexedDB.
+     * @param {string} name
+     * @returns {Promise<void>}
+     */
+    static deleteIndex(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_deleteIndex(ptr0, len0);
+        return ret;
+    }
+    /**
+     * Check if a persistent index exists in IndexedDB.
+     * @param {string} name
+     * @returns {Promise<boolean>}
+     */
+    static exists(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_exists(ptr0, len0);
+        return ret;
+    }
+    /**
+     * Get field names from the schema.
+     * @returns {any}
+     */
+    fieldNames() {
+        const ret = wasm.localindex_fieldNames(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Get a document by its address.
+     * @param {string} segment_id
+     * @param {number} doc_id
+     * @returns {Promise<any>}
+     */
+    getDocument(segment_id, doc_id) {
+        const ptr0 = passStringToWasm0(segment_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_getDocument(this.__wbg_ptr, ptr0, len0, doc_id);
+        return ret;
+    }
+    /**
+     * Number of indexed documents (across all committed segments).
+     * @returns {number}
+     */
+    numDocs() {
+        const ret = wasm.localindex_numDocs(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Open an existing persistent index from IndexedDB.
+     *
+     * Loads the file manifest and all index files into a RamDirectory.
+     * @param {string} name
+     * @returns {Promise<LocalIndex>}
+     */
+    static open(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_open(ptr0, len0);
+        return ret;
+    }
+    /**
+     * Number of documents pending (not yet committed).
+     * @returns {number}
+     */
+    pendingDocs() {
+        const ret = wasm.localindex_pendingDocs(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Search the index.
+     *
+     * Returns `{ hits: [{ address: { segment_id, doc_id }, score }], total_hits }`.
+     * @param {string} query_str
+     * @param {number} limit
+     * @returns {Promise<any>}
+     */
+    search(query_str, limit) {
+        const ptr0 = passStringToWasm0(query_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_search(this.__wbg_ptr, ptr0, len0, limit);
+        return ret;
+    }
+    /**
+     * Search with offset for pagination.
+     * @param {string} query_str
+     * @param {number} limit
+     * @param {number} offset
+     * @returns {Promise<any>}
+     */
+    searchOffset(query_str, limit, offset) {
+        const ptr0 = passStringToWasm0(query_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.localindex_searchOffset(this.__wbg_ptr, ptr0, len0, limit, offset);
+        return ret;
+    }
+}
+if (Symbol.dispose) LocalIndex.prototype[Symbol.dispose] = LocalIndex.prototype.free;
+
 /**
  * Remote index that loads data via HTTP with slice caching
  */
@@ -480,7 +674,9 @@ export class RemoteIndex {
      *
      * Accepts both query language syntax (field:term, AND, OR, NOT, grouping)
      * and simple text (tokenized and searched across default fields).
-     * Returns document addresses (segment_id + doc_id) without document content.
+     *
+     * Returns `{ hits: [{ address: { segment_id: string, doc_id: number }, score: number }], total_hits: number }`.
+     * Use `get_document(hit.address.segment_id, hit.address.doc_id)` to fetch document content.
      * @param {string} query_str
      * @param {number} limit
      * @returns {Promise<any>}
@@ -547,6 +743,17 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg___wbindgen_bigint_get_as_i64_447a76b5c6ef7bda: function(arg0, arg1) {
+            const v = arg1;
+            const ret = typeof(v) === 'bigint' ? v : undefined;
+            getDataViewMemory0().setBigInt64(arg0 + 8 * 1, isLikeNone(ret) ? BigInt(0) : ret, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+        },
+        __wbg___wbindgen_boolean_get_c0f3f60bac5a78d1: function(arg0) {
+            const v = arg0;
+            const ret = typeof(v) === 'boolean' ? v : undefined;
+            return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+        },
         __wbg___wbindgen_debug_string_5398f5bb970e0daa: function(arg0, arg1) {
             const ret = debugString(arg1);
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -554,6 +761,14 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg___wbindgen_in_41dbb8413020e076: function(arg0, arg1) {
+            const ret = arg0 in arg1;
+            return ret;
+        },
+        __wbg___wbindgen_is_bigint_e2141d4f045b7eda: function(arg0) {
+            const ret = typeof(arg0) === 'bigint';
+            return ret;
+        },
         __wbg___wbindgen_is_function_3c846841762788c1: function(arg0) {
             const ret = typeof(arg0) === 'function';
             return ret;
@@ -562,6 +777,11 @@ function __wbg_get_imports() {
             const ret = arg0 === null;
             return ret;
         },
+        __wbg___wbindgen_is_object_781bc9f159099513: function(arg0) {
+            const val = arg0;
+            const ret = typeof(val) === 'object' && val !== null;
+            return ret;
+        },
         __wbg___wbindgen_is_string_7ef6b97b02428fae: function(arg0) {
             const ret = typeof(arg0) === 'string';
             return ret;
@@ -570,6 +790,14 @@ function __wbg_get_imports() {
             const ret = arg0 === undefined;
             return ret;
         },
+        __wbg___wbindgen_jsval_eq_ee31bfad3e536463: function(arg0, arg1) {
+            const ret = arg0 === arg1;
+            return ret;
+        },
+        __wbg___wbindgen_jsval_loose_eq_5bcc3bed3c69e72b: function(arg0, arg1) {
+            const ret = arg0 == arg1;
+            return ret;
+        },
         __wbg___wbindgen_number_get_34bb9d9dcfa21373: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'number' ? obj : undefined;
@@ -607,6 +835,10 @@ function __wbg_get_imports() {
             const ret = arg0.call(arg1, arg2);
             return ret;
         }, arguments); },
+        __wbg_call_e133b57c9155d22c: function() { return handleError(function (arg0, arg1) {
+            const ret = arg0.call(arg1);
+            return ret;
+        }, arguments); },
         __wbg_call_f858478a02f9600f: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
             const ret = arg0.call(arg1, arg2, arg3, arg4);
             return ret;
@@ -638,6 +870,10 @@ function __wbg_get_imports() {
             const ret = arg0.entries();
             return ret;
         },
+        __wbg_entries_e8a20ff8c9757101: function(arg0) {
+            const ret = Object.entries(arg0);
+            return ret;
+        },
         __wbg_error_8d9a8e04cd1d3588: function(arg0) {
             console.error(arg0);
         },
@@ -664,6 +900,13 @@ function __wbg_get_imports() {
             const ret = arg0.fetch(arg1);
             return ret;
         },
+        __wbg_getRandomValues_3f44b700395062e5: function() { return handleError(function (arg0, arg1) {
+            globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+        }, arguments); },
+        __wbg_get_326e41e095fb2575: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_get_3ef1eba1850ade27: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
@@ -676,6 +919,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
+        __wbg_get_unchecked_329cfe50afab7352: function(arg0, arg1) {
+            const ret = arg0[arg1 >>> 0];
+            return ret;
+        },
         __wbg_has_926ef2ff40b308cf: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.has(arg0, arg1);
             return ret;
@@ -691,6 +938,16 @@ function __wbg_get_imports() {
         __wbg_info_7d4e223bb1a7e671: function(arg0) {
             console.info(arg0);
         },
+        __wbg_instanceof_ArrayBuffer_101e2bf31071a9f6: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof ArrayBuffer;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
         __wbg_instanceof_IdbDatabase_5f436cc89cc07f14: function(arg0) {
             let result;
             try {
@@ -721,6 +978,16 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_instanceof_Map_f194b366846aca0c: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof Map;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
         __wbg_instanceof_Response_9b4d9fd451e051b1: function(arg0) {
             let result;
             try {
@@ -755,10 +1022,26 @@ function __wbg_get_imports() {
             const ret = Array.isArray(arg0);
             return ret;
         },
+        __wbg_isSafeInteger_ecd6a7f9c3e053cd: function(arg0) {
+            const ret = Number.isSafeInteger(arg0);
+            return ret;
+        },
+        __wbg_iterator_d8f549ec8fb061b1: function() {
+            const ret = Symbol.iterator;
+            return ret;
+        },
+        __wbg_length_b3416cf66a5452c8: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
         __wbg_length_ea16607d7b61445b: function(arg0) {
             const ret = arg0.length;
             return ret;
         },
+        __wbg_localindex_new: function(arg0) {
+            const ret = LocalIndex.__wrap(arg0);
+            return ret;
+        },
         __wbg_log_524eedafa26daa59: function(arg0) {
             console.log(arg0);
         },
@@ -820,6 +1103,10 @@ function __wbg_get_imports() {
             const ret = arg0.next();
             return ret;
         }, arguments); },
+        __wbg_next_e01a967809d1aa68: function(arg0) {
+            const ret = arg0.next;
+            return ret;
+        },
         __wbg_now_c6d7a7d35f74f6f1: function(arg0) {
             const ret = arg0.now();
             return ret;
@@ -975,22 +1262,22 @@ function __wbg_get_imports() {
             console.warn(arg0);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 205, function: Function { arguments: [NamedExternref("Event")], shim_idx: 206, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 289, function: Function { arguments: [NamedExternref("Event")], shim_idx: 290, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen_efede8c867e8014b___closure__destroy___dyn_core_5858575f5ab61d4b___ops__function__FnMut__web_sys_108d82c43c7519e2___features__gen_IdbVersionChangeEvent__IdbVersionChangeEvent____Output_______, wasm_bindgen_efede8c867e8014b___convert__closures_____invoke___web_sys_108d82c43c7519e2___features__gen_IdbVersionChangeEvent__IdbVersionChangeEvent______true_);
             return ret;
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 205, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 206, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 289, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 290, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen_efede8c867e8014b___closure__destroy___dyn_core_5858575f5ab61d4b___ops__function__FnMut__web_sys_108d82c43c7519e2___features__gen_IdbVersionChangeEvent__IdbVersionChangeEvent____Output_______, wasm_bindgen_efede8c867e8014b___convert__closures_____invoke___web_sys_108d82c43c7519e2___features__gen_IdbVersionChangeEvent__IdbVersionChangeEvent______true__1);
             return ret;
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 602, function: Function { arguments: [], shim_idx: 603, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 762, function: Function { arguments: [], shim_idx: 763, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen_efede8c867e8014b___closure__destroy___dyn_core_5858575f5ab61d4b___ops__function__FnMut_____Output_______, wasm_bindgen_efede8c867e8014b___convert__closures_____invoke_______true_);
             return ret;
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 632, function: Function { arguments: [Externref], shim_idx: 633, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 792, function: Function { arguments: [Externref], shim_idx: 793, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen_efede8c867e8014b___closure__destroy___dyn_core_5858575f5ab61d4b___ops__function__FnMut__wasm_bindgen_efede8c867e8014b___JsValue____Output___core_5858575f5ab61d4b___result__Result_____wasm_bindgen_efede8c867e8014b___JsError___, wasm_bindgen_efede8c867e8014b___convert__closures_____invoke___wasm_bindgen_efede8c867e8014b___JsValue__core_5858575f5ab61d4b___result__Result_____wasm_bindgen_efede8c867e8014b___JsError___true_);
             return ret;
         },
@@ -1070,6 +1357,9 @@ const IndexRegistryFinalization = (typeof FinalizationRegistry === 'undefined')
 const IpfsIndexFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_ipfsindex_free(ptr >>> 0, 1));
+const LocalIndexFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_localindex_free(ptr >>> 0, 1));
 const RemoteIndexFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_remoteindex_free(ptr >>> 0, 1));

package/package.json

@@ -5,7 +5,7 @@
     "izihawa"
   ],
   "description": "WASM bindings for Hermes search engine",
-  "version": "1.8.28",
+  "version": "1.8.29",
   "license": "MIT",
   "repository": {
     "type": "git",