fuzzy

README

Fuzzy

Fuzzy is a fast and accurate fuzzy matching library for file search. It combines multiple search algorithms with a smart frecency-based ranking system to provide relevant results quickly.

[!IMPORTANT] Fuzzy focuses on accuracy and typo tolerance while maintaining high performance.
It is optimized for file path searching rather than just single strings. This package is intended for local use or side projects.

---

Features

• Typo tolerance: Handles common typing errors using Levenshtein distance
• Multi-algorithm: Uses bitset filtering and optimal alignment fuzzy matching
• Frecency ranking: Learns from user behavior to prioritize frequently and recently used files
• Parallel processing: Scalable performance for large datasets
• Thread-safe: Safe for concurrent use in multi-threaded applications

Installation

go get github.com/versenilvis/fuzzy

Requirements: Go 1.21+

Usage

Basic Example

package main

import (
	"fmt"
	"github.com/versenilvis/fuzzy"
)

func main() {
	// 1. Create Searcher
	files := []string{
		"/home/user/Documents/report.pdf",
		"/home/user/Documents/contract.docx",
		"/home/user/Music/song.mp3",
		"/home/user/Code/main.go",
		"/home/user/Code/utils.go",
	}

	searcher := fuzzy.NewSearcher(files)

	// 2. Basic Search
	fmt.Println("--- Searching 'report' ---")
	results := searcher.Search("report")
	for _, path := range results {
		fmt.Println("  ->", path)
	}

	// 3. Typo Tolerance
	fmt.Println("\n--- Searching 'maiin' (typo) ---")
	results = searcher.Search("maiin")
	for _, path := range results {
		fmt.Println("  ->", path)
	}

	// 4. Learning from User behavior
	searcher.RecordSelection("main", "/home/user/Code/main.go")
	
	// Subsequent searches will prioritize this file
	results = searcher.Search("mai")
}

API Reference

NewSearcher(items []string) *Searcher

Creates a new searcher optimized for file paths.

Search(query string, opts ...SearchOption) []string

Returns the top matching results for a query, automatically applying frecency boosts.

RecordSelection(query, selected string)

Records a selection to increase the priority (frecency) of a file for future searches.

License

This project is licensed under the 0BSD License. Meaning you can do whatever you want with it.

Documentation

Overview

Package fuzzy - Entry point for fuzzy searching

Index

• func LevenshteinRatio(s1, s2 string) int
• func Normalize(s string) string
• type MatchResult
• type SearchOptions
• type Searcher
  • func NewPlainSearcher(items []string) *Searcher
  • func NewSearcher(items []string) *Searcher
  • func NewSearcherWithMemory(items []string, memory *core.FileMemory) *Searcher
  • func (s *Searcher) ClearCache()
  • func (s *Searcher) RecordSelection(query, filePath string)
  • func (s *Searcher) Search(query string, opts ...*SearchOptions) []string
  • func (s *Searcher) SearchDebug(query string)
  • func (s *Searcher) SearchWithScores(query string, opts ...*SearchOptions) []MatchResult

Functions

func LevenshteinRatio

func LevenshteinRatio(s1, s2 string) int

LevenshteinRatio exposes core Levenshtein distance logic

func Normalize

func Normalize(s string) string

Normalize exposes core normalization logic

Types

type MatchResult

type MatchResult struct {
	Str   string
	Score int
}

MatchResult represents a scored search result

type SearchOptions

type SearchOptions struct {
	ContextBoosts map[string]int // Optional boosts for specific items
	Limit         int            // Maximum number of results to return
}

SearchOptions provides advanced search configuration

type Searcher

type Searcher struct {
	Originals  []string            // Original items
	Normalized [][]byte            // Normalized items for fast matching
	Memory     *core.FileMemory    // Frecency memory system
	Filter     *core.UnigramFilter // Bitset filter for candidates
	// contains filtered or unexported fields
}

Searcher is the main object for performing fuzzy searches

func NewPlainSearcher

func NewPlainSearcher(items []string) *Searcher

NewPlainSearcher creates a searcher for plain text items

func NewSearcher

func NewSearcher(items []string) *Searcher

NewSearcher creates a searcher optimized for file paths

func NewSearcherWithMemory

func NewSearcherWithMemory(items []string, memory *core.FileMemory) *Searcher

NewSearcherWithMemory creates a searcher with existing memory

func (*Searcher) ClearCache

func (s *Searcher) ClearCache()

ClearCache clears selection history

func (*Searcher) RecordSelection

func (s *Searcher) RecordSelection(query, filePath string)

RecordSelection records an item selection to update frecency

func (*Searcher) Search

func (s *Searcher) Search(query string, opts ...*SearchOptions) []string

Search performs fuzzy search and returns matching strings

func (*Searcher) SearchDebug

func (s *Searcher) SearchDebug(query string)

SearchDebug prints debug information for a query

func (*Searcher) SearchWithScores

func (s *Searcher) SearchWithScores(query string, opts ...*SearchOptions) []MatchResult

SearchWithScores performs fuzzy search and returns scored results