@finbheara/archive-client 0.3.1 → 0.5.0

package/README.md

@@ -2,8 +2,8 @@
 
 Open a versioned release of an Irish dance results dataset and work with it locally: download,
 verify, decompress and cache it by tag, keep a user-local cache of releases, and resolve feises,
-schools, competitions, registration lists, dancers, results, majors, teachers and
-adjudicators against one. A command line, `idq`, is a thin wrapper over the same calls.
+schools, competitions, registration lists, dancers, results, majors, teams, event dates, teachers
+and adjudicators against one. A command line, `idq`, is a thin wrapper over the same calls.
 
 Bun 1.4.2 or later (the databases open through `bun:sqlite`). MIT.
 
@@ -20,7 +20,7 @@ type declarations (`.d.ts`), so a TypeScript project needs Bun's types (`"types"
 `bunx idq <verb>`.
 
 The version is 0.x while the API settles: a minor bump may break, so pin a minor
-(`"@finbheara/archive-client": "0.2.x"`).
+(`"@finbheara/archive-client": "0.5.x"`).
 
 ## Configuration
 
@@ -85,6 +85,13 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `staff` | `staff.teacher`, `staff.adjudicator` | 260 |
 | `majors.order` | `majors.competitions` | 260 |
 | `feises`, `comps` | `feises.find`, `feises.series`, `comps.*`, `registrations.resolve` | 265 |
+| `results.stream`, `majors.stream` | `results.stream`, `results.entries` | 255 |
+| `feises.dates` | `feises.dates` | 245 |
+| `dancers.records` | `dancers.records` | 215 |
+| `dancers.years` | `dancers.years` | 245 |
+| `majors.tabs` | `majors.tabulated` | 215 |
+| `teams` | `teams.results`, `teams.rosters`, `teams.resultRosters` | 260 |
+| `events` | `events.years` | 260 |
 
 A spec is `pinned` (the default: the user-local pin, else the latest), `latest`, a cut number
 (`42`, or `42.1` for a fraction) or a tag (`archive-YYYY.MM.DD-N`).
@@ -138,8 +145,9 @@ outside the cache root.
 
 The release databases carry a primary key per table and nothing more, so lookups build side
 indexes, one SQLite file per index per tag, each keyed on its builder's version and the sha256 of
-every input it read. A file whose key is stale is rebuilt, never served. Four ship here, and a
-caller may hand its own (`builders` option, an `IndexBuilder`):
+every input it read. A file whose key is stale is rebuilt, never served. These ship here, and a
+caller may hand its own (`builders` option, an `IndexBuilder`, with an optional async `load` step
+whose answer its `build` receives):
 
 - `schools`: every published school print with the ids its rows carry, filed into a
   `@finbheara/domain` `schoolEncoder` noun index, with the registry and the retired ids
@@ -151,6 +159,9 @@ caller may hand its own (`builders` option, an `IndexBuilder`):
 - `staff` (keyed the same way): teachers and adjudicators by name (a `roleEncoder` noun index) and TD number: the
   schools' staff lists and TD links, the adjudicator register, and the seats each sat
 - `comps`: every competition by its feis and the feis's own code, with its series and year
+- `teams`: the team results, the roster teams with their members, and how they join, by
+  event-year
+- `events`: every event-year's dates and place
 
 ## Feises
 
@@ -270,6 +281,75 @@ A row carries the prints and the ids that stand for them: the address, the compe
 and age, the place, the name and school as printed with the dancer and school ids. The majors are
 read from `majors.sqlite`, fetched on first use.
 
