@statewalker/indexer-mem-minisearch 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+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,53 @@
+# @statewalker/indexer-mem-minisearch
+
+In-memory implementation of `@statewalker/indexer-api` combining [MiniSearch](https://github.com/lucaong/minisearch) for full-text search with `@statewalker/indexer-mem`'s `MemVectorIndex` for embeddings. Optional streaming persistence via `IndexerPersistence`.
+
+## Installation
+
+```sh
+pnpm add @statewalker/indexer-mem-minisearch
+```
+
+## Usage
+
+```ts
+import { createMiniSearchIndexer } from "@statewalker/indexer-mem-minisearch";
+
+const indexer = createMiniSearchIndexer();
+const index = await indexer.createIndex({
+  name: "docs",
+  fulltext: { language: "en" },
+  vector: { dimensionality: 384, model: "all-MiniLM-L6-v2" },
+});
+
+await index.addDocument([
+  { path: "/docs/a", blockId: "1", content: "hello world" },
+]);
+
+for await (const hit of index.search({ queries: ["hello"], topK: 10 })) {
+  console.log(hit.path, hit.blockId, hit.score);
+}
+```
+
+### With persistence
+
+```ts
+import { createMiniSearchIndexer } from "@statewalker/indexer-mem-minisearch";
+import type { IndexerPersistence } from "@statewalker/indexer-api";
+
+const persistence: IndexerPersistence = /* … your save/load adapter … */;
+const indexer = createMiniSearchIndexer({ persistence });
+```
+
+Wire format (stable across releases): `__manifest__` (JSON array of index names), `${name}/__config__`, `${name}/fts` (MiniSearch `toJSON()`), `${name}/vec` (Arrow IPC from `MemVectorIndex`).
+
+## API
+
+- `createMiniSearchIndexer(options?)` — returns an `Indexer`. Options: `persistence?: IndexerPersistence`.
+- `MiniSearchIndexerOptions` — option type.
+
+## Related
+
+- `@statewalker/indexer-api` — the pluggable contract.
+- `@statewalker/indexer-mem-flexsearch` — drop-in alternative using FlexSearch.
+- `@statewalker/indexer-mem` — provides the vector sub-index (`MemVectorIndex`).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { MiniSearchFullTextIndex } from "./minisearch-full-text-index.js";
+import { MiniSearchIndexerOptions, createMiniSearchIndexer } from "./minisearch-indexer.js";
+import { miniSearchFullTextProvider } from "./minisearch-provider.js";
+export { MiniSearchFullTextIndex, type MiniSearchIndexerOptions, createMiniSearchIndexer, miniSearchFullTextProvider };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { MiniSearchFullTextIndex } from "./minisearch-full-text-index.js";
+import { miniSearchFullTextProvider } from "./minisearch-provider.js";
+import { createMiniSearchIndexer } from "./minisearch-indexer.js";
+export { MiniSearchFullTextIndex, createMiniSearchIndexer, miniSearchFullTextProvider };

package/dist/minisearch-full-text-index.d.ts

@@ -0,0 +1,41 @@
+import { FullTextBlock, FullTextIndex, FullTextIndexInfo, FulltextQuery, FulltextResult } from "@statewalker/indexer-fulltext";
+import { BlockReference, DocumentPath, PathSelector, PersistableSearchIndex, PersistenceEntry } from "@statewalker/indexer-api";
+//#region src/minisearch-full-text-index.d.ts
+export declare class MiniSearchFullTextIndex implements FullTextIndex, PersistableSearchIndex<FullTextBlock, FulltextQuery, FulltextResult> {
+  private readonly info;
+  private miniSearch;
+  private blocks;
+  private keySet;
+  private closed;
+  constructor(info: FullTextIndexInfo);
+  private ensureOpen;
+  private searchInternal;
+  getIndexInfo(): Promise<FullTextIndexInfo>;
+  search(params: FulltextQuery): AsyncGenerator<FulltextResult>;
+  addDocument(blocks: FullTextBlock[]): Promise<void>;
+  addDocuments(blocks: Iterable<FullTextBlock[]> | AsyncIterable<FullTextBlock[]>): Promise<void>;
+  deleteDocuments(pathSelectors: PathSelector[] | AsyncIterable<PathSelector>): Promise<void>;
+  private removeByKey;
+  getSize(pathPrefix?: DocumentPath): Promise<number>;
+  getDocumentPaths(pathPrefix?: DocumentPath): AsyncGenerator<DocumentPath>;
+  getDocumentBlocksRefs(pathPrefix?: DocumentPath): AsyncGenerator<BlockReference>;
+  getDocumentsBlocks(pathPrefix?: DocumentPath): AsyncGenerator<FullTextBlock>;
+  close(_options?: {
+    force?: boolean;
+  }): Promise<void>;
+  flush(): Promise<void>;
+  deleteIndex(): Promise<void>;
+  /**
+   * Stream the FTS sub-index's state as a single named entry. The composite
+   * prefixes this with `${indexName}/${subName}/` before it hits persistence.
+   */
+  serialise(): AsyncIterable<PersistenceEntry>;
+  /** Restore the FTS sub-index from a previously-produced entry set. */
+  loadFrom(entries: Iterable<PersistenceEntry>): Promise<void>;
+  /** Serialize to JSON (v3 format with path data) */
+  serialize(): string;
+  /** Deserialize from JSON — handles v3 format */
+  static deserialize(info: FullTextIndexInfo, json: string): MiniSearchFullTextIndex;
+}
+//#endregion
+//# sourceMappingURL=minisearch-full-text-index.d.ts.map

package/dist/minisearch-full-text-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-full-text-index.d.ts","names":["FullTextSearchParams","FullTextSearchResult"],"sources":["../src/minisearch-full-text-index.ts"],"mappings":";;;qBAgCa,mCAET,eACA,uBAAuB,eAAeA,eAAsBC;mBAE7C;UACT;UACA;UACA;UACA;EAER,YAAY,MAAM;UAQV;UAMA;EAiDF,gBAAgB,QAAQ;EAKvB,OAAO,QAAQD,gBAAuB,eAAeC;EAqCtD,YAAY,QAAQ,kBAAkB;EAkBtC,aACJ,QAAQ,SAAS,mBAAmB,cAAc,mBACjD;EAOG,gBACJ,eAAe,iBAAiB,cAAc,gBAC7C;UAoBK;EAQF,QAAQ,aAAa,eAAe;EAUnC,iBAAiB,aAAa,eAAe,eAAe;EAW5D,sBAAsB,aAAa,eAAe,eAAe;EASjE,mBAAmB,aAAa,eAAe,eAAe;EAc/D,MAAM;IAAa;MAAoB;EAIvC,SAAS;EAIT,eAAe;;;;;EAad,aAAa,cAAc;;EAK5B,SAAS,SAAS,SAAS,oBAAoB;;EAerD;;SAyBO,YAAY,MAAM,mBAAmB,eAAe"}

package/dist/minisearch-full-text-index.js

@@ -0,0 +1,232 @@
+import { compositeKey, matchesPrefix, readEntryBytes, singleChunk, toAsyncIterable, toBytes } from "@statewalker/indexer-core";
+import MiniSearch from "minisearch";
+//#region src/minisearch-full-text-index.ts
+var MiniSearchFullTextIndex = class MiniSearchFullTextIndex {
+	info;
+	miniSearch;
+	blocks = /* @__PURE__ */ new Map();
+	keySet = /* @__PURE__ */ new Set();
+	closed = false;
+	constructor(info) {
+		this.info = info;
+		this.miniSearch = new MiniSearch({
+			fields: ["content"],
+			idField: "key"
+		});
+	}
+	ensureOpen() {
+		if (this.closed) throw new Error("FullTextIndex is closed");
+	}
+	searchInternal(query, topK, pathPrefixes) {
+		let results = this.miniSearch.search(query, {
+			prefix: true,
+			fuzzy: .2
+		});
+		if (results.length === 0) results = this.miniSearch.search(query, { prefix: true });
+		if (results.length === 0) {
+			if (query.split(/\s+/).filter((w) => w.length > 1).length > 1) results = this.miniSearch.search(query, {
+				prefix: true,
+				fuzzy: .2,
+				combineWith: "OR"
+			});
+		}
+		let filtered = results.map((r) => ({
+			key: r.id,
+			score: r.score
+		}));
+		if (pathPrefixes && pathPrefixes.length > 0) filtered = filtered.filter((r) => {
+			const block = this.blocks.get(r.key);
+			return block !== void 0 && pathPrefixes.some((p) => matchesPrefix(block.path, p));
+		});
+		return filtered.slice(0, topK).map((r) => {
+			const block = this.blocks.get(r.key);
+			return {
+				path: block?.path ?? "/",
+				blockId: block?.blockId ?? "",
+				snippet: block?.content ?? "",
+				score: r.score
+			};
+		});
+	}
+	async getIndexInfo() {
+		this.ensureOpen();
+		return { ...this.info };
+	}
+	async *search(params) {
+		this.ensureOpen();
+		const { queries, paths } = params;
+		const topK = params.topK ?? 100;
+		if (!queries || queries.length === 0) return;
+		const merged = /* @__PURE__ */ new Map();
+		for (const query of queries) {
+			const results = this.searchInternal(query, topK, paths);
+			for (const r of results) {
+				const key = compositeKey(r.path, r.blockId);
+				const existing = merged.get(key);
+				if (!existing) merged.set(key, {
+					result: r,
+					best: r.score,
+					total: r.score
+				});
+				else {
+					existing.total += r.score;
+					if (r.score > existing.best) {
+						existing.best = r.score;
+						existing.result = r;
+					}
+				}
+			}
+		}
+		const sorted = [...merged.values()].sort((a, b) => b.total - a.total);
+		for (const { result, total } of sorted.slice(0, topK)) yield {
+			...result,
+			score: total
+		};
+	}
+	async addDocument(blocks) {
+		this.ensureOpen();
+		for (const block of blocks) {
+			const key = compositeKey(block.path, block.blockId);
+			if (this.keySet.has(key)) this.miniSearch.discard(key);
+			this.miniSearch.add({
+				key,
+				content: block.content
+			});
+			this.keySet.add(key);
+			this.blocks.set(key, {
+				path: block.path,
+				blockId: block.blockId,
+				content: block.content,
+				metadata: block.metadata
+			});
+		}
+	}
+	async addDocuments(blocks) {
+		this.ensureOpen();
+		for await (const batch of blocks) await this.addDocument(batch);
+	}
+	async deleteDocuments(pathSelectors) {
+		this.ensureOpen();
+		for await (const sel of toAsyncIterable(pathSelectors)) if (sel.blockId !== void 0) {
+			const key = compositeKey(sel.path, sel.blockId);
+			this.removeByKey(key);
+		} else {
+			const keysToDelete = [];
+			for (const [key, block] of this.blocks) if (matchesPrefix(block.path, sel.path)) keysToDelete.push(key);
+			for (const key of keysToDelete) this.removeByKey(key);
+		}
+	}
+	removeByKey(key) {
+		if (this.keySet.has(key)) {
+			this.miniSearch.discard(key);
+			this.keySet.delete(key);
+		}
+		this.blocks.delete(key);
+	}
+	async getSize(pathPrefix) {
+		this.ensureOpen();
+		if (pathPrefix === void 0) return this.blocks.size;
+		let count = 0;
+		for (const block of this.blocks.values()) if (matchesPrefix(block.path, pathPrefix)) count++;
+		return count;
+	}
+	async *getDocumentPaths(pathPrefix) {
+		this.ensureOpen();
+		const paths = /* @__PURE__ */ new Set();
+		for (const block of this.blocks.values()) if (pathPrefix === void 0 || matchesPrefix(block.path, pathPrefix)) paths.add(block.path);
+		for (const p of paths) yield p;
+	}
+	async *getDocumentBlocksRefs(pathPrefix) {
+		this.ensureOpen();
+		for (const block of this.blocks.values()) if (pathPrefix === void 0 || matchesPrefix(block.path, pathPrefix)) yield {
+			path: block.path,
+			blockId: block.blockId
+		};
+	}
+	async *getDocumentsBlocks(pathPrefix) {
+		this.ensureOpen();
+		for (const block of this.blocks.values()) if (pathPrefix === void 0 || matchesPrefix(block.path, pathPrefix)) yield {
+			path: block.path,
+			blockId: block.blockId,
+			content: block.content,
+			metadata: block.metadata
+		};
+	}
+	async close(_options) {
+		this.closed = true;
+	}
+	async flush() {
+		this.ensureOpen();
+	}
+	async deleteIndex() {
+		this.ensureOpen();
+		this.blocks.clear();
+		this.keySet.clear();
+		this.closed = true;
+	}
+	/**
+	* Stream the FTS sub-index's state as a single named entry. The composite
+	* prefixes this with `${indexName}/${subName}/` before it hits persistence.
+	*/
+	async *serialise() {
+		yield {
+			name: "json",
+			content: singleChunk(toBytes(this.serialize()))
+		};
+	}
+	/** Restore the FTS sub-index from a previously-produced entry set. */
+	async loadFrom(entries) {
+		this.ensureOpen();
+		for (const e of entries) {
+			if (e.name !== "json") continue;
+			const bytes = await readEntryBytes(e);
+			const json = new TextDecoder().decode(bytes);
+			const rebuilt = MiniSearchFullTextIndex.deserialize(this.info, json);
+			this.miniSearch = rebuilt.miniSearch;
+			this.blocks = rebuilt.blocks;
+			this.keySet = rebuilt.keySet;
+			return;
+		}
+	}
+	/** Serialize to JSON (v3 format with path data) */
+	serialize() {
+		const blocksData = [];
+		for (const block of this.blocks.values()) blocksData.push({
+			path: block.path,
+			blockId: block.blockId,
+			content: block.content,
+			metadata: block.metadata
+		});
+		return JSON.stringify({
+			version: 3,
+			miniSearch: this.miniSearch.toJSON(),
+			blocks: blocksData,
+			keys: [...this.keySet]
+		});
+	}
+	/** Deserialize from JSON — handles v3 format */
+	static deserialize(info, json) {
+		const parsed = JSON.parse(json);
+		if (parsed.version !== 3) throw new Error(`MiniSearchFullTextIndex: unsupported serialised version ${String(parsed.version)} (expected 3)`);
+		const index = new MiniSearchFullTextIndex(info);
+		index.miniSearch = MiniSearch.loadJSON(JSON.stringify(parsed.miniSearch), {
+			fields: ["content"],
+			idField: "key"
+		});
+		index.keySet = new Set(parsed.keys);
+		for (const block of parsed.blocks) {
+			const key = compositeKey(block.path, block.blockId);
+			index.blocks.set(key, {
+				path: block.path,
+				blockId: block.blockId,
+				content: block.content,
+				metadata: block.metadata
+			});
+		}
+		return index;
+	}
+};
+//#endregion
+export { MiniSearchFullTextIndex };
+
+//# sourceMappingURL=minisearch-full-text-index.js.map

package/dist/minisearch-full-text-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-full-text-index.js","names":[],"sources":["../src/minisearch-full-text-index.ts"],"sourcesContent":["import type {\n  BlockReference,\n  DocumentPath,\n  Metadata,\n  PathSelector,\n  PersistableSearchIndex,\n  PersistenceEntry,\n} from \"@statewalker/indexer-api\";\nimport {\n  compositeKey,\n  matchesPrefix,\n  readEntryBytes,\n  singleChunk,\n  toAsyncIterable,\n  toBytes,\n} from \"@statewalker/indexer-core\";\nimport type {\n  FullTextBlock,\n  FullTextIndex,\n  FullTextIndexInfo,\n  FulltextQuery as FullTextSearchParams,\n  FulltextResult as FullTextSearchResult,\n} from \"@statewalker/indexer-fulltext\";\nimport MiniSearch from \"minisearch\";\n\ninterface StoredBlock {\n  path: DocumentPath;\n  blockId: string;\n  content: string;\n  metadata?: Metadata;\n}\n\nexport class MiniSearchFullTextIndex\n  implements\n    FullTextIndex,\n    PersistableSearchIndex<FullTextBlock, FullTextSearchParams, FullTextSearchResult>\n{\n  private readonly info: FullTextIndexInfo;\n  private miniSearch: MiniSearch;\n  private blocks = new Map<string, StoredBlock>();\n  private keySet = new Set<string>();\n  private closed = false;\n\n  constructor(info: FullTextIndexInfo) {\n    this.info = info;\n    this.miniSearch = new MiniSearch({\n      fields: [\"content\"],\n      idField: \"key\",\n    });\n  }\n\n  private ensureOpen(): void {\n    if (this.closed) {\n      throw new Error(\"FullTextIndex is closed\");\n    }\n  }\n\n  private searchInternal(\n    query: string,\n    topK: number,\n    pathPrefixes?: DocumentPath[],\n  ): FullTextSearchResult[] {\n    let results = this.miniSearch.search(query, {\n      prefix: true,\n      fuzzy: 0.2,\n    });\n\n    if (results.length === 0) {\n      results = this.miniSearch.search(query, { prefix: true });\n    }\n\n    if (results.length === 0) {\n      const words = query.split(/\\s+/).filter((w) => w.length > 1);\n      if (words.length > 1) {\n        results = this.miniSearch.search(query, {\n          prefix: true,\n          fuzzy: 0.2,\n          combineWith: \"OR\",\n        });\n      }\n    }\n\n    // Filter by path prefixes\n    let filtered = results.map((r) => ({\n      key: r.id as string,\n      score: r.score,\n    }));\n\n    if (pathPrefixes && pathPrefixes.length > 0) {\n      filtered = filtered.filter((r) => {\n        const block = this.blocks.get(r.key);\n        return block !== undefined && pathPrefixes.some((p) => matchesPrefix(block.path, p));\n      });\n    }\n\n    return filtered.slice(0, topK).map((r) => {\n      const block = this.blocks.get(r.key);\n      return {\n        path: block?.path ?? (\"/\" as DocumentPath),\n        blockId: block?.blockId ?? \"\",\n        snippet: block?.content ?? \"\",\n        score: r.score,\n      };\n    });\n  }\n\n  async getIndexInfo(): Promise<FullTextIndexInfo> {\n    this.ensureOpen();\n    return { ...this.info };\n  }\n\n  async *search(params: FullTextSearchParams): AsyncGenerator<FullTextSearchResult> {\n    this.ensureOpen();\n    const { queries, paths } = params;\n    const topK = params.topK ?? 100;\n\n    if (!queries || queries.length === 0) return;\n\n    // Multi-query: search for each and ACCUMULATE per-block scores, so a block\n    // matching more queries ranks higher (the FulltextQuery contract). Taking the\n    // max instead would let a block that is the top hit for one query outrank a\n    // block matching several queries. The snippet is kept from the strongest\n    // single-query match.\n    const merged = new Map<string, { result: FullTextSearchResult; best: number; total: number }>();\n\n    for (const query of queries) {\n      const results = this.searchInternal(query, topK, paths);\n      for (const r of results) {\n        const key = compositeKey(r.path, r.blockId);\n        const existing = merged.get(key);\n        if (!existing) {\n          merged.set(key, { result: r, best: r.score, total: r.score });\n        } else {\n          existing.total += r.score;\n          if (r.score > existing.best) {\n            existing.best = r.score;\n            existing.result = r;\n          }\n        }\n      }\n    }\n\n    const sorted = [...merged.values()].sort((a, b) => b.total - a.total);\n    for (const { result, total } of sorted.slice(0, topK)) {\n      yield { ...result, score: total };\n    }\n  }\n\n  async addDocument(blocks: FullTextBlock[]): Promise<void> {\n    this.ensureOpen();\n    for (const block of blocks) {\n      const key = compositeKey(block.path, block.blockId);\n      if (this.keySet.has(key)) {\n        this.miniSearch.discard(key);\n      }\n      this.miniSearch.add({ key, content: block.content });\n      this.keySet.add(key);\n      this.blocks.set(key, {\n        path: block.path,\n        blockId: block.blockId,\n        content: block.content,\n        metadata: block.metadata,\n      });\n    }\n  }\n\n  async addDocuments(\n    blocks: Iterable<FullTextBlock[]> | AsyncIterable<FullTextBlock[]>,\n  ): Promise<void> {\n    this.ensureOpen();\n    for await (const batch of blocks) {\n      await this.addDocument(batch);\n    }\n  }\n\n  async deleteDocuments(\n    pathSelectors: PathSelector[] | AsyncIterable<PathSelector>,\n  ): Promise<void> {\n    this.ensureOpen();\n    for await (const sel of toAsyncIterable(pathSelectors)) {\n      if (sel.blockId !== undefined) {\n        const key = compositeKey(sel.path, sel.blockId);\n        this.removeByKey(key);\n      } else {\n        const keysToDelete: string[] = [];\n        for (const [key, block] of this.blocks) {\n          if (matchesPrefix(block.path, sel.path)) {\n            keysToDelete.push(key);\n          }\n        }\n        for (const key of keysToDelete) {\n          this.removeByKey(key);\n        }\n      }\n    }\n  }\n\n  private removeByKey(key: string): void {\n    if (this.keySet.has(key)) {\n      this.miniSearch.discard(key);\n      this.keySet.delete(key);\n    }\n    this.blocks.delete(key);\n  }\n\n  async getSize(pathPrefix?: DocumentPath): Promise<number> {\n    this.ensureOpen();\n    if (pathPrefix === undefined) return this.blocks.size;\n    let count = 0;\n    for (const block of this.blocks.values()) {\n      if (matchesPrefix(block.path, pathPrefix)) count++;\n    }\n    return count;\n  }\n\n  async *getDocumentPaths(pathPrefix?: DocumentPath): AsyncGenerator<DocumentPath> {\n    this.ensureOpen();\n    const paths = new Set<DocumentPath>();\n    for (const block of this.blocks.values()) {\n      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {\n        paths.add(block.path);\n      }\n    }\n    for (const p of paths) yield p;\n  }\n\n  async *getDocumentBlocksRefs(pathPrefix?: DocumentPath): AsyncGenerator<BlockReference> {\n    this.ensureOpen();\n    for (const block of this.blocks.values()) {\n      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {\n        yield { path: block.path, blockId: block.blockId };\n      }\n    }\n  }\n\n  async *getDocumentsBlocks(pathPrefix?: DocumentPath): AsyncGenerator<FullTextBlock> {\n    this.ensureOpen();\n    for (const block of this.blocks.values()) {\n      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {\n        yield {\n          path: block.path,\n          blockId: block.blockId,\n          content: block.content,\n          metadata: block.metadata,\n        };\n      }\n    }\n  }\n\n  async close(_options?: { force?: boolean }): Promise<void> {\n    this.closed = true;\n  }\n\n  async flush(): Promise<void> {\n    this.ensureOpen();\n  }\n\n  async deleteIndex(): Promise<void> {\n    this.ensureOpen();\n    this.blocks.clear();\n    this.keySet.clear();\n    this.closed = true;\n  }\n\n  // --- PersistableSearchIndex --------------------------------------------------\n\n  /**\n   * Stream the FTS sub-index's state as a single named entry. The composite\n   * prefixes this with `${indexName}/${subName}/` before it hits persistence.\n   */\n  async *serialise(): AsyncIterable<PersistenceEntry> {\n    yield { name: \"json\", content: singleChunk(toBytes(this.serialize())) };\n  }\n\n  /** Restore the FTS sub-index from a previously-produced entry set. */\n  async loadFrom(entries: Iterable<PersistenceEntry>): Promise<void> {\n    this.ensureOpen();\n    for (const e of entries) {\n      if (e.name !== \"json\") continue;\n      const bytes = await readEntryBytes(e);\n      const json = new TextDecoder().decode(bytes);\n      const rebuilt = MiniSearchFullTextIndex.deserialize(this.info, json);\n      this.miniSearch = rebuilt.miniSearch;\n      this.blocks = rebuilt.blocks;\n      this.keySet = rebuilt.keySet;\n      return;\n    }\n  }\n\n  /** Serialize to JSON (v3 format with path data) */\n  serialize(): string {\n    const blocksData: Array<{\n      path: string;\n      blockId: string;\n      content: string;\n      metadata?: Metadata;\n    }> = [];\n    for (const block of this.blocks.values()) {\n      blocksData.push({\n        path: block.path,\n        blockId: block.blockId,\n        content: block.content,\n        metadata: block.metadata,\n      });\n    }\n\n    return JSON.stringify({\n      version: 3,\n      miniSearch: this.miniSearch.toJSON(),\n      blocks: blocksData,\n      keys: [...this.keySet],\n    });\n  }\n\n  /** Deserialize from JSON — handles v3 format */\n  static deserialize(info: FullTextIndexInfo, json: string): MiniSearchFullTextIndex {\n    const parsed = JSON.parse(json) as {\n      version?: number;\n      miniSearch: unknown;\n      blocks: Array<{\n        path: string;\n        blockId: string;\n        content: string;\n        metadata?: Metadata;\n      }>;\n      keys: string[];\n    };\n\n    if (parsed.version !== 3) {\n      throw new Error(\n        `MiniSearchFullTextIndex: unsupported serialised version ${String(parsed.version)} (expected 3)`,\n      );\n    }\n\n    const index = new MiniSearchFullTextIndex(info);\n    index.miniSearch = MiniSearch.loadJSON(JSON.stringify(parsed.miniSearch), {\n      fields: [\"content\"],\n      idField: \"key\",\n    });\n    index.keySet = new Set(parsed.keys);\n    for (const block of parsed.blocks) {\n      const key = compositeKey(block.path as DocumentPath, block.blockId);\n      index.blocks.set(key, {\n        path: block.path as DocumentPath,\n        blockId: block.blockId,\n        content: block.content,\n        metadata: block.metadata,\n      });\n    }\n\n    return index;\n  }\n}\n"],"mappings":";;;AAgCA,IAAa,0BAAb,MAAa,wBAIb;CACE;CACA;CACA,yBAAiB,IAAI,IAAyB;CAC9C,yBAAiB,IAAI,IAAY;CACjC,SAAiB;CAEjB,YAAY,MAAyB;EACnC,KAAK,OAAO;EACZ,KAAK,aAAa,IAAI,WAAW;GAC/B,QAAQ,CAAC,SAAS;GAClB,SAAS;EACX,CAAC;CACH;CAEA,aAA2B;EACzB,IAAI,KAAK,QACP,MAAM,IAAI,MAAM,yBAAyB;CAE7C;CAEA,eACE,OACA,MACA,cACwB;EACxB,IAAI,UAAU,KAAK,WAAW,OAAO,OAAO;GAC1C,QAAQ;GACR,OAAO;EACT,CAAC;EAED,IAAI,QAAQ,WAAW,GACrB,UAAU,KAAK,WAAW,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;EAG1D,IAAI,QAAQ,WAAW,GACP;OAAA,MAAM,MAAM,KAAK,CAAC,CAAC,QAAQ,MAAM,EAAE,SAAS,CAClD,CAAC,CAAC,SAAS,GACjB,UAAU,KAAK,WAAW,OAAO,OAAO;IACtC,QAAQ;IACR,OAAO;IACP,aAAa;GACf,CAAC;EAAA;EAKL,IAAI,WAAW,QAAQ,KAAK,OAAO;GACjC,KAAK,EAAE;GACP,OAAO,EAAE;EACX,EAAE;EAEF,IAAI,gBAAgB,aAAa,SAAS,GACxC,WAAW,SAAS,QAAQ,MAAM;GAChC,MAAM,QAAQ,KAAK,OAAO,IAAI,EAAE,GAAG;GACnC,OAAO,UAAU,KAAA,KAAa,aAAa,MAAM,MAAM,cAAc,MAAM,MAAM,CAAC,CAAC;EACrF,CAAC;EAGH,OAAO,SAAS,MAAM,GAAG,IAAI,CAAC,CAAC,KAAK,MAAM;GACxC,MAAM,QAAQ,KAAK,OAAO,IAAI,EAAE,GAAG;GACnC,OAAO;IACL,MAAM,OAAO,QAAS;IACtB,SAAS,OAAO,WAAW;IAC3B,SAAS,OAAO,WAAW;IAC3B,OAAO,EAAE;GACX;EACF,CAAC;CACH;CAEA,MAAM,eAA2C;EAC/C,KAAK,WAAW;EAChB,OAAO,EAAE,GAAG,KAAK,KAAK;CACxB;CAEA,OAAO,OAAO,QAAoE;EAChF,KAAK,WAAW;EAChB,MAAM,EAAE,SAAS,UAAU;EAC3B,MAAM,OAAO,OAAO,QAAQ;EAE5B,IAAI,CAAC,WAAW,QAAQ,WAAW,GAAG;EAOtC,MAAM,yBAAS,IAAI,IAA2E;EAE9F,KAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,UAAU,KAAK,eAAe,OAAO,MAAM,KAAK;GACtD,KAAK,MAAM,KAAK,SAAS;IACvB,MAAM,MAAM,aAAa,EAAE,MAAM,EAAE,OAAO;IAC1C,MAAM,WAAW,OAAO,IAAI,GAAG;IAC/B,IAAI,CAAC,UACH,OAAO,IAAI,KAAK;KAAE,QAAQ;KAAG,MAAM,EAAE;KAAO,OAAO,EAAE;IAAM,CAAC;SACvD;KACL,SAAS,SAAS,EAAE;KACpB,IAAI,EAAE,QAAQ,SAAS,MAAM;MAC3B,SAAS,OAAO,EAAE;MAClB,SAAS,SAAS;KACpB;IACF;GACF;EACF;EAEA,MAAM,SAAS,CAAC,GAAG,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;EACpE,KAAK,MAAM,EAAE,QAAQ,WAAW,OAAO,MAAM,GAAG,IAAI,GAClD,MAAM;GAAE,GAAG;GAAQ,OAAO;EAAM;CAEpC;CAEA,MAAM,YAAY,QAAwC;EACxD,KAAK,WAAW;EAChB,KAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,MAAM,aAAa,MAAM,MAAM,MAAM,OAAO;GAClD,IAAI,KAAK,OAAO,IAAI,GAAG,GACrB,KAAK,WAAW,QAAQ,GAAG;GAE7B,KAAK,WAAW,IAAI;IAAE;IAAK,SAAS,MAAM;GAAQ,CAAC;GACnD,KAAK,OAAO,IAAI,GAAG;GACnB,KAAK,OAAO,IAAI,KAAK;IACnB,MAAM,MAAM;IACZ,SAAS,MAAM;IACf,SAAS,MAAM;IACf,UAAU,MAAM;GAClB,CAAC;EACH;CACF;CAEA,MAAM,aACJ,QACe;EACf,KAAK,WAAW;EAChB,WAAW,MAAM,SAAS,QACxB,MAAM,KAAK,YAAY,KAAK;CAEhC;CAEA,MAAM,gBACJ,eACe;EACf,KAAK,WAAW;EAChB,WAAW,MAAM,OAAO,gBAAgB,aAAa,GACnD,IAAI,IAAI,YAAY,KAAA,GAAW;GAC7B,MAAM,MAAM,aAAa,IAAI,MAAM,IAAI,OAAO;GAC9C,KAAK,YAAY,GAAG;EACtB,OAAO;GACL,MAAM,eAAyB,CAAC;GAChC,KAAK,MAAM,CAAC,KAAK,UAAU,KAAK,QAC9B,IAAI,cAAc,MAAM,MAAM,IAAI,IAAI,GACpC,aAAa,KAAK,GAAG;GAGzB,KAAK,MAAM,OAAO,cAChB,KAAK,YAAY,GAAG;EAExB;CAEJ;CAEA,YAAoB,KAAmB;EACrC,IAAI,KAAK,OAAO,IAAI,GAAG,GAAG;GACxB,KAAK,WAAW,QAAQ,GAAG;GAC3B,KAAK,OAAO,OAAO,GAAG;EACxB;EACA,KAAK,OAAO,OAAO,GAAG;CACxB;CAEA,MAAM,QAAQ,YAA4C;EACxD,KAAK,WAAW;EAChB,IAAI,eAAe,KAAA,GAAW,OAAO,KAAK,OAAO;EACjD,IAAI,QAAQ;EACZ,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,cAAc,MAAM,MAAM,UAAU,GAAG;EAE7C,OAAO;CACT;CAEA,OAAO,iBAAiB,YAAyD;EAC/E,KAAK,WAAW;EAChB,MAAM,wBAAQ,IAAI,IAAkB;EACpC,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,eAAe,KAAA,KAAa,cAAc,MAAM,MAAM,UAAU,GAClE,MAAM,IAAI,MAAM,IAAI;EAGxB,KAAK,MAAM,KAAK,OAAO,MAAM;CAC/B;CAEA,OAAO,sBAAsB,YAA2D;EACtF,KAAK,WAAW;EAChB,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,eAAe,KAAA,KAAa,cAAc,MAAM,MAAM,UAAU,GAClE,MAAM;GAAE,MAAM,MAAM;GAAM,SAAS,MAAM;EAAQ;CAGvD;CAEA,OAAO,mBAAmB,YAA0D;EAClF,KAAK,WAAW;EAChB,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,IAAI,eAAe,KAAA,KAAa,cAAc,MAAM,MAAM,UAAU,GAClE,MAAM;GACJ,MAAM,MAAM;GACZ,SAAS,MAAM;GACf,SAAS,MAAM;GACf,UAAU,MAAM;EAClB;CAGN;CAEA,MAAM,MAAM,UAA+C;EACzD,KAAK,SAAS;CAChB;CAEA,MAAM,QAAuB;EAC3B,KAAK,WAAW;CAClB;CAEA,MAAM,cAA6B;EACjC,KAAK,WAAW;EAChB,KAAK,OAAO,MAAM;EAClB,KAAK,OAAO,MAAM;EAClB,KAAK,SAAS;CAChB;;;;;CAQA,OAAO,YAA6C;EAClD,MAAM;GAAE,MAAM;GAAQ,SAAS,YAAY,QAAQ,KAAK,UAAU,CAAC,CAAC;EAAE;CACxE;;CAGA,MAAM,SAAS,SAAoD;EACjE,KAAK,WAAW;EAChB,KAAK,MAAM,KAAK,SAAS;GACvB,IAAI,EAAE,SAAS,QAAQ;GACvB,MAAM,QAAQ,MAAM,eAAe,CAAC;GACpC,MAAM,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK;GAC3C,MAAM,UAAU,wBAAwB,YAAY,KAAK,MAAM,IAAI;GACnE,KAAK,aAAa,QAAQ;GAC1B,KAAK,SAAS,QAAQ;GACtB,KAAK,SAAS,QAAQ;GACtB;EACF;CACF;;CAGA,YAAoB;EAClB,MAAM,aAKD,CAAC;EACN,KAAK,MAAM,SAAS,KAAK,OAAO,OAAO,GACrC,WAAW,KAAK;GACd,MAAM,MAAM;GACZ,SAAS,MAAM;GACf,SAAS,MAAM;GACf,UAAU,MAAM;EAClB,CAAC;EAGH,OAAO,KAAK,UAAU;GACpB,SAAS;GACT,YAAY,KAAK,WAAW,OAAO;GACnC,QAAQ;GACR,MAAM,CAAC,GAAG,KAAK,MAAM;EACvB,CAAC;CACH;;CAGA,OAAO,YAAY,MAAyB,MAAuC;EACjF,MAAM,SAAS,KAAK,MAAM,IAAI;EAY9B,IAAI,OAAO,YAAY,GACrB,MAAM,IAAI,MACR,2DAA2D,OAAO,OAAO,OAAO,EAAE,cACpF;EAGF,MAAM,QAAQ,IAAI,wBAAwB,IAAI;EAC9C,MAAM,aAAa,WAAW,SAAS,KAAK,UAAU,OAAO,UAAU,GAAG;GACxE,QAAQ,CAAC,SAAS;GAClB,SAAS;EACX,CAAC;EACD,MAAM,SAAS,IAAI,IAAI,OAAO,IAAI;EAClC,KAAK,MAAM,SAAS,OAAO,QAAQ;GACjC,MAAM,MAAM,aAAa,MAAM,MAAsB,MAAM,OAAO;GAClE,MAAM,OAAO,IAAI,KAAK;IACpB,MAAM,MAAM;IACZ,SAAS,MAAM;IACf,SAAS,MAAM;IACf,UAAU,MAAM;GAClB,CAAC;EACH;EAEA,OAAO;CACT;AACF"}

