rapid-fuzzy 1.1.1 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 [![npm version](https://img.shields.io/npm/v/rapid-fuzzy)](https://www.npmjs.com/package/rapid-fuzzy)
 [![npm downloads](https://img.shields.io/npm/dm/rapid-fuzzy)](https://www.npmjs.com/package/rapid-fuzzy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/)
 
 Blazing-fast fuzzy search for JavaScript — powered by Rust, works everywhere.
 
@@ -28,7 +28,7 @@ Try rapid-fuzzy in the browser — no installation required: **[Open Playground]
 import { search } from 'rapid-fuzzy';
 
 const results = search('typscript', ['TypeScript', 'JavaScript', 'Python']);
-// → [{ item: 'TypeScript', score: 0.85, index: 0 }, ...]
+// → [{ item: 'TypeScript', score: 0.85, index: 0, positions: [] }, ...]
 ```
 
 For repeated searches, use `FuzzyIndex` for up to 297x faster lookups:
@@ -50,15 +50,9 @@ pnpm add rapid-fuzzy
 
 ### Runtime-specific notes
 
-- **Node.js** (>=20): Uses native bindings via napi-rs for best performance.
-- **Browser / Deno / Bun**: Falls back to a WASM build automatically. The WASM binary is ~660 KB raw (~230 KB gzipped).
-
-> **Browser WASM requirement**: The WASM build uses `SharedArrayBuffer` for threading, which requires the following HTTP headers on your page:
-> ```
-> Cross-Origin-Opener-Policy: same-origin
-> Cross-Origin-Embedder-Policy: require-corp
-> ```
-> Without these headers, you will see `SharedArrayBuffer is not defined`. See [MDN: SharedArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements) for details.
+- **Node.js** (>=22): Uses native bindings via napi-rs for best performance.
+- **Bun**: Uses native napi-rs bindings. WASM fallback also works — see [Bun section](#bun) below.
+- **Browser / CDN / Cloudflare Workers / Deno**: Falls back to the wasm-bindgen WASM build (~195 KB raw). No `SharedArrayBuffer` or COOP/COEP headers required.
 
 ### Framework Integration (SSR)
 
@@ -84,7 +78,103 @@ export default {
 };
 ```
 
-On the client side, rapid-fuzzy automatically falls back to WASM — no additional configuration needed beyond the SharedArrayBuffer headers above.
+On the client side, rapid-fuzzy automatically falls back to WASM — no additional configuration needed.
+
+### Browser and Edge Runtime Usage
+
+#### CDN (no bundler required)
+
+Import directly from [esm.sh](https://esm.sh) in any `<script type="module">`:
+
+```html
+<script type="module">
+  import { search, FuzzyIndex } from 'https://esm.sh/rapid-fuzzy';
+
+  const results = search('typscript', ['TypeScript', 'JavaScript', 'Python']);
+  console.log(results[0].item); // 'TypeScript'
+
+  const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python']);
+  console.log(index.search('typscript')[0].item); // 'TypeScript'
+  index.destroy();
+</script>
+```
+
+See [`examples/cdn-usage/`](examples/cdn-usage/) for a complete HTML example.
+
+#### Cloudflare Workers
+
+Install the package and import it in your Worker script. Wrangler bundles the WASM binary automatically:
+
+```bash
+npm install rapid-fuzzy
+```
+
+```js
+// worker.js
+import { search, FuzzyIndex } from 'rapid-fuzzy';
+
+// Create the index once at module scope (shared across requests)
+const index = new FuzzyIndex(['hello', 'world', 'foo', 'bar']);
+
+export default {
+  fetch(request) {
+    const { searchParams } = new URL(request.url);
+    const query = searchParams.get('q') ?? '';
+    const results = index.search(query);
+    return Response.json(results);
+  },
+};
+```
+
+```toml
+# wrangler.toml
+name = "rapid-fuzzy-worker"
+main = "worker.js"
+compatibility_date = "2025-01-01"
+```
+
+See [`examples/cloudflare-workers/`](examples/cloudflare-workers/) for a complete example.
+
+#### Deno
+
+Use rapid-fuzzy via the `npm:` specifier (Deno 1.28+):
+
+```ts
+import { search } from 'npm:rapid-fuzzy';
+
+const results = search('typscript', ['TypeScript', 'JavaScript', 'Python']);
+console.log(results[0].item); // 'TypeScript'
+```
+
+Or import from a CDN directly:
+
+```ts
+import { search } from 'https://esm.sh/rapid-fuzzy';
+```
+
+#### Bun
+
+Bun uses the native napi-rs bindings when available (fastest). You can also use the wasm-bindgen WASM files directly if needed:
+
+```typescript
+import * as wasm from 'rapid-fuzzy/rapid-fuzzy-wasm-bindgen_bg.js';
+import { readFileSync } from 'node:fs';
+
+const wasmPath = require.resolve('rapid-fuzzy/rapid-fuzzy-wasm-bindgen_bg.wasm');
+const wasmModule = new WebAssembly.Module(readFileSync(wasmPath));
+const wasmInstance = new WebAssembly.Instance(wasmModule, {
+  './rapid-fuzzy-wasm-bindgen_bg.js': wasm,
+});
+wasm.__wbg_set_wasm(wasmInstance.exports);
+
+// Now use the WASM API directly
+const results = wasm.search('typscript', ['TypeScript', 'JavaScript', 'Python']);
+const index = new wasm.FuzzyIndex(['apple', 'banana', 'cherry']);
+index.search('aple');
+index.destroy();
+```
+
+See [`e2e/wasm-bun.test.ts`](e2e/wasm-bun.test.ts) for a complete working example.
 
 ## API
 
@@ -127,12 +217,25 @@ closest('xyz', items, 0.5);
 ### String Distance
 
 ```typescript
-import { levenshtein, jaroWinkler, sorensenDice, hamming } from 'rapid-fuzzy';
+import {
+  levenshtein,
+  jaro,
+  jaroWinkler,
+  sorensenDice,
+  hamming,
+  normalizedHamming,
+  indel,
+  normalizedIndel,
+} from 'rapid-fuzzy';
 
 levenshtein('kitten', 'sitting');     // 3
-jaroWinkler('MARTHA', 'MARHTA');      // 0.961
+jaro('martha', 'marhta');             // 0.944 (similarity between 0–1)
+jaroWinkler('MARTHA', 'MARHTA');      // 0.961 (jaro + prefix bonus)
 sorensenDice('night', 'nacht');       // 0.25
 hamming('karolin', 'kathrin');        // 3 (null if lengths differ)
+normalizedHamming('karolin', 'kathrin'); // 0.571 (similarity 0–1, null if lengths differ)
+indel('abc', 'ac');                   // 1 (insertions + deletions only, no substitutions)
+normalizedIndel('kitten', 'sitting'); // 0.615 (similarity 0–1)
 ```
 
 ### Query Syntax
@@ -184,7 +287,9 @@ searchObjects('new york', items, { keys: ['address.city'] });
 
 ### Persistent Index
 
-For applications that search the same dataset repeatedly (autocomplete, file finders, etc.), use `FuzzyIndex` or `FuzzyObjectIndex` to keep data on the Rust side and eliminate per-search FFI overhead:
+For applications that search the same dataset repeatedly (autocomplete, file finders, etc.), use `FuzzyIndex` or `FuzzyObjectIndex` to keep data on the Rust side and eliminate per-search FFI overhead.
+
+**When to use which:** The standalone `search()` function requires zero setup and is ideal for one-off queries or small datasets. `FuzzyIndex` has an initial build cost but delivers sub-millisecond repeated queries, making it the better choice when querying the same dataset multiple times (autocomplete, live search, file finders).
 
 ```typescript
 import { FuzzyIndex, FuzzyObjectIndex } from 'rapid-fuzzy';
@@ -195,6 +300,9 @@ const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python', ...]);
 index.search('typscript', { maxResults: 5 });
 index.closest('tsc');
 
+// Tip: FuzzyIndex caches results internally — extending a previous query
+// (e.g. typing "app" → "apple") reuses cached candidates for faster lookups.
+
 // Index-only results (no string cloning — less GC pressure)
 const hits = index.searchIndices('typscript', { maxResults: 5 });
 // → [{ index: 0, score: 0.85, positions: [] }, ...]
@@ -233,15 +341,19 @@ This makes FuzzyIndex ideal for search-as-you-type UIs where each keystroke exte
 
 #### Index Serialization
 
-Save a FuzzyIndex to avoid rebuilding on startup:
+Save and restore a `FuzzyIndex` to avoid rebuilding on startup:
 
 ```typescript
-const buffer = index.serialize();
-fs.writeFileSync('search-index.bin', buffer);
+import { FuzzyIndex } from 'rapid-fuzzy';
 
-// Load later (faster than rebuilding from scratch)
-const restored = FuzzyIndex.deserialize(fs.readFileSync('search-index.bin'));
-restored.search('query');
+const index = new FuzzyIndex(['apple', 'banana', 'cherry']);
+
+// Serialize to Buffer
+const data = index.serialize();
+
+// Restore from serialized data
+const restored = FuzzyIndex.deserialize(data);
+restored.search('aple'); // works immediately
 ```
 
 > **Note:** The serialization format is version-specific. Regenerate the index after updating rapid-fuzzy.
@@ -301,7 +413,10 @@ All token-based functions include `Batch` and `Many` variants (e.g., `tokenSortR
 <details>
 <summary><strong>Batch Operations</strong></summary>
 
-All distance functions have `Batch` and `Many` variants that amortize FFI overhead:
+All distance functions have `Batch` and `Many` variants that amortize FFI overhead. `*Batch` functions compute metrics for multiple pairs at once, while `*Many` functions compare a single reference string against multiple candidates.
+
+- **`*Batch`** — compute distances for an array of string pairs (many-to-many)
+- **`*Many`** — compare one reference string against many candidates (one-to-many)
 
 ```typescript
 import { levenshteinBatch, levenshteinMany } from 'rapid-fuzzy';
@@ -327,13 +442,142 @@ jaroWinklerMany('MARTHA', candidates, 0.8);       // minSimilarity → returns 0
 
 </details>
 
+<details>
+<summary><strong>TypedArray Variants</strong></summary>
+
+All `*Many` functions have TypedArray counterparts that return `Uint32Array` or `Float64Array` instead of `Array<number>`. These avoid boxing overhead and GC pressure when processing large candidate sets.
+
+- **`*ManyU32`** — returns `Uint32Array` (for integer distances: `levenshteinManyU32`, `damerauLevenshteinManyU32`, `indelManyU32`)
+- **`*ManyF64`** — returns `Float64Array` (for similarity scores: `jaroManyF64`, `jaroWinklerManyF64`, `normalizedLevenshteinManyF64`, `normalizedIndelManyF64`, `sorensenDiceManyF64`, `tokenSortRatioManyF64`, `tokenSetRatioManyF64`, `partialRatioManyF64`, `weightedRatioManyF64`)
+
+```typescript
+import { levenshteinManyU32, jaroWinklerManyF64 } from 'rapid-fuzzy';
+
+const candidates = ['sitting', 'kittens', 'kitchen'];
+
+// Returns Uint32Array instead of Array<number>
+levenshteinManyU32('kitten', candidates);       // Uint32Array [3, 1, 2]
+
+// Returns Float64Array instead of Array<number>
+jaroWinklerManyF64('kitten', candidates);       // Float64Array [0.746, 0.976, 0.933]
+```
+
+> **When to use**: Prefer TypedArray variants when comparing against thousands of candidates. The returned typed arrays can also be passed directly to WebGL, WASM, or worker threads without copying.
+
+</details>
+
+## Framework Integration
+
+`FuzzyIndex` and `FuzzyObjectIndex` are designed for repeated search on the same data — build the index once, search many times. The examples below show the recommended pattern for each major framework.
+
+### React
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { FuzzyObjectIndex } from 'rapid-fuzzy/objects';
+
+const users = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' },
+];
+
+function UserSearch() {
+  const indexRef = useRef<FuzzyObjectIndex<typeof users[number]> | null>(null);
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState(users);
+
+  useEffect(() => {
+    indexRef.current = new FuzzyObjectIndex(users, {
+      keys: [{ name: 'name', weight: 2.0 }, 'email'],
+    });
+    return () => indexRef.current?.destroy();
+  }, []); // rebuild only when data changes — pass `users` as dependency if dynamic
+
+  useEffect(() => {
+    if (!indexRef.current) return;
+    if (!query) { setResults(users); return; }
+    setResults(indexRef.current.search(query).map((r) => r.item));
+  }, [query]);
+
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search…" />
+      <ul>{results.map((u) => <li key={u.email}>{u.name}</li>)}</ul>
+    </>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { ref, watch, onUnmounted } from 'vue';
+import { FuzzyObjectIndex } from 'rapid-fuzzy/objects';
+
+const users = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' },
+];
+
+const query = ref('');
+const results = ref(users);
+
+const index = new FuzzyObjectIndex(users, {
+  keys: [{ name: 'name', weight: 2.0 }, 'email'],
+});
+
+watch(query, (q) => {
+  results.value = q ? index.search(q).map((r) => r.item) : users;
+});
+
+onUnmounted(() => index.destroy());
+</script>
+
+<template>
+  <input v-model="query" placeholder="Search…" />
+  <ul><li v-for="u in results" :key="u.email">{{ u.name }}</li></ul>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+  import { FuzzyObjectIndex } from 'rapid-fuzzy/objects';
+
+  const users = [
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' },
+  ];
+
+  let query = '';
+
+  const index = new FuzzyObjectIndex(users, {
+    keys: [{ name: 'name', weight: 2.0 }, 'email'],
+  });
+
+  $: results = query ? index.search(query).map((r) => r.item) : users;
+
+  onDestroy(() => index.destroy());
+</script>
+
+<input bind:value={query} placeholder="Search…" />
+<ul>{#each results as u}<li>{u.name}</li>{/each}</ul>
+```
+
+> **Note**: Always call `index.destroy()` in your cleanup handler (`useEffect` return, `onUnmounted`, `onDestroy`) to free Rust-side memory.
+
 ## Choosing an Algorithm
 
 | Use case | Recommended | Why |
 |---|---|---|
 | Typo detection / spell check | `levenshtein`, `damerauLevenshtein` | Counts edits; Damerau adds transposition support |
-| Fixed-length comparison | `hamming` | Counts differing positions; only for equal-length strings |
+| Insertion/deletion only edits | `indel`, `normalizedIndel` | No substitutions — useful for diff-like or DNA alignment scenarios |
+| Fixed-length comparison | `hamming`, `normalizedHamming` | Counts differing positions; only for equal-length strings |
 | Name / address matching | `jaroWinkler`, `tokenSortRatio` | Prefix-weighted or order-independent matching |
+| Character-level similarity | `jaro` | Good baseline similarity without prefix weighting |
 | Document / text similarity | `sorensenDice` | Bigram-based; handles longer text well |
 | Normalized comparison (0–1) | `normalizedLevenshtein` | Length-independent similarity score |
 | Reordered words / messy data | `tokenSortRatio`, `tokenSetRatio` | Handles word order differences and extra tokens |
@@ -344,11 +588,27 @@ jaroWinklerMany('MARTHA', candidates, 0.8);       // minSimilarity → returns 0
 
 **Return types:**
 
-- `levenshtein`, `damerauLevenshtein`, `hamming` → integer (edit/difference count; `hamming` returns `null` if lengths differ)
-- `jaro`, `jaroWinkler`, `sorensenDice`, `normalizedLevenshtein` → float between 0.0 (no match) and 1.0 (identical)
+- `levenshtein`, `damerauLevenshtein`, `hamming`, `indel` → integer (edit/difference count; `hamming` returns `null` if lengths differ)
+- `jaro`, `jaroWinkler`, `sorensenDice`, `normalizedLevenshtein`, `normalizedIndel` → float between 0.0 (no match) and 1.0 (identical)
+- `normalizedHamming` → float between 0.0 and 1.0 (`null` if lengths differ)
 - `tokenSortRatio`, `tokenSetRatio`, `partialRatio`, `weightedRatio` → float between 0.0 and 1.0
 - `search` → array of `{ item, score, index, positions }` sorted by relevance (score: 0.0–1.0)
 
+### Memory Usage
+
+`FuzzyIndex` and `FuzzyObjectIndex` store items and precomputed data (UTF-32 representations, character masks, bigram index) on the Rust side. Always call `.destroy()` when the index is no longer needed to free this memory immediately rather than waiting for garbage collection.
+
+For read-heavy workloads, prefer `searchIndices()` over `search()` — it returns only indices and scores without cloning item strings back to JavaScript, reducing GC pressure.
+
+Serialized indexes use a compact binary format suitable for disk or IndexedDB storage. The serialized size is larger than raw text due to precomputed data, but deserialization is faster than rebuilding.
+
+### Error Handling
+
+- `hamming()` / `normalizedHamming()` return `null` when the input strings have different lengths.
+- `closest()` returns `null` if no match meets the `minScore` threshold (or if the item list is empty).
+- Calling methods on a `FuzzyIndex` or `FuzzyObjectIndex` after `.destroy()` throws an error.
+- `searchObjects()` and `FuzzyObjectIndex` throw a `TypeError` if `options.keys` is missing or empty.
+
 ## Benchmarks
 
 Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.dev/guide/features.html#benchmarking). Each benchmark processes 6 realistic string pairs of varying length and similarity.
@@ -424,6 +684,30 @@ Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.
 | **Browser** | ✅ WASM (~230 KB gzipped) | ✅ | ✅ | ✅ | ✅ |
 | **TypeScript** | ✅ full | ✅ full | ✅ | ✅ | ✅ |
 
+## Troubleshooting
+
+### "Cannot find native binding" error
+
+The native binary for your platform may not have been installed correctly. Run `npm rebuild rapid-fuzzy` or delete `node_modules` and reinstall. Ensure your platform and architecture are [supported by napi-rs](https://napi.rs/docs/cross-build/summary).
+
+### WASM fails to load in the browser
+
+Verify that your bundler is configured to handle `.wasm` files. If loading from a CDN, check that the server serves `.wasm` files with the correct `application/wasm` MIME type and that CORS headers allow the request.
+
+### SSR or Edge runtime errors
+
+Server-side rendering frameworks need to externalize rapid-fuzzy so the native module is not bundled. See [Framework Integration (SSR)](#framework-integration-ssr) above. For edge runtimes (Cloudflare Workers, Deno Deploy), rapid-fuzzy automatically uses the WASM build — see [Browser and Edge Runtime Usage](#browser-and-edge-runtime-usage).
+
+### Bun WASM initialization
+
+Bun does not yet support the TC39 WebAssembly ESM integration that wasm-bindgen relies on. If you need the WASM build in Bun, initialize it manually — see the [Bun section](#bun) for a complete code example.
+
+## Limitations
+
+- **WASM memory limit**: The WASM build is subject to the WebAssembly linear memory maximum of 4 GB (65,536 pages of 64 KB). This is sufficient for most use cases but may be a constraint for extremely large datasets.
+- **Synchronous search**: All search and distance functions are synchronous. This is by design — operations are fast enough (sub-millisecond for indexed search) that async overhead would be counterproductive. For large index construction, use `FuzzyIndex.fromAsync()`.
+- **No phonetic or language-specific matching**: rapid-fuzzy focuses on edit-distance and character-level fuzzy matching. It does not perform phonetic matching (e.g., Soundex, Metaphone) or language-specific stemming/lemmatization.
+
 ## Migration Guides
 
 Switching from another library? These guides provide API mapping tables, code examples, and performance comparisons:
@@ -433,6 +717,9 @@ Switching from another library? These guides provide API mapping tables, code ex
 - [**From leven / fastest-levenshtein**](docs/migration/from-leven.md) — Multi-algorithm upgrade with batch APIs
 - [**From fuzzysort**](docs/migration/from-fuzzysort.md) — Richer matching with query syntax and 10 distance algorithms
 - [**From uFuzzy**](docs/migration/from-ufuzzy.md) — Weighted object search, batch APIs, and persistent indexes
+- [**From fuzzball**](docs/migration/from-fuzzball.md) — Same ratio functions (token sort, token set, weighted), now 0.0–1.0 scale
+- [**From FlexSearch**](docs/migration/from-flexsearch.md) — Typo-tolerant fuzzy search to replace exact-token full-text search
+- [**From MiniSearch**](docs/migration/from-minisearch.md) — Faster fuzzy search with richer distance algorithms
 
 ## License
 

package/browser.js

@@ -1,4 +1,4 @@
-export * from 'rapid-fuzzy-wasm32-wasi'
+export * from './rapid-fuzzy-wasm-bindgen.js';
 
 // --- JS utilities (appended by scripts/patch-binding.js) ---
 export { highlight, highlightRanges } from './highlight.mjs';

package/highlight.d.mts

@@ -1,2 +1,2 @@
-export { highlight, highlightRanges } from './highlight.js';
 export type { HighlightRange } from './highlight.js';
+export { highlight, highlightRanges } from './highlight.js';

package/index.d.mts

@@ -1,11 +1,11 @@
-export * from './index.js';
-export { highlight, highlightRanges } from './highlight.js';
 export type { HighlightRange } from './highlight.js';
-export { searchObjects, FuzzyObjectIndex } from './objects.js';
+export { highlight, highlightRanges } from './highlight.js';
+export * from './index.js';
 export type {
   KeyConfig,
-  ObjectSearchOptions,
-  ObjectSearchResult,
   ObjectIndexOptions,
   ObjectIndexSearchOptions,
+  ObjectSearchOptions,
+  ObjectSearchResult,
 } from './objects.js';
+export { FuzzyObjectIndex, searchObjects } from './objects.js';

package/index.d.ts

@@ -13,6 +13,13 @@
 export declare class FuzzyIndex {
   /** Create a new FuzzyIndex from an array of strings. */
   constructor(items: Array<string>)
+  /**
+   * Construct a FuzzyIndex on the libuv thread pool, returning a Promise.
+   *
+   * For large datasets this keeps the JavaScript event loop unblocked during
+   * index construction. The synchronous constructor is fine for small datasets.
+   */
+  static fromAsync(items: Array<string>): Promise<FuzzyIndex>
   /** Return the number of items in the index. */
   get size(): number
   /**
@@ -94,6 +101,15 @@ export declare class KeyedFuzzyIndex {
    * Returns results sorted by combined weighted score (best match first).
    */
   search(query: string, options?: SearchOptions | undefined | null): Array<KeySearchResult>
+  /**
+   * Find the index of the closest matching item.
+   *
+   * Returns the index of the best match, or null if no match is found.
+   * If `min_score` is provided, returns null when the best match scores below the threshold.
+   *
+   * Use the returned index to look up the item in your own data array.
+   */
+  closest(query: string, minScore?: number | undefined | null): number | null
   /**
    * Add a single item to the index.
    *
@@ -116,6 +132,16 @@ export declare class KeyedFuzzyIndex {
   remove(index: number): boolean
   /** Free the internal data. After calling this, the index is empty. */
   destroy(): void
+  /**
+   * Serialize the index to a compact binary format.
+   *
+   * The returned Buffer can be written to disk, stored in IndexedDB,
+   * or transferred over the network. Use `KeyedFuzzyIndex.deserialize()` to
+   * reconstruct the index.
+   */
+  serialize(): Buffer
+  /** Reconstruct a KeyedFuzzyIndex from a previously serialized Buffer. */
+  static deserialize(data: Buffer): KeyedFuzzyIndex
 }
 
 /**
@@ -178,6 +204,35 @@ export declare function hammingBatch(pairs: Array<Array<string>>): Array<number
  */
 export declare function hammingMany(reference: string, candidates: Array<string>, maxDistance?: number | undefined | null): Array<number | undefined | null>
 
+/**
+ * Compute the Indel distance between two strings.
+ *
+ * The Indel distance counts the minimum number of insertions and deletions
+ * (no substitutions) required to transform one string into the other.
+ * It equals `len(a) + len(b) - 2 * LCS_length(a, b)`.
+ *
+ * Useful when substitutions are semantically two operations (one deletion +
+ * one insertion), such as in DNA sequence alignment.
+ */
+export declare function indel(a: string, b: string): number
+
+/**
+ * Compute the Indel distance for multiple pairs of strings in a single call.
+ *
+ * Returns an array of distances in the same order as the input pairs.
+ * Each pair must be an array of exactly two strings `[a, b]`.
+ */
+export declare function indelBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the Indel distance from one reference string to many candidates.
+ *
+ * Returns an array of distances, one per candidate, in the same order as the input.
+ * If `max_distance` is provided, candidates with distance exceeding the threshold
+ * will return `max_distance + 1` (enabling early termination for better performance).
+ */
+export declare function indelMany(reference: string, candidates: Array<string>, maxDistance?: number | undefined | null): Array<number>
+
 /**
  * A lightweight search result containing only index and score (no item string).
  *
@@ -304,6 +359,55 @@ export declare const enum MatchType {
   Fuzzy = 'Fuzzy'
 }
 
+/**
+ * Compute the normalized Hamming similarity between two strings.
+ *
+ * Returns `null` if the strings have different lengths.
+ * Returns a value between 0.0 (no matching characters) and 1.0 (identical).
+ */
+export declare function normalizedHamming(a: string, b: string): number | null
+
+/**
+ * Compute the normalized Hamming similarity for multiple pairs of strings in a single call.
+ *
+ * Returns an array of scores in the same order as the input pairs.
+ * Returns `null` for pairs with different lengths.
+ */
+export declare function normalizedHammingBatch(pairs: Array<Array<string>>): Array<number | undefined | null>
+
+/**
+ * Compute the normalized Hamming similarity from one reference string to many candidates.
+ *
+ * Returns an array of scores, one per candidate, in the same order as the input.
+ * Returns `null` for candidates with a different length than the reference.
+ * If `min_similarity` is provided, candidates with similarity below the threshold
+ * will also return `null` (enabling early termination for better performance).
+ */
+export declare function normalizedHammingMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number | undefined | null>
+
+/**
+ * Compute the normalized Indel similarity between two strings.
+ *
+ * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ */
+export declare function normalizedIndel(a: string, b: string): number
+
+/**
+ * Compute the normalized Indel similarity for multiple pairs of strings in a single call.
+ *
+ * Returns an array of similarity scores in the same order as the input pairs.
+ */
+export declare function normalizedIndelBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the normalized Indel similarity from one reference string to many candidates.
+ *
+ * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates with similarity below the threshold
+ * will return `0.0` (enabling early termination for better performance).
+ */
+export declare function normalizedIndelMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
+
 /**
  * Compute the normalized Levenshtein similarity between two strings.
  *
@@ -348,8 +452,9 @@ export declare function partialRatioBatch(pairs: Array<Array<string>>): Array<nu
  * Compute the partial ratio from one reference string to many candidates.
  *
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates scoring below the threshold return `0.0`.
  */
-export declare function partialRatioMany(reference: string, candidates: Array<string>): Array<number>
+export declare function partialRatioMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
 
 /**
  * Perform fuzzy search over a list of strings.
@@ -436,8 +541,10 @@ export declare function sorensenDiceBatch(pairs: Array<Array<string>>): Array<nu
  * Compute the Sorensen-Dice coefficient from one reference string to many candidates.
  *
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates scoring below the threshold return `0.0`.
+ * Reference bigrams are pre-computed once and reused for all candidates.
  */
-export declare function sorensenDiceMany(reference: string, candidates: Array<string>): Array<number>
+export declare function sorensenDiceMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
 
 /**
  * Compute the token set ratio between two strings.
@@ -460,8 +567,9 @@ export declare function tokenSetRatioBatch(pairs: Array<Array<string>>): Array<n
  * Compute the token set ratio from one reference string to many candidates.
  *
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates scoring below the threshold return `0.0`.
  */
-export declare function tokenSetRatioMany(reference: string, candidates: Array<string>): Array<number>
+export declare function tokenSetRatioMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
 
 /**
  * Compute the token sort ratio between two strings.
@@ -484,8 +592,9 @@ export declare function tokenSortRatioBatch(pairs: Array<Array<string>>): Array<
  * Compute the token sort ratio from one reference string to many candidates.
  *
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates scoring below the threshold return `0.0`.
  */
-export declare function tokenSortRatioMany(reference: string, candidates: Array<string>): Array<number>
+export declare function tokenSortRatioMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
 
 /**
  * Compute the weighted ratio between two strings.
@@ -508,8 +617,22 @@ export declare function weightedRatioBatch(pairs: Array<Array<string>>): Array<n
  * Compute the weighted ratio from one reference string to many candidates.
  *
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ * If `min_similarity` is provided, candidates scoring below the threshold return `0.0`.
  */
-export declare function weightedRatioMany(reference: string, candidates: Array<string>): Array<number>
+export declare function weightedRatioMany(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Array<number>
 
 // --- JS utilities (appended by scripts/patch-binding.js) ---
 export { highlight, highlightRanges, HighlightRange } from './highlight';
+/** TypedArray variants — identical to the `*Many` counterparts but return a typed array instead of `Array<number>`, reducing GC pressure for large candidate sets. */
+export declare function levenshteinManyU32(reference: string, candidates: Array<string>, maxDistance?: number | undefined | null): Uint32Array;
+export declare function damerauLevenshteinManyU32(reference: string, candidates: Array<string>, maxDistance?: number | undefined | null): Uint32Array;
+export declare function indelManyU32(reference: string, candidates: Array<string>, maxDistance?: number | undefined | null): Uint32Array;
+export declare function jaroManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function jaroWinklerManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function sorensenDiceManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function normalizedLevenshteinManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function normalizedIndelManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function tokenSortRatioManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function tokenSetRatioManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function partialRatioManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;
+export declare function weightedRatioManyF64(reference: string, candidates: Array<string>, minSimilarity?: number | undefined | null): Float64Array;