rapid-fuzzy 0.3.0 → 0.4.0

package/README.md

@@ -69,6 +69,9 @@ search('app', items, 5);
 const [match] = search('hlo', ['hello world'], { includePositions: true });
 // → { item: 'hello world', score: 0.75, index: 0, positions: [0, 2, 4] }
 
+// Case-sensitive matching (default: smart case)
+search('Type', items, { isCaseSensitive: true });
+
 // Find the single best match
 closest('tsc', ['TypeScript', 'JavaScript', 'Python']);
 // → 'TypeScript'
@@ -78,6 +81,59 @@ closest('xyz', items, 0.5);
 // → null
 ```
 
+### Object Search
+
+Search across object properties with weighted keys — a drop-in replacement for fuse.js's `keys` option:
+
+```typescript
+import { searchObjects } from 'rapid-fuzzy';
+
+const users = [
+  { name: 'John Smith', email: 'john@example.com' },
+  { name: 'Jane Doe', email: 'jane@example.com' },
+  { name: 'Bob Johnson', email: 'bob@test.com' },
+];
+
+// Search across multiple keys
+const results = searchObjects('john', users, {
+  keys: ['name', 'email'],
+});
+// → [{ item: { name: 'John Smith', ... }, score: 0.95, keyScores: [0.98, 0.85], index: 0 }]
+
+// Weighted keys — prioritize name matches over email
+searchObjects('john', users, {
+  keys: [
+    { name: 'name', weight: 2.0 },
+    { name: 'email', weight: 1.0 },
+  ],
+});
+
+// Nested key paths
+searchObjects('new york', items, { keys: ['address.city'] });
+```
+
+### Match Highlighting
+
+Convert matched positions into highlighted markup for UI rendering:
+
+```typescript
+import { search, highlight, highlightRanges } from 'rapid-fuzzy';
+
+const results = search('fzy', ['fuzzy'], { includePositions: true });
+const { item, positions } = results[0];
+
+// String markers
+highlight(item, positions, '<b>', '</b>');
+// → '<b>f</b>u<b>zy</b>'
+
+// Callback (React, JSX, custom DOM)
+highlight(item, positions, (matched) => `<mark>${matched}</mark>`);
+
+// Raw ranges for custom rendering
+highlightRanges(item, positions);
+// → [{ start: 0, end: 1, matched: true }, { start: 1, end: 2, matched: false }, ...]
+```
+
 ### Token-Based Matching
 
 Order-independent and partial string matching, inspired by Python's [RapidFuzz](https://github.com/rapidfuzz/RapidFuzz):
@@ -199,8 +255,10 @@ cargo bench           # Rust internal benchmarks
 |---|---|---|---|---|
 | **Algorithms** | Levenshtein, Jaro-Winkler, Sorensen-Dice, Damerau-Levenshtein, token sort/set, partial ratio, fuzzy search | Bitap-based fuzzy | Levenshtein only | Substring fuzzy |
 | **Runtime** | Rust (native + WASM) | Pure JS | Pure JS | Pure JS |
+| **Object search** | Yes (searchObjects with weighted keys) | Yes (keys option) | No | Yes (keys) |
 | **Score threshold** | Yes (minScore) | Yes (threshold) | No | Yes (threshold) |
 | **Match positions** | Yes (includePositions) | Yes | No | Yes |
+| **Highlight utility** | Yes (highlight, highlightRanges) | No (manual) | No | Yes (highlight) |
 | **Batch API** | Yes | No | No | No |
 | **Node.js native** | Yes (napi-rs) | No | No | No |
 | **Browser support** | Yes (WASM) | Yes | Yes | Yes |
@@ -211,7 +269,7 @@ cargo bench           # Rust internal benchmarks
 Switching from another library? These guides provide API mapping tables, code examples, and performance comparisons:
 
 - [**From string-similarity**](docs/migration/from-string-similarity.md) — Same Dice coefficient algorithm, now maintained and faster
-- [**From fuse.js**](docs/migration/from-fuse-js.md) — 13–41x faster fuzzy search with a simpler API
+- [**From fuse.js**](docs/migration/from-fuse-js.md) — 17–40x faster fuzzy search with a simpler API
 - [**From leven / fastest-levenshtein**](docs/migration/from-leven.md) — Multi-algorithm upgrade with batch APIs
 
 ## License

package/browser.js

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

package/highlight.d.ts

@@ -0,0 +1,55 @@
+/** A range within a string, indicating whether it was matched. */
+export interface HighlightRange {
+  /** Start index (inclusive). */
+  start: number;
+  /** End index (exclusive). */
+  end: number;
+  /** Whether this range was part of the match. */
+  matched: boolean;
+}
+
+/**
+ * Highlight matched characters in a search result string.
+ *
+ * Use with `SearchResult.positions` from a search with `includePositions: true`.
+ *
+ * @example String markers
+ * ```typescript
+ * const results = search('fzy', ['fuzzy'], { includePositions: true });
+ * highlight(results[0].item, results[0].positions, '<b>', '</b>');
+ * // → '<b>f</b>u<b>zy</b>'
+ * ```
+ *
+ * @example Callback (React, custom DOM, etc.)
+ * ```typescript
+ * highlight(result.item, result.positions, (matched) => `<mark>${matched}</mark>`);
+ * ```
+ */
+export declare function highlight(
+  item: string,
+  positions: Array<number>,
+  open: string,
+  close: string,
+): string;
+export declare function highlight(
+  item: string,
+  positions: Array<number>,
+  callback: (matched: string) => string,
+): string;
+
+/**
+ * Convert matched positions into an array of ranges for custom rendering.
+ *
+ * Each range indicates a contiguous segment of the string and whether it was
+ * part of the match. Useful for building custom highlight components.
+ *
+ * @example
+ * ```typescript
+ * const ranges = highlightRanges(result.item, result.positions);
+ * // → [{ start: 0, end: 1, matched: true }, { start: 1, end: 2, matched: false }, ...]
+ * ```
+ */
+export declare function highlightRanges(
+  item: string,
+  positions: Array<number>,
+): Array<HighlightRange>;

package/highlight.js

@@ -0,0 +1,58 @@
+// Pure JS highlight utilities — works in both Node.js and browser environments.
+// This file is manually maintained (not auto-generated by napi-rs).
+
+'use strict';
+
+/**
+ * @param {string} item
+ * @param {number[]} positions
+ * @returns {Array<{start: number, end: number, matched: boolean}>}
+ */
+function highlightRanges(item, positions) {
+  if (!item) return [];
+  if (!positions || positions.length === 0) {
+    return [{ start: 0, end: item.length, matched: false }];
+  }
+
+  const set = new Set(positions);
+  const ranges = [];
+  let i = 0;
+
+  while (i < item.length) {
+    const matched = set.has(i);
+    const start = i;
+    while (i < item.length && set.has(i) === matched) i++;
+    ranges.push({ start, end: i, matched });
+  }
+
+  return ranges;
+}
+
+/**
+ * @param {string} item
+ * @param {number[]} positions
+ * @param {string | ((substring: string) => string)} openOrCallback
+ * @param {string} [close]
+ * @returns {string}
+ */
+function highlight(item, positions, openOrCallback, close) {
+  if (!positions || positions.length === 0) return item;
+
+  const ranges = highlightRanges(item, positions);
+  const useCallback = typeof openOrCallback === 'function';
+
+  const parts = [];
+  for (const range of ranges) {
+    const segment = item.slice(range.start, range.end);
+    if (range.matched) {
+      parts.push(useCallback ? openOrCallback(segment) : openOrCallback + segment + (close ?? ''));
+    } else {
+      parts.push(segment);
+    }
+  }
+
+  return parts.join('');
+}
+
+module.exports.highlight = highlight;
+module.exports.highlightRanges = highlightRanges;

package/highlight.mjs

@@ -0,0 +1,57 @@
+// ESM version of highlight utilities — for browser bundlers and ESM-only environments.
+// Keep in sync with highlight.js (CJS version).
+
+/**
+ * Convert matched positions into an array of ranges for custom rendering.
+ *
+ * @param {string} item - The original string from the search result.
+ * @param {number[]} positions - Array of matched character indices.
+ * @returns {Array<{start: number, end: number, matched: boolean}>} Array of ranges.
+ */
+export function highlightRanges(item, positions) {
+  if (!item) return [];
+  if (!positions || positions.length === 0) {
+    return [{ start: 0, end: item.length, matched: false }];
+  }
+
+  const set = new Set(positions);
+  const ranges = [];
+  let i = 0;
+
+  while (i < item.length) {
+    const matched = set.has(i);
+    const start = i;
+    while (i < item.length && set.has(i) === matched) i++;
+    ranges.push({ start, end: i, matched });
+  }
+
+  return ranges;
+}
+
+/**
+ * Highlight matched characters in a search result string.
+ *
+ * @param {string} item - The original string from the search result.
+ * @param {number[]} positions - Array of matched character indices.
+ * @param {string | ((substring: string) => string)} openOrCallback - Opening tag or callback.
+ * @param {string} [close] - Closing tag (required when openOrCallback is a string).
+ * @returns {string} The highlighted string.
+ */
+export function highlight(item, positions, openOrCallback, close) {
+  if (!positions || positions.length === 0) return item;
+
+  const ranges = highlightRanges(item, positions);
+  const useCallback = typeof openOrCallback === 'function';
+
+  const parts = [];
+  for (const range of ranges) {
+    const segment = item.slice(range.start, range.end);
+    if (range.matched) {
+      parts.push(useCallback ? openOrCallback(segment) : openOrCallback + segment + (close ?? ''));
+    } else {
+      parts.push(segment);
+    }
+  }
+
+  return parts.join('');
+}

package/index.d.mts

@@ -1 +1,5 @@
 export * from './index.d.ts';
+export { highlight, highlightRanges } from './highlight.d.ts';
+export type { HighlightRange } from './highlight.d.ts';
+export { searchObjects } from './objects';
+export type { KeyConfig, ObjectSearchOptions, ObjectSearchResult } from './objects';

package/index.d.ts

@@ -114,6 +114,19 @@ export declare function jaroWinklerBatch(pairs: Array<Array<string>>): Array<num
  */
 export declare function jaroWinklerMany(reference: string, candidates: Array<string>): Array<number>
 
+/** A single result from multi-key fuzzy search. */
+export interface KeySearchResult {
+  /** The index of the item in the original input array. */
+  index: number
+  /** The combined weighted score normalized to 0.0-1.0 range. */
+  score: number
+  /**
+   * Per-key scores in the same order as the input keys.
+   * A score of 0.0 means the item did not match on that key.
+   */
+  keyScores: Array<number>
+}
+
 /**
  * Compute the Levenshtein distance between two strings.
  *
@@ -196,6 +209,17 @@ export declare function partialRatioMany(reference: string, candidates: Array<st
  */
 export declare function search(query: string, items: Array<string>, options?: number | SearchOptions | undefined | null): Array<SearchResult>
 
+/**
+ * Perform fuzzy search across multiple text keys with weights.
+ *
+ * `key_texts[k]` is an array of strings for key `k`, one per item.
+ * All inner arrays must have the same length (the number of items).
+ * `weights` specifies the relative importance of each key.
+ *
+ * Returns results sorted by combined weighted score (best match first).
+ */
+export declare function searchKeys(query: string, keyTexts: Array<Array<string>>, weights: Array<number>, options?: SearchOptions | undefined | null): Array<KeySearchResult>
+
 /** Options for the search function. */
 export interface SearchOptions {
   /** Maximum number of results to return. */
@@ -204,6 +228,11 @@ export interface SearchOptions {
   minScore?: number
   /** If true, include matched character positions in results. */
   includePositions?: boolean
+  /**
+   * If true, matching is case-sensitive. Default is smart case
+   * (case-insensitive unless the query contains uppercase characters).
+   */
+  isCaseSensitive?: boolean
 }
 
 /** A single fuzzy search result with the matched item and its score. */
@@ -314,3 +343,6 @@ export declare function weightedRatioBatch(pairs: Array<Array<string>>): Array<n
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
  */
 export declare function weightedRatioMany(reference: string, candidates: Array<string>): Array<number>
+
+// --- JS utilities (appended by scripts/patch-binding.js) ---
+export { highlight, highlightRanges, HighlightRange } from './highlight';

package/index.js

@@ -597,6 +597,7 @@ module.exports.partialRatio = nativeBinding.partialRatio
 module.exports.partialRatioBatch = nativeBinding.partialRatioBatch
 module.exports.partialRatioMany = nativeBinding.partialRatioMany
 module.exports.search = nativeBinding.search
+module.exports.searchKeys = nativeBinding.searchKeys
 module.exports.sorensenDice = nativeBinding.sorensenDice
 module.exports.sorensenDiceBatch = nativeBinding.sorensenDiceBatch
 module.exports.sorensenDiceMany = nativeBinding.sorensenDiceMany
@@ -609,3 +610,8 @@ module.exports.tokenSortRatioMany = nativeBinding.tokenSortRatioMany
 module.exports.weightedRatio = nativeBinding.weightedRatio
 module.exports.weightedRatioBatch = nativeBinding.weightedRatioBatch
 module.exports.weightedRatioMany = nativeBinding.weightedRatioMany
+
+// --- JS utilities (appended by scripts/patch-binding.js) ---
+const _hl = require('./highlight.js');
+module.exports.highlight = _hl.highlight;
+module.exports.highlightRanges = _hl.highlightRanges;

package/index.mjs

@@ -6,6 +6,7 @@ const binding = require('./index.js');
 export const {
   FuzzyIndex,
   closest,
+  searchKeys,
   damerauLevenshtein,
   damerauLevenshteinBatch,
   damerauLevenshteinMany,
@@ -37,4 +38,8 @@ export const {
   weightedRatio,
   weightedRatioBatch,
   weightedRatioMany,
-} = binding;
+  highlight,
+  highlightRanges,
+} = { ...binding, ...require('./highlight.js') };
+
+export const { searchObjects } = require('./objects.js');

package/objects.d.ts

@@ -0,0 +1,42 @@
+import type { SearchOptions } from './index';
+
+export interface KeyConfig {
+  name: string;
+  weight?: number;
+}
+
+export interface ObjectSearchOptions extends SearchOptions {
+  keys: Array<string | KeyConfig>;
+}
+
+export interface ObjectSearchResult<T> {
+  item: T;
+  index: number;
+  score: number;
+  keyScores: Array<number>;
+}
+
+/**
+ * Perform fuzzy search across object arrays with weighted keys.
+ *
+ * Wraps `searchKeys()` with an ergonomic API that accepts row-oriented
+ * objects and returns matched items directly.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'John Smith', email: 'john@example.com' },
+ *   { name: 'Jane Doe', email: 'jane@example.com' },
+ * ];
+ *
+ * const results = searchObjects('john', users, {
+ *   keys: [{ name: 'name', weight: 2.0 }, 'email'],
+ * });
+ * // results[0].item → { name: 'John Smith', email: 'john@example.com' }
+ * ```
+ */
+export declare function searchObjects<T>(
+  query: string,
+  items: Array<T>,
+  options: ObjectSearchOptions,
+): Array<ObjectSearchResult<T>>;