package/dist/minisearch-indexer.d.ts

@@ -0,0 +1,13 @@
+import { Indexer, IndexerPersistence } from "@statewalker/indexer-api";
+//#region src/minisearch-indexer.d.ts
+export interface MiniSearchIndexerOptions {
+  persistence?: IndexerPersistence;
+}
+/**
+ * In-memory Indexer combining MiniSearch full-text and brute-force vector
+ * sub-indexes via the Provider model. Multiple sub-indexes of either modality
+ * can be created on one Index (e.g. English and French FTS sub-indexes).
+ */
+export declare function createMiniSearchIndexer(options?: MiniSearchIndexerOptions): Indexer;
+//#endregion
+//# sourceMappingURL=minisearch-indexer.d.ts.map

package/dist/minisearch-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-indexer.d.ts","names":[],"sources":["../src/minisearch-indexer.ts"],"mappings":";;iBAKiB;EACf,cAAc;;;;;;;wBAQA,wBAAwB,UAAU,2BAA2B"}

package/dist/minisearch-indexer.js

@@ -0,0 +1,19 @@
+import { miniSearchFullTextProvider } from "./minisearch-provider.js";
+import { createPersistenceBackedIndexer } from "@statewalker/indexer-core";
+import { memVectorProvider } from "@statewalker/indexer-mem";
+//#region src/minisearch-indexer.ts
+/**
+* In-memory Indexer combining MiniSearch full-text and brute-force vector
+* sub-indexes via the Provider model. Multiple sub-indexes of either modality
+* can be created on one Index (e.g. English and French FTS sub-indexes).
+*/
+function createMiniSearchIndexer(options) {
+	return createPersistenceBackedIndexer({
+		persistence: options?.persistence,
+		providers: [miniSearchFullTextProvider, memVectorProvider]
+	});
+}
+//#endregion
+export { createMiniSearchIndexer };
+
+//# sourceMappingURL=minisearch-indexer.js.map

