@finbheara/archive-client 0.30.0 → 0.32.0

package/README.md

@@ -88,8 +88,10 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `feises`, `comps` | `feises.find`, `feises.series`, `comps.*`, `registrations.resolve` | 265 |
 | `comps.dance` | the `dance` a comp of `comps.*` carries: null, never refused, without it | 270 |
 | `results.stream`, `majors.stream` | `results.stream`, `results.entries` | 255 |
+| `results.stream.competition`, `majors.stream.competition` | the competition fields a streamed row carries (`competition_line`, `dance_printed`, `dance`, `recalled_only`, `comp_flags`, `competitors_basis`); absent, never refused, without them | 270 |
 | `feises.dates` | `feises.dates` | 245 |
 | `dancers.records` | `dancers.records` | 215 |
+| `dancers.records.names` | the `names_printed` a record of `dancers.records` carries; absent, never refused, without it | 215 |
 | `dancers.years` | `dancers.years` | 245 |
 | `majors.tabs` | `majors.tabulated` | 215 |
 | `teams` | `teams.results`, `teams.rosters`, `teams.resultRosters` | 260 |
@@ -210,6 +212,14 @@ 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 MAJORS EVENT IS NO FEIS SERIES. A code of the release's roster (`NAIDC`, either case) is never
+read as a name, so it never answers a feis whose name happens to print its letters. It answers the
+series the release files that event's platform captures under (the code in lowercase, its
+instances the code and a four-digit year, `via: "majors"`), or `none` with `why` naming the event,
+and `s.major` is its roster row (`{ code, tier, name }`). `rel.comps.place` reads it the same way: the captures of the asked event-year, held, or
+no feis with `why`. The roster is the manifest's `roster`; a release written before it carries one
+reads the codes its rows show are majors (a `T1` to `T3` event, a series filed under event-year
+instances), and a code those rows never name is not known there (`rosterOf(rel)`).
 `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
@@ -565,6 +575,25 @@ competition beside its own fields: `competition`, `event`, `year`, `tier`, `comp
 `(file, line)` is one row, where an `address` may carry one row per section). Rows come in the
 release's own order, a competition's rows together.
 
+THE COMPETITION FIELDS, where the release carries them (`rel.capability("results.stream.competition")`,
+`"majors.stream.competition"` for scope `majors`), are on every row, null meaning no value:
+
+| field | what it is |
+| --- | --- |
+| `competition_line` | the competition's own line in `file`: `(file, competition_line)` is one competition of the release exactly |
+| `dance_printed` | the dance field as the page printed it. A platform that prints no title prints only this, so a filter on the kind of competition reads `title` and `dance_printed` together |
+| `dance` | the competition's one dance as the release reads it (`reel`), null where it reads none |
+| `recalled_only` | true where the page printed the recalled dancers only |
+| `comp_flags` | what the page printed about itself, int-packed, one bit a flag (bit 10: recalled only). The release's `DATA-DICTIONARY.md` carries the register of every bit, and a published bit never moves |
+| `competitors_basis` | what `competitors` stands on: `printed` (the page printed a competed count), `counted` (the page printed the whole field, its cards counted), `entered` or `registered` (only the top was printed: the page's entered or registered count), null where there is no number |
+
+A release without them streams every row with the six fields ABSENT, never null.
+
+THE COMPETITION'S KEY is `competition` (`<event-year>.<comp>` at a major, `<platform>:<host>.<comp>`
+at a feis), which holds across releases. Inside one release `(file, competition_line)` is exact: a
+competition captured twice (two files of one platform) carries one `competition` in both and two
+`(file, competition_line)` keys, and `primary_source` names the copy another source stands in for.
+
 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.
 
@@ -578,13 +607,20 @@ the place the address's recall row carries.
 
 ```ts
 await rel.dancers.records();                   // every dancer: display, appearances, birth_lo, birth_hi,
-                                               // birth_source, birth_conflict, genders, scope
+                                               // birth_source, birth_conflict, genders, scope,
+                                               // names_printed (dancers.records.names)
 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
 ```
 
+`dancers.records` covers EVERY dancer the release gives an id: a majors dancer, a feis row attached
+to one, and a feis-local dancer (`scope: "per-release"`, valid in its release only). It is not the
+majors' dancers only. A caller who wants those keeps the `dancer_id`s a `scope: "majors"` stream
+carries. `names_printed` is every distinct name the dancer's rows print, sorted, over every row of
+the dancer, feis rows included.
+
 ## Marks sheets and panels
 
 ```ts
@@ -781,7 +817,7 @@ A feis the release holds names itself, its year and its series. A platform feis
 (`<token>:<host>`) the release holds competitions of and no `feises` line names (a source that
 carried a feis's results and not the feis itself) is held too, on its own id and its competitions'
 year (`via: "id"`, as a feis with its line is), its series the one its host code reaches if
-exactly one brand matches the stem, else null. A majors or championship event id is never held so. A series instance or brand id
+exactly one brand matches the stem, else null. A majors or championship event id is never held so: a roster code places only the platform captures filed under its event-year (`via: "majors"`), else nothing, saying why. A series instance or brand id
 names the series. A feis id the release does not hold is placed in a series by its host code
 (`<token>:<stem><yy>` where the held codes of that stem carry their own year), and a stem two
 series share answers `ambiguous`. A host id of digits alone (`qf:926`, `fw:1001`) is a sequence