@finbheara/archive-client 0.25.0 → 0.27.0

package/README.md

@@ -95,6 +95,8 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `teams` | `teams.results`, `teams.rosters`, `teams.resultRosters` | 260 |
 | `teams.fields` | the fields `teams.results` (`age`, `gender`, `printed_status`) and `teams.rosters` (`dance`, `school_printed_as_of`, a member's `gender`) carry; absent, never refused, without it | 266 |
 | `events` | `events.years` | 260 |
+| `upcoming.feises` | `upcoming.feises`, and the `next` of `feises.series` (null with the reason without it) | 285 |
+| `upcoming.fields`, `upcoming.entrants` | `upcoming.fields`, `upcoming.entrants` (285 and 290 carry the tables empty) | 291 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -208,8 +210,11 @@ s.next;       // the next scheduled instance where the release knows one, else n
 A series is asked by any id of it (a feis, instance or brand id, a retired one followed), by a
 host code with or without its year (held codes `<stem><yy>` whose two digits are their own year,
 never a host id of digits alone, which is a sequence number), or by a name (a glob, or a plain word read as `*word*`). Two series answer `ambiguous` with both.
-A release holds a feis-year once its results are captured and carries no calendar, so `next` is
-`null` today, with the reason.
+`next` is the series' earliest occurrence of the feis-index dated on or after the cut's day
+(`rel.upcoming.feises`, state `upcoming`), under its brand id or one retired onto it: `{ feis_id,
+date, date_hi, occurrence_id, name_printed, hosts, captured_id, series_basis }`, `feis_id` the
+first listing's that names one. It is `null` with `next_why` where the feis-index lists none, and
+on a release without `upcoming_feises` (feature `upcoming.feises`).
 
 ## Schools
 
@@ -648,6 +653,49 @@ every release the `teams` feature names, and `(await rel.capability("teams.field
 a release has. The rows are read once per
 release into the `teams` and `events` indexes.
 
+## Upcoming feiseanna and their competitor lists
+
+```ts
+const o = await rel.upcoming.feises({ state: "upcoming", from: "2026-11-01" });
+o.feises;    // [{ occurrence_id, occurrence_ids, name_printed, date_lo, date_hi, year, hosts,
+             //    feis_brand_id, feis_instance_id, series_basis, brand_candidates, captured_id, state }]
+const f = await rel.upcoming.fields({ state: "pending" });  // state, feis, field_id, from, to
+f.fields;    // [{ field_id, feis_id, source, host_id, competition_code, count_only, occurrence_id,
+             //    name_printed, date_lo, date_hi, year, feis_brand_id, comp, state, flags,
+             //    results_competitions, results_feis_ids, 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, ... }]
+```
+
+`upcoming.feises` is every occurrence of the cut's feis-index the release holds no results of:
+`upcoming` (dated on or after the cut's day) or `no-results` (before it), each with every
+platform's or calendar's listing (`hosts`) and its feis series where one was named (`series_basis`
+says how; `none` leaves `feis_brand_id` null, the unjoined ones).
+
+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`,
+`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`, ...).
+
+`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`
+(`initial-only`: a FeisWeb print is a surname and an initial; `name-hidden`: QuickFeis printed
+`(Name Hidden)`, so the row has no name and no answer). A QuickFeis registrant list
+(`transcripts/*.registrationlist.jsonl`) is one field per printed code, each registrant a row as
+printed. `count_only` marks a field read from an older registration-by-school page of
+the corpus `entrants/` part: its rows are schools' counts (`level_counts`), with no names, and a
+host with a registrant list publishes no such field. An unknown field or version answers no rows and says
+why. On a release without the tables each call refuses by name.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -816,6 +864,9 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
                 | --associations [--school <school_id>]]
     idq teams [--release <spec>] [--event <e>] [--year <y>] [--rosters | --joins]
     idq events [--release <spec>] [--event <e>] [--year <y>]