package/dist/minisearch-indexer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-indexer.js","names":[],"sources":["../src/minisearch-indexer.ts"],"sourcesContent":["import type { Indexer, IndexerPersistence } from \"@statewalker/indexer-api\";\nimport { createPersistenceBackedIndexer } from \"@statewalker/indexer-core\";\nimport { memVectorProvider } from \"@statewalker/indexer-mem\";\nimport { miniSearchFullTextProvider } from \"./minisearch-provider.js\";\n\nexport interface MiniSearchIndexerOptions {\n  persistence?: IndexerPersistence;\n}\n\n/**\n * In-memory Indexer combining MiniSearch full-text and brute-force vector\n * sub-indexes via the Provider model. Multiple sub-indexes of either modality\n * can be created on one Index (e.g. English and French FTS sub-indexes).\n */\nexport function createMiniSearchIndexer(options?: MiniSearchIndexerOptions): Indexer {\n  return createPersistenceBackedIndexer({\n    persistence: options?.persistence,\n    providers: [miniSearchFullTextProvider, memVectorProvider],\n  });\n}\n"],"mappings":";;;;;;;;;AAcA,SAAgB,wBAAwB,SAA6C;CACnF,OAAO,+BAA+B;EACpC,aAAa,SAAS;EACtB,WAAW,CAAC,4BAA4B,iBAAiB;CAC3D,CAAC;AACH"}

