@finbheara/archive-client 0.24.0 → 0.26.0

package/README.md

@@ -95,6 +95,15 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `teams` | `teams.results`, `teams.rosters`, `teams.resultRosters` | 260 |
 | `teams.fields` | the fields `teams.results` (`age`, `gender`, `printed_status`) and `teams.rosters` (`dance`, `school_printed_as_of`, a member's `gender`) carry; absent, never refused, without it | 266 |
 | `events` | `events.years` | 260 |
+| `upcoming.feises` | `upcoming.feises`, and the `next` of `feises.series` (null with the reason without it) | 285 |
+| `upcoming.fields`, `upcoming.entrants` | `upcoming.fields`, `upcoming.entrants` (285 and 290 carry the tables empty) | 291 |
+| `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
+| `feis-panels` | `feisPanels.query` | 260 |
+| `staff.adjudicators` | `staff.adjudicators` | 230 |
+| `schools.registry` | `schools.list` | 260 |
+| `schools.prints`, `schools.redirects` | `schools.prints`; `schools.redirects` | 184 |
+| `schools.lineage` | `schools.links`, `schools.line`, `schools.lineage` | 184 |
+| `schools.associations` | `schools.associations` | 215 |
 
 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`).
@@ -201,8 +210,11 @@ s.next;       // the next scheduled instance where the release knows one, else n
 A series is asked by any id of it (a feis, instance or brand id, a retired one followed), by a
 host code with or without its year (held codes `<stem><yy>` whose two digits are their own year,
 never a host id of digits alone, which is a sequence number), or by a name (a glob, or a plain word read as `*word*`). Two series answer `ambiguous` with both.
-A release holds a feis-year once its results are captured and carries no calendar, so `next` is
-`null` today, with the reason.
+`next` is the series' earliest occurrence of the feis-index dated on or after the cut's day
+(`rel.upcoming.feises`, state `upcoming`), under its brand id or one retired onto it: `{ feis_id,
+date, date_hi, occurrence_id, name_printed, hosts, captured_id, series_basis }`, `feis_id` the
+first listing's that names one. It is `null` with `next_why` where the feis-index lists none, and
+on a release without `upcoming_feises` (feature `upcoming.feises`).
 
 ## Schools
 
@@ -227,6 +239,29 @@ rows were published under and their rows, so it agrees with each print lookup of
 
 Every answer carries the release tag it came from.
 
+### The schools in bulk
+
+```ts
+await rel.schools.list();          // { schools: [{ school_id, display, regions, places }] }: the registry
+await rel.schools.prints({ event: "<event>", year: 2024 });
+                                   // { prints: [{ event, year, print, school_id, rows }] }
+await rel.schools.redirects();     // { redirects: [{ old_id, new_id, kind, since }] }
+await rel.schools.lineage();       // { edges: [{ id, direction, other, shape, year, provisional,
+                                   //             decision, confidence }] }
+await rel.schools.associations({ school_id: "<id>" });
+                                   // { associations: [{ at, seq, date, person, person_printed,
+                                   //   person_type, credentials, caption, school_printed, school_id,
+                                   //   association_type, src_type, src, candidate_school_id, candidate_rung, ... }] }
+```
+
+`prints` is every (print, school id) pair the release's result rows attach in an event-year (the
+print trimmed), with the rows that carry it: an event's (case-blind), a year's, both or every one.
+A row attached to no school is in no pair, and a team result's school is `rel.teams.results`'.
+`lineage` is each edge end as the release publishes it (an edge may carry both ends): `links` and
+`line` are the graph over them. `associations` is the people a directory lists beside a school, as
+evidence of an association, never an identity: `school_id` is the school the print attached to,
+`candidate_school_id` one it reached without attaching.
+
 ### How two schools are linked
 
 ```ts
@@ -550,6 +585,33 @@ await rel.feises.dates();                      // every feis id with its first a
 await rel.majors.tabulated({ min_true_round: 3 });     // the majors addresses marked to round 3 or later
 ```
 
