Function: seasonLoader()
seasonLoader<
R>(def):SeasonLoader<R>
Defined in: src/core/releases.ts:843
A per-season loader: every season is fetched in turn, a season with no
published asset (HTTP 404) is skipped with one warning (or, with
onMissing: "raise", throws NoDataError), any other failure
raises AssetFetchError, and the seasons are concatenated (columns unioned,
gaps null-filled, drifted types cast to their supertype). Seasons below
minSeason raise SeasonNotFoundError before anything is fetched.
Type Parameters
R
R extends object = ReleaseRow
Parameters
def
The loader's manifest entry: fn, a url with a {season} token, optional
minSeason, idInt64 and onMissing.
Returns
SeasonLoader<R>
An async loader taking SeasonLoaderOptions (seasons required; columns,
format, maxCells, timeoutMs optional) and resolving to row objects, or to column
arrays with format: "columns". Every error is a rejection, including a bad seasons.
Throws
SdvError (rejected) when seasons is missing, or a season is not an integer / 4-digit
year string; when format is neither "rows" nor "columns"; when a season's cells would
push the running total over maxCells (that season is not decoded; earlier ones already
were); or when an asset is not decodable parquet (cause set).
Throws
SeasonNotFoundError (rejected) when a season is below def.minSeason — before any
fetch.
Throws
NoDataError (rejected) with onMissing: "raise", when a season has no published
asset (HTTP 404). Without it the season is skipped and named in one SDV_RELEASE warning.
Throws
AssetFetchError (rejected) for any failed download other than a 404 (propagated from the transport) — a failed fetch is never reported as a missing season.
Remarks
Seasons are processed one at a time: download, read the footer, add its cells to the running
total, refuse if over maxCells, else decode and drop the download. At most one compressed
download is held at once. The concat matches polars diagonal_relaxed (columns unioned in
first-seen order, gaps null-filled, a column whose type drifts between seasons cast to the
supertype: anything + string -> string, boolean + number -> number). The INT64 policy then
runs on id columns and INT64-stored columns (applyInt64Policy). A Date cast to
string becomes its ISO timestamp, not polars' YYYY-MM-DD (known gap).
Example
const loadPbp = seasonLoader({ fn: "load_cfb_pbp", url: "https://x/pbp_{season}.parquet" });
const rows = await loadPbp({ seasons: [2023, 2024], columns: ["game_id", "epa"] });