@finbheara/archive-client 0.31.0 → 0.33.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 |
@@ -97,6 +99,7 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `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 |
+| `upcoming.fields.instance` | the `feis_instance_id` `upcoming.fields` carries; absent, never refused, without it | 320 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -573,6 +576,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.
 
@@ -586,13 +608,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
@@ -669,7 +698,8 @@ o.feises;    // [{ occurrence_id, occurrence_ids, name_printed, date_lo, date_hi
              //    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, flags,
+             //    name_printed, date_lo, date_hi, year, feis_brand_id, feis_instance_id, comp,
+             //    state, flags,
              //    results_competitions, results_feis_ids, held_out, merged_into, version, versions,
              //    captured_date, sha256,
              //    limits, entrants, stated_rows, printed_total }]
@@ -684,7 +714,10 @@ d.departures; // [{ field_id, feis_id, occurrence_id, feis_brand_id, competition
 `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).
+says how; `none` leaves `feis_brand_id` null, the unjoined ones). An occurrence whose series one
+filed brand answers is given its `feis_instance_id` when it is ANNOUNCED, before any capture of it
+is held (`series_basis` `announced` on every later release), and its captures land on that
+instance when they arrive, so a field's `feis_instance_id` is the id its results will carry.
 
 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:

package/dist/chunks/{index-cgsefd2y.js → index-g8ab43kz.js}

@@ -465,6 +465,32 @@ var FEATURES2 = [
     since: 255,
     calls: "results.stream, results.entries (scope majors)"
   },
