@finbheara/archive-client 0.27.0 → 0.29.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, 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,14 +681,25 @@ says how; `none` leaves `feis_brand_id` null, the unjoined ones).
 A FIELD is one competition a competitor list names, `<feis_id>/<code>`, the same id on every cut. A later capture of the host is a new `version`
 (a capture id; `versions` lists them), never a new field. `state` says how it stands on the cut:
 `pending` (on the list), `results` (the release holds its results, `results_competitions` the
-join), `passed` (its first day is before the cut's day and no result is held) or `withdrawn` (the
-host's newest capture no longer lists it). `comp` is the competition reading of its code (`arm`,
+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`,
 `level`, `feis_level`, `age`, `population`, `kind`, `title`, `why`), null on a count list. A
 QuickFeis registrant list's field reads it off the list's own by-event label (`source`
 `registration-list`, `title` the label as printed), and `flags` holds the cross-check of the
 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`

package/dist/chunks/{index-8c1pk7gw.js → index-2sdphw48.js}

@@ -3950,7 +3950,15 @@ function needsRelease2(tag, c) {
   return new Error(`archive-client: ${tag} is too old for ${c.feature} (${c.calls}): it lacks ${c.missing.join(", ")}. Open a release of cut ${c.since} or later`);
 }
 
-var FIELD_STATES2 = ["pending", "results", "passed", "withdrawn"];
+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;
@@ -3982,6 +3990,8 @@ function fieldOf(r) {
     flags: json(r.flags, []),
     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,
@@ -4100,6 +4110,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");
@@ -4937,4 +4978,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-8c1pk7gw.js";
+} from "./chunks/index-2sdphw48.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,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-8c1pk7gw.js";
+} from "./chunks/index-2sdphw48.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/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 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,12 @@
 import type { Release } from "./release.js";
-export type FieldState = "pending" | "results" | "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;
+}
 export type UpcomingFeisState = "upcoming" | "no-results";
 export interface UpcomingHost {
     source: string;
@@ -56,6 +62,8 @@ export interface UpcomingField {
     flags: string[];
     results_competitions: string[];
     results_feis_ids: string[];
+    held_out: HeldOut[];
+    merged_into: string | null;
     version: string;
     versions: string[];
     captured_date: string;
@@ -110,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;
@@ -135,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.27.0",
+	"version": "0.29.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",
@@ -44,7 +44,7 @@
 		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/domain": "0.57.2",
+		"@finbheara/domain": "0.58.0",
 		"@finbheara/names": "0.30.0",
 		"hyparquet": "1.31.2"
 	},