or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-fuzzy

Small, standalone fuzzy search / fuzzy filter library that works in both browser and Node.js environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fuzzy@0.1.x

To install, run

npx @tessl/cli install tessl/npm-fuzzy@0.1.0

index.mddocs/

Fuzzy

Fuzzy is a lightweight, standalone fuzzy search and filtering library that works in both browser and Node.js environments. It implements fuzzy matching algorithms similar to Sublime Text's command-p file search, allowing developers to perform approximate string matching where characters in a search pattern can match non-consecutive characters in target strings.

Package Information

  • Package Name: fuzzy
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install fuzzy

Core Imports

var fuzzy = require('fuzzy');

Browser (global):

// Available as global 'fuzzy' object
console.log(fuzzy);

Note: This library does not support ES module imports. Use CommonJS require() or browser global access only.

Basic Usage

var fuzzy = require('fuzzy');

// Simple string filtering
var list = ['baconing', 'narwhal', 'a mighty bear canoe'];
var results = fuzzy.filter('bcn', list);
var matches = results.map(function(el) { return el.string; });
console.log(matches);
// ['baconing', 'a mighty bear canoe']

// With highlighting
var options = { pre: '<b>', post: '</b>' };
var highlighted = fuzzy.filter('bcn', list, options);
console.log(highlighted[0].string);
// '<b>b</b>a<b>c</b>o<b>n</b>ing'

Capabilities

Boolean Fuzzy Matching

Tests if a pattern fuzzy matches a string, returning a simple boolean result.

/**
 * Does pattern fuzzy match str?
 * @param {string} pattern - The search pattern
 * @param {string} str - The string to test against  
 * @returns {boolean} True if pattern matches, false otherwise
 */
fuzzy.test(pattern, str);

Usage Example:

var fuzzy = require('fuzzy');

console.log(fuzzy.test('back', 'imaback'));    // true
console.log(fuzzy.test('back', 'bakck'));      // true
console.log(fuzzy.test('back', 'abck'));       // false

Highlighted Fuzzy Matching

Performs fuzzy matching with scoring and optional highlighting of matched characters.

/**
 * If pattern matches str, wrap each matching character in opts.pre and opts.post.
 * If no match, return null.
 * @param {string} pattern - The search pattern
 * @param {string} str - The string to match against
 * @param {Object} [opts] - Options object
 * @param {string} [opts.pre=''] - String to wrap before matching characters
 * @param {string} [opts.post=''] - String to wrap after matching characters  
 * @param {boolean} [opts.caseSensitive=false] - Whether matching is case sensitive
 * @returns {Object|null} Match result with rendered string and score, or null if no match
 */
fuzzy.match(pattern, str, opts);

Usage Example:

var fuzzy = require('fuzzy');

var result = fuzzy.match('ab', 'ZaZbZ', {pre: '<', post: '>'});
console.log(result.rendered); // 'Z<a>Z<b>Z'
console.log(result.score);    // 3

// Case sensitivity
var result2 = fuzzy.match('Ab', 'aB', {caseSensitive: true});
console.log(result2); // null (no match due to case sensitivity)

Array Filtering with Ranking

Main entry point that filters an array for fuzzy matches and returns results with ranking and metadata.

/**
 * Filters arr for matches against pattern. Returns an array with matching values.
 * @param {string} pattern - The search pattern
 * @param {Array} arr - Array of items to filter  
 * @param {Object} [opts] - Options object
 * @param {string} [opts.pre=''] - String to wrap before matching characters
 * @param {string} [opts.post=''] - String to wrap after matching characters
 * @param {Function} [opts.extract] - Function to extract string from each element for matching
 * @returns {Array} Array of FilterResult objects sorted by score
 */
fuzzy.filter(pattern, arr, opts);

Usage Examples:

var fuzzy = require('fuzzy');

// Basic array filtering
var list = ['baconing', 'narwhal', 'a mighty bear canoe'];
var results = fuzzy.filter('bcn', list);
console.log(results);
// [
//   {string: 'baconing', score: 3, index: 0, original: 'baconing'},
//   {string: 'a mighty bear canoe', score: 3, index: 2, original: 'a mighty bear canoe'}
// ]

// With highlighting
var options = { pre: '<b>', post: '</b>' };
var highlighted = fuzzy.filter('bcn', list, options);
console.log(highlighted[0].string);
// '<b>b</b>a<b>c</b>o<b>n</b>ing'

// With object extraction
var objectList = [
  {name: 'baconing', category: 'food'},
  {name: 'narwhal', category: 'animal'},
  {name: 'a mighty bear canoe', category: 'vehicle'}
];
var extractResults = fuzzy.filter('bcn', objectList, {
  pre: '<b>',
  post: '</b>',
  extract: function(el) { return el.name; }
});
console.log(extractResults[0]);
// {
//   string: '<b>b</b>a<b>c</b>o<b>n</b>ing',
//   score: 3,
//   index: 0, 
//   original: {name: 'baconing', category: 'food'}
// }

Simple String Array Filtering

Simplified filtering that returns only matching strings from an array, without scoring or metadata.

/**
 * Return all elements of array that have a fuzzy match against pattern.
 * @param {string} pattern - The search pattern
 * @param {Array<string>} array - Array of strings to filter
 * @returns {Array<string>} Array of strings that match the pattern
 */
fuzzy.simpleFilter(pattern, array);

Usage Example:

var fuzzy = require('fuzzy');

var list = ['baconing', 'narwhal', 'a mighty bear canoe'];
var matches = fuzzy.simpleFilter('bcn', list);
console.log(matches);
// ['baconing', 'a mighty bear canoe']

Types

MatchResult

/**
 * Result object returned by fuzzy.match()
 * @typedef {Object} MatchResult
 * @property {string} rendered - The string with highlighted matches
 * @property {number} score - The match score (higher = better match)
 */

FilterResult

/**
 * Result object returned by fuzzy.filter()
 * @typedef {Object} FilterResult
 * @property {string} string - The rendered string with highlights
 * @property {number} score - The match score (higher = better match)
 * @property {number} index - Original index in the input array
 * @property {*} original - The original element from the input array
 */

MatchOptions

/**
 * Options for fuzzy.match()
 * @typedef {Object} MatchOptions
 * @property {string} [pre=''] - String to wrap before matching characters
 * @property {string} [post=''] - String to wrap after matching characters
 * @property {boolean} [caseSensitive=false] - Whether matching is case sensitive
 */

FilterOptions

/**
 * Options for fuzzy.filter()
 * @typedef {Object} FilterOptions
 * @property {string} [pre=''] - String to wrap before matching characters
 * @property {string} [post=''] - String to wrap after matching characters
 * @property {Function} [extract] - Function to extract string from each element for matching
 */

Error Handling

  • fuzzy.match() returns null when no match is found
  • fuzzy.filter() returns an empty array when no matches are found
  • Invalid input handling:
    • Non-string patterns: fuzzy.filter() returns the original array unchanged
    • Empty or null arrays: fuzzy.filter() returns an empty array
    • Empty patterns: Always match (return all items)

Scoring Algorithm

The fuzzy matching algorithm uses a scoring system that:

  • Awards points for each matching character
  • Gives bonus points for consecutive character matches
  • Assigns infinite score to exact matches
  • Sorts results by score (highest first), breaking ties by original array index

Performance Characteristics

  • Lightweight: ~1KB minified
  • Browser and Node.js compatible
  • Case-insensitive matching by default (configurable)
  • Handles Unicode characters
  • Optimized for interactive search experiences