nhl-api-ts 0.1.0 → 0.2.1

package/dist/api/helpers.d.mts

@@ -1,5 +1,6 @@
 import type { Context } from '#src/context.mjs';
-import type { Id, JsonObject } from '#src/utils.mjs';
+import type { AllPlayersEntry, PlayerSummaryStatistics } from '#src/types/index.mjs';
+import type { Id } from '#src/utils.mjs';
 /**
  * Gets all game IDs for a specified season by querying every team's
  * schedule. Games appear once per participating team, so ids may repeat.
@@ -9,11 +10,11 @@ import type { Id, JsonObject } from '#src/utils.mjs';
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.gameIdsBySeason({ season: '20232024', gameTypes: [2] })
  */
-export declare const gameIdsBySeason: (ctx: Context, { season, gameTypes, apiSleepRate, }: {
+export declare function gameIdsBySeason(ctx: Context, { season, gameTypes, apiSleepRate, }: {
     season: Id;
     gameTypes?: number[];
     apiSleepRate?: number;
-}) => Promise<number[]>;
+}): Promise<number[]>;
 /**
  * Gets every rostered player across all NHL teams for a given season. Each
  * player gets a `team` abbreviation and flattened `firstName` / `lastName`.
@@ -22,10 +23,10 @@ export declare const gameIdsBySeason: (ctx: Context, { season, gameTypes, apiSle
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 0.5.
  * @example await client.helpers.allPlayers({ season: '20232024' })
  */
-export declare const allPlayers: (ctx: Context, { season, apiSleepRate }: {
+export declare function allPlayers(ctx: Context, { season, apiSleepRate }: {
     season: Id;
     apiSleepRate?: number;
-}) => Promise<JsonObject[]>;
+}): Promise<AllPlayersEntry[]>;
 /**
  * Gets summary statistics for every skater in a given season, merged with
  * the roster info from `allPlayers` (stat fields win on key collisions).
@@ -35,10 +36,10 @@ export declare const allPlayers: (ctx: Context, { season, apiSleepRate }: {
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.allPlayersSummaryStatistics({ season: '20232024' })
  */
-export declare const allPlayersSummaryStatistics: (ctx: Context, { season, apiSleepRate }: {
+export declare function allPlayersSummaryStatistics(ctx: Context, { season, apiSleepRate }: {
     season: Id;
     apiSleepRate?: number;
-}) => Promise<JsonObject[]>;
+}): Promise<PlayerSummaryStatistics[]>;
 export declare const helpersApi: {
     readonly gameIdsBySeason: typeof gameIdsBySeason;
     readonly allPlayers: typeof allPlayers;

package/dist/api/helpers.mjs

@@ -12,7 +12,7 @@ import { teams as fetchTeams, teamRoster } from '#src/api/teams.mjs';
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.gameIdsBySeason({ season: '20232024', gameTypes: [2] })
  */
-export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1, }) => {
+export async function gameIdsBySeason(ctx, { season, gameTypes, apiSleepRate = 1, }) {
     const teams = await fetchTeams(ctx);
     const gameIds = [];
     for (const team of teams) {
@@ -33,7 +33,7 @@ export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1
         }
     }
     return gameIds;
-};
+}
 /**
  * Gets every rostered player across all NHL teams for a given season. Each
  * player gets a `team` abbreviation and flattened `firstName` / `lastName`.
@@ -42,7 +42,7 @@ export const gameIdsBySeason = async (ctx, { season, gameTypes, apiSleepRate = 1
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 0.5.
  * @example await client.helpers.allPlayers({ season: '20232024' })
  */
-export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
+export async function allPlayers(ctx, { season, apiSleepRate = 0.5 }) {
     const teams = await fetchTeams(ctx);
     console.error('Fetching all player base stats. This may take a while...');
     const outData = [];
@@ -63,7 +63,7 @@ export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
         }
     }
     return outData;