package/objects.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { searchKeys } = require('./index.js');
+
+/**
+ * Get a nested property value from an object using a dot-separated path.
+ * @param {Record<string, unknown>} obj
+ * @param {string} path
+ * @returns {string}
+ */
+function getNestedValue(obj, path) {
+  let current = obj;
+  for (const key of path.split('.')) {
+    if (current == null) return '';
+    current = current[key];
+  }
+  return current == null ? '' : String(current);
+}
+
+/**
+ * Perform fuzzy search across object arrays with weighted keys.
+ *
+ * Wraps `searchKeys()` with an ergonomic API that accepts row-oriented
+ * objects and returns matched items directly.
+ *
+ * @template T
+ * @param {string} query - The search query.
+ * @param {T[]} items - Array of objects to search.
+ * @param {object} options - Search options with keys configuration.
+ * @param {Array<string | { name: string; weight?: number }>} options.keys - Keys to search.
+ * @param {number} [options.maxResults] - Maximum results to return.
+ * @param {number} [options.minScore] - Minimum score threshold.
+ * @param {boolean} [options.isCaseSensitive] - Enable case-sensitive matching.
+ * @returns {Array<{ item: T; index: number; score: number; keyScores: number[] }>}
+ */
+function searchObjects(query, items, options) {
+  const { keys, ...searchOpts } = options;
+
+  const normalizedKeys = keys.map((k) =>
+    typeof k === 'string' ? { name: k, weight: 1.0 } : { name: k.name, weight: k.weight ?? 1.0 },
+  );
+
+  const keyTexts = normalizedKeys.map((k) => items.map((item) => getNestedValue(item, k.name)));
+  const weights = normalizedKeys.map((k) => k.weight);
+
+  const nativeOpts = Object.keys(searchOpts).length > 0 ? searchOpts : undefined;
+
+  const results = searchKeys(query, keyTexts, weights, nativeOpts);
+
+  return results.map((r) => ({
+    item: items[r.index],
+    index: r.index,
+    score: r.score,
+    keyScores: r.keyScores,
+  }));
+}
+
+module.exports = { searchObjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapid-fuzzy",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Rust-powered fuzzy search and string distance for JavaScript/TypeScript. 10-50x faster than fuse.js/leven.",
   "license": "MIT",
   "author": "derodero24",
@@ -46,7 +46,12 @@
     "index.mjs",
     "index.d.ts",
     "index.d.mts",
-    "browser.js"
+    "objects.js",
+    "objects.d.ts",
+    "browser.js",
+    "highlight.js",
+    "highlight.mjs",
+    "highlight.d.ts"
   ],
   "napi": {
     "binaryName": "rapid-fuzzy",
@@ -68,6 +73,7 @@
   "packageManager": "pnpm@10.32.1",
   "scripts": {
     "build": "napi build --manifest-path crates/core/Cargo.toml --platform --release --js index.js --dts index.d.ts --output-dir .",
+    "postbuild": "node scripts/patch-binding.js",
     "build:debug": "napi build --manifest-path crates/core/Cargo.toml --platform --js index.js --dts index.d.ts --output-dir .",
     "build:wasm": "napi build --manifest-path crates/core/Cargo.toml --platform --release --js index.js --dts index.d.ts --output-dir . --target wasm32-wasip1-threads",
     "artifacts": "napi artifacts",
@@ -80,6 +86,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:wasm": "vitest run __test__/wasm.spec.ts",
+    "test:browser": "playwright test",
+    "test:bun": "bun test e2e/wasm-bun.test.ts",
+    "test:deno": "deno test --allow-read --allow-env --allow-net --node-modules-dir=auto e2e/wasm-deno.test.ts",
     "test:watch": "vitest watch",
     "bench": "vitest bench",
     "bench:readme": "npx tsx scripts/update-bench-readme.ts",
@@ -99,6 +108,7 @@
     "@emnapi/runtime": "^1.9.0",
     "@napi-rs/cli": "^3.5.1",
     "@napi-rs/wasm-runtime": "^1.1.1",
+    "@playwright/test": "^1.58.2",
     "@tybys/wasm-util": "^0.10.1",
     "@types/node": "^24.0.0",
     "@types/string-similarity": "^4.0.2",
@@ -111,6 +121,7 @@
     "publint": "^0.3.18",
     "string-similarity": "^4.0.4",
     "typescript": "^5.9.3",
+    "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
   "pnpm": {
@@ -119,14 +130,14 @@
     ]
   },
   "optionalDependencies": {
-    "rapid-fuzzy-darwin-x64": "0.3.0",
-    "rapid-fuzzy-darwin-arm64": "0.3.0",
-    "rapid-fuzzy-linux-x64-gnu": "0.3.0",
-    "rapid-fuzzy-linux-x64-musl": "0.3.0",
-    "rapid-fuzzy-linux-arm64-gnu": "0.3.0",
-    "rapid-fuzzy-linux-arm64-musl": "0.3.0",
-    "rapid-fuzzy-win32-x64-msvc": "0.3.0",
-    "rapid-fuzzy-win32-arm64-msvc": "0.3.0",
-    "rapid-fuzzy-wasm32-wasi": "0.3.0"
+    "rapid-fuzzy-darwin-x64": "0.4.0",
+    "rapid-fuzzy-darwin-arm64": "0.4.0",
+    "rapid-fuzzy-linux-x64-gnu": "0.4.0",
+    "rapid-fuzzy-linux-x64-musl": "0.4.0",
+    "rapid-fuzzy-linux-arm64-gnu": "0.4.0",
+    "rapid-fuzzy-linux-arm64-musl": "0.4.0",
+    "rapid-fuzzy-win32-x64-msvc": "0.4.0",
+    "rapid-fuzzy-win32-arm64-msvc": "0.4.0",
+    "rapid-fuzzy-wasm32-wasi": "0.4.0"
   }
 }