fuzzy

fuzzy is a small, dependency-free Go library that brings Sublime Text/VS Code-style fuzzy matching to any Go program. Given a search pattern and a list of strings (or anything implementing the Source interface), it scores and ranks matches based on first-character hits, camelCase boundaries, separator-adjacency, and character adjacency, then returns the matched character positions so callers can highlight results.

It’s built for interactive use cases like fuzzy-finders and command palettes: matching runs at millisecond speed even against large candidate lists, and the library ships with zero external dependencies beyond the Go standard library.

What You Get

• Find/FindNoSort functions matching directly against a []string slice
• FindFrom/FindFromNoSort for matching against any custom type via the Source interface (String(i), Len())
• FindFromIter/FindFromIterNoSort for matching against a lazy iter.Seq[string] iterator without materializing a slice
• Match results carrying the matched string, its original index, matched character positions, and a numeric score for ranking or highlighting
• Unicode-aware matching (case folding via unicode.SimpleFold, not just ASCII)

Common Use Cases

• Fuzzy-finder file pickers that let a developer jump to files in large repositories by typing a partial name
• Command palettes and quick-open menus ranking command/action names against a typed fragment
• Code symbol search matching function/class/symbol names against a typed query, using camelCase-boundary bonuses
• Interactive terminal UI selectors that narrow a large list of options as the user types

Under The Hood

Architecture fuzzy is organized as a single, flat package with no internal layering — every exported entry point (Find, FindFrom, FindFromIter, and their NoSort variants) funnels through one core scoring loop, FindFromIterNoSort, with a thin adapter (iterFromSource) bridging slice-based and custom Source-based callers onto a shared Go iterator. Find and FindFrom additionally invoke a stable sort over the returned Matches (which implements sort.Interface) to rank results by descending score. There’s no dependency injection or plugin architecture; the closest thing to an abstraction boundary is the Source interface, so a change to the core scoring algorithm propagates directly and uniformly to every public function that wraps it.

Tech Stack The library is pure Go with no runtime dependencies — its only declared dependency is a test-only pretty-printing helper. Tooling is a plain Makefile wrapping go build/test/install, golangci-lint for linting, and goimports for import formatting, with a single GitHub Actions workflow running the full lint-and-test suite on every push and pull request. There’s no framework, database, or external service integration of any kind — it’s a standalone algorithmic package meant to be imported directly into other Go programs via go get.

Code Quality Testing is table-driven and centers on canned match-quality scenarios (unicode input, camelCase boundaries, ranking order, adjacent-match bonuses), using a small pretty-printing library for readable diffs on failures rather than a full assertion framework. Error handling is minimal by design since the public API has almost no error paths — empty patterns and embedded NUL runes are handled defensively rather than causing panics. Naming follows idiomatic Go conventions throughout, and CI enforces both linting and tests on every change, giving the codebase consistent style despite its small size.

API Design The public surface is organized by input shape — a plain string slice, a custom Source interface, or a lazy iterator — each paired with a sorted and an unsorted variant, so a caller typically needs a single import and one function call to get ranked, highlightable matches. Documentation is thorough relative to the package’s size: detailed doc comments explain the scoring rules, the README walks through both slice-based and custom-Source usage, and a working example demonstrates an interactive fuzzy-finder built on top of the library. The only notable ergonomic cost is the small amount of boilerplate required to implement the Source interface for non-slice data, which is an inherent tradeoff rather than an oversight.