Skip to content

Conversation

@lalvarezt
Copy link
Contributor

@lalvarezt lalvarezt commented Oct 27, 2025

📺 PR Description

Summary

Adds a new sorting strategy selector that gives users control over how results are ordered. Three strategies are now available:

  • fuzzy (default): Sort results by fuzzy match score
  • disabled: Preserve the natural entry order from the source
  • frecency: Boost frequently and recently used items to the top

Motivation

Different use cases benefit from different sorting approaches. While fuzzy matching works well for exploring results, some channels like shell history benefit from preserving chronological order. The new frecency strategy learns from user behavior to surface the most relevant results based on frequency and recency of selection.

Key Features

  • CLI flag: --sorting-strategy <STRATEGY> to override sorting behavior
  • Configuration support: Set sorting strategy globally or per-channel in config files
  • Persistent frecency tracking: Maintains a database of selection history across sessions

Usage Examples

# Use default fuzzy matching
tv files --sorting-strategy fuzzy

# Use frecency-based sorting
tv files --sorting-strategy frecency

# Preserve natural order (no sorting)
tv env --sorting-strategy disabled

The sorting strategy can be configured globally in config.toml:

sorting_strategy = "fuzzy"

Or per-channel in cable channel definitions:

[sorting]
strategy = "disabled"

Implementation Notes

This feature leverages a custom fork of the nucleo fuzzy matcher that adds frecency support. The frecency algorithm tracks both frequency (how often items are selected) and recency
(when they were last used) to prioritize results.

Why Vendoring

Why frecency is a better match inside nucleo

  1. Tight Integration with Matching Pipeline
  • Frecency scoring happens during the match loop in parallel workers
  • Needs direct access to item data without serialization overhead
  • Shares the same threading/synchronization primitives
  1. Performance
  • Frecency scores computed alongside fuzzy match scores in same parallel iteration
  • Zero-copy access to item data
  • No IPC or serialization between matcher and frecency scorer

Checklist

  • my commits and PR title follow the conventional commits format
  • if this is a new feature, I have added tests to consolidate the feature and prevent regressions
  • if this is a bug fix, I have added a test that reproduces the bug (if applicable)
  • I have added a reasonable amount of documentation to the code where appropriate

This PR resolves #671 and resolves #672

Edit: Added why vendoring rationale as opposed to #671

@alexpasmantier alexpasmantier force-pushed the main branch 4 times, most recently from d1362c0 to bae2241 Compare November 1, 2025 15:14
@alexpasmantier alexpasmantier force-pushed the main branch 2 times, most recently from 32dc349 to d2034a8 Compare November 21, 2025 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant