# Fuzzy Ranking

> Fuzzy Ranking is an Agent Skill for development published in the TanStack/table repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Rank fuzzy matches with rankItem, filter with RankingInfo.passed, compare saved ranking metadata with compareItems, and configure rankings, thresholds, accessors, min/max bounds, or diacritics. Load for @tanstack/match-sorter-utils itself or fuzzy Table filterMeta wiring.

- Skill name: `fuzzy-ranking`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/TanStack/table/blob/HEAD/packages/match-sorter-utils/skills/fuzzy-ranking/SKILL.md
- Repository: TanStack/table (28,185 GitHub stars when collected)

## SKILL.md

## Setup

<!-- skill-snippet:check -->

```ts
import { compareItems, rankItem, rankings } from '@tanstack/match-sorter-utils'

const query = 'tan'
const values = ['table', 'tanner', 'router']
export const ranked = values
  .map((value) => ({
    value,
    info: rankItem(value, query, { threshold: rankings.MATCHES }),
  }))
  .filter((entry) => entry.info.passed)
  .sort((a, b) => compareItems(a.info, b.info))
```

## Core Patterns

### Separate ranking, filtering, and sorting

Call `rankItem` once, filter on `info.passed`, retain the `RankingInfo`, then order matching results with `compareItems`.

### Rank object fields through accessors

```ts
type Person = { name: string; email: string }
const person: Person = { name: 'Ada Lovelace', email: 'ada@example.test' }
const info = rankItem(person, 'lov', {
  accessors: [(item) => item.name, (item) => item.email],
})
```

Accessor options can set a per-accessor threshold plus minRanking/maxRanking bounds.

### Store ranking as Table filter metadata

In a Table filterFn, call `addMeta?.({ itemRank })`. Register the corresponding
meta shape with `filterMeta: metaHelper<{ itemRank: RankingInfo }>()`. A related
sortFn reads `row.columnFiltersMeta[columnId]?.itemRank` and uses `compareItems`,
falling back to an ordinary comparator for ties or absent metadata. For the
primary Table composition, load `@tanstack/table-core#global-filtering` and
register the fuzzy filter under `filterFns` for `globalFilterFn: 'fuzzy'`.

## Common Mistakes

### HIGH Numeric rank used as pass flag

Wrong: `if (rankItem(value, query).rank) include(value)`.

Correct: test `rankItem(value, query).passed`.

Ranks below the configured threshold can still be nonzero; `passed` records the threshold decision.

Source: TanStack/table:packages/match-sorter-utils/src/index.ts

### HIGH Ranking recomputed during sorting

Wrong: call `rankItem` for both rows on every comparator invocation.

Correct: retain RankingInfo during filtering and pass the stored values to `compareItems`.

Sorting is called many times; recomputing also risks using different query/options than the filter decision.

Source: TanStack/table:docs/framework/react/guide/fuzzy-filtering.md

### MEDIUM compareItems direction reversed twice

Wrong: negate `compareItems(a, b)` because a larger rank should appear first.

Correct: use `compareItems(a, b)` directly for ascending fuzzy relevance.

The function already returns -1 when `a.rank` is greater than `b.rank`.

Source: TanStack/table:packages/match-sorter-utils/src/index.ts

## API Discovery

Inspect `node_modules/@tanstack/match-sorter-utils/src/index.ts` for the installed `RankItemOptions`, accessor attributes, ranking constants, and comparator behavior. For TanStack Table metadata integration, load the global-filtering and sorting skills.

---

Source: https://www.openparable.com/skill/development/fuzzy-ranking (OpenParable). Cite the canonical URL above.
