@finbheara/archive-client 0.3.1 → 0.4.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.4.x"`).
 
 ## Configuration
 
@@ -85,6 +85,8 @@ 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 |
+| `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 +140,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 +154,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 +276,32 @@ 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.
 
+## 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 +426,8 @@ 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 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]

package/dist/chunks/{index-3va2jzse.js → index-v8e0qe9f.js}

@@ -1586,8 +1586,240 @@ class SchoolResolver2 {
   }
 }
 
+import { parquetMetadata, parquetReadObjects, parquetSchema } from "hyparquet";
+var COMPRESSORS = {
+  ZSTD: (input) => new Uint8Array(Bun.zstdDecompressSync(input))
+};
+var tableAsset = (table) => `${table}.parquet`;
+function plain(v) {
+  if (typeof v === "bigint")
+    return v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v;
+  if (Array.isArray(v))
+    return v.map(plain);
+  if (v !== null && typeof v === "object" && !(v instanceof Date)) {
+    const o = {};
+    for (const [k, x] of Object.entries(v))
+      o[k] = plain(x);
+    return o;
+  }
+  return v;
+}
+async function readParquet(path, columns) {
+  const file = await Bun.file(path).arrayBuffer();
+  const rows = await parquetReadObjects({
+    file,
+    compressors: COMPRESSORS,
+    ...columns !== undefined ? { columns: [...columns] } : {}
+  });
+  return rows.map((r) => plain(r));
+}
+async function parquetColumns(path) {
+  const meta = parquetMetadata(await Bun.file(path).arrayBuffer());
+  return new Set(parquetSchema(meta).children.map((c) => c.element.name));
+}
+
+var str = (v) => typeof v === "string" && v !== "" ? v : null;
+var num = (v) => typeof v === "number" ? v : null;
+var strs = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+var scope = (id) => id === null ? null : id >= FEIS_LOCAL_ID_FLOOR2 ? "per-release" : "stable";
+var TEAM_TABLES = [
+  "team_results",
+  "roster_teams",
+  "roster_members",
+  "team_result_rosters",
+  "event_years"
+];
+var TEAMS_SCHEMA = `
+CREATE TABLE event_year(event_year TEXT PRIMARY KEY, event TEXT NOT NULL, year INTEGER NOT NULL);
+CREATE TABLE result(address TEXT PRIMARY KEY, competition TEXT, event TEXT, year INTEGER,
+	card TEXT, comp_no TEXT, title TEXT, category TEXT, hands INTEGER, letter TEXT, label TEXT,
+	name_printed TEXT, school_printed TEXT, school_loc TEXT, school_id TEXT, place INTEGER,
+	place_printed TEXT, tie INTEGER, competitors INTEGER, atts TEXT, ord INTEGER);
+CREATE TABLE roster_team(team TEXT PRIMARY KEY, kind TEXT, event TEXT, year INTEGER,
+	comp_no TEXT, title TEXT, team_index TEXT, seq INTEGER, school_id TEXT, school_printed TEXT,
+	ord INTEGER);
+CREATE TABLE roster_member(team TEXT, seq INTEGER, name_printed TEXT, name TEXT, yob INTEGER,
+	dancer_id INTEGER, ord INTEGER);
+CREATE TABLE result_roster(team TEXT, event TEXT, year INTEGER, comp_no TEXT, school_id TEXT,
+	result_address TEXT, join_kind TEXT, via_split INTEGER, roster_teams INTEGER,
+	result_teams INTEGER, roster_index TEXT, result_letter TEXT, ord INTEGER);
+`;
+var TEAMS_INDEXES = [
+  "CREATE INDEX result_ey ON result(event COLLATE NOCASE, year)",
+  "CREATE INDEX result_year ON result(year)",
+  "CREATE INDEX roster_team_ey ON roster_team(event COLLATE NOCASE, year)",
+  "CREATE INDEX roster_team_year ON roster_team(year)",
+  "CREATE INDEX roster_member_team ON roster_member(team)",
+  "CREATE INDEX result_roster_ey ON result_roster(event COLLATE NOCASE, year)",
+  "CREATE INDEX result_roster_year ON result_roster(year)"
+];
+async function readTables(rel, tables) {
+  const out = {};
+  for (const t of tables) {
+    await rel.fetch(tableAsset(t));
+    out[t] = await readParquet(rel.path(tableAsset(t)));
+  }
+  return out;
+}
+var teamsIndex = {
+  name: "teams",
+  version: "1",
+  inputs: TEAM_TABLES.map(tableAsset),
+  says: "the team results, the roster teams with their members, and how they join, by event-year",
+  load: (rel) => readTables(rel, TEAM_TABLES),
+  build(_rel, out, loaded) {
+    const t = loaded;
+    out.run(TEAMS_SCHEMA);
+    const ey = new Map;
+    const putEy = out.prepare("INSERT OR IGNORE INTO event_year VALUES (?, ?, ?)");
+    for (const r of t.event_years) {
+      const k = str(r.event_year);
+      const event = str(r.event);
+      const year = num(r.year);
+      if (k === null || event === null || year === null)
+        continue;
+      ey.set(k, { event, year });
+      putEy.run(k, event, year);
+    }
+    const putR = out.prepare("INSERT OR IGNORE INTO result VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    let ord = 0;
+    for (const r of t.team_results)
+      putR.run(str(r.address), str(r.slug), str(r.event), num(r.year), str(r.card), str(r.comp_no), str(r.title), str(r.category), num(r.hands), str(r.letter), str(r.label), str(r.name_printed), str(r.school_printed), str(r.school_loc), str(r.school_id), num(r.place), str(r.place_printed), num(r.tie), num(r.competitors), JSON.stringify(strs(r.atts)), ord++);
+    const putT = out.prepare("INSERT OR IGNORE INTO roster_team VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    for (const r of t.roster_teams) {
+      const e = ey.get(str(r.event_year) ?? "");
+      putT.run(str(r.team), str(r.kind), e?.event ?? null, num(r.year) ?? e?.year ?? null, str(r.comp_no), str(r.title), str(r.team_index), num(r.seq), str(r.school_id), str(r.school_print_materialized), ord++);
+    }
+    const putM = out.prepare("INSERT INTO roster_member VALUES (?, ?, ?, ?, ?, ?, ?)");
+    for (const r of t.roster_members)
+      putM.run(str(r.team), num(r.seq), typeof r.name_printed === "string" ? r.name_printed : "", str(r.name), num(r.yob), num(r.dancer_id), ord++);
+    const putJ = out.prepare("INSERT INTO result_roster VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    for (const r of t.team_result_rosters) {
+      const e = ey.get(str(r.event_year) ?? "");
+      putJ.run(str(r.team), e?.event ?? null, e?.year ?? null, str(r.comp_no), str(r.school_id), str(r.result_address), str(r.join_kind), num(r.via_split) === 1 ? 1 : 0, num(r.roster_teams), num(r.result_teams), str(r.roster_index), str(r.result_letter), ord++);
+    }
+    for (const s of TEAMS_INDEXES)
+      out.run(s);
+  }
+};
+var EVENTS_SCHEMA = `CREATE TABLE event_year(event TEXT NOT NULL, year INTEGER NOT NULL,
+	date_lo TEXT, date_hi TEXT, resolution TEXT, source TEXT, date_printed TEXT, place TEXT,
+	place_printed TEXT, PRIMARY KEY(event, year))`;
+var eventsIndex = {
+  name: "events",
+  version: "1",
+  inputs: [tableAsset("event_years")],
+  says: "every event-year: its dates (and how fine they are) and its place",
+  load: (rel) => readTables(rel, ["event_years"]),
+  build(_rel, out, loaded) {
+    const rows = loaded.event_years ?? [];
+    out.run(EVENTS_SCHEMA);
+    const put = out.prepare("INSERT OR IGNORE INTO event_year VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    for (const r of rows) {
+      const event = str(r.event);
+      const year = num(r.year);
+      if (event === null || year === null)
+        continue;
+      put.run(event, year, str(r.date_lo), str(r.date_hi), str(r.resolution), str(r.source), JSON.stringify(strs(r.date_printed)), str(r.place), JSON.stringify(strs(r.place_printed)));
+    }
+    out.run("CREATE INDEX event_year_event ON event_year(event COLLATE NOCASE)");
+  }
+};
+function whereOf(q, prefix = "") {
+  const where = [];
+  const args = [];
+  if (q.event !== undefined) {
+    where.push(`${prefix}event = ? COLLATE NOCASE`);
+    args.push(q.event);
+  }
+  if (q.year !== undefined) {
+    where.push(`${prefix}year = ?`);
+    args.push(q.year);
+  }
+  return { sql: where.length === 0 ? "" : ` WHERE ${where.join(" AND ")}`, args };
+}
+
+class TeamFinder2 {
+  rel;
+  constructor(rel) {
+    this.rel = rel;
+  }
+  db() {
+    return this.rel.indexDb("teams");
+  }
+  async results(q = {}) {
+    const db = await this.db();
+    const w = whereOf(q);
+    const rows = db.query(`SELECT address, competition, event, year, card, comp_no, title, category, hands, letter,
+				        label, name_printed, school_printed, school_loc, school_id, place, place_printed, tie,
+				        competitors, atts
+				 FROM result${w.sql} ORDER BY year, event, competition, place IS NULL, place, ord`).all(...w.args);
+    return {
+      tag: this.rel.tag,
+      asked: q,
+      results: rows.map((r) => ({ ...r, atts: JSON.parse(r.atts) }))
+    };
+  }
+  async rosters(q = {}) {
+    const db = await this.db();
+    const w = whereOf(q, "t.");
+    const teams = db.query(`SELECT team, kind, event, year, comp_no, title, team_index, seq, school_id, school_printed
+				 FROM roster_team t${w.sql} ORDER BY year, event, ord`).all(...w.args);
+    const members = new Map;
+    for (const m of db.query(`SELECT m.team AS team, m.seq AS seq, m.name_printed AS name_printed, m.name AS name,
+				        m.yob AS yob, m.dancer_id AS dancer_id
+				 FROM roster_member m JOIN roster_team t ON t.team = m.team${w.sql}
+				 ORDER BY m.team, m.seq, m.ord`).all(...w.args)) {
+      const { team, ...rest } = m;
+      let list = members.get(team);
+      if (list === undefined)
+        members.set(team, list = []);
+      list.push({ ...rest, dancer_scope: scope(rest.dancer_id) });
+    }
+    return {
+      tag: this.rel.tag,
+      asked: q,
+      teams: teams.map((t) => ({ ...t, members: members.get(t.team) ?? [] }))
+    };
+  }
+  async resultRosters(q = {}) {
+    const db = await this.db();
+    const w = whereOf(q);
+    const rows = db.query(`SELECT team, event, year, comp_no, school_id, result_address, join_kind, via_split,
+				        roster_teams, result_teams, roster_index, result_letter
+				 FROM result_roster${w.sql} ORDER BY year, event, ord`).all(...w.args);
+    return {
+      tag: this.rel.tag,
+      asked: q,
+      joins: rows.map((r) => ({ ...r, via_split: r.via_split === 1 }))
+    };
+  }
+}
+
+class EventFinder2 {
+  rel;
+  constructor(rel) {
+    this.rel = rel;
+  }
+  async years(q = {}) {
+    const db = await this.rel.indexDb("events");
+    const w = whereOf(q);
+    const rows = db.query(`SELECT event, year, date_lo, date_hi, resolution, source, date_printed, place, place_printed
+				 FROM event_year${w.sql} ORDER BY year, event`).all(...w.args);
+    return {
+      tag: this.rel.tag,
+      asked: q,
+      years: rows.map((r) => ({
+        ...r,
+        date_printed: JSON.parse(r.date_printed),
+        place_printed: JSON.parse(r.place_printed)
+      }))
+    };
+  }
+}
+
 function defaultBuilders2() {
-  return [schoolsIndex, feisesIndex, compsIndex, dancersIndex, staffIndex];
+  return [schoolsIndex, feisesIndex, compsIndex, dancersIndex, staffIndex, teamsIndex, eventsIndex];
 }
 var indexDir = (rel) => join(rel.dir, "index");
 var indexPath2 = (rel, name) => join(indexDir(rel), `${name}.sqlite`);
@@ -1623,6 +1855,8 @@ function buildIndex2(rel, b, o) {
   const key = indexKey2(rel, b);
   if (!o.force && keyOf(out) === key)
     return out;
+  if (b.load !== undefined && o.loaded === undefined)
+    throw new Error(`archive-client: index "${b.name}" reads its inputs first: build it with ensureIndex (or rel.index)`);
   mkdirSync(indexDir(rel), { recursive: true });
   const tmp = `${out}.building.${process.pid}`;
   rmSync(tmp, { force: true });
@@ -1632,7 +1866,7 @@ function buildIndex2(rel, b, o) {
     db.run("PRAGMA journal_mode = OFF");
     db.run("PRAGMA synchronous = OFF");
     db.run("CREATE TABLE meta(k TEXT PRIMARY KEY, v TEXT NOT NULL)");
-    db.transaction(() => b.build(rel, db))();
+    db.transaction(() => b.build(rel, db, o.loaded))();
     const put = db.prepare("INSERT INTO meta(k, v) VALUES (?, ?)");
     put.run("key", key);
     put.run("builder", b.name);
@@ -1649,6 +1883,12 @@ function buildIndex2(rel, b, o) {
   o.log?.(`index ${rel.tag} ${b.name}: built in ${((performance.now() - t0) / 1000).toFixed(1)} s`);
   return out;
 }
+async function ensureIndex2(rel, b, o) {
+  if (!o.force && isCurrent2(rel, b))
+    return indexPath2(rel, b.name);
+  const loaded = b.load === undefined ? undefined : await b.load(rel);
+  return buildIndex2(rel, b, { ...o, loaded });
+}
 function listIndexes2(rel) {
   const dir = indexDir(rel);
   if (!existsSync(dir))
@@ -2058,6 +2298,81 @@ var FEATURES2 = [
     since: 265,
     calls: "comps.resolve, comps.syllabus, comps.syllabusFor, registrations.resolve (the comps index)"
   },
+  {
+    feature: "teams",
+    needs: [
+      ...[
+        "slug",
+        "address",
+        "event",
+        "year",
+        "card",
+        "comp_no",
+        "title",
+        "category",
+        "hands",
+        "letter",
+        "label",
+        "name_printed",
+        "school_printed",
+        "school_loc",
+        "school_id",
+        "place",
+        "place_printed",
+        "tie",
+        "competitors",
+        "atts"
+      ].map((c) => `table:team_results.${c}`),
+      ...[
+        "team",
+        "kind",
+        "event_year",
+        "year",
+        "comp_no",
+        "title",
+        "team_index",
+        "seq",
+        "school_id",
+        "school_print_materialized"
+      ].map((c) => `table:roster_teams.${c}`),
+      ...["team", "seq", "name_printed", "name", "yob", "dancer_id"].map((c) => `table:roster_members.${c}`),
+      ...[
+        "event_year",
+        "comp_no",
+        "team",
+        "result_address",
+        "school_id",
+        "join_kind",
+        "via_split",
+        "roster_teams",
+        "result_teams",
+        "roster_index",
+        "result_letter"
+      ].map((c) => `table:team_result_rosters.${c}`),
+      "table:event_years.event_year",
+      "table:event_years.event",
+      "table:event_years.year"
+    ],
+    since: 260,
+    calls: "teams.results, teams.rosters, teams.resultRosters (the teams index)"
+  },
+  {
+    feature: "events",
+    needs: [
+      "event_year",
+      "event",
+      "year",
+      "date_lo",
+      "date_hi",
+      "resolution",
+      "source",
+      "date_printed",
+      "place",
+      "place_printed"
+    ].map((c) => `table:event_years.${c}`),
+    since: 260,
+    calls: "events.years (the events index)"
+  },
   {
     feature: "staff",
     needs: [
@@ -2072,6 +2387,13 @@ var FEATURES2 = [
   }
 ];
 async function hasNeed(probe, n) {
+  const t = /^table:([A-Za-z_]+)(?:\.([A-Za-z_]+))?$/.exec(n);
+  if (t !== null) {
+    if (probe.tableColumns === undefined)
+      return false;
+    const cols = await probe.tableColumns(t[1]);
+    return t[2] === undefined ? cols.size > 0 : cols.has(t[2]);
+  }
   const m = /^(results|majors):([A-Za-z_]+)(?:\.([A-Za-z_]+))?$/.exec(n);
   if (m === null)
     return probe.publishes(n);
@@ -2143,6 +2465,8 @@ class Release2 {
   staff;
   comps;
   registrations;
+  teams;
+  events;
   opts;
   handles = new Map;
   remoteAssets = null;
@@ -2163,6 +2487,8 @@ class Release2 {
     this.staff = new StaffFinder2(this);
     this.comps = new CompResolver2(this);
     this.registrations = new RegistrationResolver2(this, this.comps, opts.dancerResolver);
+    this.teams = new TeamFinder2(this);
+    this.events = new EventFinder2(this);
   }
   receipt() {
     return readReceipt(this.dir) ?? { tag: this.tag, source: "unknown", files: {} };
@@ -2207,7 +2533,14 @@ class Release2 {
       await this.fetch(name);
       return this.db(name);
     },
-    publishes: (asset) => this.publishes(asset)
+    publishes: (asset) => this.publishes(asset),
+    tableColumns: async (table) => {
+      const asset = tableAsset(table);
+      if (!await this.publishes(asset))
+        return new Set;
+      await this.fetch(asset);
+      return parquetColumns(this.path(asset));
+    }
   };
   checked = new Map;
   async capability(feature) {
@@ -2304,7 +2637,7 @@ class Release2 {
     if (FEATURES2.some((f) => f.feature === b.name))
       await this.require(b.name);
     await this.fetch(...b.inputs);
-    return buildIndex2(this, b, { force: o.force ?? false, log: this.opts.log });
+    return ensureIndex2(this, b, { force: o.force ?? false, log: this.opts.log });
   }
   async indexDb(name) {
     const key = `index:${name}`;
@@ -2523,7 +2856,7 @@ class ReleaseManager2 {
       await rel.fetch(...b.inputs);
       built.push({
         name,
-        path: buildIndex2(rel, b, { force: o.force ?? false, log: this.opts.log })
+        path: await ensureIndex2(rel, b, { force: o.force ?? false, log: this.opts.log })
       });
     }
     rel.close();
@@ -2596,4 +2929,4 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, NO_CALENDAR2, FeisFinder2, StaffFinder2, SchoolResolver2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, nameOrderOf, DancerResolver2, readPopulation2, canonicalOf2, CompResolver2, NO_CALENDAR2, FeisFinder2, StaffFinder2, SchoolResolver2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   nameOrderOf,
   openRelease2,
   releases2
-} from "./chunks/index-3va2jzse.js";
+} from "./chunks/index-v8e0qe9f.js";
 import"./chunks/index-hne1wadw.js";
 import"./chunks/index-hghdy980.js";
 
@@ -50,6 +50,12 @@ var USAGE = `usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]
   majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]
                                     the majors: every event and its years; an event's
                                     competitions; a competition's, an event's or a dancer's rows