package/dist/minisearch-provider.d.ts

@@ -0,0 +1,10 @@
+import { FullTextProvider } from "@statewalker/indexer-fulltext";
+//#region src/minisearch-provider.d.ts
+/**
+ * `FullTextProvider` backed by {@link MiniSearchFullTextIndex}. Wired into an
+ * `Indexer` alongside a `VectorProvider` to compose a full-text + vector
+ * Indexer.
+ */
+export declare const miniSearchFullTextProvider: FullTextProvider;
+//#endregion
+//# sourceMappingURL=minisearch-provider.d.ts.map

package/dist/minisearch-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-provider.d.ts","names":[],"sources":["../src/minisearch-provider.ts"],"mappings":";;;;;;;qBAYa,4BAA4B"}

package/dist/minisearch-provider.js

@@ -0,0 +1,21 @@
+import { MiniSearchFullTextIndex } from "./minisearch-full-text-index.js";
+import { FULL_TEXT_TYPE } from "@statewalker/indexer-fulltext";
+//#region src/minisearch-provider.ts
+/**
+* `FullTextProvider` backed by {@link MiniSearchFullTextIndex}. Wired into an
+* `Indexer` alongside a `VectorProvider` to compose a full-text + vector
+* Indexer.
+*/
+const miniSearchFullTextProvider = {
+	type: FULL_TEXT_TYPE,
+	create(config) {
+		return new MiniSearchFullTextIndex({
+			language: config.language,
+			metadata: config.metadata
+		});
+	}
+};
+//#endregion
+export { miniSearchFullTextProvider };
+
+//# sourceMappingURL=minisearch-provider.js.map