-};
+}
 /**
  * Gets summary statistics for every skater in a given season, merged with
  * the roster info from `allPlayers` (stat fields win on key collisions).
@@ -73,7 +73,7 @@ export const allPlayers = async (ctx, { season, apiSleepRate = 0.5 }) => {
  * @param params.apiSleepRate Seconds to sleep between team requests. Defaults to 1.
  * @example await client.helpers.allPlayersSummaryStatistics({ season: '20232024' })
  */
-export const allPlayersSummaryStatistics = async (ctx, { season, apiSleepRate = 1 }) => {
+export async function allPlayersSummaryStatistics(ctx, { season, apiSleepRate = 1 }) {
     console.error('WARNING: This method will take a while to run.  In the event of rate limiting, you may need to increase the api_sleep_rate.');
     const players = await allPlayers(ctx, { season, apiSleepRate });
     const teams = await fetchTeams(ctx);
@@ -98,7 +98,7 @@ export const allPlayersSummaryStatistics = async (ctx, { season, apiSleepRate =
             : undefined;
         return player ? { ...player, ...statEntry } : statEntry;
     });
-};
+}
 export const helpersApi = {
     gameIdsBySeason,
     allPlayers,

package/dist/api/misc.d.mts

@@ -1,36 +1,36 @@
 import type { Context } from '#src/context.mjs';
-import type { JsonObject } from '#src/utils.mjs';
+import type { Country, DraftYear, GlossaryEntry, SeasonRules, StatsConfig } from '#src/types/index.mjs';
 /**
  * Gets the full NHL glossary of statistical terms and abbreviations.
  *
  * @example https://api.nhle.com/stats/rest/en/glossary?sort=fullName
  */
-export declare const glossary: (ctx: Context) => Promise<JsonObject[]>;
+export declare function glossary(ctx: Context): Promise<GlossaryEntry[]>;
 /**
  * Gets the stats API configuration, including available report types and
  * filters.
  *
  * @example https://api.nhle.com/stats/rest/en/config
  */
-export declare const config: (ctx: Context) => Promise<JsonObject>;
+export declare function config(ctx: Context): Promise<StatsConfig>;
 /**
  * Gets the list of countries recognized by the NHL.
  *
  * @example https://api.nhle.com/stats/rest/en/country
  */
-export declare const countries: (ctx: Context) => Promise<JsonObject[]>;
+export declare function countries(ctx: Context): Promise<Country[]>;
 /**
  * Gets rules and metadata for every NHL season on record.
  *
  * @example https://api.nhle.com/stats/rest/en/season
  */
-export declare const seasonSpecificRulesAndInfo: (ctx: Context) => Promise<JsonObject[]>;
+export declare function seasonSpecificRulesAndInfo(ctx: Context): Promise<SeasonRules[]>;
 /**
  * Gets the number of rounds for each NHL draft year.
  *
  * @example https://api.nhle.com/stats/rest/en/draft
  */
-export declare const draftYearAndRounds: (ctx: Context) => Promise<JsonObject[]>;
+export declare function draftYearAndRounds(ctx: Context): Promise<DraftYear[]>;
 export declare const miscApi: {
     readonly glossary: typeof glossary;
     readonly config: typeof config;

package/dist/api/misc.mjs

@@ -8,32 +8,42 @@ async function getData(ctx, resource) {
  *
  * @example https://api.nhle.com/stats/rest/en/glossary?sort=fullName
  */
-export const glossary = async (ctx) => getData(ctx, 'stats/rest/en/glossary?sort=fullName');
+export async function glossary(ctx) {
+    return getData(ctx, 'stats/rest/en/glossary?sort=fullName');
+}
 /**
  * Gets the stats API configuration, including available report types and
  * filters.
  *
  * @example https://api.nhle.com/stats/rest/en/config
  */
-export const config = async (ctx) => (await ctx.get(Endpoint.API_CORE, 'stats/rest/en/config')).json();
+export async function config(ctx) {
+    return (await ctx.get(Endpoint.API_CORE, 'stats/rest/en/config')).json();
+}
 /**
  * Gets the list of countries recognized by the NHL.
  *
  * @example https://api.nhle.com/stats/rest/en/country
  */
-export const countries = async (ctx) => getData(ctx, 'stats/rest/en/country');
+export async function countries(ctx) {
+    return getData(ctx, 'stats/rest/en/country');
+}
 /**
  * Gets rules and metadata for every NHL season on record.
  *
  * @example https://api.nhle.com/stats/rest/en/season
  */
-export const seasonSpecificRulesAndInfo = async (ctx) => getData(ctx, 'stats/rest/en/season');
+export async function seasonSpecificRulesAndInfo(ctx) {
+    return getData(ctx, 'stats/rest/en/season');
+}
 /**
  * Gets the number of rounds for each NHL draft year.
  *
  * @example https://api.nhle.com/stats/rest/en/draft
  */
-export const draftYearAndRounds = async (ctx) => getData(ctx, 'stats/rest/en/draft');
+export async function draftYearAndRounds(ctx) {
+    return getData(ctx, 'stats/rest/en/draft');
+}
 export const miscApi = {
     glossary,
     config,

package/dist/api/players.d.mts

@@ -1,14 +1,15 @@
 import type { Context } from '#src/context.mjs';
-import type { Id, JsonObject } from '#src/utils.mjs';
+import type { Prospects, Roster } from '#src/types/index.mjs';
+import type { Id } from '#src/utils.mjs';
 /**
  * Gets prospects for a specific team, grouped by position.
  *
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
  * @example https://api-web.nhle.com/v1/prospects/BUF
  */
-export declare const prospectsByTeam: (ctx: Context, { teamAbbr }: {
+export declare function prospectsByTeam(ctx: Context, { teamAbbr }: {
     teamAbbr: string;
-}) => Promise<JsonObject>;
+}): Promise<Prospects>;
 /**
  * Gets the roster for a given team and season, grouped by position
  * (forwards, defensemen, goalies). Same data as `teams.teamRoster`.
@@ -17,10 +18,10 @@ export declare const prospectsByTeam: (ctx: Context, { teamAbbr }: {
  * @param params.season Season in YYYYYYYY format, e.g. 20232024
  * @example https://api-web.nhle.com/v1/roster/BUF/20232024
  */
-export declare const playersByTeam: (ctx: Context, { teamAbbr, season }: {
+export declare function playersByTeam(ctx: Context, { teamAbbr, season }: {
     teamAbbr: string;
     season: Id;
-}) => Promise<JsonObject>;
+}): Promise<Roster>;
 export declare const playersApi: {
     readonly prospectsByTeam: typeof prospectsByTeam;
     readonly playersByTeam: typeof playersByTeam;

package/dist/api/players.mjs

@@ -5,7 +5,9 @@ import { Endpoint } from '#src/http-client.mjs';
  * @param params.teamAbbr Team abbreviation, e.g. BUF, TOR
  * @example https://api-web.nhle.com/v1/prospects/BUF
  */
-export const prospectsByTeam = async (ctx, { teamAbbr }) => (await ctx.get(Endpoint.API_WEB_V1, `prospects/${teamAbbr}`)).json();
+export async function prospectsByTeam(ctx, { teamAbbr }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `prospects/${teamAbbr}`)).json();
+}
 /**
  * Gets the roster for a given team and season, grouped by position
  * (forwards, defensemen, goalies). Same data as `teams.teamRoster`.
@@ -14,5 +16,7 @@ export const prospectsByTeam = async (ctx, { teamAbbr }) => (await ctx.get(Endpo
  * @param params.season Season in YYYYYYYY format, e.g. 20232024
  * @example https://api-web.nhle.com/v1/roster/BUF/20232024
  */
-export const playersByTeam = async (ctx, { teamAbbr, season }) => (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season}`)).json();
+export async function playersByTeam(ctx, { teamAbbr, season }) {
+    return (await ctx.get(Endpoint.API_WEB_V1, `roster/${teamAbbr}/${season}`)).json();
+}
 export const playersApi = { prospectsByTeam, playersByTeam };

package/dist/api/query/builder.d.mts

@@ -15,6 +15,8 @@ export interface QueryContext {
  * filters are skipped and their errors collected; valid filters are joined
  * with " and ".
  */
+/** Fact filter `buildQuery` applies unless told otherwise. */
+export declare const DEFAULT_FACT_QUERY = "gamesPlayed>=1";
 export declare function buildQuery(filters: readonly Filter[], factQuery?: string): QueryContext;
 /** True if there are no validation errors. */
 export declare function isValidQuery(context: QueryContext): boolean;

package/dist/api/query/builder.mjs

@@ -4,7 +4,9 @@ import { toQuery, validateFilter } from '#src/api/query/filters.mjs';
  * filters are skipped and their errors collected; valid filters are joined
  * with " and ".
  */
-export function buildQuery(filters, factQuery = 'gamesPlayed>=1') {
+/** Fact filter `buildQuery` applies unless told otherwise. */
+export const DEFAULT_FACT_QUERY = 'gamesPlayed>=1';
+export function buildQuery(filters, factQuery = DEFAULT_FACT_QUERY) {
     const outputFilters = [];
     const errors = [];
     for (const filter of filters) {

package/dist/api/query/index.d.mts

@@ -1,4 +1,4 @@
 export { buildQuery, isValidQuery, type QueryContext, } from '#src/api/query/builder.mjs';
 export * from '#src/api/query/filters.mjs';
-export { goalieStatsSorts } from '#src/api/query/sorting/goalie-sorts.mjs';
-export { defaultSortForReport, SKATER_REPORT_TYPES, type SortExpr, } from '#src/api/query/sorting/sorting-options.mjs';
+export { type GoalieReportType, goalieStatsSorts, } from '#src/api/query/sorting/goalie-sorts.mjs';
+export { defaultSortForReport, SKATER_REPORT_TYPES, type SkaterReportType, type SortExpr, } from '#src/api/query/sorting/sorting-options.mjs';

package/dist/api/query/index.mjs

@@ -1,4 +1,4 @@
 export { buildQuery, isValidQuery, } from '#src/api/query/builder.mjs';
 export * from '#src/api/query/filters.mjs';
-export { goalieStatsSorts } from '#src/api/query/sorting/goalie-sorts.mjs';
+export { goalieStatsSorts, } from '#src/api/query/sorting/goalie-sorts.mjs';
 export { defaultSortForReport, SKATER_REPORT_TYPES, } from '#src/api/query/sorting/sorting-options.mjs';

package/dist/api/query/sorting/goalie-sorts.d.mts

@@ -1,4 +1,59 @@
 import type { SortExpr } from '#src/api/query/sorting/sorting-options.mjs';
+/** Default sort criteria per goalie report type. */
+export declare const goalieSortingByReport: {
+    summary: SortExpr[];
+    advanced: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    bios: ({
+        property: string;
+        direction: "ASC_CI";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    daysrest: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    penaltyShots: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    savesByStrength: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    shootout: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    startedVsRelieved: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+};
+/** Goalie report types that have a default sort configured. */
+export type GoalieReportType = keyof typeof goalieSortingByReport;
 /**
  * Default sorting criteria for goalie stats reports. Falls back to the
  * goalie summary sort for unknown report types.

package/dist/api/query/sorting/goalie-sorts.mjs

@@ -3,57 +3,52 @@ const goalieSummaryDefaultSorting = [
     { property: 'gamesPlayed', direction: 'ASC' },
     { property: 'playerId', direction: 'ASC' },
 ];
+/** Default sort criteria per goalie report type. */
+export const goalieSortingByReport = {
+    summary: goalieSummaryDefaultSorting,
+    advanced: [
+        { property: 'qualityStart', direction: 'DESC' },
+        { property: 'goalsAgainstAverage', direction: 'ASC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    bios: [
+        { property: 'lastName', direction: 'ASC_CI' },
+        { property: 'goalieFullName', direction: 'ASC_CI' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    daysrest: [
+        { property: 'wins', direction: 'DESC' },
+        { property: 'savePct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    penaltyShots: [
+        { property: 'penaltyShotsSaves', direction: 'DESC' },
+        { property: 'penaltyShotSavePct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    savesByStrength: [
+        { property: 'wins', direction: 'DESC' },
+        { property: 'savePct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    shootout: [
+        { property: 'shootoutWins', direction: 'DESC' },
+        { property: 'shootoutSavePct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    startedVsRelieved: [
+        { property: 'gamesStarted', direction: 'DESC' },
+        { property: 'gamesStartedSavePct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+};
+const sortingLookup = goalieSortingByReport;
 /**
  * Default sorting criteria for goalie stats reports. Falls back to the
  * goalie summary sort for unknown report types.
  */
 export function goalieStatsSorts(report) {
-    switch (report) {
-        case 'summary':
-            return goalieSummaryDefaultSorting;
-        case 'advanced':
-            return [
-                { property: 'qualityStart', direction: 'DESC' },
-                { property: 'goalsAgainstAverage', direction: 'ASC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'bios':
-            return [
-                { property: 'lastName', direction: 'ASC_CI' },
-                { property: 'goalieFullName', direction: 'ASC_CI' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'daysrest':
-            return [
-                { property: 'wins', direction: 'DESC' },
-                { property: 'savePct', direction: 'DESC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'penaltyShots':
-            return [
-                { property: 'penaltyShotsSaves', direction: 'DESC' },
-                { property: 'penaltyShotSavePct', direction: 'DESC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'savesByStrength':
-            return [
-                { property: 'wins', direction: 'DESC' },
-                { property: 'savePct', direction: 'DESC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'shootout':
-            return [
-                { property: 'shootoutWins', direction: 'DESC' },
-                { property: 'shootoutSavePct', direction: 'DESC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        case 'startedVsRelieved':
-            return [
-                { property: 'gamesStarted', direction: 'DESC' },
-                { property: 'gamesStartedSavePct', direction: 'DESC' },
-                { property: 'playerId', direction: 'ASC' },
-            ];
-        default:
-            return goalieSummaryDefaultSorting;
-    }
+    return ((Object.hasOwn(sortingLookup, report)
+        ? sortingLookup[report]
+        : undefined) ?? goalieSummaryDefaultSorting);
 }

package/dist/api/query/sorting/sorting-options.d.mts

@@ -2,6 +2,130 @@ export interface SortExpr {
     property: string;
     direction: 'ASC' | 'DESC' | 'ASC_CI' | 'DESC_CI' | (string & {});
 }
+declare const defaultSortingByReport: {
+    summary: SortExpr[];
+    bios: ({
+        property: string;
+        direction: "ASC_CI";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    faceoffpercentages: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    faceoffwins: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    goalsForAgainst: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    realtime: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    penalties: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    penaltykill: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    penaltyShots: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    powerplay: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    puckPossessions: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    summaryshooting: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    percentages: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    scoringRates: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    scoringpergame: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    shootout: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    shottype: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+    timeonice: ({
+        property: string;
+        direction: "DESC";
+    } | {
+        property: string;
+        direction: "ASC";
+    })[];
+};
+/** Skater report types that have a default sort configured. */
+export type SkaterReportType = keyof typeof defaultSortingByReport;
 /** Skater report types that have a default sort configured. */
 export declare const SKATER_REPORT_TYPES: string[];
 /**
@@ -9,3 +133,4 @@ export declare const SKATER_REPORT_TYPES: string[];
  * summary sort for unknown report types.
  */
 export declare function defaultSortForReport(report: string): SortExpr[];
+export {};

package/dist/api/query/sorting/sorting-options.mjs

@@ -80,6 +80,7 @@ const defaultSortingByReport = {
         { property: 'playerId', direction: 'ASC' },
     ],
 };
+const sortingLookup = defaultSortingByReport;
 /** Skater report types that have a default sort configured. */
 export const SKATER_REPORT_TYPES = Object.keys(defaultSortingByReport);
 /**
@@ -87,7 +88,7 @@ export const SKATER_REPORT_TYPES = Object.keys(defaultSortingByReport);
  * summary sort for unknown report types.
  */
 export function defaultSortForReport(report) {
-    return ((Object.hasOwn(defaultSortingByReport, report)
-        ? defaultSortingByReport[report]
+    return ((Object.hasOwn(sortingLookup, report)
+        ? sortingLookup[report]
         : undefined) ?? skaterSummaryDefaultSorting);
 }