+    idq upcoming [--release <spec>] [--state <s,...>] [--feis <id>] [--from <date>] [--to <date>]
+    idq upcoming --entrants <field_id> [--version <capture id>]
+    idq upcoming --feises [--state upcoming|no-results] [--brand <series>] [--from <date>] [--to <date>]
     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-2ms980hc.js → index-8c1pk7gw.js}

@@ -201,6 +201,7 @@ var feisesIndex = {
   }
 };
 var NO_CALENDAR2 = "the release holds a feis-year once its results are captured and carries no calendar of scheduled feiseanna";
+var NO_UPCOMING2 = "the release's feis-index lists no occurrence of the series dated on or after the cut's day";
 var globToLike = (g) => g.replace(/[\\%_]/g, (c) => `\\${c}`).replace(/\*/g, "%").replace(/\?/g, "_");
 
 class FeisFinder2 {
@@ -296,6 +297,29 @@ class FeisFinder2 {
       instances
     };
   }
+  async nextOf(brand) {
+    if ((await this.rel.capability("upcoming.feises")).state === "missing")
+      return { next: null, next_why: NO_CALENDAR2 };
+    const db = await this.rel.indexDb("feises");
+    const retired = db.query("SELECT old_id FROM redirect WHERE new_id = ? AND kind = 'brand' ORDER BY old_id").all(brand).map((r) => r.old_id);
+    let best = null;
+    for (const id of [brand, ...retired])
+      for (const o of (await this.rel.upcoming.feises({ state: "upcoming", brand: id })).feises) {
+        if (best !== null && (best.date < o.date_lo || best.date === o.date_lo && best.occurrence_id <= o.occurrence_id))
+          continue;
+        best = {
+          feis_id: o.hosts.find((h) => h.feis_id !== null)?.feis_id ?? null,
+          date: o.date_lo,
+          date_hi: o.date_hi,
+          occurrence_id: o.occurrence_id,
+          name_printed: o.name_printed,
+          hosts: o.hosts,
+          captured_id: o.captured_id,
+          series_basis: o.series_basis
+        };
+      }
+    return best === null ? { next: null, next_why: NO_UPCOMING2 } : { next: best };
+  }
   async series(q) {
     const asked = q.trim();
     const answer = async (brands, via, more = {}) => {
@@ -314,8 +338,7 @@ class FeisFinder2 {
         host: u?.host ?? null,
         years: u?.years ?? [],
         instances: u?.instances ?? [],
-        next: null,
-        ...u !== null ? { next_why: NO_CALENDAR2 } : {},
+        ...u !== null ? await this.nextOf(u.series_id) : { next: null },
         candidates,
         ...arm === "ambiguous" ? { why: `${candidates.length} series answer "${asked}": ${brands.join(", ")}` } : {},
         ...more
@@ -3716,6 +3739,94 @@ var FEATURES2 = [
     since: 260,
     calls: "events.years (the events index)"
   },
+  {
+    feature: "upcoming.feises",
+    needs: [
+      "occurrence_id",
+      "occurrence_ids",
+      "name_printed",
+      "date_lo",
+      "date_hi",
+      "year",
+      "hosts",
+      "feis_brand_id",
+      "feis_instance_id",
+      "series_basis",
+      "brand_candidates",
+      "captured_id",
+      "results_state"
+    ].map((c) => `results:upcoming_feises.${c}`),
+    since: 285,
+    calls: "upcoming.feises, the `next` of feises.series"
+  },
+  {
+    feature: "upcoming.fields",
+    needs: [
+      "field_id",
+      "feis_id",
+      "source",
+      "host_id",
+      "competition_code",
+      "count_only",
+      "occurrence_id",
+      "name_printed",
+      "date_lo",
+      "date_hi",
+      "year",
+      "feis_brand_id",
+      "comp_arm",
+      "comp_source",
+      "comp_kind",
+      "level",
+      "feis_level",
+      "age",
+      "population",
+      "comp_title",
+      "comp_why",
+      "state",
+      "results_competitions",
+      "results_feis_ids",
+      "version",
+      "versions",
+      "captured_date",
+      "sha256",
+      "limits",
+      "entrants",
+      "stated_rows",
+      "printed_total"
+    ].map((c) => `results:upcoming_fields.${c}`),
+    since: 291,
+    calls: "upcoming.fields (285 and 290 carry the table empty)"
+  },
+  {
+    feature: "upcoming.entrants",
+    needs: [
+      "feis_id",
+      "captured_id",
+      "row_id",
+      "source",
+      "host_id",
+      "row_kind",
+      "count_only",
+      "n",
+      "name_printed",
+      "school_printed",
+      "school_id",
+      "school_rung",
+      "school_candidates",
+      "competitions",
+      "field_ids",
+      "level_counts",
+      "yob",
+      "asked",
+      "arm",
+      "candidate_ids",
+      "candidates",
+      "flags"
+    ].map((c) => `results:upcoming_entrants.${c}`),
+    since: 291,
+    calls: "upcoming.entrants (285 and 290 carry the table empty)"
+  },
   {
     feature: "staff",
     needs: [
@@ -3815,14 +3926,14 @@ var FEATURES2 = [
   }
 ];
 async function hasNeed(probe, n) {
-  const t = /^table:([A-Za-z_]+)(?:\.([A-Za-z_]+))?$/.exec(n);
+  const t = /^table:([A-Za-z_]\w*)(?:\.([A-Za-z_]\w*))?$/.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);
+  const m = /^(results|majors):([A-Za-z_]\w*)(?:\.([A-Za-z_]\w*))?$/.exec(n);
   if (m === null)
     return probe.publishes(n);
   const cols = columnsOf2(await probe.db(m[1]), m[2]);
@@ -3839,6 +3950,187 @@ 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 json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
+function fieldOf(r) {
+  const countOnly = r.count_only === 1;
+  return {
+    field_id: r.field_id,
+    feis_id: r.feis_id,
+    source: r.source,
+    host_id: r.host_id,
+    competition_code: r.competition_code ?? null,
+    count_only: countOnly,
+    occurrence_id: r.occurrence_id ?? null,
+    name_printed: r.name_printed,
+    date_lo: r.date_lo ?? null,
+    date_hi: r.date_hi ?? null,
+    year: r.year,
+    feis_brand_id: r.feis_brand_id ?? null,
+    comp: r.comp_arm === null ? null : {
+      arm: r.comp_arm,
+      source: r.comp_source ?? null,
+      kind: r.comp_kind ?? null,
+      level: r.level ?? null,
+      feis_level: r.feis_level ?? null,
+      age: r.age ?? null,
+      population: r.population ?? null,
+      title: r.comp_title ?? null,
+      why: r.comp_why ?? null
+    },
+    state: r.state,
+    flags: json(r.flags, []),
+    results_competitions: json(r.results_competitions, []),
+    results_feis_ids: json(r.results_feis_ids, []),
+    version: r.version,
+    versions: json(r.versions, []),
+    captured_date: r.captured_date,
+    sha256: r.sha256,
+    limits: json(r.limits, []),
+    entrants: r.entrants,
+    stated_rows: r.stated_rows ?? null,
+    printed_total: json(r.printed_total, null)
+  };
+}
+function entrantOf(r) {
+  return {
+    feis_id: r.feis_id,
+    captured_id: r.captured_id,
+    row_id: r.row_id,
+    source: r.source,
+    host_id: r.host_id,
+    row_kind: r.row_kind,
+    count_only: r.count_only === 1,
+    n: r.n,
+    name_printed: r.name_printed ?? null,
+    school_printed: r.school_printed ?? null,
+    school_id: r.school_id ?? null,
+    school_rung: r.school_rung,
+    school_candidates: json(r.school_candidates, []),
+    competitions: json(r.competitions, []),
+    field_ids: json(r.field_ids, []),
+    level_counts: json(r.level_counts, null),
+    yob: r.yob ?? null,
+    asked: json(r.asked, null),
+    arm: r.arm ?? null,
+    candidates: json(r.candidates, []),
+    flags: json(r.flags, [])
+  };
+}
+function feisOf(r) {
+  return {
+    occurrence_id: r.occurrence_id,
+    occurrence_ids: json(r.occurrence_ids, []),
+    name_printed: r.name_printed,
+    date_lo: r.date_lo,
+    date_hi: r.date_hi ?? null,
+    year: r.year,
+    hosts: json(r.hosts, []),
+    feis_brand_id: r.feis_brand_id ?? null,
+    feis_instance_id: r.feis_instance_id ?? null,
+    series_basis: r.series_basis,
+    brand_candidates: json(r.brand_candidates, []),
+    captured_id: r.captured_id,
+    state: r.results_state
+  };
+}
+
+class UpcomingFinder2 {
+  rel;
+  constructor(rel) {
+    this.rel = rel;
+  }
+  async db(feature) {
+    await this.rel.fetch("results");
+    await this.rel.require(feature);
+    return this.rel.db("results");
+  }
+  async feises(q = {}) {
+    const db = await this.db("upcoming.feises");
+    const where = [];
+    const args = [];
+    if (q.state !== undefined) {
+      where.push("results_state = ?");
+      args.push(q.state);
+    }
+    if (q.brand !== undefined) {
+      where.push("feis_brand_id = ?");
+      args.push(q.brand);
+    }
+    if (q.from !== undefined) {
+      where.push("date_lo >= ?");
+      args.push(q.from);
+    }
+    if (q.to !== undefined) {
+      where.push("date_lo <= ?");
+      args.push(q.to);
+    }
+    const sql = `SELECT * FROM upcoming_feises${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY date_lo, occurrence_id`;
+    const rows = db.query(sql).all(...args);
+    return { tag: this.rel.tag, feises: rows.map(feisOf) };
+  }
+  async fields(q = {}) {
+    const db = await this.db("upcoming.fields");
+    const where = [];
+    const args = [];
+    if (q.state !== undefined) {
+      const states = typeof q.state === "string" ? [q.state] : [...q.state];
+      if (states.length === 0)
+        return { tag: this.rel.tag, fields: [] };
+      where.push(`state IN (${states.map(() => "?").join(", ")})`);
+      args.push(...states);
+    }
+    if (q.feis !== undefined) {
+      where.push("(feis_id = ? OR feis_brand_id = ? OR occurrence_id = ?)");
+      args.push(q.feis, q.feis, q.feis);
+    }
+    if (q.field_id !== undefined) {
+      where.push("field_id = ?");
+      args.push(q.field_id);
+    }
+    if (q.from !== undefined) {
+      where.push("date_lo >= ?");
+      args.push(q.from);
+    }
+    if (q.to !== undefined) {
+      where.push("date_lo <= ?");
+      args.push(q.to);
+    }
+    const sql = `SELECT * FROM upcoming_fields${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY date_lo, feis_id, field_id`;
+    const rows = db.query(sql).all(...args);
+    return { tag: this.rel.tag, fields: rows.map(fieldOf) };
+  }
+  async entrants(q) {
+    const [field] = (await this.fields({ field_id: q.field_id })).fields;
+    const db = await this.db("upcoming.entrants");
+    if (field === undefined)
+      return {
+        tag: this.rel.tag,
+        field: null,
+        version: null,
+        entrants: [],
+        why: `the release holds no field "${q.field_id}"`
+      };
+    const version = q.version ?? field.version;
+    if (!field.versions.includes(version))
+      return {
+        tag: this.rel.tag,
+        field,
+        version,
+        entrants: [],
+        why: `${field.field_id} has no version ${version} (versions ${field.versions.join(", ")})`
+      };
+    const rows = db.query("SELECT * FROM upcoming_entrants WHERE feis_id = ? AND captured_id = ? ORDER BY row_id").all(field.feis_id, version).map(entrantOf).filter((e) => e.field_ids.includes(field.field_id));
+    return {
+      tag: this.rel.tag,
+      field,
+      version,
+      entrants: rows,
+      ...rows.length === 0 ? { why: `${field.field_id} lists no row in version ${version}` } : {}
+    };
+  }
+}
+
 function tagDir(root, tag) {
   if (parseArchiveTag2(tag) === null)
     throw new Error(`archive-client: "${tag}" is not a release tag (archive-YYYY.MM.DD[-N[.k]])`);
@@ -3895,6 +4187,7 @@ class Release2 {
   registrations;
   teams;
   events;
+  upcoming;
   tabs;
   panels;
   feisPanels;
@@ -3920,6 +4213,7 @@ class Release2 {
     this.registrations = new RegistrationResolver2(this, this.comps, opts.dancerResolver);
     this.teams = new TeamFinder2(this);
     this.events = new EventFinder2(this);
+    this.upcoming = new UpcomingFinder2(this);
     this.tabs = new TabFinder2(this);
     this.panels = new PanelFinder2(this);
     this.feisPanels = new FeisPanelFinder2(this);
@@ -4643,4 +4937,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, 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, 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, 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-2ms980hc.js";
+} from "./chunks/index-8c1pk7gw.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -360,6 +360,32 @@ var VERBS = [
       "                                    each event-year's dates and place"
     ]
   },
+  {
+    verb: "upcoming",
+    value: [
+      "--release",
+      "--state",
+      "--feis",
+      "--from",
+      "--to",
+      "--entrants",
+      "--version",
+      "--brand"
+    ],
+    bool: ["--feises"],
+    usage: [
+      "  upcoming [--release <spec>] [--state pending,results,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",
+      "                                    occurrence id",
+      "  upcoming --entrants <field_id> [--version <capture id>]",
+      "                                    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"
+    ]
+  },
   {
     verb: "teacher",
     value: ["--release"],
@@ -766,6 +792,7 @@ var ANSWERING = new Set([
   "schools",
   "teams",
   "events",
+  "upcoming",
   "teacher",
   "adjudicator",
   "comp",
@@ -1032,7 +1059,7 @@ async function main(argv, io = {}) {
               say(`    ${i.year ?? "?"}  ${i.date_lo ?? "?"}  ${i.feis_ids.join(", ")}`);
           }
           if (a.arm === "unique")
-            say(`  next: ${a.next === null ? `unknown (${a.next_why ?? ""})` : `${a.next.feis_id ?? "?"} ${a.next.date}`}`);
+            say(`  next: ${a.next === null ? `unknown (${a.next_why ?? ""})` : `${a.next.feis_id ?? "?"} ${a.next.date}  ${a.next.occurrence_id} (${a.next.hosts.map((h) => h.source).join(",")}; ${a.next.series_basis})`}`);
         });
         rel.close();
         return a.arm === "none" ? 1 : 0;
@@ -1433,6 +1460,60 @@ async function main(argv, io = {}) {
           rel.close();
         }
       }
+      case "upcoming": {
+        const rel = await open(spec, { ...opts, assets: [] });
+        try {
+          const from = p.flags.get("--from");
+          const to = p.flags.get("--to");
+          const range = {
+            ...from !== undefined ? { from } : {},
+            ...to !== undefined ? { to } : {}
+          };
+          const state = p.flags.get("--state");
+          const fieldId = p.flags.get("--entrants");
+          if (fieldId !== undefined) {
+            const version = p.flags.get("--version");
+            const a = await rel.upcoming.entrants({
+              field_id: fieldId,
+              ...version !== undefined ? { version } : {}
+            });
+            out(a, () => {
+              for (const e of a.entrants)
+                say(`  ${e.arm ?? "-"}  ${e.candidates.map((c) => c.dancer_id).join(",") || "-"}  "${e.name_printed ?? ""}"  ${e.school_id ?? "(no id)"} "${e.school_printed ?? ""}"${e.flags.length > 0 ? `  [${e.flags.join(",")}]` : ""}`);
+              say(`${a.entrants.length} row(s) of ${a.field?.field_id ?? fieldId} version ${a.version ?? "-"}${a.why !== undefined ? ` (${a.why})` : ""} in ${a.tag}`);
+            });
+            return a.entrants.length === 0 ? 1 : 0;
+          }
+          if (p.bools.has("--feises")) {
+            const brand = p.flags.get("--brand");
+            const a = await rel.upcoming.feises({
+              ...state !== undefined ? { state } : {},
+              ...brand !== undefined ? { brand } : {},
+              ...range
+            });
+            out(a, () => {
+              for (const f of a.feises)
+                say(`  ${f.date_lo}  ${f.occurrence_id}  "${f.name_printed}"  ${f.feis_brand_id ?? "(no series)"} (${f.series_basis})  ${f.hosts.map((h) => h.feis_id ?? `${h.source}:${h.host_id}`).join(", ")}  [${f.state}]`);
+              say(`${a.feises.length} feis occurrence(s) in ${a.tag}`);
+            });
+            return a.feises.length === 0 ? 1 : 0;
+          }
+          const feis = p.flags.get("--feis");
+          const a = await rel.upcoming.fields({
+            ...state !== undefined ? { state: state.split(",") } : {},
+            ...feis !== undefined ? { feis } : {},
+            ...range
+          });
+          out(a, () => {
+            for (const f of a.fields)
+              say(`  ${f.date_lo ?? "?"}  ${f.field_id}  ${f.state}  ${f.entrants} row(s)  v${f.version}  ${f.feis_brand_id ?? "(no series)"}  ${f.comp === null ? "" : f.comp.arm === "none" ? "comp unread" : `${f.comp.level ?? "?"} ${f.comp.age ?? "?"} ${f.comp.population ?? ""}`}`);
+            say(`${a.fields.length} field(s) in ${a.tag}`);
+          });
+          return a.fields.length === 0 ? 1 : 0;
+        } finally {
+          rel.close();
+        }
+      }
       case "teacher":
       case "adjudicator": {
         if (rest.length === 0) {

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   NAME_LEVELS2,
   nameLevel2,
   NO_CALENDAR2,
+  NO_UPCOMING2,
   FeisFinder2,
   ADVANCEMENT_DANCES2,
   entryRank2,
@@ -49,6 +50,8 @@ import {
   FEATURES2,
   capabilityOf2,
   needsRelease2,
+  FIELD_STATES2,
+  UpcomingFinder2,
   resolveTag2,
   Release2,
   openRelease2,
@@ -71,7 +74,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-2ms980hc.js";
+} from "./chunks/index-8c1pk7gw.js";
 import {
   cacheRoot2,
   repoOf2
@@ -95,6 +98,7 @@ export {
   EventFinder2 as EventFinder,
   FEATURES2 as FEATURES,
   FEIS_LOCAL_ID_FLOOR2 as FEIS_LOCAL_ID_FLOOR,
+  FIELD_STATES2 as FIELD_STATES,
   FeisFinder2 as FeisFinder,
   FeisPanelFinder2 as FeisPanelFinder,
   LATEST_CHECK_BUDGET_MS2 as LATEST_CHECK_BUDGET_MS,
@@ -104,6 +108,7 @@ export {
   MajorsFinder2 as MajorsFinder,
   NAME_LEVELS2 as NAME_LEVELS,
   NO_CALENDAR2 as NO_CALENDAR,
+  NO_UPCOMING2 as NO_UPCOMING,
   PanelFinder2 as PanelFinder,
   RegistrationResolver2 as RegistrationResolver,
   Release2 as Release,
@@ -113,6 +118,7 @@ export {
   StaffFinder2 as StaffFinder,
   TabFinder2 as TabFinder,
   TeamFinder2 as TeamFinder,
+  UpcomingFinder2 as UpcomingFinder,
   buildIndex2 as buildIndex,
   buildTag2 as buildTag,
   cacheRoot2 as cacheRoot,

package/dist/types/feises.d.ts

@@ -1,5 +1,6 @@
 import type { IndexBuilder } from "./indexes.js";
 import type { Release } from "./release.js";
+import type { UpcomingHost } from "./upcoming.js";
 export interface Feis {
     feis_id: string;
     source: string;
@@ -53,6 +54,12 @@ export interface Series {
 export interface SeriesNext {
     feis_id: string | null;
     date: string;
+    date_hi: string | null;
+    occurrence_id: string;
+    name_printed: string;
+    hosts: UpcomingHost[];
+    captured_id: string;
+    series_basis: string;
 }
 export interface SeriesAnswer {
     tag: string;
@@ -74,6 +81,7 @@ export interface SeriesAnswer {
     why?: string;
 }
 export declare const NO_CALENDAR = "the release holds a feis-year once its results are captured and carries no calendar of scheduled feiseanna";
+export declare const NO_UPCOMING = "the release's feis-index lists no occurrence of the series dated on or after the cut's day";
 export declare class FeisFinder {
     private readonly rel;
     constructor(rel: Release);
@@ -88,5 +96,6 @@ export declare class FeisFinder {
     find(q: FeisQuery): Promise<FeisAnswer>;
     codeStem(token: string, stem: string): Promise<string[]>;
     seriesOf(brand: string): Promise<Series>;
+    nextOf(brand: string): Promise<Pick<SeriesAnswer, "next" | "next_why">>;
     series(q: string): Promise<SeriesAnswer>;
 }

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { NAME_LEVELS, type NameLevel, nameLevel } from "./dancers-names.js";
 export { ADVANCEMENT_DANCES, type DancerGrades, type DancerLevelAnswer, type DancerLevelQuery, type LevelRange, } from "./dancer-level.js";
 export { type Comp, type CompAnswer, type CompDance, type CompKind, type CompQuery, CompResolver, type CompSource, type FeisPlace, type SyllabusAnswer, type SyllabusForAnswer, type SyllabusSource, type TitleCheck, canonicalOf, syllabusSourceOf, } 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 Feis, type FeisAnswer, FeisFinder, type FeisQuery, NO_CALENDAR, NO_UPCOMING, type Series, type SeriesAnswer, type SeriesInstance, type SeriesNext, } from "./feises.js";
 export { type IndexBuilder, type IndexFile, buildIndex, defaultBuilders, ensureIndex, indexKey, indexPath, isCurrent, listIndexes, } from "./indexes.js";
 export { type CutVersion, LOCAL_DIR, type LocalBuild, type PickedBuild, buildTag, incomplete, localRoot, newerThan, openBuild, pickBuild, releaseVersion, sweepBuilds, } from "./local.js";
 export { type CachedRelease, DEFAULT_KEEP, type ReleaseList, ReleaseManager, type RemovalPlan, type UseResult, releases, } from "./manager.js";
@@ -24,4 +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 { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/release.d.ts

@@ -14,6 +14,7 @@ import { type SchoolReaderChoice, SchoolResolver } from "./schools.js";
 import { FeisPanelFinder, PanelFinder, TabFinder } from "./tabs.js";
 import { type ReleaseSpec } from "./tag.js";
 import { EventFinder, TeamFinder } from "./teams.js";
+import { UpcomingFinder } from "./upcoming.js";
 export interface OpenOptions extends ClientOptions {
     assets?: readonly string[];
     remote?: Remote;
@@ -45,6 +46,7 @@ export declare class Release {
     readonly registrations: RegistrationResolver;
     readonly teams: TeamFinder;
     readonly events: EventFinder;
+    readonly upcoming: UpcomingFinder;
     readonly tabs: TabFinder;
     readonly panels: PanelFinder;
     readonly feisPanels: FeisPanelFinder;

package/dist/types/upcoming.d.ts

@@ -0,0 +1,139 @@
+import type { Release } from "./release.js";
+export type FieldState = "pending" | "results" | "passed" | "withdrawn";
+export declare const FIELD_STATES: readonly FieldState[];
+export type UpcomingFeisState = "upcoming" | "no-results";
+export interface UpcomingHost {
+    source: string;
+    host_id: string;
+    feis_id: string | null;
+    series: string | null;
+    name_printed: string | null;
+    date_lo: string | null;
+    date_hi: string | null;
+    url: string | null;
+}
+export interface UpcomingFeis {
+    occurrence_id: string;
+    occurrence_ids: string[];
+    name_printed: string;
+    date_lo: string;
+    date_hi: string | null;
+    year: number;
+    hosts: UpcomingHost[];
+    feis_brand_id: string | null;
+    feis_instance_id: string | null;
+    series_basis: string;
+    brand_candidates: string[];
+    captured_id: string;
+    state: UpcomingFeisState;
+}
+export interface FieldComp {
+    arm: "unique" | "ambiguous" | "none";
+    source: string | null;
+    kind: string | null;
+    level: string | null;
+    feis_level: number | null;
+    age: string | null;
+    population: string | null;
+    title: string | null;
+    why: string | null;
+}
+export interface UpcomingField {
+    field_id: string;
+    feis_id: string;
+    source: string;
+    host_id: string;
+    competition_code: string | null;
+    count_only: boolean;
+    occurrence_id: string | null;
+    name_printed: string;
+    date_lo: string | null;
+    date_hi: string | null;
+    year: number;
+    feis_brand_id: string | null;
+    comp: FieldComp | null;
+    state: FieldState;
+    flags: string[];
+    results_competitions: string[];
+    results_feis_ids: string[];
+    version: string;
+    versions: string[];
+    captured_date: string;
+    sha256: string;
+    limits: string[];
+    entrants: number;
+    stated_rows: number | null;
+    printed_total: unknown;
+}
+export interface EntrantCandidate {
+    dancer_id: number;
+    scope: string;
+    kind: string | null;
+    score: number;
+    name: string | null;
+    age: string | null;
+    school: string | null;
+}
+export interface UpcomingEntrant {
+    feis_id: string;
+    captured_id: string;
+    row_id: string;
+    source: string;
+    host_id: string;
+    row_kind: string;
+    count_only: boolean;
+    n: number;
+    name_printed: string | null;
+    school_printed: string | null;
+    school_id: string | null;
+    school_rung: string;
+    school_candidates: string[];
+    competitions: string[];
+    field_ids: string[];
+    level_counts: Record<string, number> | null;
+    yob: number | null;
+    asked: Record<string, unknown> | null;
+    arm: "unique" | "ambiguous" | "none" | null;
+    candidates: EntrantCandidate[];
+    flags: string[];
+}
+export interface UpcomingFeisQuery {
+    state?: UpcomingFeisState;
+    brand?: string;
+    from?: string;
+    to?: string;
+}
+export interface UpcomingFieldQuery {
+    state?: FieldState | readonly FieldState[];
+    feis?: string;
+    field_id?: string;
+    from?: string;
+    to?: string;
+}
+export interface UpcomingEntrantQuery {
+    field_id: string;
+    version?: string;
+}
+export interface UpcomingFeisAnswer {
+    tag: string;
+    feises: UpcomingFeis[];
+}
+export interface UpcomingFieldAnswer {
+    tag: string;
+    fields: UpcomingField[];
+}
+export interface UpcomingEntrantAnswer {
+    tag: string;
+    field: UpcomingField | null;
+    version: string | null;
+    entrants: UpcomingEntrant[];
+    why?: string;
+}
+export declare class UpcomingFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    private db;
+    feises(q?: UpcomingFeisQuery): Promise<UpcomingFeisAnswer>;
+    fields(q?: UpcomingFieldQuery): Promise<UpcomingFieldAnswer>;
+    entrants(q: UpcomingEntrantQuery): Promise<UpcomingEntrantAnswer>;
+}

package/package.json

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