+## Every row, streamed
+
+```ts
+for await (const row of rel.results.stream({ scope: "majors" })) { ... }
+for await (const row of rel.results.stream({
+  scope: "platform",            // "majors" | "transcribed" | "platform" | "all"
+  primary: true,                // only rows no other source stands in for
+  year: [2015, 2024],           // a year or an inclusive range
+  feis_level: [600, 700],       // also: event (one or several), tier, category, dancer_id, school_id
+})) { ... }
+for await (const entry of rel.results.entries({ scope: "all", event: "<event>" })) { ... }
+```
+
+A stream yields one row at a time and never holds the table in memory. A row carries its
+competition beside its own fields: `competition`, `event`, `year`, `tier`, `comp_no`, `title`,
+`category`, `age`, `age_printed`, `gender`, `competitors`, `feis_level`, `level_printed`,
+`date_printed`, `source`, `round`, and at a feis its `feis_id`, `feis_date_lo` and
+`feis_date_hi`. Its own: `address`, `section`, `card`, `place`, `place_printed`, `tie`,
+`relative_place`, `atts`, `withdrawn`, `qualifier`, `name_printed`, `name`, `school_printed`,
+`school_loc`, `school_id`, `dancer_id`, `dancer_scope`, `yob`, `yob_printed`, `points_printed`,
+`platform_dancer_id`, `primary_source`. Rows come in the release's own order, a competition's
+rows together.
+
+The scopes: `majors` reads the majors (tiers T1 to T3), `transcribed` the transcribed rows of
+every tier, `platform` every row a results platform published, `all` every row.
+
+AN ENTRY is one row per address, the row the card stands for: a card printed in several sections
+(a recall order, the final, a single round's solo placing, a qualifying heat) keeps the final's
+row, then the sectionless page's, the recall order's, the standings', the unplaced row, a heat's
+and last a solo round's (`entryRank`), and two rows of one rank keep the later. `recall_place` is
+the place the address's recall row carries.
+
+## Bulk reads
+
+```ts
+await rel.dancers.records();                   // every dancer: display, appearances, birth_lo, birth_hi,
+                                               // birth_source, birth_conflict, genders, scope
+await rel.dancers.records({ ids: [1001] });
+await rel.dancers.years({ ids: [1001], year: 2025 });  // region, region_source, nationals, geohash
+await rel.feises.dates();                      // every feis id with its first and last day
+await rel.majors.tabulated({ min_true_round: 3 });     // the majors addresses marked to round 3 or later
+```
+
+## Teams and event-years
+
+```ts
+const r = await rel.teams.results({ event: "<event>", year: 2024 });
+r.results;   // [{ address, competition, event, year, comp_no, title, category, hands, letter, label,
+             //    school_printed, school_id, place, place_printed, tie, competitors, atts, ... }]
+const t = await rel.teams.rosters({ event: "<event>", year: 2024 });
+t.teams;     // [{ team, kind, event, year, comp_no, title, team_index, seq, school_id, school_printed,
+             //    members: [{ seq, name_printed, name, yob, dancer_id, dancer_scope }] }]
+const j = await rel.teams.resultRosters({ event: "<event>", year: 2024 });
+j.joins;     // [{ team, result_address, join_kind, via_split, roster_index, result_letter, ... }]
+const e = await rel.events.years({ event: "<event>" });
+e.years;     // [{ event, year, date_lo, date_hi, resolution, source, date_printed, place, place_printed }]
+```
+
+A query names an event (case-blind), a year, both, or neither (every row). Everything comes from
+ONE release: a roster member's `dancer_id` is the same release's id as the results', so a caller
+never joins team records of one release to dancer ids of another. A roster is a sheet of a school's
+teams (`kind: "rosterTeam"`) or a result card's own line-up (`lineup`). `join_kind` says how a
+roster team met the results (`exact`, `card`, `branch`) or why it did not (`no-result`,
+`no-school`, `no-roster`, `multi-team-unjoined`), and `result_address` is null where none joined.
+An event-year's dates are a window (`date_lo`, `date_hi`) with how fine it is (`resolution`:
+`day`, `month`, `calendar`) and what it is read from (`source`), and `place` is a place-tree node
+where the release knows one. A field the source left empty is null. The rows are read once per
+release into the `teams` and `events` indexes.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -394,6 +474,15 @@ and the competitions still resolve.
                [--population girls|boys] [--rows]
     idq results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <c>] [--school <s>] [--year <y>] [--limit <n>]
     idq majors [--release <spec>] [--event <e>] [--year <y>] [--comp <c>] [--dancer <id>] [--rows]
+    idq stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]
+               [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]
+               [--level <n,...>] [--dancer <id,...>] [--school <school_id>] [--primary]
+    idq records [--release <spec>] [--dancer <id,...>]
+    idq records --years [--release <spec>] [--dancer <id,...>] [--year <y>]
+    idq feis-dates [--release <spec>]
+    idq tabulated [--release <spec>] [--min-round <n>]
+    idq teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]
+    idq events [--release <spec>] [--event <e>] [--year <y>]
     idq teacher [--release <spec>] <name|TD number>
     idq adjudicator [--release <spec>] <name|TD number>
     idq comp [--release <spec>] <feis> <code> [--year y] [--title t]
@@ -403,7 +492,7 @@ and the competitions still resolve.
     idq resolve dancer [<name>] [--school s] [--comp <feis>/<code> | --yob y | --band b --year y]
     idq resolve registrations
 
-`dancer` prints the results of the one dancer where the answer is unique (every candidate's with
+`stream` prints one JSON line per row (or entry), as it reads them. `dancer` prints the results of the one dancer where the answer is unique (every candidate's with
 `--rows`). `--json` prints the call's answer as it is. `--cache` and `--repo` override the defaults.
 
 `resolve` speaks JSON lines: one answer per line out, and with no positional question the