+## Marks sheets and panels
+
+```ts
+const s = await rel.tabs.query({ competition: "<competition>" });   // or { address }, and a { round }
+s.rows;      // [{ address, competition, card, line, event, year, tier, round, true_round, seat_index,
+             //    section, panel_size, column_order, drop_rule, the judge (name, print, TD number,
+             //    id, unmatched reason), mark, mark_printed, place, place_printed, tie, points,
+             //    points_printed }]
+for await (const t of rel.tabs.stream({ tier: ["T1", "T2", "T3"], year: [2015, 2025] })) ...
+await rel.panels.query({ competition: "<competition>" });  // { seats: [{ competition, panel, round,
+             //    seat_index, address, the judge (print, TD number, id, unmatched reason) }] }
+await rel.feisPanels.query({ address: "fweb:<code>.<comp>" });  // { seats: [{ address, platform, round,
+             //    seat_index, panel_size, panel_kind, the judge (print, state printed, TD number, id,
+             //    unmatched reason, basis) }] }
+```
+
+A marks sheet is a row per card, round and seat, with the seat's mark, place and points as read
+beside their prints, from `results.sqlite` (every tabulated sheet, the T4 events' too). The stream
+takes an event (or several, case-blind), a year or an inclusive range, tiers, competitions, or
+nothing (every cell), and yields one competition's rows together. A sheet's `event`, `year` and
+`tier` are its competition's: a solo competition's from the results, a team competition's from the
+team results (with the tier the release gives that event-year's solo competitions). A sheet the
+release places in neither carries nulls, and a filter on them never reaches it. `panels` and
+`feisPanels` with nothing named answer every seat. `round` is `rx` where one panel sat every round.
+A seat carries its judge's TD number where the release linked one, else a judge id, else the
+reason it is linked to neither (`TabRow`, `PanelSeat` and `FeisPanelSeat` name the fields).
+
 ## Teams and event-years
 
 ```ts
@@ -591,11 +653,52 @@ every release the `teams` feature names, and `(await rel.capability("teams.field
 a release has. The rows are read once per
 release into the `teams` and `events` indexes.
 
+## Upcoming feiseanna and their competitor lists
+
+```ts
+const o = await rel.upcoming.feises({ state: "upcoming", from: "2026-11-01" });
+o.feises;    // [{ occurrence_id, occurrence_ids, name_printed, date_lo, date_hi, year, hosts,
+             //    feis_brand_id, feis_instance_id, series_basis, brand_candidates, captured_id, state }]
+const f = await rel.upcoming.fields({ state: "pending" });  // state, feis, field_id, from, to
+f.fields;    // [{ field_id, feis_id, source, host_id, competition_code, count_only, occurrence_id,
+             //    name_printed, date_lo, date_hi, year, feis_brand_id, comp, state,
+             //    results_competitions, results_feis_ids, version, versions, captured_date, sha256,
+             //    limits, entrants, stated_rows, printed_total }]
+const e = await rel.upcoming.entrants({ field_id: "fweb:ABC26/101" });  // version: an older capture
+e.entrants;  // [{ name_printed, school_printed, school_id, yob, arm, candidates, flags,
+             //    competitions, field_ids, captured_id, row_id, ... }]
+```
+
+`upcoming.feises` is every occurrence of the cut's feis-index the release holds no results of:
+`upcoming` (dated on or after the cut's day) or `no-results` (before it), each with every
+platform's or calendar's listing (`hosts`) and its feis series where one was named (`series_basis`
+says how; `none` leaves `feis_brand_id` null, the unjoined ones).
+
+A FIELD is one competition a competitor list names, `<feis_id>/<code>`, the same id on every cut. A later capture of the host is a new `version`
+(a capture id; `versions` lists them), never a new field. `state` says how it stands on the cut:
+`pending` (on the list), `results` (the release holds its results, `results_competitions` the
+join), `passed` (its first day is before the cut's day and no result is held) or `withdrawn` (the
+host's newest capture no longer lists it). `comp` is the competition reading of its code (`arm`,
+`level`, `feis_level`, `age`, `population`, `kind`, `title`, `why`), null on a count list.
+`limits` names what the capture cannot show (`registered-not-danced`, `paid-in-full-only`, ...).
+
+`upcoming.entrants` answers a field's rows in one version, its current one by default. A
+registrant carries the resolver's `arm` and `candidates`, NEVER A `dancer_id`: a list shows who
+registered, not who danced, and a `unique` row's one candidate is read with its `flags`
+(`initial-only`: a FeisWeb print is a surname and an initial). `count_only` marks a field read from
+a registration-by-school page of the corpus `entrants/` part: its rows are schools' counts
+(`level_counts`), with no names. A QuickFeis registrant list (`transcripts/*.registrationlist.jsonl`)
+is not read into these tables yet. An unknown field or version answers no rows and says
+why. On a release without the tables each call refuses by name.
+
 ## Teachers and adjudicators
 
 ```ts
 await rel.staff.teacher("<name>");        // or a TD number
 await rel.staff.adjudicator("<name>");
+await rel.staff.adjudicators({ year: 2025 });   // the register's rows (or a TD number's, or every one):
+       // [{ the TD number, year, cat, name_printed, country, country_printed, country_code, region,
+       //    region_printed, region_code, geohash, src }] (`RegisterRow`)
 ```
 
 One person per TD number (else per judge id, else per name): the schools taught at (role,
@@ -747,8 +850,18 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq records --years [--release <spec>] [--dancer <id,...>] [--year <y>]
     idq feis-dates [--release <spec>]
     idq tabulated [--release <spec>] [--min-round <n>]
+    idq tabs [--release <spec>] --comp <competition> | --address <address> [--round <r>]
+    idq tabs --stream [--release <spec>] [--comp <c,...>] [--event <e,...>] [--year <y> | --year <from>..<to>] [--tier <t,...>]
+    idq panels [--release <spec>] [--comp <competition>]
+    idq feis-panels [--release <spec>] [--address <feis competition>] [--platform <p>]
+    idq register [--release <spec>] [--year <y>] [--td <TD number>]
+    idq schools [--release <spec>] [--prints [--event <e>] [--year <y>] | --redirects | --lineage
+                | --associations [--school <school_id>]]
     idq teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]
     idq events [--release <spec>] [--event <e>] [--year <y>]
+    idq upcoming [--release <spec>] [--state <s,...>] [--feis <id>] [--from <date>] [--to <date>]
+    idq upcoming --entrants <field_id> [--version <capture id>]
+    idq upcoming --feises [--state upcoming|no-results] [--brand <series>] [--from <date>] [--to <date>]
     idq teacher [--release <spec>] <name|TD number>
     idq adjudicator [--release <spec>] <name|TD number>
     idq comp [--release <spec>] <feis> <code> [--year y] [--title t]
@@ -759,7 +872,7 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
                        [--oireachtas <region>[:<year>]]
     idq resolve registrations
 
-`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
+`stream` (and `tabs --stream`) prints one JSON line per row (or entry, or cell), 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.
 
 `update` moves to the newest published release, as a package manager's `update` moves to the newest