@finbheara/archive-client 0.28.0 → 0.30.0

package/README.md

@@ -662,11 +662,15 @@ o.feises;    // [{ occurrence_id, occurrence_ids, name_printed, date_lo, date_hi
 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,
-             //    results_competitions, results_feis_ids, held_out, version, versions, captured_date, sha256,
+             //    results_competitions, results_feis_ids, held_out, merged_into, 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, ... }]
+const d = await rel.upcoming.departures({ reason: ["results", "merged"] });  // feis, field_id, from, to
+d.departures; // [{ field_id, feis_id, occurrence_id, feis_brand_id, competition_code, date_lo, date_hi,
+             //    reason, competitions, feis_ids, merged_into, held_out, last_version }]
 ```
 
 `upcoming.feises` is every occurrence of the cut's feis-index the release holds no results of:
@@ -677,7 +681,9 @@ 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), `held-out` (the results exist and the release holds them out: the platform door's knockout
+join), `merged` (the host registered it apart and ran it as one competition with another field: its
+results are that field's, and `merged_into` names the survivor, the first by `field_id`, which
+reads `results`), `held-out` (the results exist and the release holds them out: the platform door's knockout
 lists the competition, a team, music or arts event, and `held_out` names each competition with the
 knockout's reason, so there is nothing to score against), `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`,
@@ -687,6 +693,13 @@ QuickFeis registrant list's field reads it off the list's own by-event label (`s
 list's two documents (`no-event-section`, `event-rows-differ`); `[]` on any other field.
 `limits` names what the capture cannot show (`registered-not-danced`, `paid-in-full-only`, ...).
 
+THE DEPARTURE RECORD IS THE STATE. Every state but `pending` is how the field left the list, and
+`upcoming.departures` answers one record per departed field: its `reason`, what it became
+(`competitions`, the results join; `merged_into`; `held_out`) and `last_version`. It is
+re-derived on every cut from what the release holds, so a field that left keeps its record on every
+later cut while the corpus keeps its capture, and a `passed` field whose results arrive later reads
+`results` on that cut: a consumer that skips a release still sees it.
+
 `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`
@@ -764,7 +777,11 @@ codes, a plausible answer and a wrong one. So an unheld feis-year there answers
 over the newest earlier syllabus, and a code with no title is `none`, saying why. The code of a
 held feis-year is still read from that feis-year's own competitions.
 