+  {
+    feature: "results.stream.competition",
+    needs: [
+      "results:results.competition_line",
+      "results:competitions.dance_printed",
+      "results:competitions.dance",
+      "results:competitions.recalled_only",
+      "results:competitions.flags",
+      "results:competitions.competitors_basis"
+    ],
+    since: 270,
+    calls: "the competition fields a row of results.stream and results.entries carries (competition_line, dance_printed, dance, recalled_only, comp_flags, competitors_basis; scopes transcribed, platform, all): absent, never refused, on a release without them"
+  },
+  {
+    feature: "majors.stream.competition",
+    needs: [
+      "majors:results.competition_line",
+      "majors:competitions.dance_printed",
+      "majors:competitions.dance",
+      "majors:competitions.recalled_only",
+      "majors:competitions.flags",
+      "majors:competitions.competitors_basis"
+    ],
+    since: 270,
+    calls: "the same competition fields on a row of results.stream and results.entries (scope majors): absent, never refused, on a release without them"
+  },
   {
     feature: "majors.tabs",
     needs: ["majors:tabs.address", "majors:tabs.true_round"],
@@ -491,6 +517,12 @@ var FEATURES2 = [
     since: 215,
     calls: "dancers.records"
   },
+  {
+    feature: "dancers.records.names",
+    needs: ["results:dancers.names_printed"],
+    since: 215,
+    calls: "the `names_printed` a record of dancers.records carries: absent, never refused, on a release without it"
+  },
   {
     feature: "dancers.years",
     needs: [
@@ -650,6 +682,12 @@ var FEATURES2 = [
     since: 291,
     calls: "upcoming.fields (285 and 290 carry the table empty)"
   },
+  {
+    feature: "upcoming.fields.instance",
+    needs: ["results:upcoming_fields.feis_instance_id"],
+    since: 320,
+    calls: "upcoming.fields' `feis_instance_id` (absent, never null, without it)"
+  },
   {
     feature: "upcoming.entrants",
     needs: [
@@ -1225,9 +1263,12 @@ var COLUMNS = `r.address AS address, r.competition AS competition, c.event AS ev
 	r.yob_printed AS yob_printed, r.points_printed AS points_printed,
 	r.platform_dancer_id AS platform_dancer_id, r.primary_source AS primary_source,
 	r.file AS file, r.line AS line`;
+var COMPETITION_COLUMNS = `, r.competition_line AS competition_line,
+	c.dance_printed AS dance_printed, c.dance AS dance, c.recalled_only AS recalled_only,
+	c.flags AS comp_flags, c.competitors_basis AS competitors_basis`;
 var TRANSCRIBED = "('transcript', 'manifested')";
 var scopeDb = (s) => s === "majors" ? "majors" : "results";
-function streamSql(q) {
+function streamSql(q, shape = {}) {
   const where = [];
   const args = [];
   const list = (col, v, nocase = false) => {
@@ -1268,7 +1309,7 @@ function streamSql(q) {
   if (q.primary === true)
     where.push("(r.primary_source IS NULL OR r.primary_source = '')");
   return {
-    sql: `SELECT ${COLUMNS} FROM results r JOIN competitions c ON c.file = r.file AND c.line = r.competition_line${where.length === 0 ? "" : ` WHERE ${where.join(" AND ")}`} ORDER BY r.file, r.line`,
+    sql: `SELECT ${COLUMNS}${shape.competition === true ? COMPETITION_COLUMNS : ""} FROM results r JOIN competitions c ON c.file = r.file AND c.line = r.competition_line${where.length === 0 ? "" : ` WHERE ${where.join(" AND ")}`} ORDER BY r.file, r.line`,
     args
   };
 }
@@ -1280,10 +1321,16 @@ function feisDates(db) {
 }
 var text = (v) => v === null || v === "" ? null : v;
 function rowOf(r, dates) {
-  const { atts, withdrawn, ...rest } = r;
+  const { atts, withdrawn, recalled_only, ...rest } = r;
   const d = dates.get(r.event);
   return {
     ...rest,
+    ..."competition_line" in r ? {
+      dance_printed: text(r.dance_printed ?? null),
+      dance: text(r.dance ?? null),
+      recalled_only: recalled_only === 1,
+      competitors_basis: text(r.competitors_basis ?? null)
+    } : {},
     feis_id: d === undefined ? null : r.event,
     feis_date_lo: d?.lo ?? null,
     feis_date_hi: d?.hi ?? null,
@@ -1294,9 +1341,9 @@ function rowOf(r, dates) {
     dancer_scope: r.dancer_id === null ? null : r.dancer_id >= FEIS_LOCAL_ID_FLOOR2 ? "per-release" : "stable"
   };
 }
-async function* streamRows(db, q) {
+async function* streamRows(db, q, shape = {}) {
   const dates = feisDates(db);
-  const { sql, args } = streamSql(q);
+  const { sql, args } = streamSql(q, shape);
   const stmt = db.prepare(sql);
   try {
     for (const r of stmt.iterate(...args))
@@ -1305,9 +1352,9 @@ async function* streamRows(db, q) {
     stmt.finalize();
   }
 }
-async function* entryRows(db, q) {
+async function* entryRows(db, q, shape = {}) {
   const dates = feisDates(db);
-  const { sql, args } = streamSql(q);
+  const { sql, args } = streamSql(q, shape);
   const stmt = db.prepare(sql);
   let file = null;
   let held = new Map;
@@ -1403,13 +1450,16 @@ class ResultFinder2 {
     const db = scopeDb(q.scope);
     await this.rel.fetch(db);
     await this.rel.require(db === "majors" ? "majors.stream" : "results.stream");
-    return this.rel.db(db);
+    const competition = (await this.rel.capability(`${db}.stream.competition`)).state === "full";
+    return { db: this.rel.db(db), shape: { competition } };
   }
   async* stream(q) {
-    yield* streamRows(await this.streamDb(q), q);
+    const { db, shape } = await this.streamDb(q);
+    yield* streamRows(db, q, shape);
   }
   async* entries(q) {
-    yield* entryRows(await this.streamDb(q), q);
+    const { db, shape } = await this.streamDb(q);
+    yield* entryRows(db, q, shape);
   }
 }
 
@@ -2065,16 +2115,18 @@ class DancerResolver2 {
     await this.rel.fetch("results");
     await this.rel.require("dancers.records");
     const db = this.rel.db("results");
-    const sql = "SELECT dancer_id, display, appearances, birth_lo, birth_hi, birth_source, birth_conflict, genders FROM dancers";
+    const names = (await this.rel.capability("dancers.records.names")).state === "full";
+    const sql = `SELECT dancer_id, display, appearances, birth_lo, birth_hi, birth_source, birth_conflict, genders${names ? ", names_printed" : ""} FROM dancers`;
     const rows = q.ids === undefined ? db.query(`${sql} ORDER BY dancer_id`).all() : idChunks(q.ids).flatMap((c) => db.query(`${sql} WHERE dancer_id IN (${c.map(() => "?").join(",")})`).all(...c));
     rows.sort((a, b) => a.dancer_id - b.dancer_id);
     return {
       tag: this.rel.tag,
-      records: rows.map((r) => ({
+      records: rows.map(({ names_printed, ...r }) => ({
         ...r,
         scope: r.dancer_id >= FEIS_LOCAL_ID_FLOOR2 ? "per-release" : "stable",
         birth_conflict: r.birth_conflict === 1,
-        genders: r.genders === "" ? [] : r.genders.split(",")
+        genders: r.genders === "" ? [] : r.genders.split(","),
+        ...names_printed === undefined ? {} : { names_printed: JSON.parse(names_printed) }
       }))
     };
   }
@@ -4089,6 +4141,7 @@ function fieldOf(r) {
     date_hi: r.date_hi ?? null,
     year: r.year,
     feis_brand_id: r.feis_brand_id ?? null,
+    ...r.feis_instance_id === undefined ? {} : { feis_instance_id: r.feis_instance_id ?? null },
     comp: r.comp_arm === null ? null : {
       arm: r.comp_arm,
       source: r.comp_source ?? null,

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-cgsefd2y.js";
+} from "./chunks/index-g8ab43kz.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";

package/dist/index.js

@@ -76,7 +76,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-cgsefd2y.js";
+} from "./chunks/index-g8ab43kz.js";
 import {
   cacheRoot2,
   repoOf2

package/dist/types/dancers.d.ts

@@ -193,6 +193,7 @@ export interface DancerBulkRecord {
     birth_source: string;
     birth_conflict: boolean;
     genders: string[];
+    names_printed?: string[];
 }
 export interface DancerYear {
     dancer_id: number;

package/dist/types/index.d.ts

@@ -22,7 +22,7 @@ export { type SchoolAnswer, type SchoolCandidate, type SchoolQuery, SchoolResolv
 export { LINEAGE_FILE, type SchoolLineAnswer, type SchoolLinksAnswer, linksOfLineage, releaseSchoolGraph, } from "./school-links.js";
 export type { LineCandidate, LinkPath, LinkPolicy, LinkQuery, LinkStep, PathFlags, SchoolLink, StepFlags, StepPolicy, } from "@finbheara/domain/school-graph";
 export { type Capability, FEATURES, type Feature, type SchemaProbe, capabilityOf, columnsOf, needsRelease, } from "./schema.js";
-export { type EntryRow, type StreamQuery, type StreamRow, type StreamScope, entryRank, } from "./stream.js";
+export { type EntryRow, type StreamCompetition, type StreamQuery, type StreamRow, type StreamScope, entryRank, } from "./stream.js";
 export { type FeisPanelSeat, FeisPanelFinder, PanelFinder, type PanelSeat, type RegisterRow, type TabAnswer, TabFinder, type TabQuery, type TabRow, type TabStreamQuery, } from "./tabs.js";
 export { EventFinder, type EventYear, type EventYearQuery, type ResultRoster, type RosterMember, type RosterTeam, TeamFinder, type TeamResult, } from "./teams.js";
 export { type EntrantCandidate, FIELD_STATES, type FieldComp, DEPARTURE_REASONS, type DepartureReason, type FieldState, type HeldOut, type UpcomingDeparture, type UpcomingDepartureAnswer, type UpcomingDepartureQuery, type UpcomingEntrant, type UpcomingEntrantAnswer, type UpcomingEntrantQuery, type UpcomingFeis, type UpcomingFeisAnswer, type UpcomingFeisQuery, type UpcomingFeisState, type UpcomingField, type UpcomingFieldAnswer, type UpcomingFieldQuery, UpcomingFinder, type UpcomingHost, } from "./upcoming.js";

package/dist/types/stream.d.ts

@@ -11,7 +11,15 @@ export interface StreamQuery {
     school_id?: string;
     primary?: boolean;
 }
-export interface StreamRow {
+export interface StreamCompetition {
+    competition_line: number;
+    dance_printed: string | null;
+    dance: string | null;
+    recalled_only: boolean;
+    comp_flags: number;
+    competitors_basis: string | null;
+}
+export interface StreamRow extends Partial<StreamCompetition> {
     address: string;
     competition: string;
     event: string;
@@ -60,8 +68,11 @@ export interface EntryRow extends StreamRow {
     recall_place: number | null;
 }
 export declare function entryRank(section: string): number;
+export interface StreamShape {
+    competition?: boolean;
+}
 export declare const scopeDb: (s: StreamScope) => "majors" | "results";
-export declare function streamSql(q: StreamQuery): {
+export declare function streamSql(q: StreamQuery, shape?: StreamShape): {
     sql: string;
     args: (string | number)[];
 };
@@ -69,5 +80,5 @@ export declare function feisDates(db: Database): Map<string, {
     lo: string | null;
     hi: string | null;
 }>;
-export declare function streamRows(db: Database, q: StreamQuery): AsyncGenerator<StreamRow>;
-export declare function entryRows(db: Database, q: StreamQuery): AsyncGenerator<EntryRow>;
+export declare function streamRows(db: Database, q: StreamQuery, shape?: StreamShape): AsyncGenerator<StreamRow>;
+export declare function entryRows(db: Database, q: StreamQuery, shape?: StreamShape): AsyncGenerator<EntryRow>;

package/dist/types/upcoming.d.ts

@@ -57,6 +57,7 @@ export interface UpcomingField {
     date_hi: string | null;
     year: number;
     feis_brand_id: string | null;
+    feis_instance_id?: string | null;
     comp: FieldComp | null;
     state: FieldState;
     flags: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.31.0",
+	"version": "0.33.0",
 	"description": "Open a versioned release of an Irish dance results archive: download, verify, decompress and cache it by tag, keep the cache, and resolve feises and schools against it",
 	"keywords": ["irish-dance", "results", "release", "cache", "sqlite"],
 	"license": "MIT",