@zmnatz/usa-club-rugby-data 0.1.0 → 0.2.0

package/README.md

@@ -82,4 +82,4 @@ bun run test      # in this package
 bun run build     # dist/, ESM with declarations
 ```
 
-Releases are published from GitHub releases by `.github/workflows/publish.yml`, using npm trusted publishing (no stored token).
+Releases are published from GitHub releases by `.github/workflows/publish.yml`, using npm trusted publishing (no stored token). The workflow stages the version; approve it with 2FA on npmjs.com to release it.

package/dist/data.d.ts

@@ -17,6 +17,16 @@ export interface PublishedClubFile extends ParticipationSnapshot {
     /** When the data last changed; always present in a published file. */
     generatedAt: string;
 }
+/** Which clubs each player is in the record of, by CMS id, for finding a player from
+ *  their id. Not published: worked out from the club files by `buildPlayerIndex`, which
+ *  leaves out players whose profile isn't public. */
+export interface PublishedPlayersFile {
+    season: string;
+    players: Record<string, {
+        name: string;
+        clubs: string[];
+    }>;
+}
 /** `archive/fixtures/<season>.json`: every senior club fixture that season by id. */
 export interface ArchiveFixturesFile {
     season: string;

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export * from './api.ts';
 export * from './archive.ts';
 export * from './csv.ts';
-export type { ArchiveFixturesFile, ArchiveMatchesFile, PublishedClubFile, PublishedFixturesFile, PublishedIndexFile, } from './data.ts';
+export type { ArchiveFixturesFile, ArchiveMatchesFile, PublishedClubFile, PublishedFixturesFile, PublishedIndexFile, PublishedPlayersFile, } from './data.ts';
 export * from './eligibility.ts';
 export * from './feeds.ts';
 export * from './live.ts';
 export type * from './match.ts';
 export * from './participation.ts';
+export * from './players.ts';
 export * from './playerHistory.ts';
 export * from './published.ts';
 export * from './rugbyXplorer.ts';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './eligibility.js';
 export * from './feeds.js';
 export * from './live.js';
 export * from './participation.js';
+export * from './players.js';
 export * from './playerHistory.js';
 export * from './published.js';
 export * from './rugbyXplorer.js';

package/dist/players.d.ts

@@ -0,0 +1,74 @@
+import type { PublishedPlayersFile } from './data.ts';
+import type { FeedFixture } from './feeds.ts';
+import { type ParticipationSnapshot, type PlayerRound, type PossibleFixture } from './participation.ts';
+import type { PublishedClub } from './published.ts';
+import type { Club, EligibilityBreakdown, EligibilityRules, PlayerEligibility } from './types.ts';
+export interface PlayerOptions {
+    rules?: EligibilityRules;
+    /** The time possible remaining matches are counted from. Defaults to now. */
+    now?: Date;
+}
+/** One club's published file, with what's worked out from it. */
+export interface ClubContext {
+    club: PublishedClub;
+    snapshot: ParticipationSnapshot;
+    /** The fixtures in the club's divisions. */
+    fixtures: FeedFixture[];
+    breakdown: EligibilityBreakdown;
+}
+/** What a player's fixtures are worked out from: a club, its published file and its fixtures. */
+export interface PlayerRecordInput {
+    club: Pick<Club, 'sides'>;
+    snapshot: ParticipationSnapshot;
+    fixtures: FeedFixture[];
+}
+/** A club's verdicts and the fixtures they're counted from. */
+export declare function clubContext(club: PublishedClub, snapshot: ParticipationSnapshot, allFixtures: FeedFixture[], { rules, now }?: PlayerOptions): ClubContext;
+/** One side's fixtures for one player. */
+export interface SideRounds {
+    teamName: string;
+    rounds: PlayerRound[];
+}
+/** The fixtures behind a verdict. */
+export interface PlayerFixtures {
+    /** A round table per side of the club, the player's own side first. */
+    sides: SideRounds[];
+    /** Why an on-track player is on track; empty for anyone else. */
+    possible: PossibleFixture[];
+}
+/** Each side's rounds for the player, own side first; every side feeds the verdict. */
+export declare function sideRounds(player: PlayerEligibility, club: Pick<Club, 'sides'>, snapshot: ParticipationSnapshot, fixtures: FeedFixture[], rules?: EligibilityRules): SideRounds[];
+/** The fixtures a verdict counted as possible, on the player's side and the sides
+ *  below it, or every side for the top one. */
+export declare function possibleFor(player: PlayerEligibility, club: Pick<Club, 'sides'>, fixtures: FeedFixture[], { rules, now }?: PlayerOptions): PossibleFixture[];
+/** The fixtures behind one player's verdict in a club. */
+export declare function playerFixtures(player: PlayerEligibility, { club, snapshot, fixtures }: PlayerRecordInput, options?: PlayerOptions): PlayerFixtures;
+/** A player's verdict on one side of one club, with the fixtures behind it. */
+export interface PlayerClubEntry {
+    clubKey: string;
+    clubName: string;
+    /** The side this verdict is for, e.g. "D1". */
+    sideLabel: string;
+    /** Another player in this side shares the name, so show the id to tell them apart. */
+    showCmsId: boolean;
+    /** Without its raw rows, which only the fixtures were worked out from. */
+    player: PlayerEligibility;
+    fixtures: PlayerFixtures;
+}
+/** A player and their verdict on every club side they're listed on. */
+export interface PlayerProfile {
+    /** The player's CMS id. */
+    id: string;
+    name: string;
+    clubs: PlayerClubEntry[];
+}
+/** A player's verdicts in one club: one per side they're listed on. */
+export declare function playerEntries(playerId: string, context: ClubContext, options?: PlayerOptions): PlayerClubEntry[];
+/** Clubs and sides in the order a profile lists them. */
+export declare function sortEntries(entries: PlayerClubEntry[]): PlayerClubEntry[];
+/** Which clubs each player is in the record of, for finding a player from their id.
+ *  A player whose profile isn't public ("Name Withheld") is left out. */
+export declare function buildPlayerIndex(season: string, clubs: {
+    club: Pick<PublishedClub, 'key'>;
+    breakdown: EligibilityBreakdown;
+}[]): PublishedPlayersFile;

package/dist/players.js

@@ -0,0 +1,92 @@
+import { computeBreakdown } from './eligibility.js';
+import { clubFixtures, participationRows, playerRounds, possibleFixtures, remainingMatches, } from './participation.js';
+import { isNameWithheld } from './playerHistory.js';
+import { DEFAULT_RULES } from './rules.js';
+import { hasSharedName, sharedNames } from './eligibility.js';
+/** A club's verdicts and the fixtures they're counted from. */
+export function clubContext(club, snapshot, allFixtures, { rules = DEFAULT_RULES, now = new Date() } = {}) {
+    const fixtures = clubFixtures(allFixtures, club);
+    const remaining = remainingMatches(fixtures, club, rules, now);
+    return {
+        club,
+        snapshot,
+        fixtures,
+        breakdown: computeBreakdown(participationRows(snapshot, club, rules), club.sides, rules, remaining),
+    };
+}
+/** Each side's rounds for the player, own side first; every side feeds the verdict. */
+export function sideRounds(player, club, snapshot, fixtures, rules = DEFAULT_RULES) {
+    const sides = club.sides.map((side) => side.teamName);
+    return [player.teamName, ...sides.filter((side) => side !== player.teamName)].map((teamName) => ({
+        teamName,
+        rounds: playerRounds({
+            fixtures,
+            teamName,
+            season: snapshot.season,
+            rows: player.rows,
+            gaps: snapshot.gaps,
+            resultIds: snapshot.resultIds ?? [],
+            rules,
+        }),
+    }));
+}
+/** The fixtures a verdict counted as possible, on the player's side and the sides
+ *  below it, or every side for the top one. */
+export function possibleFor(player, club, fixtures, { rules = DEFAULT_RULES, now = new Date() } = {}) {
+    const lists = possibleFixtures(fixtures, club, rules, now);
+    const index = club.sides.findIndex((side) => side.teamName === player.teamName);
+    return club.sides
+        .slice(Math.max(index, 0))
+        .flatMap((side) => lists[side.teamName] ?? [])
+        .sort((a, b) => new Date(a.dateTime).getTime() - new Date(b.dateTime).getTime());
+}
+/** The fixtures behind one player's verdict in a club. */
+export function playerFixtures(player, { club, snapshot, fixtures }, options = {}) {
+    const { rules = DEFAULT_RULES } = options;
+    return {
+        sides: sideRounds(player, club, snapshot, fixtures, rules),
+        possible: player.pending.length > 0 ? possibleFor(player, club, fixtures, options) : [],
+    };
+}
+/** A player's verdicts in one club: one per side they're listed on. */
+export function playerEntries(playerId, context, options = {}) {
+    const { club, breakdown } = context;
+    return breakdown.sides.flatMap((side) => {
+        const player = side.players.find((candidate) => candidate.playerId === playerId);
+        if (!player)
+            return [];
+        return [
+            {
+                clubKey: club.key,
+                clubName: club.name,
+                sideLabel: side.label,
+                showCmsId: hasSharedName(player, sharedNames(side.players)),
+                player: { ...player, rows: [] },
+                fixtures: playerFixtures(player, context, options),
+            },
+        ];
+    });
+}
+/** Clubs and sides in the order a profile lists them. */
+export function sortEntries(entries) {
+    return [...entries].sort((a, b) => a.clubName.localeCompare(b.clubName) || a.sideLabel.localeCompare(b.sideLabel));
+}
+/** Which clubs each player is in the record of, for finding a player from their id.
+ *  A player whose profile isn't public ("Name Withheld") is left out. */
+export function buildPlayerIndex(season, clubs) {
+    const found = new Map();
+    for (const { club, breakdown } of clubs) {
+        for (const side of breakdown.sides) {
+            for (const player of side.players) {
+                if (isNameWithheld(player.name))
+                    continue;
+                const entry = found.get(player.playerId) ?? { name: player.name, clubs: [] };
+                if (!entry.clubs.includes(club.key))
+                    entry.clubs.push(club.key);
+                found.set(player.playerId, entry);
+            }
+        }
+    }
+    const players = Object.fromEntries([...found].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    return { season, players };
+}

package/dist/published.d.ts

@@ -1,6 +1,8 @@
+import type { PublishedPlayersFile } from './data.ts';
 import type { Club, EligibilityBreakdown, EligibilityRules, PlayerEligibility } from './types.ts';
 import type { FeedFixture } from './feeds.ts';
 import { type ParticipationSnapshot } from './participation.ts';
+import { type PlayerProfile } from './players.ts';
 import { type TeamSide } from './teamSide.ts';
 /** Where the reference deployment publishes its nightly data. */
 export declare const DEFAULT_PUBLISHED_URL = "https://zmnatz.github.io/usa-club-rugby-eligibility/data";
@@ -59,6 +61,14 @@ export declare function createPublishedClient({ baseUrl, fetch: fetcher, }?: Pub
     teams(): Promise<TeamRecord[]>;
     /** A club's verdicts side by side. */
     eligibility(key: string, options?: EligibilityOptions): Promise<EligibilityBreakdown>;
+    /** Which clubs each player is in the record of, by CMS id. Not a published file: worked
+     *  out from every club's file, so it reads them all. */
+    playerIndex(options?: EligibilityOptions): Promise<PublishedPlayersFile>;
+    /** A player from their CMS id: their verdict on every club side they're listed on, with
+     *  the fixtures behind each. Null when the id isn't in the published record (players
+     *  whose profile isn't public aren't). Reads every club to find them, so for many lookups
+     *  build the index once with `playerIndex`. */
+    player(id: string, options?: EligibilityOptions): Promise<PlayerProfile | null>;
     /** Every player with a verdict on each of a club's sides, one record per side. */
     players(key: string, options?: EligibilityOptions): Promise<PlayerRecord[]>;
 };

package/dist/published.js

@@ -1,5 +1,6 @@
 import { computeBreakdown } from './eligibility.js';
 import { clubFixtures, participationRows, remainingMatches } from './participation.js';
+import { buildPlayerIndex, clubContext, playerEntries, sortEntries } from './players.js';
 import { DEFAULT_RULES } from './rules.js';
 import { parseTeamSide } from './teamSide.js';
 // Readers for the data the nightly job publishes: public/data/index.json,
@@ -58,6 +59,32 @@ export function createPublishedClient({ baseUrl = DEFAULT_PUBLISHED_URL, fetch:
             const [{ club: found, snapshot }, all] = await Promise.all([club(key), fixtures()]);
             return clubEligibility(snapshot, all, found, options);
         },
+        /** Which clubs each player is in the record of, by CMS id. Not a published file: worked
+         *  out from every club's file, so it reads them all. */
+        async playerIndex(options = {}) {
+            const [{ clubs, season }, all] = await Promise.all([index(), fixtures()]);
+            const contexts = await Promise.all(clubs.map(async (published) => {
+                const { snapshot } = await club(published.key);
+                return { club: published, breakdown: clubContext(published, snapshot, all, options).breakdown };
+            }));
+            return buildPlayerIndex(season, contexts);
+        },
+        /** A player from their CMS id: their verdict on every club side they're listed on, with
+         *  the fixtures behind each. Null when the id isn't in the published record (players
+         *  whose profile isn't public aren't). Reads every club to find them, so for many lookups
+         *  build the index once with `playerIndex`. */
+        async player(id, options = {}) {
+            const found = (await this.playerIndex(options)).players[id];
+            if (!found)
+                return null;
+            const all = await fixtures();
+            const entries = [];
+            for (const key of found.clubs) {
+                const { club: published, snapshot } = await club(key);
+                entries.push(...playerEntries(id, clubContext(published, snapshot, all, options), options));
+            }
+            return { id, name: found.name, clubs: sortEntries(entries) };
+        },
         /** Every player with a verdict on each of a club's sides, one record per side. */
         async players(key, options = {}) {
             const [{ club: found, snapshot }, all] = await Promise.all([club(key), fixtures()]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmnatz/usa-club-rugby-data",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "USA Club Rugby senior club teams, players and NCS eligibility from the Rugby Xplorer match record: typed readers for the nightly published data, a rate-limited CMS client, and the reproducible eligibility rules.",
   "keywords": [
     "rugby",
@@ -53,7 +53,7 @@
     "prepublishOnly": "bun run build && bun run test"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.0.0",
     "typescript": "^7.0.2",
     "vitest": "^5.1.0"
   }