@nlptools/distance 0.0.3 → 0.0.4

package/README.md

@@ -11,6 +11,7 @@
 - Edit distance: Levenshtein, LCS (Myers O(ND) and DP)
 - Token similarity: Jaccard, Cosine, Sorensen-Dice (character multiset and n-gram variants)
 - Hash-based deduplication: SimHash, MinHash, LSH
+- Fuzzy search: `FuzzySearch` class and `findBestMatch` with multi-algorithm support
 - Diff: based on `@algorithm.ts/diff` (Myers and DP backends)
 - All distance algorithms include normalized similarity variants (0-1 range)
 
@@ -123,6 +124,45 @@ const query = lsh.query(mh.digest(), 0.5);
 // => [["doc1", 0.67]]
 ```
 
+### Fuzzy Search
+
+```typescript
+import { FuzzySearch, findBestMatch } from "@nlptools/distance";
+
+// String array search
+const search = new FuzzySearch(["apple", "banana", "cherry"]);
+search.search("aple");
+// => [{ item: "apple", score: 0.8, index: 0 }]
+
+// Object array with weighted keys
+const books = [
+  { title: "Old Man's War", author: "John Scalzi" },
+  { title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
+];
+const bookSearch = new FuzzySearch(books, {
+  keys: [
+    { name: "title", weight: 0.7 },
+    { name: "author", weight: 0.3 },
+  ],
+  algorithm: "cosine",
+  threshold: 0.3,
+});
+bookSearch.search("old man");
+// => [{ item: { title: "Old Man's War", ... }, score: 0.52, index: 0 }]
+
+// One-shot best match
+findBestMatch("kitten", ["sitting", "kit", "mitten"]);
+// => { item: "kit", score: 0.5, index: 1 }
+
+// With per-key details
+const detailed = new FuzzySearch(books, {
+  keys: [{ name: "title" }, { name: "author" }],
+  includeMatchDetails: true,
+});
+detailed.search("gatsby");
+// => [{ item: ..., score: 0.45, index: 1, matches: { title: 0.6, author: 0.1 } }]
+```
+
 ### Diff
 
 ```typescript
@@ -172,6 +212,27 @@ const result = diff("abc", "ac");
 | `MinHash.estimate(sig1, sig2)`   | Static: estimate Jaccard from signatures                           |
 | `LSH`                            | Class with `insert()`, `query()`, `remove()`                       |
 
+### Fuzzy Search
+
+| Function / Class                             | Description                                        |
+| -------------------------------------------- | -------------------------------------------------- |
+| `FuzzySearch<T>(collection, options?)`       | Search engine with dynamic collection management   |
+| `findBestMatch(query, collection, options?)` | One-shot convenience: returns best match or `null` |
+
+**FuzzySearch options:**
+
+| Option                | Type                               | Default         | Description                   |
+| --------------------- | ---------------------------------- | --------------- | ----------------------------- |
+| `algorithm`           | `BuiltinAlgorithm \| SimilarityFn` | `"levenshtein"` | Similarity algorithm to use   |
+| `keys`                | `ISearchKey[]`                     | `[]`            | Object fields to search on    |
+| `threshold`           | `number`                           | `0`             | Min similarity score (0-1)    |
+| `limit`               | `number`                           | `Infinity`      | Max results to return         |
+| `caseSensitive`       | `boolean`                          | `false`         | Case-insensitive by default   |
+| `includeMatchDetails` | `boolean`                          | `false`         | Include per-key scores        |
+| `lsh`                 | `{ numHashes?, numBands? }`        | —               | Enable LSH for large datasets |
+
+**Built-in algorithms:** `"levenshtein"`, `"lcs"`, `"jaccard"`, `"jaccardNgram"`, `"cosine"`, `"cosineNgram"`, `"sorensen"`, `"sorensenNgram"`
+
 ### Diff
 
 | Function               | Description                 | Returns          |
@@ -180,14 +241,19 @@ const result = diff("abc", "ac");
 
 ### Types
 
-| Type              | Description                              |
-| ----------------- | ---------------------------------------- |
-| `DiffType`        | Enum: `ADDED`, `REMOVED`, `COMMON`       |
-| `IDiffItem<T>`    | Diff result item with type and tokens    |
-| `IDiffOptions<T>` | Options for diff (equals, lcs algorithm) |
-| `ISimHashOptions` | Options for SimHash (bits, hashFn)       |
-| `IMinHashOptions` | Options for MinHash (numHashes, seed)    |
-| `ILSHOptions`     | Options for LSH (numBands, numHashes)    |
+| Type                    | Description                                  |
+| ----------------------- | -------------------------------------------- |
+| `DiffType`              | Enum: `ADDED`, `REMOVED`, `COMMON`           |
+| `IDiffItem<T>`          | Diff result item with type and tokens        |
+| `IDiffOptions<T>`       | Options for diff (equals, lcs algorithm)     |
+| `ISimHashOptions`       | Options for SimHash (bits, hashFn)           |
+| `IMinHashOptions`       | Options for MinHash (numHashes, seed)        |
+| `ILSHOptions`           | Options for LSH (numBands, numHashes)        |
+| `IFuzzySearchOptions`   | Options for FuzzySearch constructor          |
+| `IFindBestMatchOptions` | Options for findBestMatch function           |
+| `ISearchKey`            | Searchable key config (name, weight, getter) |
+| `ISearchResult<T>`      | Search result with item, score, index        |
+| `SimilarityFn`          | `(a: string, b: string) => number` in [0,1]  |
 
 ## Performance
 
@@ -232,6 +298,20 @@ Unit: microseconds per operation (us/op).
 
 TS implementations use V8 JIT optimization + `Int32Array` ASCII fast path + integer-encoded bigrams, avoiding JS-WASM boundary overhead entirely.
 
+### Fuzzy Search: NLPTools vs Fuse.js
+
+Benchmark: 20 items in collection, 6 queries per iteration, 1000 iterations.
+Unit: milliseconds per operation (ms/op). Algorithm: levenshtein (default).
+
+| Scenario                | NLPTools | Fuse.js |
+| ----------------------- | -------- | ------- |
+| Setup (constructor)     | 0.0002   | 0.0050  |
+| Search (string array)   | 0.0114   | 0.1077  |
+| Search (object, 1 key)  | 0.0176   | 0.3308  |
+| Search (object, 2 keys) | 0.0289   | 0.6445  |
+
+Both libraries return identical top-1 results for all test queries. NLPTools scores are normalized similarity (0-1, higher is better); Fuse.js uses Bitap error scores (0 = perfect, lower is better).
+
 ## Dependencies
 
 - `fastest-levenshtein` — fastest JS Levenshtein implementation

package/dist/index.d.mts

@@ -389,4 +389,292 @@ declare class LSH {
   get size(): number;
 }
 //#endregion
-export { DiffType, type IDiffItem, type IDiffOptions, ILSHOptions, type ILcs, type ILcsAlgorithm, IMinHashOptions, ISimHashOptions, LSH, LcsPairsFunc, LcsSizeFunc, MinHash, SimHasher, cosine, cosineNgram, diff, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };
+//#region src/search.d.ts
+/**
+ * A function that computes similarity between two strings, returning a value
+ * in [0, 1] where 1 means identical.
+ */
+type SimilarityFn = (a: string, b: string) => number;
+/**
+ * Built-in similarity algorithms. Each maps to a normalized similarity
+ * function from @nlptools/distance.
+ */
+type BuiltinAlgorithm = "levenshtein" | "lcs" | "jaccard" | "jaccardNgram" | "cosine" | "cosineNgram" | "sorensen" | "sorensenNgram";
+/**
+ * Configuration for a searchable key on an object item.
+ *
+ * @example
+ * ```ts
+ * const keys = [
+ *   { name: "title", weight: 0.7 },
+ *   { name: "author", weight: 0.3 },
+ * ];
+ * ```
+ */
+interface ISearchKey {
+  /** Property name to search on. */
+  name: string;
+  /**
+   * Weight of this key in the final score.
+   * Weights are normalized to sum to 1.0 internally.
+   * @default 1
+   */
+  weight?: number;
+  /**
+   * Optional custom getter function. If provided, used instead of
+   * reading `item[name]`. Must return a string.
+   */
+  getter?: (item: any) => string;
+}
+/**
+ * A single search result, containing the matched item, its score, and
+ * its position in the original collection.
+ *
+ * Results are sorted by score descending (best match first).
+ */
+interface ISearchResult<T> {
+  /** The matched item from the collection. */
+  item: T;
+  /**
+   * Similarity score in [0, 1], where 1 means identical.
+   * For multi-key search, this is the weighted sum of per-key scores.
+   */
+  score: number;
+  /** Index of the item in the original collection array. */
+  index: number;
+}
+/**
+ * Extended search result including per-key match details.
+ * Only produced when `includeMatchDetails` is true.
+ */
+interface ISearchResultWithDetails<T> extends ISearchResult<T> {
+  /**
+   * Per-key similarity scores.
+   * Keys are the key names from the ISearchKey configuration.
+   * Values are individual similarity scores in [0, 1].
+   */
+  matches: Record<string, number>;
+}
+/**
+ * Options for the {@link FuzzySearch} constructor.
+ *
+ * @example
+ * ```ts
+ * // String array
+ * const search = new FuzzySearch(["apple", "banana", "cherry"]);
+ *
+ * // Object array with weighted keys
+ * const search = new FuzzySearch(books, {
+ *   keys: [
+ *     { name: "title", weight: 0.7 },
+ *     { name: "author", weight: 0.3 },
+ *   ],
+ *   algorithm: "cosine",
+ *   threshold: 0.4,
+ * });
+ * ```
+ */
+interface IFuzzySearchOptions {
+  /**
+   * Similarity algorithm to use for comparing strings.
+   *
+   * - A string from {@link BuiltinAlgorithm} selects a built-in function.
+   * - A custom {@link SimilarityFn} can be provided for full control.
+   *
+   * @default "levenshtein"
+   */
+  algorithm?: BuiltinAlgorithm | SimilarityFn;
+  /**
+   * Keys to search on when the collection contains objects.
+   * Ignored for string arrays.
+   */
+  keys?: ISearchKey[];
+  /**
+   * Minimum similarity score (0-1) for a result to be included.
+   * Results scoring below this threshold are excluded.
+   * @default 0
+   */
+  threshold?: number;
+  /**
+   * Maximum number of results to return.
+   * @default Infinity
+   */
+  limit?: number;
+  /**
+   * Whether search should be case-insensitive.
+   * When true, both the query and the item strings are lowercased
+   * before comparison.
+   * @default false (case-insensitive by default)
+   */
+  caseSensitive?: boolean;
+  /**
+   * Include per-key match details in results.
+   * When true, results include a `matches` field with individual
+   * similarity scores per key.
+   * @default false
+   */
+  includeMatchDetails?: boolean;
+  /**
+   * Enable LSH-accelerated search for large collections (>1000 items).
+   * Uses MinHash + banding as a candidate filter, then re-scores with
+   * the exact algorithm. Provides sub-linear query time at the cost of
+   * approximate results (some true matches may be missed).
+   */
+  lsh?: {
+    /** Number of hash functions for MinHash signature size. @default 128 */numHashes?: number;
+    /**
+     * Number of bands for LSH banding.
+     * More bands = higher recall, lower precision.
+     * @default 16
+     */
+    numBands?: number;
+  };
+}
+/**
+ * Options for the {@link findBestMatch} function.
+ *
+ * @example
+ * ```ts
+ * const result = findBestMatch("kitten", ["sitting", "kit", "mitten"], {
+ *   algorithm: "levenshtein",
+ *   threshold: 0.3,
+ * });
+ * ```
+ */
+interface IFindBestMatchOptions {
+  /** Similarity algorithm. @default "levenshtein" */
+  algorithm?: BuiltinAlgorithm | SimilarityFn;
+  /** Keys for object-array search. */
+  keys?: ISearchKey[];
+  /** Minimum similarity score. @default 0 */
+  threshold?: number;
+  /** Whether search is case-insensitive. @default false (case-insensitive) */
+  caseSensitive?: boolean;
+}
+/**
+ * Fuzzy search engine for finding similar items in a collection.
+ *
+ * Supports both string arrays and object arrays with weighted multi-key search.
+ * Uses any similarity algorithm from @nlptools/distance, with optional LSH
+ * acceleration for large datasets.
+ *
+ * @example
+ * ```ts
+ * // String array search
+ * const search = new FuzzySearch(["apple", "banana", "cherry"]);
+ * const results = search.search("aple"); // [{ item: "apple", score: 0.75, index: 0 }]
+ *
+ * // Object array with weighted keys
+ * const books = [
+ *   { title: "Old Man's War", author: "John Scalzi" },
+ *   { title: "The Lock Artist", author: "Steve Hamilton" },
+ * ];
+ * const bookSearch = new FuzzySearch(books, {
+ *   keys: [
+ *     { name: "title", weight: 0.7 },
+ *     { name: "author", weight: 0.3 },
+ *   ],
+ *   algorithm: "cosine",
+ * });
+ * const results = bookSearch.search("old man"); // finds "Old Man's War"
+ * ```
+ */
+declare class FuzzySearch<T> {
+  private readonly similarityFn;
+  private readonly keys;
+  private readonly threshold;
+  private readonly limit;
+  private readonly caseSensitive;
+  private readonly includeMatchDetails;
+  private readonly isObjectArray;
+  private collection;
+  private readonly useLSH;
+  private readonly lshNumHashes;
+  private readonly lshNumBands;
+  private lshIndex;
+  private minHashSignatures;
+  constructor(collection: ReadonlyArray<T>, options?: IFuzzySearchOptions);
+  /**
+   * Search the collection for items similar to the query.
+   *
+   * @param query - The search query string
+   * @param limit - Optional per-query limit override
+   * @returns Array of results sorted by score descending
+   */
+  search(query: string, limit?: number): ISearchResult<T>[];
+  /**
+   * Add an item to the collection.
+   * If LSH is enabled, the index is updated incrementally.
+   */
+  add(item: T): void;
+  /**
+   * Remove an item from the collection by index.
+   * If LSH is enabled, the index is rebuilt (O(n)).
+   *
+   * @returns true if the item was found and removed
+   */
+  remove(index: number): boolean;
+  /**
+   * Replace the entire collection.
+   * If LSH is enabled, the index is rebuilt.
+   */
+  setCollection(collection: ReadonlyArray<T>): void;
+  /**
+   * Get the current collection.
+   */
+  getCollection(): ReadonlyArray<T>;
+  /**
+   * Get the number of items in the collection.
+   */
+  get size(): number;
+  /**
+   * Clear the collection and any LSH index.
+   */
+  clear(): void;
+  private searchLinear;
+  private searchWithLSH;
+  private buildLSHIndex;
+  private buildMinHashSignature;
+  private computeItemScore;
+  private computeDetailedScore;
+  private extractSearchText;
+  private extractKeyValue;
+  private normalizeString;
+}
+/**
+ * Find the single best match for a query against a collection.
+ *
+ * This is a convenience wrapper around {@link FuzzySearch} for one-shot queries.
+ * For repeated searches against the same collection, prefer creating a
+ * {@link FuzzySearch} instance directly.
+ *
+ * Time: O(n * k) where n = collection size, k = number of keys
+ *
+ * @param query - The search query string
+ * @param collection - Array of strings or objects to search
+ * @param options - Search configuration
+ * @returns The best matching result, or null if nothing meets the threshold
+ *
+ * @example
+ * ```ts
+ * // String array
+ * const result = findBestMatch("kitten", ["sitting", "kit", "mitten"]);
+ * console.log(result?.item); // "kit"
+ * console.log(result?.score); // 0.5
+ *
+ * // Object array with weighted keys
+ * const books = [
+ *   { title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
+ *   { title: "Great Expectations", author: "Charles Dickens" },
+ * ];
+ * const result = findBestMatch("grate gatsbi", books, {
+ *   keys: [
+ *     { name: "title", weight: 0.7 },
+ *     { name: "author", weight: 0.3 },
+ *   ],
+ * });
+ * ```
+ */
+declare function findBestMatch<T>(query: string, collection: ReadonlyArray<T>, options?: IFindBestMatchOptions): ISearchResult<T> | null;
+//#endregion
+export { BuiltinAlgorithm, DiffType, FuzzySearch, type IDiffItem, type IDiffOptions, IFindBestMatchOptions, IFuzzySearchOptions, ILSHOptions, type ILcs, type ILcsAlgorithm, IMinHashOptions, ISearchKey, ISearchResult, ISearchResultWithDetails, ISimHashOptions, LSH, LcsPairsFunc, LcsSizeFunc, MinHash, SimHasher, SimilarityFn, cosine, cosineNgram, diff, findBestMatch, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };

package/dist/index.mjs

@@ -800,4 +800,335 @@ function bandHash(slice) {
 	return hash.toString(36);
 }
 //#endregion
-export { DiffType, LSH, MinHash, SimHasher, cosine, cosineNgram, diff, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };
+//#region src/search.ts
+const BUILTIN_ALGORITHMS = {
+	levenshtein: levenshteinNormalized,
+	lcs: lcsNormalized,
+	jaccard,
+	jaccardNgram,
+	cosine,
+	cosineNgram,
+	sorensen,
+	sorensenNgram
+};
+function resolveKeys(rawKeys) {
+	if (rawKeys.length === 0) return [];
+	const totalWeight = rawKeys.reduce((sum, k) => sum + (k.weight ?? 1), 0);
+	return rawKeys.map((k) => ({
+		...k,
+		normalizedWeight: totalWeight > 0 ? (k.weight ?? 1) / totalWeight : 1 / rawKeys.length
+	}));
+}
+function resolveAlgorithm(algo) {
+	if (algo === void 0) return BUILTIN_ALGORITHMS.levenshtein;
+	if (typeof algo === "function") return algo;
+	return BUILTIN_ALGORITHMS[algo];
+}
+/**
+* Fuzzy search engine for finding similar items in a collection.
+*
+* Supports both string arrays and object arrays with weighted multi-key search.
+* Uses any similarity algorithm from @nlptools/distance, with optional LSH
+* acceleration for large datasets.
+*
+* @example
+* ```ts
+* // String array search
+* const search = new FuzzySearch(["apple", "banana", "cherry"]);
+* const results = search.search("aple"); // [{ item: "apple", score: 0.75, index: 0 }]
+*
+* // Object array with weighted keys
+* const books = [
+*   { title: "Old Man's War", author: "John Scalzi" },
+*   { title: "The Lock Artist", author: "Steve Hamilton" },
+* ];
+* const bookSearch = new FuzzySearch(books, {
+*   keys: [
+*     { name: "title", weight: 0.7 },
+*     { name: "author", weight: 0.3 },
+*   ],
+*   algorithm: "cosine",
+* });
+* const results = bookSearch.search("old man"); // finds "Old Man's War"
+* ```
+*/
+var FuzzySearch = class {
+	similarityFn;
+	keys;
+	threshold;
+	limit;
+	caseSensitive;
+	includeMatchDetails;
+	isObjectArray;
+	collection;
+	useLSH;
+	lshNumHashes;
+	lshNumBands;
+	lshIndex;
+	minHashSignatures;
+	constructor(collection, options = {}) {
+		this.similarityFn = resolveAlgorithm(options.algorithm);
+		this.keys = resolveKeys(options.keys ?? []);
+		this.isObjectArray = this.keys.length > 0;
+		this.threshold = options.threshold ?? 0;
+		this.limit = options.limit ?? Infinity;
+		this.caseSensitive = options.caseSensitive ?? false;
+		this.includeMatchDetails = options.includeMatchDetails ?? false;
+		this.collection = [...collection];
+		const lshOpts = options.lsh;
+		this.useLSH = lshOpts !== void 0;
+		this.lshNumHashes = lshOpts?.numHashes ?? 128;
+		this.lshNumBands = lshOpts?.numBands ?? 16;
+		this.lshIndex = null;
+		this.minHashSignatures = /* @__PURE__ */ new Map();
+		if (this.useLSH && this.collection.length > 0) this.buildLSHIndex();
+	}
+	/**
+	* Search the collection for items similar to the query.
+	*
+	* @param query - The search query string
+	* @param limit - Optional per-query limit override
+	* @returns Array of results sorted by score descending
+	*/
+	search(query, limit) {
+		const effectiveLimit = limit ?? this.limit;
+		if (effectiveLimit === 0 || this.collection.length === 0) return [];
+		const normalizedQuery = this.normalizeString(query);
+		if (this.useLSH && this.lshIndex !== null) return this.searchWithLSH(normalizedQuery, effectiveLimit);
+		return this.searchLinear(normalizedQuery, effectiveLimit);
+	}
+	/**
+	* Add an item to the collection.
+	* If LSH is enabled, the index is updated incrementally.
+	*/
+	add(item) {
+		const index = this.collection.length;
+		this.collection.push(item);
+		if (this.useLSH && this.lshIndex !== null) {
+			const text = this.extractSearchText(item);
+			const sig = this.buildMinHashSignature(text);
+			this.minHashSignatures.set(index, sig);
+			this.lshIndex.insert(String(index), sig);
+		}
+	}
+	/**
+	* Remove an item from the collection by index.
+	* If LSH is enabled, the index is rebuilt (O(n)).
+	*
+	* @returns true if the item was found and removed
+	*/
+	remove(index) {
+		if (index < 0 || index >= this.collection.length) return false;
+		this.collection.splice(index, 1);
+		if (this.useLSH) this.buildLSHIndex();
+		return true;
+	}
+	/**
+	* Replace the entire collection.
+	* If LSH is enabled, the index is rebuilt.
+	*/
+	setCollection(collection) {
+		this.collection = [...collection];
+		if (this.useLSH && this.collection.length > 0) this.buildLSHIndex();
+		else if (this.useLSH) {
+			this.lshIndex = null;
+			this.minHashSignatures.clear();
+		}
+	}
+	/**
+	* Get the current collection.
+	*/
+	getCollection() {
+		return this.collection;
+	}
+	/**
+	* Get the number of items in the collection.
+	*/
+	get size() {
+		return this.collection.length;
+	}
+	/**
+	* Clear the collection and any LSH index.
+	*/
+	clear() {
+		this.collection = [];
+		this.lshIndex = null;
+		this.minHashSignatures.clear();
+	}
+	searchLinear(normalizedQuery, limit) {
+		const candidates = [];
+		for (let i = 0; i < this.collection.length; i++) {
+			const item = this.collection[i];
+			if (this.isObjectArray) if (this.includeMatchDetails) {
+				const { score, matches } = this.computeDetailedScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i,
+					matches
+				});
+			} else {
+				const score = this.computeItemScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i
+				});
+			}
+			else {
+				const itemStr = this.normalizeString(item);
+				const score = this.similarityFn(normalizedQuery, itemStr);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i
+				});
+			}
+		}
+		candidates.sort((a, b) => b.score - a.score);
+		if (candidates.length <= limit) return candidates;
+		return candidates.slice(0, limit);
+	}
+	searchWithLSH(normalizedQuery, limit) {
+		const queryText = this.isObjectArray ? normalizedQuery : normalizedQuery;
+		const querySig = this.buildMinHashSignature(queryText);
+		const candidateIds = this.lshIndex.query(querySig, this.threshold);
+		const candidates = [];
+		for (const [id] of candidateIds) {
+			const idx = parseInt(id, 10);
+			if (idx < 0 || idx >= this.collection.length) continue;
+			const item = this.collection[idx];
+			if (this.isObjectArray) if (this.includeMatchDetails) {
+				const { score, matches } = this.computeDetailedScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx,
+					matches
+				});
+			} else {
+				const score = this.computeItemScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx
+				});
+			}
+			else {
+				const itemStr = this.normalizeString(item);
+				const score = this.similarityFn(normalizedQuery, itemStr);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx
+				});
+			}
+		}
+		candidates.sort((a, b) => b.score - a.score);
+		if (candidates.length <= limit) return candidates;
+		return candidates.slice(0, limit);
+	}
+	buildLSHIndex() {
+		this.lshIndex = new LSH({
+			numBands: this.lshNumBands,
+			numHashes: this.lshNumHashes
+		});
+		this.minHashSignatures.clear();
+		for (let i = 0; i < this.collection.length; i++) {
+			const text = this.extractSearchText(this.collection[i]);
+			const sig = this.buildMinHashSignature(text);
+			this.minHashSignatures.set(i, sig);
+			this.lshIndex.insert(String(i), sig);
+		}
+	}
+	buildMinHashSignature(text) {
+		const mh = new MinHash({ numHashes: this.lshNumHashes });
+		const grams = ngrams(text, 2);
+		for (const g of grams) mh.update(g);
+		return mh.digest();
+	}
+	computeItemScore(normalizedQuery, item) {
+		let score = 0;
+		for (const key of this.keys) {
+			const value = this.extractKeyValue(item, key);
+			const normalizedValue = this.normalizeString(value);
+			score += key.normalizedWeight * this.similarityFn(normalizedQuery, normalizedValue);
+		}
+		return score;
+	}
+	computeDetailedScore(normalizedQuery, item) {
+		let score = 0;
+		const matches = {};
+		for (const key of this.keys) {
+			const value = this.extractKeyValue(item, key);
+			const normalizedValue = this.normalizeString(value);
+			const s = this.similarityFn(normalizedQuery, normalizedValue);
+			matches[key.name] = s;
+			score += key.normalizedWeight * s;
+		}
+		return {
+			score,
+			matches
+		};
+	}
+	extractSearchText(item) {
+		if (this.isObjectArray) return this.keys.map((k) => this.extractKeyValue(item, k)).join(" ");
+		return this.normalizeString(item);
+	}
+	extractKeyValue(item, key) {
+		if (key.getter) {
+			const value = key.getter(item);
+			return typeof value === "string" ? value : "";
+		}
+		const value = item[key.name];
+		return typeof value === "string" ? value : "";
+	}
+	normalizeString(str) {
+		return this.caseSensitive ? str : str.toLowerCase();
+	}
+};
+/**
+* Find the single best match for a query against a collection.
+*
+* This is a convenience wrapper around {@link FuzzySearch} for one-shot queries.
+* For repeated searches against the same collection, prefer creating a
+* {@link FuzzySearch} instance directly.
+*
+* Time: O(n * k) where n = collection size, k = number of keys
+*
+* @param query - The search query string
+* @param collection - Array of strings or objects to search
+* @param options - Search configuration
+* @returns The best matching result, or null if nothing meets the threshold
+*
+* @example
+* ```ts
+* // String array
+* const result = findBestMatch("kitten", ["sitting", "kit", "mitten"]);
+* console.log(result?.item); // "kit"
+* console.log(result?.score); // 0.5
+*
+* // Object array with weighted keys
+* const books = [
+*   { title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
+*   { title: "Great Expectations", author: "Charles Dickens" },
+* ];
+* const result = findBestMatch("grate gatsbi", books, {
+*   keys: [
+*     { name: "title", weight: 0.7 },
+*     { name: "author", weight: 0.3 },
+*   ],
+* });
+* ```
+*/
+function findBestMatch(query, collection, options = {}) {
+	const results = new FuzzySearch(collection, {
+		algorithm: options.algorithm,
+		keys: options.keys,
+		threshold: options.threshold,
+		caseSensitive: options.caseSensitive
+	}).search(query, 1);
+	return results.length > 0 ? results[0] : null;
+}
+//#endregion
+export { DiffType, FuzzySearch, LSH, MinHash, SimHasher, cosine, cosineNgram, diff, findBestMatch, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlptools/distance",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Complete string distance and similarity algorithms package with WebAssembly and JavaScript implementations",
   "keywords": [
     "algorithms",