@finbheara/archive-client 0.34.0 → 0.35.0

package/README.md

@@ -101,6 +101,8 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `upcoming.fields`, `upcoming.entrants` | `upcoming.fields`, `upcoming.entrants` (285 and 290 carry the tables empty) | 291 |
 | `upcoming.fields.instance` | the `feis_instance_id` `upcoming.fields` carries; absent, never refused, without it | 320 |
 | `calendar` | `calendar.get`, `calendar.list` | 320 |
+| `calendar.expected` | each calendar stage's `expected`; absent, never refused, without it | 320 |
+| `calendar.next` | `calendar.next` | 320 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -762,8 +764,14 @@ g.via;       // "instance" | "formerly" | "feis_id" | "occurrence_id" | null
 g.entries;   // [{ feis_instance_id, feis_brand_id, tier, name_printed, date_lo, date_hi, date_source,
              //    occurrence_ids, feis_ids, stages: { announced, syllabus, entrants, run, results },
              //    terminal, carried, formerly }]
+g.entries[0].stages.results.expected;
+             // { date, basis, n, platform } or null: "announced" | "brand" | "platform" |
+             //   "pooled" | "roster-window" | "unmeasured"
 const l = await rel.calendar.list({ stage: "entrants", state: "observed", from: "2026-11-01" });
              // brand, tier, from, to, stage, state, terminal ("none": still ahead)
