rapid-fuzzy 1.1.0 → 1.2.0

package/README.md

@@ -12,7 +12,7 @@ Blazing-fast fuzzy search for JavaScript — powered by Rust, works everywhere.
 
 ## Features
 
-- **Fast**: Up to 15,000x faster than fuse.js with FuzzyIndex (Rust + napi-rs)
+- **Fast**: Up to 15,000x faster than fuse.js in indexed mode on large datasets (Rust + napi-rs) — [see benchmarks](#benchmarks)
 - **Universal**: Works in Node.js (native), browsers (WASM), Deno, and Bun
 - **Zero JS dependencies**: Pure Rust core with napi-rs bindings
 - **Type-safe**: Full TypeScript support with auto-generated type definitions
@@ -51,14 +51,110 @@ 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).
+- **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.
 
-> **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.
+### Framework Integration (SSR)
+
+Native modules need to be externalized in SSR frameworks:
+
+**Next.js**
+
+```js
+// next.config.js
+const nextConfig = {
+  serverExternalPackages: ['rapid-fuzzy'],
+};
+```
+
+**Vite SSR**
+
+```js
+// vite.config.js
+export default {
+  ssr: {
+    external: ['rapid-fuzzy'],
+  },
+};
+```
+
+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 — see [`e2e/wasm-bun.test.ts`](e2e/wasm-bun.test.ts) for the manual initialization pattern.
 
 ## API
 
@@ -101,12 +197,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
@@ -169,6 +278,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: [] }, ...]
@@ -192,6 +304,38 @@ index.destroy();
 userIndex.destroy();
 ```
 
+#### Incremental Search (Autocomplete)
+
+FuzzyIndex automatically caches matching candidates. When a new query extends the previous one, only cached candidates are re-scored:
+
+```typescript
+const index = new FuzzyIndex(items);
+index.search('app');    // scores all items, caches matches
+index.search('apple');  // only re-scores cached candidates — much faster
+index.search('xyz');    // different query — full scan, new cache
+```
+
+This makes FuzzyIndex ideal for search-as-you-type UIs where each keystroke extends the query.
+
+#### Index Serialization
+
+Save and restore a `FuzzyIndex` to avoid rebuilding on startup:
+
+```typescript
+import { FuzzyIndex } from 'rapid-fuzzy';
+
+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.
+
 ### Match Highlighting
 
 Convert matched positions into highlighted markup for UI rendering:
@@ -247,7 +391,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';
@@ -273,13 +420,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 |
@@ -290,8 +566,9 @@ 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)
 

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

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

package/index.d.mts

@@ -1,11 +1,11 @@
-export * from './index.d.ts';
-export { highlight, highlightRanges } from './highlight.d.ts';
-export type { HighlightRange } from './highlight.d.ts';
-export { searchObjects, FuzzyObjectIndex } from './objects';
+export * from './index.js';
+export { highlight, highlightRanges } from './highlight.js';
+export type { HighlightRange } from './highlight.js';
+export { searchObjects, FuzzyObjectIndex } from './objects.js';
 export type {
   KeyConfig,
   ObjectSearchOptions,
   ObjectSearchResult,
   ObjectIndexOptions,
   ObjectIndexSearchOptions,
-} from './objects';
+} 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
   /**
@@ -44,7 +51,7 @@ export declare class FuzzyIndex {
   /**
    * Remove the item at the given index.
    *
-   * Returns false if the index is out of bounds.
+   * Uses swap-remove for O(1) performance. Returns false if out of bounds.
    */
   remove(index: number): boolean
   /** Free the internal data. After calling this, the index is empty. */
@@ -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;