diff --git a/src/hiscores.ts b/src/hiscores.ts index ecee1ed..a680faf 100644 --- a/src/hiscores.ts +++ b/src/hiscores.ts @@ -30,6 +30,12 @@ import { BOSSES } from './utils'; +/** + * Screen scrapes the hiscores to get the formatted rsn of a player. + * + * @param rsn Username of the player. + * @returns Formatted version of the rsn. + */ export async function getRSNFormat(rsn: string): Promise { if (typeof rsn !== 'string') { throw Error('RSN must be a string'); @@ -56,6 +62,12 @@ export async function getRSNFormat(rsn: string): Promise { } } +/** + * Parses CSV string of raw stats and returns a stats object. + * + * @param csv Raw CSV from the official OSRS API. + * @returns Parsed stats object. + */ export function parseStats(csv: string): Stats { const splitCSV = csv .split('\n') @@ -128,6 +140,15 @@ export function parseStats(csv: string): Stats { return stats; } +/** + * Fetches stats from the OSRS API and consolidates the info into a player object. + * + * **Note:** This function will make up to 5 separate network requests. + * As such, it is highly subject to the performance of the official OSRS API. + * + * @param rsn Username of the player. + * @returns Player object. + */ export async function getStats(rsn: string): Promise { if (typeof rsn !== 'string') { throw Error('RSN must be a string'); @@ -205,6 +226,13 @@ export async function getStats(rsn: string): Promise { throw Error('Player not found'); } +/** + * Fetches stats from the OSRS API and returns them as an object. + * + * @param rsn Username of the player. + * @param mode Gamemode to fetch ranks for. + * @returns Stats object. + */ export async function getStatsByGamemode( rsn: string, mode: Gamemode = 'main' @@ -267,6 +295,14 @@ export async function getSkillPage( return players; } +/** + * Screen scrapes a hiscores page of an activity or boss and returns an array of up to 25 players. + * + * @param activity Name of the activity or boss to fetch hiscores for. + * @param mode Gamemode to fetch ranks for. + * @param page Page number. + * @returns Array of `PlayerActivityRow` objects. + */ export async function getActivityPage( activity: ActivityName, mode: Gamemode = 'main', diff --git a/src/utils/helpers.ts b/src/utils/helpers.ts index 0303b57..f96068d 100644 --- a/src/utils/helpers.ts +++ b/src/utils/helpers.ts @@ -9,14 +9,36 @@ import { ACTIVITIES } from './constants'; +/** + * Will generate a stats URL for the official OSRS API. + * + * @param gamemode Gamemode to fetch ranks for. + * @param rsn Username of the player. + * @returns Encoded stats URL. + */ export const getStatsURL = (gamemode: Gamemode, rsn: string) => `${GAMEMODE_URL[gamemode]}${STATS_URL}${encodeURIComponent(rsn)}`; +/** + * Will generate a player table URL for the official OSRS hiscores website. + * + * @param gamemode Gamemode to fetch ranks for. + * @param rsn Username of the player. + * @returns Encoded player table URL. + */ export const getPlayerTableURL = (gamemode: Gamemode, rsn: string) => `${GAMEMODE_URL[gamemode]}${SCORES_URL}table=0&user=${encodeURIComponent( rsn )}`; +/** + * Will generate a skill table URL for the official OSRS hiscores website. + * + * @param gamemode Gamemode to fetch ranks for. + * @param skill Skill to fetch ranks for. + * @param page Page number. + * @returns + */ export const getSkillPageURL = ( gamemode: Gamemode, skill: SkillName, @@ -26,6 +48,14 @@ export const getSkillPageURL = ( skill )}&page=${page}`; +/** + * Will generate an activity table URL for the official OSRS hiscores website. + * + * @param gamemode Gamemode to fetch ranks for. + * @param activity Activity or boss to fetch ranks for. + * @param page Page number. + * @returns + */ export const getActivityPageURL = ( gamemode: Gamemode, activity: ActivityName, @@ -37,17 +67,35 @@ export const getActivityPageURL = ( activity )}&page=${page}`; +/** + * Extracts a number from an OSRS hiscores table cell element. + * + * @param el OSRS hiscores table cell element. + * @returns Number parsed from cell text. + */ export const numberFromElement = (el: Element | null) => { - const { innerHTML } = el || {}; + const { innerHTML } = el ?? {}; const number = innerHTML?.replace(/[\n|,]/g, '') ?? '-1'; return parseInt(number, 10); }; +/** + * Extracts a RSN from an OSRS hiscores table cell element. + * + * @param el OSRS hiscores table cell element. + * @returns RSN parsed from cell text. + */ export const rsnFromElement = (el: Element | null) => { - const { innerHTML } = el || {}; - return innerHTML?.replace(/\uFFFD/g, ' ') || ''; + const { innerHTML } = el ?? {}; + return innerHTML?.replace(/\uFFFD/g, ' ') ?? ''; }; +/** + * Will run an Axios `GET` request against a given URL after injecting a `User-Agent` header. + * + * @param url URL to run a `GET` request against. + * @returns Axios response. + */ export const httpGet = (url: string) => axios.get(url, { headers: {