or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collection-management.mdcore-search.mdextended-search.mdindex-management.mdindex.md
tile.json

tessl/npm-fuse-js

Lightweight fuzzy-search library with zero dependencies that implements efficient fuzzy string matching algorithms

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fuse.js@7.1.x

To install, run

npx @tessl/cli install tessl/npm-fuse-js@7.1.0

index.mddocs/

Fuse.js

Fuse.js is a lightweight fuzzy-search library for JavaScript with zero dependencies. It implements efficient fuzzy string matching algorithms including the Bitap algorithm for approximate string matching, enabling developers to build powerful search functionality that can handle typos, misspellings, and partial matches.

Package Information

  • Package Name: fuse.js
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install fuse.js

Core Imports

import Fuse from "fuse.js";

For CommonJS:

const Fuse = require("fuse.js");

Multiple export options available:

// Standard build
import Fuse from "fuse.js";

// Minified build
import Fuse from "fuse.js/min";

// Basic build (reduced features)
import Fuse from "fuse.js/basic";

// Basic minified build
import Fuse from "fuse.js/min-basic";

Basic Usage

import Fuse from "fuse.js";

// Simple string search
const stringFuse = new Fuse(["apple", "banana", "orange"]);
const stringResults = stringFuse.search("bana");
console.log(stringResults); // [{ item: "banana", refIndex: 1 }]

// Object search with keys
const books = [
  { title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
  { title: "To Kill a Mockingbird", author: "Harper Lee" },
  { title: "1984", author: "George Orwell" }
];

const bookFuse = new Fuse(books, {
  keys: ["title", "author"],
  includeScore: true,
  threshold: 0.3
});

const bookResults = bookFuse.search("gatsby");
console.log(bookResults[0].item.title); // "The Great Gatsby"

Architecture

Fuse.js is built around several key components:

  • Core Search Engine: Main Fuse class managing search operations and configuration
  • Bitap Algorithm: Efficient fuzzy string matching with configurable distance and threshold
  • Index System: FuseIndex class for pre-computing and caching search indices for performance
  • Extended Search: Optional unix-like search commands with logical operators
  • Configuration System: Comprehensive options for fine-tuning search behavior
  • Type System: Full TypeScript support with generic types for different data structures

Capabilities

Core Search

Main fuzzy search functionality for finding approximate matches in collections of strings or objects. Supports configurable matching algorithms, scoring, and result formatting.

class Fuse<T> {
  constructor(
    list: ReadonlyArray<T>,
    options?: IFuseOptions<T>,
    index?: FuseIndex<T>
  );
  
  search<R = T>(
    pattern: string | Expression,
    options?: FuseSearchOptions
  ): FuseResult<R>[];
}

interface FuseResult<T> {
  item: T;
  refIndex: number;
  score?: number;
  matches?: ReadonlyArray<FuseResultMatch>;
}

Core Search

Index Management

Pre-indexing system for optimizing search performance on large datasets. Includes index serialization for caching and incremental updates for dynamic collections.

static createIndex<U>(
  keys: Array<FuseOptionKey<U>>,
  list: ReadonlyArray<U>,
  options?: FuseIndexOptions<U>
): FuseIndex<U>;

static parseIndex<U>(
  index: {
    keys: ReadonlyArray<string>;
    records: FuseIndexRecords;
  },
  options?: FuseIndexOptions<U>
): FuseIndex<U>;

getIndex(): FuseIndex<T>;

Index Management

Extended Search

Advanced search syntax with unix-like commands and logical operators. Enables exact matches, prefix/suffix matching, exclusions, and complex query expressions.

type Expression =
  | { [key: string]: string }
  | { $path: ReadonlyArray<string>; $val: string }
  | { $and?: Expression[] }
  | { $or?: Expression[] };

Extended Search

Collection Management

Dynamic collection manipulation with methods for adding, removing, and updating search data without recreating the entire index.

setCollection(docs: ReadonlyArray<T>, index?: FuseIndex<T>): void;
add(doc: T): void;
remove(predicate: (doc: T, idx: number) => boolean): T[];
removeAt(idx: number): void;

Collection Management

Configuration Types

interface IFuseOptions<T> {
  /** Case sensitivity control */
  isCaseSensitive?: boolean;
  /** Accent/diacritic handling */
  ignoreDiacritics?: boolean;
  /** Match scoring threshold (0-1) */
  threshold?: number;
  /** Pattern location preference */
  location?: number;
  /** Maximum match distance */
  distance?: number;
  /** Include match scores in results */
  includeScore?: boolean;
  /** Include match indices for highlighting */
  includeMatches?: boolean;
  /** Find all matches vs first match */
  findAllMatches?: boolean;
  /** Minimum match character length */
  minMatchCharLength?: number;
  /** Enable result sorting by score */
  shouldSort?: boolean;
  /** Custom sort function */
  sortFn?: FuseSortFunction;
  /** Fields to search in objects */
  keys?: Array<FuseOptionKey<T>>;
  /** Custom value getter function */
  getFn?: FuseGetFunction<T>;
  /** Ignore location in scoring */
  ignoreLocation?: boolean;
  /** Ignore field length normalization */
  ignoreFieldNorm?: boolean;
  /** Field length normalization weight */
  fieldNormWeight?: number;
  /** Enable extended search syntax */
  useExtendedSearch?: boolean;
}

type FuseOptionKey<T> = FuseOptionKeyObject<T> | string | string[];

interface FuseOptionKeyObject<T> {
  name: string | string[];
  weight?: number;
  getFn?: (obj: T) => ReadonlyArray<string> | string;
}

interface FuseSearchOptions {
  limit: number;
}

Static Properties

class Fuse<T> {
  /** Current library version */
  static version: string;
  
  /** Default configuration object */
  static config: Required<IFuseOptions<any>>;
  
  /** Development-only query parser (only available when NODE_ENV=development) */
  static parseQuery?: (query: Expression, options: IFuseOptions<any>) => any;
}