@finbheara/archive-client 0.28.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, 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`

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

@@ -3953,10 +3953,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 +3991,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 +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");
@@ -4944,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-5rnb63kw.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,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-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 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.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",