fuzzball.js

You can extend the matching logic beyond simple strings by using a custom scorer and a processor.

• Combining Fields: Use a processor to concatenate multiple fields from an object into a single string for scoring.
• Custom Logic: Provide a scorer function that accepts (query, choice, options). This allows you to perform logic like checking if specific properties (e.g., gender) match exactly before applying fuzzy matching to others.

When using a custom scorer, the query and choice can be any data type (objects, numbers, etc.) as long as your scorer handles them.

// Example: Scoring based on multiple fields via processor
const processor = choice => choice.field1 + " " + choice.field2;

// Example: Custom scorer for complex object matching
const query = {name: "tiger", gender: "female"};
const choices = [
  {name: "tigger", gender: "male"},
  {name: "lulu", gender: "female"}
];

function myCustomScorer(query, choice, options) {
  if (query.gender !== choice.gender) return 0;
  return fuzz.ratio(query.name, choice.name, options);
}

const results = fuzz.extract(query, choices, { scorer: myCustomScorer });

The core functionality involves calculating similarity ratios between strings or extracting the best matches from a list of choices.

By default, fuzz.extract returns an array of tuples: [choice, score, index/key]. To receive an array of objects instead, set options.returnObjects = true to get [{choice, score, key}, ...].

For asynchronous operations, use fuzz.extractAsPromised. This supports cancellation via an AbortController passed in the options.abortController field.

fuzz = require('fuzzball');

// Simple ratio
fuzz.ratio("hello world", "hiyyo wyrld"); // 64

// Token set ratio
fuzz.token_set_ratio("fuzzy was a bear", "a fuzzy bear fuzzy was"); // 100

// Extracting best matches from choices
const options = {scorer: fuzz.token_set_ratio};
const choices = ["Hood, Harry", "Mr. Minor", "Mr. Henry Hood"];
const results = fuzz.extract("mr. harry hood", choices, options);
// Results: [ [ 'Hood, Harry', 100, 0 ], [ 'Mr. Henry Hood', 85, 2 ], [ 'Mr. Minor', 40, 1 ] ]

// Async extraction with cancellation
const abortController = new AbortController();
const asyncOptions = { ...options, abortController };

fuzz.extractAsPromised("gonna get canceled", choices, asyncOptions)
  .then(res => {/* do stuff */})
  .catch((e) => {
    if (e.message === 'aborted') console.log('Search was aborted!');
  });

abortController.abort();

If you are searching a large list of terms repeatedly, you can pre-calculate expensive processing steps to boost performance.

For token_sort_ratio (using extract)

Pre-calculate the sorted tokens and attach them to each choice object as proc_sorted. This prevents process_and_sort() from running during every search.

// Pre-process choices
for (let choice of choices) {
  choice.proc_sorted = fuzz.process_and_sort(fuzz.full_process(choice.model));
}
// Use in extract
const options = { scorer: fuzz.token_sort_ratio, full_process: false };
fuzz.extract(query, choices, options);

For token_set_ratio (using extract)

Pre-calculate unique tokens and attach them to each choice object as tokens. This prevents unique_tokens() from running during every search.

// Pre-process choices
for (let choice of choices) {
  choice.tokens = fuzz.unique_tokens(fuzz.full_process(choice.model));
}
// Use in extract
const options = { scorer: fuzz.token_set_ratio, full_process: false };
fuzz.extract(query, choices, options);

For standalone functions

If using scorers as standalone functions (not via extract), pass the pre-calculated values via the options object.

• For token_sort_ratio: Set options.proc_sorted = true and pass both strings already processed by process_and_sort and full_process.
• For token_set_ratio: Pass an array of two token sets to options.tokens (e.g., [query_tokens, choice_tokens]).

The ultra_lite version of fuzzball.js provides a compact set of tools for calculating string similarity (Levenshtein distance and various ratios) and performing fuzzy extraction from a set of choices. It is suitable for environments where bundle size is a priority.

Core Capabilities

• Similarity Metrics: Calculate distance, ratio, token_set_ratio, and token_sort_ratio between strings.
• Fuzzy Extraction: Find the best matches for a query within an array of strings or an object of choices.
• Asynchronous Extraction: Use extractAsync or extractAsPromised to perform searches without blocking the main thread, supporting cancellation via AbortController or cancelToken.
• Pre-processing: Customize how strings are processed using a processor function or built-in full_process logic.

import { extract, distance, ratio } from './fuzzball_ultra_lite.esm.min.js';

// Basic similarity
const dist = distance('kitten', 'sitting');
const rat = ratio('kitten', 'sitting');

// Fuzzy extraction
const choices = ['apple', 'banana', 'cherry'];
const matches = extract('aple', choices);
// Returns array of [choice, score, index]