-A feis the release holds names itself, its year and its series. A series instance or brand id
+A feis the release holds names itself, its year and its series. A platform feis id
+(`<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
 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

package/dist/chunks/{index-5rnb63kw.js → index-db578n4y.js}

@@ -2114,6 +2114,7 @@ var entryOf = (c) => ({
   ...c.age !== null ? { age: c.age } : {},
   comp: c
 });
+var PLATFORM_FEIS_ID = /^[a-z]+:[^:\s]+$/;
 
 class CompResolver2 {
   rel;
@@ -2156,9 +2157,19 @@ class CompResolver2 {
         return this.ofSeries(asked, only, y, "series");
     }
     const m = /^([^:]+):(.*?)(\d{2})$/.exec(asked);
-    if (m !== null && !/^\d+$/.test(`${m[2]}${m[3]}`)) {
-      const [, token, stem, yy] = m;
-      const brands = await this.rel.feises.codeStem(token, stem);
+    const stemmed = m !== null && !/^\d+$/.test(`${m[2]}${m[3]}`);
+    const [, token, stem, yy] = m ?? [];
+    const brands = stemmed ? await this.rel.feises.codeStem(token, stem) : [];
+    const own = PLATFORM_FEIS_ID.test(asked) ? await this.compYears(asked) : [];
+    if (own.length === 1) {
+      const held = own[0];
+      const y = year ?? held;
+      const brand = brands.length === 1 ? brands[0] : null;
+      if (y === held || brand === null)
+        return { asked, feis_ids: [asked], brand_id: brand, year: y, held: y === held, via: "id" };
+      return this.ofSeries(asked, brand, y, "id");
+    }
+    if (stemmed) {
       const y = year ?? 2000 + Number(yy);
       if (brands.length === 1)
         return this.ofSeries(asked, brands[0], y, "code-stem");
@@ -2184,6 +2195,10 @@ class CompResolver2 {
     const ids = year === null ? [] : db.query("SELECT feis_id FROM feis WHERE brand_id = ? AND year = ? ORDER BY feis_id").all(brand, year).map((r) => r.feis_id);
     return { asked, feis_ids: ids, brand_id: brand, year, held: ids.length > 0, via };
   }
+  async compYears(feisId) {
+    const db = await this.rel.indexDb("comps");
+    return db.query("SELECT DISTINCT year FROM comp WHERE feis_id = ? AND year IS NOT NULL ORDER BY year").all(feisId).map((r) => r.year);
+  }
   async years(brand) {
     if (brand === null)
       return [];
@@ -3953,10 +3968,12 @@ function needsRelease2(tag, c) {
 var FIELD_STATES2 = [
   "pending",
   "results",
+  "merged",
   "held-out",
   "passed",
   "withdrawn"
 ];
+var DEPARTURE_REASONS2 = FIELD_STATES2.filter((s) => s !== "pending");
 var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
 function fieldOf(r) {
   const countOnly = r.count_only === 1;
@@ -3989,6 +4006,7 @@ function fieldOf(r) {
     results_competitions: json(r.results_competitions, []),
     results_feis_ids: json(r.results_feis_ids, []),
     held_out: json(r.held_out, []),
+    merged_into: r.merged_into ?? null,
     version: r.version,
     versions: json(r.versions, []),
     captured_date: r.captured_date,
@@ -4107,6 +4125,37 @@ class UpcomingFinder2 {
     const rows = db.query(sql).all(...args);
     return { tag: this.rel.tag, fields: rows.map(fieldOf) };
   }
+  async departures(q = {}) {
+    const reasons = q.reason === undefined ? DEPARTURE_REASONS2 : typeof q.reason === "string" ? [q.reason] : [...q.reason];
+    const unknown = reasons.filter((r) => !DEPARTURE_REASONS2.includes(r));
+    if (unknown.length > 0)
+      throw new Error(`upcoming.departures: no departure reason ${unknown.map((r) => JSON.stringify(r)).join(", ")} (the reasons are ${DEPARTURE_REASONS2.join(", ")})`);
+    const { tag, fields } = await this.fields({
+      state: reasons,
+      ...q.feis !== undefined ? { feis: q.feis } : {},
+      ...q.field_id !== undefined ? { field_id: q.field_id } : {},
+      ...q.from !== undefined ? { from: q.from } : {},
+      ...q.to !== undefined ? { to: q.to } : {}
+    });
+    return {
+      tag,
+      departures: fields.map((f) => ({
+        field_id: f.field_id,
+        feis_id: f.feis_id,
+        occurrence_id: f.occurrence_id,
+        feis_brand_id: f.feis_brand_id,
+        competition_code: f.competition_code,
+        date_lo: f.date_lo,
+        date_hi: f.date_hi,
+        reason: f.state,
+        competitions: f.results_competitions,
+        feis_ids: f.state === "results" && f.count_only ? f.results_feis_ids : [],
+        merged_into: f.merged_into,
+        held_out: f.held_out,
+        last_version: f.version
+      }))
+    };
+  }
   async entrants(q) {
     const [field] = (await this.fields({ field_id: q.field_id })).fields;
     const db = await this.db("upcoming.entrants");
@@ -4944,4 +4993,4 @@ function staleWarning2(answered, latest, floor, tags = [], command = "idq") {
   return `answered from ${answered}. ${floorTag ?? `cut ${floor.cut}`} is required${why}: run \`${command} use ${floor.cut}\` to get it`;
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, TabFinder2, PanelFinder2, FeisPanelFinder2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, FIELD_STATES2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, TabFinder2, PanelFinder2, FeisPanelFinder2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, FIELD_STATES2, DEPARTURE_REASONS2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-5rnb63kw.js";
+} from "./chunks/index-db578n4y.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -372,9 +372,9 @@ var VERBS = [
       "--version",
       "--brand"
     ],