package/dist/minisearch-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minisearch-provider.js","names":[],"sources":["../src/minisearch-provider.ts"],"sourcesContent":["import {\n  FULL_TEXT_TYPE,\n  type FullTextConfig,\n  type FullTextProvider,\n} from \"@statewalker/indexer-fulltext\";\nimport { MiniSearchFullTextIndex } from \"./minisearch-full-text-index.js\";\n\n/**\n * `FullTextProvider` backed by {@link MiniSearchFullTextIndex}. Wired into an\n * `Indexer` alongside a `VectorProvider` to compose a full-text + vector\n * Indexer.\n */\nexport const miniSearchFullTextProvider: FullTextProvider = {\n  type: FULL_TEXT_TYPE,\n  create(config: FullTextConfig): MiniSearchFullTextIndex {\n    return new MiniSearchFullTextIndex({\n      language: config.language,\n      metadata: config.metadata,\n    });\n  },\n};\n"],"mappings":";;;;;;;;AAYA,MAAa,6BAA+C;CAC1D,MAAM;CACN,OAAO,QAAiD;EACtD,OAAO,IAAI,wBAAwB;GACjC,UAAU,OAAO;GACjB,UAAU,OAAO;EACnB,CAAC;CACH;AACF"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@statewalker/indexer-mem-minisearch",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "description": "In-memory indexer implementation backed by MiniSearch for full-text search.",
+  "homepage": "https://github.com/statewalker/statewalker-indexer",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/statewalker-indexer.git"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "minisearch": "^7.2.0",
+    "@statewalker/indexer-core": "^0.1.1",
+    "@statewalker/indexer-api": "^0.1.1",
+    "@statewalker/indexer-fulltext": "^0.1.1",
+    "@statewalker/indexer-mem": "^0.1.2"
+  },
+  "devDependencies": {
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "@statewalker/indexer-tests": "^0.0.0",
+    "@statewalker/indexer-vector": "^0.1.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "lint": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { MiniSearchFullTextIndex } from "./minisearch-full-text-index.js";
+export { createMiniSearchIndexer, type MiniSearchIndexerOptions } from "./minisearch-indexer.js";
+export { miniSearchFullTextProvider } from "./minisearch-provider.js";

package/src/minisearch-full-text-index.ts

@@ -0,0 +1,353 @@
+import type {
+  BlockReference,
+  DocumentPath,
+  Metadata,
+  PathSelector,
+  PersistableSearchIndex,
+  PersistenceEntry,
+} from "@statewalker/indexer-api";
+import {
+  compositeKey,
+  matchesPrefix,
+  readEntryBytes,
+  singleChunk,
+  toAsyncIterable,
+  toBytes,
+} from "@statewalker/indexer-core";
+import type {
+  FullTextBlock,
+  FullTextIndex,
+  FullTextIndexInfo,
+  FulltextQuery as FullTextSearchParams,
+  FulltextResult as FullTextSearchResult,
+} from "@statewalker/indexer-fulltext";
+import MiniSearch from "minisearch";
+
+interface StoredBlock {
+  path: DocumentPath;
+  blockId: string;
+  content: string;
+  metadata?: Metadata;
+}
+
+export class MiniSearchFullTextIndex
+  implements
+    FullTextIndex,
+    PersistableSearchIndex<FullTextBlock, FullTextSearchParams, FullTextSearchResult>
+{
+  private readonly info: FullTextIndexInfo;
+  private miniSearch: MiniSearch;
+  private blocks = new Map<string, StoredBlock>();
+  private keySet = new Set<string>();
+  private closed = false;
+
+  constructor(info: FullTextIndexInfo) {
+    this.info = info;
+    this.miniSearch = new MiniSearch({
+      fields: ["content"],
+      idField: "key",
+    });
+  }
+
+  private ensureOpen(): void {
+    if (this.closed) {
+      throw new Error("FullTextIndex is closed");
+    }
+  }
+
+  private searchInternal(
+    query: string,
+    topK: number,
+    pathPrefixes?: DocumentPath[],
+  ): FullTextSearchResult[] {
+    let results = this.miniSearch.search(query, {
+      prefix: true,
+      fuzzy: 0.2,
+    });
+
+    if (results.length === 0) {
+      results = this.miniSearch.search(query, { prefix: true });
+    }
+
+    if (results.length === 0) {
+      const words = query.split(/\s+/).filter((w) => w.length > 1);
+      if (words.length > 1) {
+        results = this.miniSearch.search(query, {
+          prefix: true,
+          fuzzy: 0.2,
+          combineWith: "OR",
+        });
+      }
+    }
+
+    // Filter by path prefixes
+    let filtered = results.map((r) => ({
+      key: r.id as string,
+      score: r.score,
+    }));
+
+    if (pathPrefixes && pathPrefixes.length > 0) {
+      filtered = filtered.filter((r) => {
+        const block = this.blocks.get(r.key);
+        return block !== undefined && pathPrefixes.some((p) => matchesPrefix(block.path, p));
+      });
+    }
+
+    return filtered.slice(0, topK).map((r) => {
+      const block = this.blocks.get(r.key);
+      return {
+        path: block?.path ?? ("/" as DocumentPath),
+        blockId: block?.blockId ?? "",
+        snippet: block?.content ?? "",
+        score: r.score,
+      };
+    });
+  }
+
+  async getIndexInfo(): Promise<FullTextIndexInfo> {
+    this.ensureOpen();
+    return { ...this.info };
+  }
+
+  async *search(params: FullTextSearchParams): AsyncGenerator<FullTextSearchResult> {
+    this.ensureOpen();
+    const { queries, paths } = params;
+    const topK = params.topK ?? 100;
+
+    if (!queries || queries.length === 0) return;
+
+    // Multi-query: search for each and ACCUMULATE per-block scores, so a block
+    // matching more queries ranks higher (the FulltextQuery contract). Taking the
+    // max instead would let a block that is the top hit for one query outrank a
+    // block matching several queries. The snippet is kept from the strongest
+    // single-query match.
+    const merged = new Map<string, { result: FullTextSearchResult; best: number; total: number }>();
+
+    for (const query of queries) {
+      const results = this.searchInternal(query, topK, paths);
+      for (const r of results) {
+        const key = compositeKey(r.path, r.blockId);
+        const existing = merged.get(key);
+        if (!existing) {
+          merged.set(key, { result: r, best: r.score, total: r.score });
+        } else {
+          existing.total += r.score;
+          if (r.score > existing.best) {
+            existing.best = r.score;
+            existing.result = r;
+          }
+        }
+      }
+    }
+
+    const sorted = [...merged.values()].sort((a, b) => b.total - a.total);
+    for (const { result, total } of sorted.slice(0, topK)) {
+      yield { ...result, score: total };
+    }
+  }
+
+  async addDocument(blocks: FullTextBlock[]): Promise<void> {
+    this.ensureOpen();
+    for (const block of blocks) {
+      const key = compositeKey(block.path, block.blockId);
+      if (this.keySet.has(key)) {
+        this.miniSearch.discard(key);
+      }
+      this.miniSearch.add({ key, content: block.content });
+      this.keySet.add(key);
+      this.blocks.set(key, {
+        path: block.path,
+        blockId: block.blockId,
+        content: block.content,
+        metadata: block.metadata,
+      });
+    }
+  }
+
+  async addDocuments(
+    blocks: Iterable<FullTextBlock[]> | AsyncIterable<FullTextBlock[]>,
+  ): Promise<void> {
+    this.ensureOpen();
+    for await (const batch of blocks) {
+      await this.addDocument(batch);
+    }
+  }
+
+  async deleteDocuments(
+    pathSelectors: PathSelector[] | AsyncIterable<PathSelector>,
+  ): Promise<void> {
+    this.ensureOpen();
+    for await (const sel of toAsyncIterable(pathSelectors)) {
+      if (sel.blockId !== undefined) {
+        const key = compositeKey(sel.path, sel.blockId);
+        this.removeByKey(key);
+      } else {
+        const keysToDelete: string[] = [];
+        for (const [key, block] of this.blocks) {
+          if (matchesPrefix(block.path, sel.path)) {
+            keysToDelete.push(key);
+          }
+        }
+        for (const key of keysToDelete) {
+          this.removeByKey(key);
+        }
+      }
+    }
+  }
+
+  private removeByKey(key: string): void {
+    if (this.keySet.has(key)) {
+      this.miniSearch.discard(key);
+      this.keySet.delete(key);
+    }
+    this.blocks.delete(key);
+  }
+
+  async getSize(pathPrefix?: DocumentPath): Promise<number> {
+    this.ensureOpen();
+    if (pathPrefix === undefined) return this.blocks.size;
+    let count = 0;
+    for (const block of this.blocks.values()) {
+      if (matchesPrefix(block.path, pathPrefix)) count++;
+    }
+    return count;
+  }
+
+  async *getDocumentPaths(pathPrefix?: DocumentPath): AsyncGenerator<DocumentPath> {
+    this.ensureOpen();
+    const paths = new Set<DocumentPath>();
+    for (const block of this.blocks.values()) {
+      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {
+        paths.add(block.path);
+      }
+    }
+    for (const p of paths) yield p;
+  }
+
+  async *getDocumentBlocksRefs(pathPrefix?: DocumentPath): AsyncGenerator<BlockReference> {
+    this.ensureOpen();
+    for (const block of this.blocks.values()) {
+      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {
+        yield { path: block.path, blockId: block.blockId };
+      }
+    }
+  }
+
+  async *getDocumentsBlocks(pathPrefix?: DocumentPath): AsyncGenerator<FullTextBlock> {
+    this.ensureOpen();
+    for (const block of this.blocks.values()) {
+      if (pathPrefix === undefined || matchesPrefix(block.path, pathPrefix)) {
+        yield {
+          path: block.path,
+          blockId: block.blockId,
+          content: block.content,
+          metadata: block.metadata,
+        };
+      }
+    }
+  }
+
+  async close(_options?: { force?: boolean }): Promise<void> {
+    this.closed = true;
+  }
+
+  async flush(): Promise<void> {
+    this.ensureOpen();
+  }
+
+  async deleteIndex(): Promise<void> {
+    this.ensureOpen();
+    this.blocks.clear();
+    this.keySet.clear();
+    this.closed = true;
+  }
+
+  // --- PersistableSearchIndex --------------------------------------------------
+
+  /**
+   * Stream the FTS sub-index's state as a single named entry. The composite
+   * prefixes this with `${indexName}/${subName}/` before it hits persistence.
+   */
+  async *serialise(): AsyncIterable<PersistenceEntry> {
+    yield { name: "json", content: singleChunk(toBytes(this.serialize())) };
+  }
+
+  /** Restore the FTS sub-index from a previously-produced entry set. */
+  async loadFrom(entries: Iterable<PersistenceEntry>): Promise<void> {
+    this.ensureOpen();
+    for (const e of entries) {
+      if (e.name !== "json") continue;
+      const bytes = await readEntryBytes(e);
+      const json = new TextDecoder().decode(bytes);
+      const rebuilt = MiniSearchFullTextIndex.deserialize(this.info, json);
+      this.miniSearch = rebuilt.miniSearch;
+      this.blocks = rebuilt.blocks;
+      this.keySet = rebuilt.keySet;
+      return;
+    }
+  }
+
+  /** Serialize to JSON (v3 format with path data) */
+  serialize(): string {
+    const blocksData: Array<{
+      path: string;
+      blockId: string;
+      content: string;
+      metadata?: Metadata;
+    }> = [];
+    for (const block of this.blocks.values()) {
+      blocksData.push({
+        path: block.path,
+        blockId: block.blockId,
+        content: block.content,
+        metadata: block.metadata,
+      });
+    }
+
+    return JSON.stringify({
+      version: 3,
+      miniSearch: this.miniSearch.toJSON(),
+      blocks: blocksData,
+      keys: [...this.keySet],
+    });
+  }
+
+  /** Deserialize from JSON — handles v3 format */
+  static deserialize(info: FullTextIndexInfo, json: string): MiniSearchFullTextIndex {
+    const parsed = JSON.parse(json) as {
+      version?: number;
+      miniSearch: unknown;
+      blocks: Array<{
+        path: string;
+        blockId: string;
+        content: string;
+        metadata?: Metadata;
+      }>;
+      keys: string[];
+    };
+
+    if (parsed.version !== 3) {
+      throw new Error(
+        `MiniSearchFullTextIndex: unsupported serialised version ${String(parsed.version)} (expected 3)`,
+      );
+    }
+
+    const index = new MiniSearchFullTextIndex(info);
+    index.miniSearch = MiniSearch.loadJSON(JSON.stringify(parsed.miniSearch), {
+      fields: ["content"],
+      idField: "key",
+    });
+    index.keySet = new Set(parsed.keys);
+    for (const block of parsed.blocks) {
+      const key = compositeKey(block.path as DocumentPath, block.blockId);
+      index.blocks.set(key, {
+        path: block.path as DocumentPath,
+        blockId: block.blockId,
+        content: block.content,
+        metadata: block.metadata,
+      });
+    }
+
+    return index;
+  }
+}

package/src/minisearch-indexer.ts

@@ -0,0 +1,20 @@
+import type { Indexer, IndexerPersistence } from "@statewalker/indexer-api";
+import { createPersistenceBackedIndexer } from "@statewalker/indexer-core";
+import { memVectorProvider } from "@statewalker/indexer-mem";
+import { miniSearchFullTextProvider } from "./minisearch-provider.js";
+
+export interface MiniSearchIndexerOptions {
+  persistence?: IndexerPersistence;
+}
+
+/**
+ * In-memory Indexer combining MiniSearch full-text and brute-force vector
+ * sub-indexes via the Provider model. Multiple sub-indexes of either modality
+ * can be created on one Index (e.g. English and French FTS sub-indexes).
+ */
+export function createMiniSearchIndexer(options?: MiniSearchIndexerOptions): Indexer {
+  return createPersistenceBackedIndexer({
+    persistence: options?.persistence,
+    providers: [miniSearchFullTextProvider, memVectorProvider],
+  });
+}

package/src/minisearch-provider.ts

@@ -0,0 +1,21 @@
+import {
+  FULL_TEXT_TYPE,
+  type FullTextConfig,
+  type FullTextProvider,
+} from "@statewalker/indexer-fulltext";
+import { MiniSearchFullTextIndex } from "./minisearch-full-text-index.js";
+
+/**
+ * `FullTextProvider` backed by {@link MiniSearchFullTextIndex}. Wired into an
+ * `Indexer` alongside a `VectorProvider` to compose a full-text + vector
+ * Indexer.
+ */
+export const miniSearchFullTextProvider: FullTextProvider = {
+  type: FULL_TEXT_TYPE,
+  create(config: FullTextConfig): MiniSearchFullTextIndex {
+    return new MiniSearchFullTextIndex({
+      language: config.language,
+      metadata: config.metadata,
+    });
+  },
+};

package/src/text-codec.d.ts

@@ -0,0 +1,3 @@
+// See ../../indexer-core/src/text-codec.d.ts for rationale.
+declare const TextEncoder: { new (): { encode(input: string): Uint8Array } };
+declare const TextDecoder: { new (label?: string): { decode(input?: Uint8Array): string } };