How this library is built
Almost everything callable in sportsdataverse is generated: the ESPN wrappers, the
native (non-ESPN) families, the dataset loaders, their TypeScript row and params types, and
every reference page on this site come out of tools/codegen/generate.mjs. The generator
reads two kinds of input:
- Vendored YAML — endpoint and returns-schema YAML that sportsdataverse-py
owns.
npm run vendorcopies it verbatim from a pinned sdv-py commit intotools/codegen/vendor/upstream/(with aLOCKof git blob shas) and derivestools/codegen/endpoints/<family>.yaml. Never hand-edit a vendored file; it is clobbered on the next re-vendor andnpm run vendor:checkfails on the drift. - JS-owned YAML and TypeScript — families that exist only here (
hockeytech,odds_api,yahoo_scores,recruiting), the overlays that patch a vendored family, the utilities catalogue, the breaking-change register, and the hand-written runtime undersrc/.
Every generated file carries a visible footer naming its source and linking the page here
that explains it. The CI gates are npm run vendor:check (vendored inputs), npm run codegen:check (every generated output, this site's pages included), npm run api:check
(the public API report) and npm test.
| Surface | Source of truth | Generated | Count |
|---|---|---|---|
| ESPN (vendored) | sdv-py espn_*.yaml at the pin | src/generated/espn/*.ts, docs/docs/<league>/ | 126 endpoints × 30 leagues |
| Native, vendored | sdv-py <family>.yaml at the pin | src/generated/flat/*.ts | 23 families |
| Native, JS-owned | tools/codegen/endpoints/<family>.yaml in this repo | src/generated/flat/*.ts | 4 families |
| Dataset loaders | sdv-py releases.yaml + loader_schemas.yaml | src/generated/loaders/*.ts | 323 loaders |
| Hand-written | TypeScript under src/ | src/generated/utilities.ts, docs/docs/utilities/ | 208 utility exports |
sdv-py pin: afafaedae47b. 1059 native wrappers in total; 438 verified endpoints carry row types; 19 breaking changes on record.
The surfaces
- ESPN (vendored) — one YAML per ESPN host family, bound on every league.
- Native families, vendored — MLB, NHL, stats.nba.com, PFF, … from sdv-py.
- Native families, JS-owned — HockeyTech, The Odds API, Yahoo scores.
- Dataset loaders — the
load*readers of the published release parquet. - Hand-written modules — parsers, analytics, odds math, models, producers, discovery, the HTTP core.
Changing something
| You want to… | Edit | Then run |
|---|---|---|
| add / change a shared endpoint | sdv-py first; bump the pin in tools/codegen/vendor.yaml | npm run vendor -- --ref <sha> → npm run codegen |
| patch how JS binds a vendored family | tools/codegen/overlay/<family>.yaml | npm run vendor -- --offline → npm run codegen |
| add a JS-only endpoint | tools/codegen/endpoints/<family>.yaml (a JS-owned family) | npm run codegen |
| describe a returns-table column | sdv-py's manual_column_descriptions.yaml (vendored here) | re-vendor → npm run codegen |
| label a hand-written export | tools/codegen/utilities.yaml | npm run codegen |
| record a breaking change | tools/codegen/breaking.yaml (+ CHANGELOG.md) | npm run codegen |
| change the runtime | src/ (never src/generated/) | npm run build && npm test |
Column descriptions on every returns table resolve through tools/codegen/descriptions.mjs:
the schema's own text, then sdv-py's hand-curated manual_column_descriptions.yaml (by schema
key, then _global), then the column descriptions mined from the SDV R packages
(r_column_descriptions.yaml: the league's package, its sport's siblings, the merged union).
npm run codegen prints the fill rate per family and writes
docs/src/generated/description_coverage.json.