nhl-api-ts 0.0.0-stage → 0.2.0

package/dist/api/query/builder.mjs

@@ -0,0 +1,30 @@
+import { toQuery, validateFilter } from '#src/api/query/filters.mjs';
+/**
+ * Builds and validates a query string from a list of filters. Invalid
+ * filters are skipped and their errors collected; valid filters are joined
+ * with " and ".
+ */
+/** 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) {
+        const error = validateFilter(filter);
+        if (error) {
+            errors.push(error);
+            continue;
+        }
+        outputFilters.push(toQuery(filter));
+    }
+    return {
+        query: outputFilters.join(' and '),
+        filters,
+        errors,
+        factQuery,
+    };
+}
+/** True if there are no validation errors. */
+export function isValidQuery(context) {
+    return context.errors.length === 0;
+}

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

@@ -0,0 +1,93 @@
+import type { Id } from '#src/utils.mjs';
+export declare const PositionTypes: {
+    readonly ALL_FORWARDS: 'F';
+    readonly CENTER: 'C';
+    readonly LEFT_WING: 'L';
+    readonly RIGHT_WING: 'R';
+    readonly DEFENSE: 'D';
+};
+export type PositionTypes = (typeof PositionTypes)[keyof typeof PositionTypes];
+/** Goalie decision. W=win, L=loss, O=overtime loss. */
+export type Decision = 'W' | 'L' | 'O';
+export interface StatusQueryOptions {
+    /** Only current active players. */
+    isActive?: boolean;
+    /** Only Hall of Fame players. Takes precedence over `isActive`. */
+    isHallOfFame?: boolean;
+}
+export type Filter = {
+    kind: 'decision';
+    decision: Decision;
+} | {
+    kind: 'draft';
+    year: Id;
+    round?: Id;
+} | {
+    kind: 'experience';
+    isRookie: boolean;
+} | {
+    kind: 'franchise';
+    franchiseId: Id;
+} | {
+    kind: 'gameType';
+    gameType: Id;
+} | {
+    kind: 'homeRoad';
+    homeRoad: string;
+} | {
+    kind: 'nationality';
+    nationCode: string;
+} | {
+    kind: 'opponent';
+    opponentId: Id;
+} | {
+    kind: 'position';
+    position: PositionTypes;
+} | {
+    kind: 'season';
+    start: Id;
+    end: Id;
+} | {
+    kind: 'shootCatch';
+    shootCatch: string;
+} | {
+    kind: 'status';
+    isActive: boolean;
+    isHallOfFame: boolean;
+};
+export declare const filter: {
+    /** @param decision W, L, O */
+    readonly decision: (decision: Decision) => Filter;
+    /**
+     * @param year Draft year
+     * @param round Optional draft round. The API seems to default this to "1".
+     */
+    readonly draft: (year: Id, round?: Id) => Filter;
+    /** isRookie: true = rookies only, false = veterans only. */
+    readonly experience: (isRookie: boolean) => Filter;
+    readonly franchise: (franchiseId: Id) => Filter;
+    /** @param gameType 1=Preseason, 2=Regular season, 3=Playoffs */
+    readonly gameType: (gameType: Id) => Filter;
+    /** @param homeRoad H or R to indicate home or road games. */
+    readonly homeRoad: (homeRoad: string) => Filter;
+    /**
+     * Country/Nationality codes can be found via the `client.misc.countries()`
+     * endpoint, e.g. "CAN", "USA", "SWE", "FIN", "CZE", "RUS".
+     */
+    readonly nationality: (nationCode: string) => Filter;
+    /** @param opponentId The ID of the opponent franchise. */
+    readonly opponent: (opponentId: Id) => Filter;
+    readonly position: (position: PositionTypes) => Filter;
+    /** Seasons in YYYYYYYY format, e.g. 20232024. */
+    readonly season: (start: Id, end: Id) => Filter;
+    /** @param shootCatch L or R */
+    readonly shootCatch: (shootCatch: string) => Filter;
+    /**
+     * Player status. Not supplying either option matches active and inactive
+     * players.
+     */
+    readonly status: ({ isActive, isHallOfFame, }?: StatusQueryOptions) => Filter;
+};
+export declare function toQuery(filter: Filter): string;
+/** Returns an error message if the filter is invalid, otherwise undefined. */
+export declare function validateFilter(filter: Filter): string | undefined;