+const n = await rel.calendar.next({ brand: "plf" });
+             // [{ feis_brand_id, year, run_expected, run_expected_basis, run_expected_n,
+             //    from_instance_id, from_date }]: a series' next edition no listing names yet
 ```
 
 ONE ROW PER FEIS INSTANCE, on the id its results carry: a feis-series instance (`<brand>.<year>`),
@@ -780,6 +788,20 @@ order: only results after the run is a belief. `get` tries the instance id, then
 a capture, then an occurrence id, and says which met (`via`). On a release without the table each
 call refuses by name.
 
+EXPECTED DAYS (`calendar.expected`): each stage carries `expected`, `{ date, basis, n, platform }`
+or null. `announced` is the listing's own first day; `brand` the series' edition the year before
+plus 364 days, `n` its held years; `platform` a platform's capture lag (the P90 of first results
+capture less last day) or list lead (the median of first day less first list capture), measured
+over the feiseanna run in the 180 days before the cut, `n` at least 10; `pooled` every platform's
+results lags together, for a feis whose hosts have no capture form (`platform` `all`) and, NAMED, in
+place of a platform measured on fewer than 10 (`platform` the host's); `roster-window` a majors event-year
+no capture dates; `unmeasured` no day. A stage still ahead always carries one; an observed stage
+carries the day its estimator gives it where one applies, so the misses can be read. The lags are
+capture's own scrape cadence, re-measured every release. `next` lists each series with two or more
+held years, the last the release's year or the one before, whose next edition is not on the
+calendar: its year and expected first day. It is never an instance: an id is minted only once a
+listing names the edition.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -958,6 +980,7 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq calendar [--release <spec>] <instance|feis id|occurrence id>
     idq calendar [--brand <series>] [--tier <t>] [--from <date>] [--to <date>] [--stage <s>] [--state <s>]
                  [--terminal results|withdrawn|passed-no-results|none]
+    idq calendar --next [--brand <series>]
     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-cwhyrcyx.js → index-gt7yxxp8.js}

@@ -722,6 +722,26 @@ var FEATURES2 = [
     since: 320,
     calls: "calendar.get, calendar.list"
   },
+  {
+    feature: "calendar.expected",
+    needs: ["announced", "syllabus", "entrants", "run", "results"].flatMap((st) => ["", "_basis", "_n", "_platform"].map((x) => `results:feis_calendar.${st}_expected${x}`)),
+    since: 320,
+    calls: "each calendar stage's `expected` (absent, never refused, without it)"
+  },
+  {
+    feature: "calendar.next",
+    needs: [
+      "feis_brand_id",
+      "year",
+      "run_expected",
+      "run_expected_basis",
+      "run_expected_n",
+      "from_instance_id",
+      "from_date"
+    ].map((c) => `results:feis_series_next.${c}`),
+    since: 320,
+    calls: "calendar.next"
+  },
   {
     feature: "upcoming.entrants",
     needs: [
@@ -3877,13 +3897,26 @@ var CALENDAR_TERMINALS2 = [
   "passed-no-results"
 ];
 var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
-function entryOf2(r) {
+function expectedOf(r, s) {
+  const basis = r[`${s}_expected_basis`];
+  if (basis === null || basis === undefined)
+    return null;
+  const n = r[`${s}_expected_n`];
+  return {
+    date: r[`${s}_expected`] ?? null,
+    basis,
+    n: n === null || n === undefined ? null : Number(n),
+    platform: r[`${s}_expected_platform`] ?? null
+  };
+}
+function entryOf2(r, expected) {
   const stages = Object.fromEntries(CALENDAR_STAGES2.map((s) => [
     s,
     {
       state: r[`${s}_state`],
       date: r[`${s}_date`] ?? null,
-      cite: r[`${s}_cite`] ?? null
+      cite: r[`${s}_cite`] ?? null,
+      ...expected ? { expected: expectedOf(r, s) } : {}
     }
   ]));
   return {
@@ -3914,6 +3947,27 @@ class CalendarFinder2 {
     await this.rel.require("calendar");
     return this.rel.db("results");
   }
+  async expected() {
+    return (await this.rel.capability("calendar.expected")).state === "full";
+  }
+  async next(q = {}) {
+    await this.rel.fetch("results");
+    await this.rel.require("calendar.next");
+    const db = this.rel.db("results");
+    const rows = q.brand === undefined ? db.query("SELECT * FROM feis_series_next ORDER BY run_expected, feis_brand_id").all() : db.query("SELECT * FROM feis_series_next WHERE feis_brand_id = ? ORDER BY run_expected").all(q.brand);
+    return {
+      tag: this.rel.tag,
+      next: rows.map((r) => ({
+        feis_brand_id: r.feis_brand_id,
+        year: Number(r.year),
+        run_expected: r.run_expected,
+        run_expected_basis: "brand",
+        run_expected_n: Number(r.run_expected_n),
+        from_instance_id: r.from_instance_id,
+        from_date: r.from_date
+      }))
+    };
+  }
   async get(id) {
     const db = await this.db();
     const ways = [
@@ -3924,8 +3978,10 @@ class CalendarFinder2 {
     ];
     for (const [via, where] of ways) {
       const rows = db.query(`SELECT * FROM feis_calendar WHERE ${where} ORDER BY feis_instance_id`).all(id);
-      if (rows.length > 0)
-        return { tag: this.rel.tag, asked: id, via, entries: rows.map(entryOf2) };
+      if (rows.length > 0) {
+        const e = await this.expected();
+        return { tag: this.rel.tag, asked: id, via, entries: rows.map((r) => entryOf2(r, e)) };
+      }
     }
     return {
       tag: this.rel.tag,
@@ -3967,7 +4023,8 @@ class CalendarFinder2 {
       add("terminal = ?", q.terminal);
     const sql = `SELECT * FROM feis_calendar${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY date_lo IS NULL, date_lo, feis_instance_id`;
     const rows = db.query(sql).all(...args);
-    return { tag: this.rel.tag, entries: rows.map(entryOf2) };
+    const e = await this.expected();
+    return { tag: this.rel.tag, entries: rows.map((r) => entryOf2(r, e)) };
   }
 }
 

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-cwhyrcyx.js";
+} from "./chunks/index-gt7yxxp8.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -395,7 +395,7 @@ var VERBS = [
   {
     verb: "calendar",
     value: ["--release", "--brand", "--tier", "--from", "--to", "--stage", "--state", "--terminal"],
-    bool: [],
+    bool: ["--next"],
     usage: [
       "  calendar [--release <spec>] <instance|feis id|occurrence id>",
       "                                    one feis instance's stages: announced, syllabus, entrants,",
@@ -404,7 +404,11 @@ var VERBS = [
       "  calendar [--brand <series>] [--tier T1..T4] [--from <date>] [--to <date>]",
       "           [--stage announced|syllabus|entrants|run|results] [--state observed|pending|not-captured]",
       "           [--terminal results|withdrawn|passed-no-results|none]",
-      "                                    the instances a query names, by first day"
+      "                                    the instances a query names, by first day; each stage's",
+      "                                    expected day with its basis and n where the release has them",
+      "  calendar --next [--brand <series>]",
+      "                                    each series' next edition no listing names yet: its year",
+      "                                    and expected first day from the year before (basis brand)"
     ]
   },
   {
@@ -523,6 +527,7 @@ function parseArgs(argv) {
   return { positional, flags, bools };
 }
 var mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+var expectedText = (e) => e === null || e === undefined ? "" : `  expected ${e.date ?? "-"} (${e.basis}${e.platform !== null ? ` ${e.platform}` : ""}${e.n !== null ? `, n ${e.n}` : ""})`;
 function printPlan(p, say) {
   for (const k of p.keep)
     say(`keep    ${k.tag} (${k.why})`);
@@ -1553,13 +1558,23 @@ async function main(argv, io = {}) {
         const rel = await open(spec, { ...opts, assets: [] });
         try {
           const line = (e) => `  ${e.date_lo ?? "?"}  ${e.feis_instance_id}  ${e.tier}  ${["announced", "syllabus", "entrants", "run", "results"].map((s) => `${s}:${e.stages[s].state === "observed" ? e.stages[s].date ?? "seen" : e.stages[s].state}`).join(" ")}  [${e.terminal ?? "ahead"}]${e.name_printed !== null ? `  "${e.name_printed}"` : ""}`;
+          if (p.bools.has("--next")) {
+            const brand = p.flags.get("--brand");
+            const a = await rel.calendar.next(brand === undefined ? {} : { brand });
+            out(a, () => {
+              for (const n of a.next)
+                say(`  ${n.run_expected}  ${n.feis_brand_id}  ${n.year}  brand n ${n.run_expected_n}  from ${n.from_instance_id} (${n.from_date})`);
+              say(`${a.next.length} next edition(s) in ${a.tag}`);
+            });
+            return a.next.length === 0 ? 1 : 0;
+          }
           if (rest.length > 0) {
             const a = await rel.calendar.get(rest.join(" "));
             out(a, () => {
               for (const e of a.entries) {
                 say(line(e));
                 for (const s of ["announced", "syllabus", "entrants", "run", "results"])
-                  say(`      ${s}  ${e.stages[s].state}  ${e.stages[s].date ?? "-"}  ${e.stages[s].cite ?? "-"}${e.carried.includes(s) ? "  (carried)" : ""}`);
+                  say(`      ${s}  ${e.stages[s].state}  ${e.stages[s].date ?? "-"}  ${e.stages[s].cite ?? "-"}${e.carried.includes(s) ? "  (carried)" : ""}${expectedText(e.stages[s].expected)}`);
               }
               say(`${a.entries.length} instance(s) for "${a.asked}"${a.via !== null ? ` by ${a.via}` : ""}${a.why !== undefined ? ` (${a.why})` : ""} in ${a.tag}`);
             });

package/dist/index.js

@@ -80,7 +80,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-cwhyrcyx.js";
+} from "./chunks/index-gt7yxxp8.js";
 import {
   cacheRoot2,
   repoOf2

package/dist/types/calendar.d.ts

@@ -5,10 +5,18 @@ export type CalendarStageState = "observed" | "pending" | "not-captured";
 export declare const CALENDAR_STAGE_STATES: readonly CalendarStageState[];
 export type CalendarTerminal = "results" | "withdrawn" | "passed-no-results";
 export declare const CALENDAR_TERMINALS: readonly CalendarTerminal[];
+export type CalendarExpectedBasis = "announced" | "brand" | "platform" | "pooled" | "roster-window" | "unmeasured";
+export interface CalendarExpected {
+    date: string | null;
+    basis: CalendarExpectedBasis;
+    n: number | null;
+    platform: string | null;
+}
 export interface CalendarStageValue {
     state: CalendarStageState;
     date: string | null;
     cite: string | null;
+    expected?: CalendarExpected | null;
 }
 export interface CalendarEntry {
     feis_instance_id: string;
@@ -38,6 +46,19 @@ export interface CalendarAnswer {
     tag: string;
     entries: CalendarEntry[];
 }
+export interface CalendarNext {
+    feis_brand_id: string;
+    year: number;
+    run_expected: string;
+    run_expected_basis: "brand";
+    run_expected_n: number;
+    from_instance_id: string;
+    from_date: string;
+}
+export interface CalendarNextAnswer {
+    tag: string;
+    next: CalendarNext[];
+}
 export interface CalendarGetAnswer {
     tag: string;
     asked: string;
@@ -49,6 +70,10 @@ export declare class CalendarFinder {
     private readonly rel;
     constructor(rel: Release);
     private db;
+    private expected;
+    next(q?: {
+        brand?: string;
+    }): Promise<CalendarNextAnswer>;
     get(id: string): Promise<CalendarGetAnswer>;
     list(q?: CalendarQuery): Promise<CalendarAnswer>;
 }

package/dist/types/index.d.ts

@@ -26,5 +26,5 @@ export { type EntryRow, type StreamCompetition, type StreamQuery, type StreamRow
 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, 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 { CALENDAR_STAGES, CALENDAR_STAGE_STATES, CALENDAR_TERMINALS, type CalendarAnswer, type CalendarEntry, CalendarFinder, type CalendarGetAnswer, type CalendarQuery, type CalendarStage, type CalendarStageState, type CalendarStageValue, type CalendarTerminal, } from "./calendar.js";
+export { CALENDAR_STAGES, CALENDAR_STAGE_STATES, CALENDAR_TERMINALS, type CalendarAnswer, type CalendarEntry, type CalendarExpected, type CalendarExpectedBasis, type CalendarNext, type CalendarNextAnswer, CalendarFinder, type CalendarGetAnswer, type CalendarQuery, type CalendarStage, type CalendarStageState, type CalendarStageValue, type CalendarTerminal, } from "./calendar.js";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/package.json

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