-    bool: ["--feises"],
+    bool: ["--feises", "--departures"],
     usage: [
-      "  upcoming [--release <spec>] [--state pending,results,held-out,passed,withdrawn] [--feis <id>]",
+      "  upcoming [--release <spec>] [--state pending,results,merged,held-out,passed,withdrawn] [--feis <id>]",
       "           [--from <date>] [--to <date>]",
       "                                    the competitor lists' fields, each with its state, version",
       "                                    and competition reading; --feis a feis, series or",
@@ -383,7 +383,12 @@ var VERBS = [
       "                                    a field's rows (default its current version): each",
       "                                    registrant's arm and candidates",
       "  upcoming --feises [--state upcoming|no-results] [--brand <series>] [--from <date>] [--to <date>]",
-      "                                    the feis-index's occurrences the release holds no results of"
+      "                                    the feis-index's occurrences the release holds no results of",
+      "  upcoming --departures [--state results,merged,held-out,passed,withdrawn] [--feis <id>]",
+      "           [--from <date>] [--to <date>]",
+      "                                    how each field left the list: its reason and what it",
+      "                                    became (results competitions, the surviving field, the",
+      "                                    held-out competitions)"
     ]
   },
   {
@@ -1499,6 +1504,19 @@ async function main(argv, io = {}) {
             return a.feises.length === 0 ? 1 : 0;
           }
           const feis = p.flags.get("--feis");
+          if (p.bools.has("--departures")) {
+            const a = await rel.upcoming.departures({
+              ...state !== undefined ? { reason: state.split(",") } : {},
+              ...feis !== undefined ? { feis } : {},
+              ...range
+            });
+            out(a, () => {
+              for (const d of a.departures)
+                say(`  ${d.date_lo ?? "?"}  ${d.field_id}  ${d.reason}  ${d.reason === "merged" ? `into ${d.merged_into}` : d.reason === "held-out" ? d.held_out.map((h) => `${h.competition} (${h.reason})`).join(", ") : d.competitions.join(", ")}`);
+              say(`${a.departures.length} departure(s) in ${a.tag}`);
+            });
+            return a.departures.length === 0 ? 1 : 0;
+          }
           const a = await rel.upcoming.fields({
             ...state !== undefined ? { state: state.split(",") } : {},
             ...feis !== undefined ? { feis } : {},

package/dist/index.js

@@ -51,6 +51,7 @@ import {
   capabilityOf2,
   needsRelease2,
   FIELD_STATES2,
+  DEPARTURE_REASONS2,
   UpcomingFinder2,
   resolveTag2,
   Release2,
@@ -74,7 +75,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-5rnb63kw.js";
+} from "./chunks/index-db578n4y.js";
 import {
   cacheRoot2,
   repoOf2
@@ -94,6 +95,7 @@ export {
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
   DEFAULT_KEEP2 as DEFAULT_KEEP,
+  DEPARTURE_REASONS2 as DEPARTURE_REASONS,
   DancerResolver2 as DancerResolver,
   EventFinder2 as EventFinder,
   FEATURES2 as FEATURES,

package/dist/types/comps.d.ts

@@ -130,6 +130,7 @@ export declare class CompResolver {
     constructor(rel: Release);
     place(feis: string, year?: number): Promise<FeisPlace>;
     private ofSeries;
+    private compYears;
     private years;
     private compsOf;
     private idsOf;

package/dist/types/index.d.ts

@@ -24,5 +24,5 @@ export { type Capability, FEATURES, type Feature, type SchemaProbe, capabilityOf
 export { type EntryRow, 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, type FieldState, type HeldOut, 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";
+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";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/upcoming.d.ts

@@ -1,6 +1,8 @@
 import type { Release } from "./release.js";
-export type FieldState = "pending" | "results" | "held-out" | "passed" | "withdrawn";
+export type FieldState = "pending" | "results" | "merged" | "held-out" | "passed" | "withdrawn";
 export declare const FIELD_STATES: readonly FieldState[];
+export type DepartureReason = Exclude<FieldState, "pending">;
+export declare const DEPARTURE_REASONS: readonly DepartureReason[];
 export interface HeldOut {
     competition: string;
     reason: string;
@@ -61,6 +63,7 @@ export interface UpcomingField {
     results_competitions: string[];
     results_feis_ids: string[];
     held_out: HeldOut[];
+    merged_into: string | null;
     version: string;
     versions: string[];
     captured_date: string;
@@ -115,6 +118,32 @@ export interface UpcomingFieldQuery {
     from?: string;
     to?: string;
 }
+export interface UpcomingDepartureQuery {
+    reason?: DepartureReason | readonly DepartureReason[];
+    feis?: string;
+    field_id?: string;
+    from?: string;
+    to?: string;
+}
+export interface UpcomingDeparture {
+    field_id: string;
+    feis_id: string;
+    occurrence_id: string | null;
+    feis_brand_id: string | null;
+    competition_code: string | null;
+    date_lo: string | null;
+    date_hi: string | null;
+    reason: DepartureReason;
+    competitions: string[];
+    feis_ids: string[];
+    merged_into: string | null;
+    held_out: HeldOut[];
+    last_version: string;
+}
+export interface UpcomingDepartureAnswer {
+    tag: string;
+    departures: UpcomingDeparture[];
+}
 export interface UpcomingEntrantQuery {
     field_id: string;
     version?: string;
@@ -140,5 +169,6 @@ export declare class UpcomingFinder {
     private db;
     feises(q?: UpcomingFeisQuery): Promise<UpcomingFeisAnswer>;
     fields(q?: UpcomingFieldQuery): Promise<UpcomingFieldAnswer>;
+    departures(q?: UpcomingDepartureQuery): Promise<UpcomingDepartureAnswer>;
     entrants(q: UpcomingEntrantQuery): Promise<UpcomingEntrantAnswer>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.28.0",
+	"version": "0.30.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",