package/dist/api/query/filters.mjs

@@ -0,0 +1,118 @@
+export const PositionTypes = {
+    ALL_FORWARDS: 'F',
+    CENTER: 'C',
+    LEFT_WING: 'L',
+    RIGHT_WING: 'R',
+    DEFENSE: 'D',
+};
+export const filter = {
+    /** @param decision W, L, O */
+    decision: (decision) => ({ kind: 'decision', decision }),
+    /**
+     * @param year Draft year
+     * @param round Optional draft round. The API seems to default this to "1".
+     */
+    draft: (year, round) => ({ kind: 'draft', year, round }),
+    /** isRookie: true = rookies only, false = veterans only. */
+    experience: (isRookie) => ({
+        kind: 'experience',
+        isRookie,
+    }),
+    franchise: (franchiseId) => ({ kind: 'franchise', franchiseId }),
+    /** @param gameType 1=Preseason, 2=Regular season, 3=Playoffs */
+    gameType: (gameType) => ({ kind: 'gameType', gameType }),
+    /** @param homeRoad H or R to indicate home or road games. */
+    homeRoad: (homeRoad) => ({ kind: 'homeRoad', homeRoad }),
+    /**
+     * Country/Nationality codes can be found via the `client.misc.countries()`
+     * endpoint, e.g. "CAN", "USA", "SWE", "FIN", "CZE", "RUS".
+     */
+    nationality: (nationCode) => ({
+        kind: 'nationality',
+        nationCode,
+    }),
+    /** @param opponentId The ID of the opponent franchise. */
+    opponent: (opponentId) => ({ kind: 'opponent', opponentId }),
+    position: (position) => ({
+        kind: 'position',
+        position,
+    }),
+    /** Seasons in YYYYYYYY format, e.g. 20232024. */
+    season: (start, end) => ({ kind: 'season', start, end }),
+    /** @param shootCatch L or R */
+    shootCatch: (shootCatch) => ({
+        kind: 'shootCatch',
+        shootCatch,
+    }),
+    /**
+     * Player status. Not supplying either option matches active and inactive
+     * players.
+     */
+    status: ({ isActive = false, isHallOfFame = false, } = {}) => ({
+        kind: 'status',
+        isActive,
+        isHallOfFame,
+    }),
+};
+export function toQuery(filter) {
+    switch (filter.kind) {
+        case 'decision': {
+            return `decision='${filter.decision}'`;
+        }
+        case 'draft': {
+            return filter.round
+                ? `draftYear=${filter.year} and draftRound=${filter.round}`
+                : `draftYear=${filter.year}`;
+        }
+        case 'experience': {
+            return `isRookie='${filter.isRookie ? '1' : '0'}'`;
+        }
+        case 'franchise': {
+            return `franchiseId=${filter.franchiseId}`;
+        }
+        case 'gameType': {
+            return `gameTypeId=${filter.gameType}`;
+        }
+        case 'homeRoad': {
+            return `homeRoad='${filter.homeRoad}'`;
+        }
+        case 'nationality': {
+            return `nationalityCode='${filter.nationCode}'`;
+        }
+        case 'opponent': {
+            return `opponentFranchiseId=${filter.opponentId}`;
+        }
+        case 'position': {
+            // All forwards require an OR clause
+            if (filter.position === PositionTypes.ALL_FORWARDS) {
+                return (`(positionCode='${PositionTypes.LEFT_WING}' ` +
+                    `or positionCode='${PositionTypes.RIGHT_WING}' ` +
+                    `or positionCode='${PositionTypes.CENTER}')`);
+            }
+            return `positionCode='${filter.position}'`;
+        }
+        case 'season': {
+            return `seasonId >= ${filter.start} and seasonId <= ${filter.end}`;
+        }
+        case 'shootCatch': {
+            return `shootsCatches='${filter.shootCatch}'`;
+        }
+        case 'status': {
+            if (filter.isHallOfFame) {
+                return 'isInHallOfFame=1';
+            }
+            if (filter.isActive) {
+                return 'active=1';
+            }
+            return '';
+        }
+    }
+}
+/** Returns an error message if the filter is invalid, otherwise undefined. */
+export function validateFilter(filter) {
+    if (filter.kind === 'decision' &&
+        !['W', 'L', 'O'].includes(filter.decision)) {
+        return 'Decision value must be one of [W, L, O]';
+    }
+    return undefined;
+}

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