+  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]
+                                    the team result rows of an event-year; with --rosters its
+                                    roster teams and their dancers; with --joins how each roster
+                                    team meets the results
+  events [--release <spec>] [--event <e>] [--year <y>]
+                                    each event-year's dates and place
   teacher [--release <spec>] <name|TD number>
                                     the staff lists' people: where they taught, the register,
                                     where they sat
@@ -313,6 +319,14 @@ async function resolveVerb(rel, what, args, p, say, stdin) {
       throw new Error("resolve comp|dancer|registrations");
   }
 }
+function eventYearOf(p) {
+  const event = p.flags.get("--event");
+  const year = p.flags.get("--year");
+  return {
+    ...event !== undefined ? { event } : {},
+    ...year !== undefined ? { year: Number(year) } : {}
+  };
+}
 async function main(argv, io = {}) {
   const say = io.say ?? ((s) => console.log(s));
   const log = io.log ?? ((s) => console.error(s));
@@ -630,6 +644,56 @@ async function main(argv, io = {}) {
           rel.close();
         }
       }
+      case "teams": {
+        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        try {
+          const q = eventYearOf(p);
+          if (p.bools.has("--rosters")) {
+            const a = await rel.teams.rosters(q);
+            out(a, () => {
+              for (const t of a.teams) {
+                say(`  ${t.year} ${t.event ?? "?"}  ${t.comp_no ?? "-"}  ${t.team_index ?? "-"}  ${t.school_id ?? "(no id)"} "${t.school_printed ?? ""}"  ${t.title ?? ""}  [${t.kind}]`);
+                for (const m of t.members)
+                  say(`      ${m.seq}  ${m.dancer_id ?? "-"}  ${m.name_printed}${m.yob === null ? "" : ` (${m.yob})`}`);
+              }
+              say(`${a.teams.length} roster team(s) in ${a.tag}`);
+            });
+            return a.teams.length === 0 ? 1 : 0;
+          }
+          if (p.bools.has("--joins")) {
+            const a = await rel.teams.resultRosters(q);
+            out(a, () => {
+              for (const j of a.joins)
+                say(`  ${j.year ?? "?"} ${j.event ?? "?"}  ${j.comp_no ?? "-"}  ${j.team}  ${j.join_kind}  ${j.result_address ?? "-"}  roster ${j.roster_index ?? "-"} result ${j.result_letter ?? "-"}`);
+              say(`${a.joins.length} join(s) in ${a.tag}`);
+            });
+            return a.joins.length === 0 ? 1 : 0;
+          }
+          const a = await rel.teams.results(q);
+          out(a, () => {
+            for (const r of a.results)
+              say(`  ${r.address}  ${r.place_printed ?? "-"}  ${r.label ?? "-"}  ${r.school_id ?? "(no id)"} "${r.school_printed ?? ""}"  ${r.title ?? ""}${r.atts.length > 0 ? `  [${r.atts.join(",")}]` : ""}`);
+            say(`${a.results.length} team result(s) in ${a.tag}`);
+          });
+          return a.results.length === 0 ? 1 : 0;
+        } finally {
+          rel.close();
+        }
+      }
+      case "events": {
+        const rel = await openRelease2(spec, { ...opts, assets: [] });
+        try {
+          const a = await rel.events.years(eventYearOf(p));
+          out(a, () => {
+            for (const y of a.years)
+              say(`  ${y.event} ${y.year}  ${y.date_lo ?? "?"}..${y.date_hi ?? "?"} (${y.resolution ?? "-"}, ${y.source ?? "-"})  ${y.place ?? "-"}${y.place_printed.length > 0 ? ` "${y.place_printed.join("; ")}"` : ""}`);
+            say(`${a.years.length} event-year(s) in ${a.tag}`);
+          });
+          return a.years.length === 0 ? 1 : 0;
+        } finally {
+          rel.close();
+        }
+      }
       case "teacher":
       case "adjudicator": {
         if (rest.length === 0) {

package/dist/index.js

@@ -17,11 +17,14 @@ import {
   FeisFinder2,
   StaffFinder2,
   SchoolResolver2,
+  TeamFinder2,
+  EventFinder2,
   defaultBuilders2,
   indexPath2,
   indexKey2,
   isCurrent2,
   buildIndex2,
+  ensureIndex2,
   listIndexes2,
   readPin2,
   youngest2,
@@ -41,7 +44,7 @@ import {
   openCached2,
   ReleaseManager2,
   releases2
-} from "./chunks/index-3va2jzse.js";
+} from "./chunks/index-v8e0qe9f.js";
 import {
   cacheRoot2,
   repoOf2
@@ -60,6 +63,7 @@ export {
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
   DancerResolver2 as DancerResolver,
+  EventFinder2 as EventFinder,
   FEATURES2 as FEATURES,
   FEIS_LOCAL_ID_FLOOR2 as FEIS_LOCAL_ID_FLOOR,
   FeisFinder2 as FeisFinder,
@@ -72,6 +76,7 @@ export {
   ResultFinder2 as ResultFinder,
   SchoolResolver2 as SchoolResolver,
   StaffFinder2 as StaffFinder,
+  TeamFinder2 as TeamFinder,
   buildIndex2 as buildIndex,
   cacheRoot2 as cacheRoot,
   canonicalOf2 as canonicalOf,
@@ -81,6 +86,7 @@ export {
   cutOf2 as cutOf,
   dancerResolverOf2 as dancerResolverOf,
   defaultBuilders2 as defaultBuilders,
+  ensureIndex2 as ensureIndex,
   fallbackRemote2 as fallbackRemote,
   ghRemote2 as ghRemote,
   httpsRemote2 as httpsRemote,

package/dist/types/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import type { OpenOptions } from "./release.js";
-export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  capabilities [--release <spec>]   what the release carries of what the client reads, from\n                                    its own schema: each feature full or missing (its calls\n                                    refuse, naming the first cut that publishes it)\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)\n                                    and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--population girls|boys] [--rows]\n                                    the dancers a name reaches, each with its evidence\n                                    (name level, age, school, population) and the arm; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (or the prior year's)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>] [--population girls|boys]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,\n                                    population?}, a registration: {name, school?, codes[], feis,\n                                    year?, population?})\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
+export declare const USAGE = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json]\n\n  config repo <owner/name>          set the user-local repository the releases come from\n  list [--remote]                   the cached releases (size, files, indexes, the pin), and\n                                    with --remote the published tags\n  fetch [--release <spec>] [--assets results,majors,<file>...]\n                                    download, verify and cache a release (default: results)\n  pin <spec>                        the user-local pin: what a bare open (spec \"pinned\") opens\n  unpin                             remove the pin (a bare open is then \"latest\")\n  current                           the pin, and whether it is cached\n  add <dir> --tag <tag>             add a release built locally (its MANIFEST.json and files)\n                                    to the cache under its tag\n  index [--release <spec>] [<name>...] [--force]\n                                    build the per-tag indexes (default: every one)\n  verify [--release <spec>]         re-hash every cached file against its receipt\n  capabilities [--release <spec>]   what the release carries of what the client reads, from\n                                    its own schema: each feature full or missing (its calls\n                                    refuse, naming the first cut that publishes it)\n  prune [--keep N] [--dry-run]      remove all but the N newest cached releases (default 1)\n                                    and the pinned one\n  rm <tag> [--dry-run]              remove one cached release (not the pinned one)\n  drop-indexes [<tag>] [--dry-run]  remove the index files (of one release, or of every one)\n  feis [--release <spec>] [--platform <p>] [--code <c>] [--id <id>] [--name <glob>] [--year <y>]\n                                    the feises a query names\n  series [--release <spec>] <name|host code|feis id>\n                                    the series a name, a host code (fweb:ABC) or any feis id\n                                    names: its years, hosts, codes and next instance\n  school [--release <spec>] <print|school_id> [--region <code>]\n                                    a school print or id to the published schools\n  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>\n         [--order surname-first|given-first] [--school <print|id>]\n         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]\n         [--population girls|boys] [--rows]\n                                    the dancers a name reaches, each with its evidence\n                                    (name level, age, school, population) and the arm; the results of\n                                    the one dancer where one answers (or --rows for each)\n  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]\n          [--school <print|id>] [--year <y>] [--limit <n>]\n                                    the published result rows, prints and ids\n  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]\n                                    the majors: every event and its years; an event's\n                                    competitions; a competition's, an event's or a dancer's rows\n  teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]\n                                    the team result rows of an event-year; with --rosters its\n                                    roster teams and their dancers; with --joins how each roster\n                                    team meets the results\n  events [--release <spec>] [--event <e>] [--year <y>]\n                                    each event-year's dates and place\n  teacher [--release <spec>] <name|TD number>\n                                    the staff lists' people: where they taught, the register,\n                                    where they sat\n  adjudicator [--release <spec>] <name|TD number>\n                                    the register's and the panels' people: the same answer\n  comp [--release <spec>] <feis> <code> [--year <y>] [--title <t>]\n                                    a feis's own comp code to the comp it names, through that\n                                    feis's syllabus (or the prior year's)\n  syllabus [--release <spec>] <feis> [year]\n                                    one feis-year's comps, in printed order\n  syllabus [--release <spec>] --for <series> [year]\n                                    a series' syllabus for a year: that year's where held,\n                                    else the newest, saying which and what it is read from\n  resolve comp [<feis> <code>] [--year <y>] [--title <t>]\n  resolve dancer [<name>] [--school <s>] [--comp <feis>/<code> | --yob <y> | --band <b> --year <y>]\n                 [--order <o>] [--as-of <date>] [--population girls|boys]\n  resolve registrations\n                                    JSONL out, one answer per line; with no positional the\n                                    questions are JSONL on stdin, one per line (a comp:\n                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,\n                                    population?}, a registration: {name, school?, codes[], feis,\n                                    year?, population?})\n\n  <spec>: pinned (the default) | latest | a cut (42, 42.1) | a tag (archive-YYYY.MM.DD-N)";
 export interface Parsed {
     positional: string[];
     flags: Map<string, string>;

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { NAME_LEVELS, type NameLevel, nameLevel } from "./dancers-names.js";
 export { type Comp, type CompAnswer, type CompKind, type CompQuery, CompResolver, type CompSource, type FeisPlace, type SyllabusAnswer, type SyllabusForAnswer, type SyllabusSource, type TitleCheck, canonicalOf, } from "./comps.js";
 export { type ClientOptions, cacheRoot, repoOf } from "./config.js";
 export { type Feis, type FeisAnswer, FeisFinder, type FeisQuery, NO_CALENDAR, type Series, type SeriesAnswer, type SeriesInstance, type SeriesNext, } from "./feises.js";
-export { type IndexBuilder, type IndexFile, buildIndex, defaultBuilders, indexKey, indexPath, isCurrent, listIndexes, } from "./indexes.js";
+export { type IndexBuilder, type IndexFile, buildIndex, defaultBuilders, ensureIndex, indexKey, indexPath, isCurrent, listIndexes, } from "./indexes.js";
 export { type CachedRelease, type ReleaseList, ReleaseManager, type RemovalPlan, releases, } from "./manager.js";
 export { type Registered, type Sat, type StaffAnswer, StaffFinder, type StaffPerson, type Taught, type TdLink, } from "./people.js";
 export { type Pin, readPin } from "./pin.js";
@@ -15,4 +15,5 @@ export { type MajorCompetition, type MajorEvent, MajorsFinder, type ResultAnswer
 export { type DancerAnswerLike, type DancerQueryLike, type DancerResolverLike, type DancerUnavailable, type RegistrationRow, type ResolvedDancer, RegistrationResolver, type ResolvedRegistration, dancerResolverOf, youngest, } from "./registrations.js";
 export { type SchoolAnswer, type SchoolCandidate, type SchoolQuery, SchoolResolver, type SchoolRung, } from "./schools.js";
 export { type Capability, FEATURES, type Feature, type SchemaProbe, capabilityOf, columnsOf, needsRelease, } from "./schema.js";
+export { EventFinder, type EventYear, type EventYearQuery, type ResultRoster, type RosterMember, type RosterTeam, TeamFinder, type TeamResult, } from "./teams.js";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/indexes.d.ts

@@ -6,7 +6,8 @@ export interface IndexBuilder {
     readonly inputs: readonly string[];
     readonly says: string;
     keyParts?(rel: Release): string[];
-    build(rel: Release, out: Database): void;
+    load?(rel: Release): Promise<unknown>;
+    build(rel: Release, out: Database, loaded?: unknown): void;
 }
 export declare function defaultBuilders(): IndexBuilder[];
 export declare const indexDir: (rel: {
@@ -21,7 +22,12 @@ export declare function isCurrent(rel: Release, b: IndexBuilder): boolean;
 export declare function buildIndex(rel: Release, b: IndexBuilder, o: {
     force: boolean;
     log?: (line: string) => void;
+    loaded?: unknown;
 }): string;
+export declare function ensureIndex(rel: Release, b: IndexBuilder, o: {
+    force: boolean;
+    log?: (line: string) => void;
+}): Promise<string>;
 export interface IndexFile {
     name: string;
     path: string;

package/dist/types/parquet.d.ts

@@ -0,0 +1,4 @@
+export declare const tableAsset: (table: string) => string;
+export declare function plain(v: unknown): unknown;
+export declare function readParquet(path: string, columns?: readonly string[]): Promise<Record<string, unknown>[]>;
+export declare function parquetColumns(path: string): Promise<Set<string>>;

package/dist/types/release.d.ts

@@ -12,6 +12,7 @@ import { MajorsFinder, ResultFinder } from "./results.js";
 import { type Capability } from "./schema.js";
 import { type SchoolReaderChoice, SchoolResolver } from "./schools.js";
 import { type ReleaseSpec } from "./tag.js";
+import { EventFinder, TeamFinder } from "./teams.js";
 export interface OpenOptions extends ClientOptions {
     assets?: readonly string[];
     remote?: Remote;
@@ -41,6 +42,8 @@ export declare class Release {
     readonly staff: StaffFinder;
     readonly comps: CompResolver;
     readonly registrations: RegistrationResolver;
+    readonly teams: TeamFinder;
+    readonly events: EventFinder;
     private readonly opts;
     private readonly handles;
     private remoteAssets;

package/dist/types/schema.d.ts

@@ -14,6 +14,7 @@ export interface Capability extends Feature {
 export interface SchemaProbe {
     db(name: string): Promise<Database>;
     publishes(asset: string): Promise<boolean>;
+    tableColumns?(table: string): Promise<Set<string>>;
 }
 export declare function hasNeed(probe: SchemaProbe, n: string): Promise<boolean>;
 export declare function capabilityOf(probe: SchemaProbe, f: Feature): Promise<Capability>;

package/dist/types/teams.d.ts

@@ -0,0 +1,105 @@
+import type { IndexBuilder } from "./indexes.js";
+import type { Release } from "./release.js";
+export interface EventYearQuery {
+    event?: string;
+    year?: number;
+}
+export interface TeamResult {
+    address: string;
+    competition: string;
+    event: string;
+    year: number;
+    card: string | null;
+    comp_no: string | null;
+    title: string | null;
+    category: string | null;
+    hands: number | null;
+    letter: string | null;
+    label: string | null;
+    name_printed: string | null;
+    school_printed: string | null;
+    school_loc: string | null;
+    school_id: string | null;
+    place: number | null;
+    place_printed: string | null;
+    tie: number | null;
+    competitors: number | null;
+    atts: string[];
+}
+export interface RosterMember {
+    seq: number;
+    name_printed: string;
+    name: string | null;
+    yob: number | null;
+    dancer_id: number | null;
+    dancer_scope: "per-release" | "stable" | null;
+}
+export interface RosterTeam {
+    team: string;
+    kind: string;
+    event: string | null;
+    year: number;
+    comp_no: string | null;
+    title: string | null;
+    team_index: string | null;
+    seq: number | null;
+    school_id: string | null;
+    school_printed: string | null;
+    members: RosterMember[];
+}
+export interface ResultRoster {
+    team: string;
+    event: string | null;
+    year: number | null;
+    comp_no: string | null;
+    school_id: string | null;
+    result_address: string | null;
+    join_kind: string;
+    via_split: boolean;
+    roster_teams: number | null;
+    result_teams: number | null;
+    roster_index: string | null;
+    result_letter: string | null;
+}
+export interface EventYear {
+    event: string;
+    year: number;
+    date_lo: string | null;
+    date_hi: string | null;
+    resolution: string | null;
+    source: string | null;
+    date_printed: string[];
+    place: string | null;
+    place_printed: string[];
+}
+export declare const teamsIndex: IndexBuilder;
+export declare const eventsIndex: IndexBuilder;
+export declare class TeamFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    private db;
+    results(q?: EventYearQuery): Promise<{
+        tag: string;
+        asked: EventYearQuery;
+        results: TeamResult[];
+    }>;
+    rosters(q?: EventYearQuery): Promise<{
+        tag: string;
+        asked: EventYearQuery;
+        teams: RosterTeam[];
+    }>;
+    resultRosters(q?: EventYearQuery): Promise<{
+        tag: string;
+        asked: EventYearQuery;
+        joins: ResultRoster[];
+    }>;
+}
+export declare class EventFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    years(q?: EventYearQuery): Promise<{
+        tag: string;
+        asked: EventYearQuery;
+        years: EventYear[];
+    }>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.3.1",
+	"version": "0.4.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",
@@ -45,7 +45,8 @@
 	},
 	"dependencies": {
 		"@finbheara/domain": "0.49.0",
-		"@finbheara/names": "0.22.0"
+		"@finbheara/names": "0.22.0",
+		"hyparquet": "1.31.2"
 	},
 	"devDependencies": {
 		"typescript": "7.0.2"