FZF Fuzzy Matching Algorithm for JavaScript

Common errors

• Cannot find module 'fzf' or its corresponding type declarations.

  cause Incorrect TypeScript `moduleResolution` settings (e.g., `nodenext`, `node16`, `bundler`) in `tsconfig.json` when using `fzf` versions older than `v0.5.2`, or a missing `fzf` installation.
  fix Ensure `fzf` is installed (`npm i fzf`) and upgrade to `fzf@0.5.2` or later. If upgrading is not feasible, adjust `compilerOptions.moduleResolution` in `tsconfig.json` to `node`.

• TypeError: Fzf is not a constructor

  cause Attempting to import `Fzf` using CommonJS `require()` syntax, but the package is primarily designed for ESM or the default export is not correctly handled in CJS environments.
  fix Use ESM `import { Fzf } from 'fzf'` instead of `const { Fzf } = require('fzf')`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• Error: Package "fzf" (v0.5.0) requires Node.js "^16" and npm "^8".

  cause Attempting to use `fzf@0.5.0` (which was removed from NPM) in an environment that does not meet its specific, higher Node.js and NPM version requirements.
  fix This specific version is known to be problematic. Upgrade to `fzf@0.5.1` or the latest stable version. Avoid using `fzf@0.5.0` entirely.

Warnings

• breaking The behavior of `options.tiebreakers` was modified in v0.5.1 to align with the original FZF implementation. If you relied on the previous tiebreaker logic, you may need to adjust your options or expected sorting behavior.
  Fix: Review the new `tiebreakers` behavior in the official documentation and update your `FzfOptions` accordingly to achieve the desired sorting.
• breaking Version 0.5.0 was critically bugged and required Node.js 16 and NPM 8, leading to it being removed from NPM. It should never be used.
  Fix: Always use `v0.5.1` or above. If you accidentally installed `0.5.0`, downgrade or upgrade to a stable version immediately (e.g., `npm install fzf@latest`).
• gotcha As a `0.x` version package, `fzf` reserves the right to introduce breaking changes in minor version increments (e.g., `0.3.x` to `0.4.x`). Always consult migration guides and release notes when updating.
  Fix: Always pin to exact versions or use carets (`^`) with caution. Thoroughly test updates before deploying to production and review migration guides provided by the library.
• gotcha Older versions of `fzf` (prior to `v0.5.2`) had issues with TypeScript `moduleResolution` settings like `nodenext`, `node16`, or `bundler`, which could prevent types from being correctly resolved.
  Fix: Upgrade to `fzf@0.5.2` or later. If upgrading is not possible, ensure your `tsconfig.json` uses a compatible `moduleResolution` setting (e.g., `node`).
• gotcha The default fuzzy algorithm was changed to 'v2' in v0.4.1 for better highlighting, but 'v1' is faster. Performance-sensitive applications might need to explicitly configure the algorithm.
  Fix: If performance is critical, instantiate `Fzf` with `{ algorithm: 'v1' }` in its options to potentially gain speed at the expense of highlighting quality. Benchmark both options for your specific use case.

Install

• npm install fzf npm
• yarn add fzf yarn
• pnpm add fzf pnpm

Imports

• Fzf
  wrong:

  const { Fzf } = require('fzf')

  correct:

  import { Fzf } from 'fzf'

  The package is primarily designed for ESM; CommonJS `require` might lead to issues or incorrect typings, especially in newer Node.js environments or with specific bundler configurations. Prioritize ESM `import`.
• FzfOptions

  import type { FzfOptions } from 'fzf'

  Import types separately using `import type` for clarity and to ensure they are correctly resolved by TypeScript, especially with `moduleResolution` set to `nodenext` or `node16`.
• FzfResultItem

  import type { FzfResultItem } from 'fzf'

  Access types for the individual matched results returned by `fzf.find()`, which include the `item`, `score`, and `positions`.

Quickstart

This quickstart initializes `Fzf` with a list of strings and performs a basic fuzzy search, demonstrating how to retrieve and iterate over the sorted results.

import { Fzf } from 'fzf';

const programmingLanguages = [
  'go', 'javascript', 'python', 'rust', 
  'swift', 'kotlin', 'elixir', 'java', 
  'lisp', 'v', 'zig', 'nim', 'rescript', 
  'd', 'haskell'
];

// Create a new Fzf instance with your list of items
const fzf = new Fzf(programmingLanguages, {
  tiebreakers: ['end', 'length'], // Example option, uses 'end' and 'length' as secondary sort keys
  limit: 5 // Limit the number of results
});

// Perform a fuzzy search
const query = 'jav';
const entries = fzf.find(query);

console.log(`Fuzzy search results for '${query}':`);
entries.forEach(entry => {
  console.log(`- ${entry.item} (Score: ${entry.score})`);
});
// Expected output: javascript, java (order depends on scores and tiebreakers)