@@ -0,0 +1,4 @@
+export { buildQuery, isValidQuery, type QueryContext, } from '#src/api/query/builder.mjs';
+export * from '#src/api/query/filters.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

@@ -0,0 +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 { defaultSortForReport, SKATER_REPORT_TYPES, } from '#src/api/query/sorting/sorting-options.mjs';

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

@@ -0,0 +1,61 @@
+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.
+ */
+export declare function goalieStatsSorts(report: string): SortExpr[];

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

@@ -0,0 +1,54 @@
+const goalieSummaryDefaultSorting = [
+    { property: 'wins', direction: 'DESC' },
+    { 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) {
+    return ((Object.hasOwn(sortingLookup, report)
+        ? sortingLookup[report]
+        : undefined) ?? goalieSummaryDefaultSorting);
+}

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

@@ -0,0 +1,136 @@
+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[];
+/**
+ * Default sort criteria for a skater stats report. Falls back to the skater
+ * summary sort for unknown report types.
+ */
+export declare function defaultSortForReport(report: string): SortExpr[];
+export {};

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

@@ -0,0 +1,94 @@
+const skaterSummaryDefaultSorting = [
+    { property: 'points', direction: 'DESC' },
+    { property: 'gamesPlayed', direction: 'ASC' },
+    { property: 'playerId', direction: 'ASC' },
+];
+const defaultSortingByReport = {
+    summary: skaterSummaryDefaultSorting,
+    bios: [
+        { property: 'lastName', direction: 'ASC_CI' },
+        { property: 'skaterFullName', direction: 'ASC_CI' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    faceoffpercentages: [
+        { property: 'totalFaceoffs', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    faceoffwins: [
+        { property: 'totalFaceoffWins', direction: 'DESC' },
+        { property: 'faceoffWinPct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    goalsForAgainst: [
+        { property: 'evenStrengthGoalDifference', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    realtime: [
+        { property: 'hits', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    penalties: [
+        { property: 'penaltyMinutes', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    penaltykill: [
+        { property: 'shTimeOnIce', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    penaltyShots: [
+        { property: 'penaltyShotsGoals', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    powerplay: [
+        { property: 'ppTimeOnIce', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    puckPossessions: [
+        { property: 'satPct', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    summaryshooting: [
+        { property: 'satTotal', direction: 'DESC' },
+        { property: 'usatTotal', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    percentages: [
+        { property: 'satPercentage', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    scoringRates: [
+        { property: 'pointsPer605v5', direction: 'DESC' },
+        { property: 'goalsPer605v5', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    scoringpergame: [
+        { property: 'pointsPerGame', direction: 'DESC' },
+        { property: 'goalsPerGame', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    shootout: [
+        { property: 'shootoutGoals', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    shottype: [
+        { property: 'shootingPct', direction: 'DESC' },
+        { property: 'shootingPctBat', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+    timeonice: [
+        { property: 'timeOnIce', direction: 'DESC' },
+        { property: 'playerId', direction: 'ASC' },
+    ],
+};
+const sortingLookup = defaultSortingByReport;
+/** Skater report types that have a default sort configured. */
+export const SKATER_REPORT_TYPES = Object.keys(defaultSortingByReport);
+/**
+ * Default sort criteria for a skater stats report. Falls back to the skater
+ * summary sort for unknown report types.
+ */
+export function defaultSortForReport(report) {
+    return ((Object.hasOwn(sortingLookup, report)
+        ? sortingLookup[report]
+        : undefined) ?? skaterSummaryDefaultSorting);
+}