resolve-team
Version:
Resolve NBA & NFL sports team names and information via fuzzy search
370 lines (366 loc) • 11.4 kB
text/typescript
/**
* Configuration options for the {@linkcode resolveTeam} API's Fuse.js search functionality.
*
* @remarks
* The threshold option controls how strictly the fuzzy search matches terms:
* - 0.0 = exact matches only
* - 0.4 = default, good balance of fuzzy/exact matching
* - 1.0 = very loose matching
*
* @example
* ```ts
* // Example with strict matching
* const strict = await resolveTeam('NY', { threshold: 0.2 })
*
* // Example with loose matching
* const loose = await resolveTeam('NY', { threshold: 0.6 })
*
* // Example with sport filtering
* const nbaOnly = await resolveTeam('NY', {
* sport: 'nba',
* threshold: 0.4
* })
*
* // Example returning full team data
* const fullData = await resolveTeam('NY', {
* full: true,
* threshold: 0.4
* })
* ```
*
* @interface
*/
interface Options {
/**
* The sport category to search within.
* Use 'nba', 'nfl', or 'all' (default).
*/
sport?: string;
/**
* Controls fuzzy search sensitivity (0 to 1).
* - 0.0: Exact matches only
* - 0.4: Default, balanced matching
* - 1.0: Very loose matching
*/
threshold?: number;
/**
* When true, returns the complete team object.
* When false (default), returns only the team name.
*/
full?: boolean;
}
/**
* Represents a sports team with its identifying information.
*
* @example
* ```ts
* const team: Team = {
* name: 'Los Angeles Lakers',
* colors: ['#552583', '#FDB927', '#000000'],
* nicknames: ['lakers', 'los angeles', 'lal'],
* abbrev: ['LAL'],
* sport: 'nba'
* }
* ```
*
* @interface
*/
interface Team {
/** The official full name of the team. */
name: string;
/** The official team colors in hexadecimal format. */
colors: string[];
/** Common nicknames and alternative names for the team. */
nicknames: string[];
/** Official abbreviations used by the league. */
abbrev: string[];
/** The sport this team belongs to (e.g., 'nba', 'nfl'). */
sport: string;
}
/**
* Represents a list of teams categorized by sport.
* This is the source data that the {@linkcode resolveTeam} API uses to identify and resolve team information.
* Currently supports NBA and NFL teams.
*
* @example
* ```ts
* const teams: TeamList = {
* nba: [
* {
* name: 'Boston Celtics',
* colors: ['#007A33', '#BA9653', '#000000'],
* nicknames: ['celtics', 'boston', 'bos'],
* abbrev: ['BOS']
* }
* ],
* nfl: [
* {
* name: 'Green Bay Packers',
* colors: ['#203731', '#FFB612'],
* nicknames: ['packers', 'green bay', 'gb'],
* abbrev: ['GB']
* }
* ]
* }
* ```
*
* @interface
*/
interface ITeamList {
/** List of NBA teams. */
nba: Team[];
/** List of NFL teams. */
nfl: Team[];
}
/**
* Acceptable sports the library can search for.
*
* i.e: 'nba', 'nfl'
*/
type SportLeague = keyof ITeamList;
/**
* Provides methods for resolving and comparing sports team names using fuzzy search capabilities.
*
* @example
* ```ts
* const resolver = new TeamResolver()
*
// Basic usage - returns team name
* const basic = await resolver.resolve('celtics')
* console.log(basic) // 'Boston Celtics'
*
// Get full team object (name, colors, nicknames, abbrev, sport)
* const full = await resolver.resolve('celtics', { full: true })
*
// Compare two teams
* const areSame = await resolver.compare('celtics', 'boston')
* console.log(areSame) // true
* ```
*/
declare class TeamResolver {
private fuseInstance;
private lastOptions;
private options;
/**
* Creates a new TeamResolver instance with optional default options.
*
* @param {Options} [options=defaultOptions] - Default options to use for all resolver operations
*/
constructor(options?: Options);
/**
* Resolves a sports team name or complete team data based on a search query.
* Uses fuzzy search to find matches even with partial or misspelled input.
*
* @remarks
* The search is performed across team names, nicknames, and abbreviations.
* The threshold option controls how strict the matching is:
* - Lower values (0.0-0.3): Require very close matches
* - Medium values (0.4-0.6): Allow moderate fuzzy matching
* - Higher values (0.7-1.0): Very loose matching, may return unexpected results
*
* @example
* ```ts
// Basic usage - returns team name
* const basic = await resolver.resolve('celtics')
* console.log(basic) // 'Boston Celtics'
*
// Get full team object
* const full = await resolver.resolve('celtics', { full: true })
*
// Restrict the search to a specific sport
* const strict = await resolver.resolve('minnesota', {
* sport: 'nfl',
* threshold: 0.2
* }) // 'Minnesota Vikings'
*
* ```
*/
resolve(query: string, options: Options & {
full: true;
}): Promise<Team | null>;
resolve(query: string, options?: Options): Promise<string | null>;
/**
* Compares two team queries to determine if they refer to the same team.
* Uses fuzzy search to handle variations in team names, nicknames, and abbreviations.
*
* @example
* ```ts
// Compare teams using default options
* const areSame = await resolver.compare('lakers', 'lal')
* console.log(areSame) // true
*
// Compare teams within a specific sport
* const nflCompare = await resolver.compare('giants', 'nyg', {
* sport: 'nfl',
* threshold: 0.3
* })
*
// Using loose matching
* const looseCompare = await resolver.compare('new york', 'ny', {
* threshold: 0.6
* })
*
// Retrieving the full team object that's matched
* const fullCompare = await resolver.compare('giants', 'nyg', {
* full: true,
* threshold: 0.3
* })
* console.log(fullCompare) // Returns the full New York Giants team object
* ```
*/
/**
* @param {string} team1 - First team query
* @param {string} team2 - Second team query
* @param {Options} [options] - Optional search configuration
* @returns {Promise<boolean>} True if both queries resolve to the same team, false otherwise
*/
compare(team1: string, team2: string): Promise<boolean>;
compare(team1: string, team2: string, options?: Options): Promise<boolean>;
/**
* @param {string} team1 - First team query
* @param {string} team2 - Second team query
* @param {Options & { full: true }} options - Search configuration with full=true to return team object
* @returns {Promise<Team | null>} The matched team object if teams are the same, null otherwise
*/
compare(team1: string, team2: string, options: Options & {
full: true;
}): Promise<Team | null>;
/**
* Returns an array of team names for the specified sport league.
*
* @param {keyof TeamList} sport - The sport league to get teams for ('nba' or 'nfl')
* @returns {string[]} Array of team names for the specified league
* @throws {Error} If invalid sport is provided
*
* @example
* ```ts
* const resolver = new TeamResolver()
* const nbaTeams = resolver.getTeamsByLeague('nba')
* console.log(nbaTeams) // ['Atlanta Hawks', 'Boston Celtics', ...]
* ```
*/
getTeamsByLeague(sport: SportLeague): Promise<string[]>;
/**
* Returns an array of all NBA team names.
*
* @returns {string[]} Array of all NBA team names
*
* @example
* ```ts
* const resolver = new TeamResolver()
* const nbaTeams = resolver.getNbaTeams()
* console.log(nbaTeams) // ['Atlanta Hawks', 'Boston Celtics', ...]
* ```
*/
getNbaTeams(): Promise<string[]>;
/**
* Returns an array of all NFL team names.
*
* @returns {string[]} Array of all NFL team names
*
* @example
* ```ts
* const resolver = new TeamResolver()
* const nflTeams = resolver.getNflTeams()
* console.log(nflTeams) // ['Arizona Cardinals', 'Atlanta Falcons', ...]
* ```
*/
getNflTeams(): Promise<string[]>;
/**
* Gets or initializes the Fuse instance for fuzzy searching.
* @private
*/
private getFuseInstance;
}
/**
* Provides methods for resolving and comparing sports team names using fuzzy search capabilities.
*
* There's also a set of {@link Options} that can be used to configure the search to set the sport, threshold, and retrieve the full team object.
*
* @example
* ```ts
* import { teamResolver } from 'resolve-team'
// Basic usage - returns team name
* const basic = await teamResolver.resolve('celtics')
* console.log(basic) // 'Boston Celtics'
*
// Get full team object (name, colors, nicknames, abbrev, sport)
* const full = await teamResolver.resolve('celtics', { full: true })
*
// Compare two teams
* const areSame = await teamResolver.compare('celtics', 'boston')
* console.log(areSame) // true
*
// Sport specific search
* const timberwolves = await teamResolver.resolve('minnesota', {
* sport: 'nba',
* threshold: 0.2
* })
* console.log(timberwolves) // 'Minnesota Timberwolves'
* ```
*/
declare const teamResolver: TeamResolver;
/**
* @deprecated Use the {@link TeamResolver} class instead.
* Resolves {@link Team} data based on the query and options provided.
* Returns the complete team object when the full option is true.
*
* @example
* ```ts
// Get full team details with strict matching
* const celtics = await resolveTeam('celtics', {
* full: true,
* threshold: 0.2
* })
// Returns:
// {
// name: 'Boston Celtics',
// colors: ['#007A33', '#BA9653', '#000000'],
// nicknames: ['celtics', 'boston', 'bos', 'celt'],
// abbrev: ['BOS'],
// sport: 'nba'
// }
*
// Search only in NBA with default threshold
* const celtics = await resolveTeam('boston', {
* full: true,
* sport: 'nba'
* })
* ```
*
* @param {string} query - The search term (team name, nickname, or abbreviation).
* @param {Options & { full: true }} options - Search options with full=true to return complete team data.
* @returns {Promise<Team|null>} The matched team object or null if no match is found.
*/
declare function resolveTeam(query: string, options: Options & {
full: true;
}): Promise<Team | null>;
/**
* @deprecated Use the {@link TeamResolver} class instead.
* Resolves a team name based on the query.
* Returns just the team name when no options are provided or full=false.
*
* @example
* ```ts
// Basic usage with default options
* const team = await resolveTeam('nyg')
* console.log(team) // 'New York Giants'
*
// Using strict matching (lower threshold)
* const exact = await resolveTeam('sf', {
* threshold: 0.2
* })
*
// Search in specific sport category
* const nfl = await resolveTeam('ny', {
* sport: 'nfl',
* threshold: 0.4
* })
*```
*
* @param {string} query - The search term (team name, nickname, or abbreviation).
* @param {Options} [options] - Optional search configuration.
* @returns {Promise<string|null>} The matched team name or null if no match is found.
*/
declare function resolveTeam(query: string, options?: Options): Promise<string | null>;
export { type Options, type Team, resolveTeam, teamResolver };