OpenParable
Skip to content
← Back to skills

Fuzzy Ranking

Development
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/TanStack/table/blob/HEAD/packages/match-sorter-utils/skills/fuzzy-ranking/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fuzzy-ranking, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Setup

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

type Person = { name: string; email: string }
const person: Person = { name: 'Ada Lovelace', email: '[email protected]' }
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.