@finbheara/archive-client 0.37.0 → 0.39.0

package/README.md

@@ -93,6 +93,7 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `dancers.records` | `dancers.records` | 215 |
 | `dancers.records.names` | the `names_printed` a record of `dancers.records` carries; absent, never refused, without it | 215 |
 | `dancers.years` | `dancers.years` | 245 |
+| `dancers.years.printed` | the `printed_regions` a dancer-year of `dancers.years` carries (every region the year printed, where `region` picks one); absent, never refused, without it | 341 |
 | `majors.tabs` | `majors.tabulated` | 215 |
 | `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 |
@@ -325,6 +326,8 @@ r.initials;    // an initials-only name with a school: { open, heldByDanceUp, re
 r.unlinked;    // rows printing a matched name that the release linked to no dancer
 
 await rel.dancers.search({ surname: "Quellan" });  // or { like: "a* quellan" }, or { name }
+                                                    // at most `limit` (default 50, 0 for all);
+                                                    // `truncated` counts the rest
 await rel.dancers.get(1001);                        // every print and school of one dancer
 ```
 
@@ -510,6 +513,9 @@ await rel.majors.competitions({ event: "<event>", year: 2023 });
 await rel.majors.results({ dancer_id: 1001 });       // a dancer's majors
 ```
 
+A query keeps at most `limit` rows (default 500; `0` is no limit) and `truncated` says how many
+more there were. Check it is `0` before reading the rows as the whole answer.
+
 A row carries the prints and the ids that stand for them: the address, the competition's title
 and age, the place, the name and school as printed with the dancer and school ids. The majors are
 read from `majors.sqlite`, fetched on first use.
@@ -617,6 +623,7 @@ await rel.dancers.records();                   // every dancer: display, appeara
                                                // names_printed (dancers.records.names)
 await rel.dancers.records({ ids: [1001] });
 await rel.dancers.years({ ids: [1001], year: 2025 });  // region, region_source, nationals, geohash
+                                               // printed_regions (dancers.years.printed)
 await rel.feises.dates();                      // every feis id with its first and last day
 await rel.majors.tabulated({ min_true_round: 3 });     // the majors addresses marked to round 3 or later
 ```
@@ -975,9 +982,9 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>
                [--order surname-first|given-first] [--school <print|id>]
                [--yob <y> | --band <band> [--year <y>] | --comp <competition>] [--as-of <date>]
-               [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]
+               [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows] [--limit <n>]
     idq results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <c>] [--school <s>] [--year <y>] [--limit <n>]
-    idq majors [--release <spec>] [--event <e>] [--year <y>] [--comp <c>] [--dancer <id>] [--rows]
+    idq majors [--release <spec>] [--event <e>] [--year <y>] [--comp <c>] [--dancer <id>] [--rows] [--limit <n>]
     idq stream [--release <spec>] --scope majors|transcribed|platform|all [--entries] [--event <e,...>]
                [--year <y> | --year <from>..<to>] [--tier <t,...>] [--category <c,...>]
                [--level <n,...>] [--dancer <id,...>] [--school <school_id>] [--primary]
@@ -1012,9 +1019,20 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq resolve dancer [<name>] [--school s] [--comp <feis>/<code> | --yob y | --band b --year y]
                        [--oireachtas <region>[:<year>]]
     idq resolve registrations
+    idq resolve teacher|adjudicator [<name|TD number>]
 
 `stream` (and `tabs --stream`) prints one JSON line per row (or entry, or cell), as it reads them. `dancer` prints the results of the one dancer where the answer is unique (every candidate's with
-`--rows`). `--json` prints the call's answer as it is. `--cache` and `--repo` override the defaults.
+`--rows`), and `--id` every row of the one dancer. `--json` prints the call's answer as it is.
+
+A LIMIT THAT CUTS AN ANSWER SAYS SO. `results`, `majors --comp|--dancer` (500 rows) and a
+`dancer` search (50 candidates) take `--limit <n>`, and `--limit 0` is no limit. Where the limit
+cut the answer, one line goes to stderr, in text and `--json` alike, and stdout is unchanged:
+
+    answered 500 of 979 rows: pass --limit 979 (or --limit 0 for all) for the rest
+
+A `dancer` search prints the same line of its candidates, and each trajectory it reads (one per
+candidate, 500 rows each) that was cut prints `answered 500 of 979 rows of dancer <id>: pass --id
+<id> for all of them`. `--cache` and `--repo` override the defaults.
 
 `update` moves to the newest published release, as a package manager's `update` moves to the newest
 version: it fetches it (verified as every download is), builds every index it knows, and only then
@@ -1061,7 +1079,10 @@ only when the release is published: `teams`, `events`) answers from the pinned r
 `resolve` speaks JSON lines: one answer per line out, and with no positional question the
 questions are JSON lines on stdin, one per line (`{feis, code, year?, title?}`,
 `{name, school?, age?, population?, oireachtas?}`,
-`{name, school?, codes, feis, year?, population?, oireachtas?}`). A line that is no JSON object,
+`{name, school?, codes, feis, year?, population?, oireachtas?}`, and for `teacher` and
+`adjudicator` `{name}` or the TD number under the key `StaffPerson` carries it in, the number read
+first where a line has both, each answered by `rel.staff.teacher` / `rel.staff.adjudicator`, one
+`StaffAnswer` a line). A line that is no JSON object,
 or no question of its kind, answers `{tag, line, error}` and the other lines still answer. The
 exit is non-zero where any line erred. A dancer's age may be given as a comp
 (`{"comp": "<feis>/<code>"}`, or `--comp` on the command line): `rel.registrations.dancer` reads

package/dist/chunks/{index-hfpcedbh.js → index-hdr8qvwf.js}

@@ -535,6 +535,12 @@ var FEATURES2 = [
     since: 245,
     calls: "dancers.years"
   },
+  {
+    feature: "dancers.years.printed",
+    needs: ["results:dancer_years.printed_regions"],
+    since: 341,
+    calls: "the `printed_regions` a dancer-year of dancers.years carries: absent, never refused, on a release without it"
+  },
   {
     feature: "teams",
     needs: [
@@ -1502,7 +1508,7 @@ function queryResults(rel, db, q) {
     where.push("c.year = ?");
     args.push(q.year);
   }
-  const limit = q.limit ?? 500;
+  const asked = q.limit ?? 500;
   const all = rel.db(db).query(`SELECT ${COLUMNS2} FROM results r JOIN competitions c ON c.file = r.file AND c.line = r.competition_line
 			 WHERE ${where.join(" AND ")}
 			 ORDER BY c.year, c.event, r.competition, r.place IS NULL, r.place, r.address`).all(...args);
@@ -1510,11 +1516,11 @@ function queryResults(rel, db, q) {
     tag: rel.tag,
     db,
     asked: q,
-    rows: all.slice(0, limit).map((r) => ({
+    rows: (asked === 0 ? all : all.slice(0, asked)).map((r) => ({
       ...r,
       dancer_scope: r.dancer_id === null ? null : r.dancer_id >= FEIS_LOCAL_ID_FLOOR2 ? "per-release" : "stable"
     })),
-    truncated: Math.max(0, all.length - limit)
+    truncated: asked === 0 ? 0 : Math.max(0, all.length - asked)
   };
 }
 
@@ -2221,12 +2227,16 @@ class DancerResolver2 {
     await this.rel.fetch("results");
     await this.rel.require("dancers.years");
     const db = this.rel.db("results");
-    const sql = "SELECT dancer_id, year, region, region_source, nationals, nationals_source, geohash FROM dancer_years";
+    const printed = (await this.rel.capability("dancers.years.printed")).state === "full";
+    const sql = `SELECT dancer_id, year, region, region_source, nationals, nationals_source, geohash${printed ? ", printed_regions" : ""} FROM dancer_years`;
     const yearSql = q.year === undefined ? "" : " AND year = ?";
     const yearArgs = q.year === undefined ? [] : [q.year];
     const rows = q.ids === undefined ? db.query(`${sql} WHERE 1${yearSql} ORDER BY dancer_id, year`).all(...yearArgs) : idChunks(q.ids).flatMap((c) => db.query(`${sql} WHERE dancer_id IN (${c.map(() => "?").join(",")})${yearSql}`).all(...c, ...yearArgs));
     rows.sort((a, b) => a.dancer_id - b.dancer_id || a.year - b.year);
-    return { tag: this.rel.tag, years: rows };
+    return {
+      tag: this.rel.tag,
+      years: rows.map(({ printed_regions: codes, ...y }) => codes === undefined ? y : { ...y, printed_regions: codes === "" ? [] : codes.split(",") })
+    };
   }
   async resolve(q) {
     const db = await this.rel.indexDb("dancers");
@@ -2237,6 +2247,7 @@ class DancerResolver2 {
         asked: q,
         arm: "none",
         candidates: [],
+        truncated: 0,
         excluded: [],
         unlinked: [],
         refused: asked.printsNoName() ? "the print names no person" : "the print reads as no person (a bare word is a surname: search it)"
@@ -2348,7 +2359,13 @@ class DancerResolver2 {
     return this.capped(a, q.limit);
   }
   capped(a, limit = 50) {
-    return { ...a, candidates: a.candidates.slice(0, limit) };
+    if (limit === 0 || a.candidates.length <= limit)
+      return a;
+    return {
+      ...a,
+      candidates: a.candidates.slice(0, limit),
+      truncated: a.candidates.length - limit
+    };
   }
   async get(dancerId) {
     const db = await this.rel.indexDb("dancers");
@@ -2606,6 +2623,7 @@ class DancerResolver2 {
       asked: q,
       arm: kept.length === 0 ? "none" : kept.length === 1 ? "unique" : "ambiguous",
       candidates: kept,
+      truncated: 0,
       excluded,
       ...preferred !== undefined ? { preferred } : {},
       unlinked: [...unlinked].map(([print, rows]) => ({ print, rows })).sort((a, b) => b.rows - a.rows || (a.print < b.print ? -1 : 1)),

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-hfpcedbh.js";
+} from "./chunks/index-hdr8qvwf.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -199,20 +199,23 @@ var VERBS = [
       "--comp",
       "--as-of",
       "--population",
-      "--oireachtas"
+      "--oireachtas",
+      "--limit"
     ],
     bool: ["--rows"],
     usage: [
       "  dancer [--release <spec>] <name> | --surname <s> | --like <glob> | --id <dancer_id>",
       "         [--order surname-first|given-first] [--school <print|id>]",
       "         [--yob <y> | --band <U10> [--year <y>] | --comp <competition>] [--as-of <date>]",
-      "         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows]",
+      "         [--population girls|boys] [--oireachtas <region>[:<year>]] [--rows] [--limit <n>]",
       "                                    the dancers a name reaches, each with its evidence",
       "                                    (name level, age, school, population, region) and the arm;",
       "                                    --oireachtas is the regional the roster is for, its region in",
       "                                    the release's spelling (SRO, MAO), its year the --as-of year",
       "                                    where none is given; the results of",
-      "                                    the one dancer where one answers (or --rows for each)"
+      "                                    the one dancer where one answers (or --rows for each, 500",
+      "                                    rows a dancer; --id reads every row); at most --limit",
+      "                                    candidates (default 50, 0 for all)"
     ]
   },
   {
@@ -222,17 +225,20 @@ var VERBS = [
     usage: [
       "  results [--release <spec>] [--dancer <id>] [--feis <id>] [--comp <competition>]",
       "          [--school <print|id>] [--year <y>] [--limit <n>]",
-      "                                    the published result rows, prints and ids"
+      "                                    the published result rows, prints and ids; at most",
+      "                                    --limit rows (default 500, 0 for all)"
     ]
   },
   {
     verb: "majors",
-    value: ["--release", "--event", "--year", "--comp", "--dancer"],
+    value: ["--release", "--event", "--year", "--comp", "--dancer", "--limit"],
     bool: [],
     usage: [
       "  majors [--release <spec>] [--event <e>] [--year <y>] [--comp <competition>] [--dancer <id>]",
+      "         [--limit <n>]",
       "                                    the majors: every event and its years; an event's",
-      "                                    competitions; a competition's, an event's or a dancer's rows"
+      "                                    competitions; a competition's, an event's or a dancer's rows",
+      "                                    (at most --limit, default 500, 0 for all)"
     ]
   },
   {
@@ -491,11 +497,15 @@ var VERBS = [
       "                 [--order <o>] [--as-of <date>] [--population girls|boys]",
       "                 [--oireachtas <region>[:<year>]]",
       "  resolve registrations",
+      "  resolve teacher|adjudicator [<name|TD number>]",
       "                                    JSONL out, one answer per line; with no positional the",
       "                                    questions are JSONL on stdin, one per line (a comp:",
       "                                    {feis, code, year?, title?}, a dancer: {name, school?, age?,",
       "                                    population?, oireachtas?}, a registration: {name, school?,",
-      "                                    codes[], feis, year?, population?, oireachtas?})"
+      "                                    codes[], feis, year?, population?, oireachtas?}, a teacher or",
+      "                                    adjudicator: {clrg} or {name}, the TD number first)",
+      "                                    A line that is no question answers {tag, line, error}, and",
+      "                                    the exit is 1 where any line erred"
     ]
   }
 ];
@@ -600,6 +610,21 @@ function printResults(a, say) {
     say("  * a feis-local dancer id: valid in this release only");
   say(`${a.rows.length} row(s) from ${a.db} in ${a.tag}${a.truncated > 0 ? `, ${a.truncated} more past the limit` : ""}`);
 }
+function cutNotice(shown, more, what = "rows") {
+  if (more <= 0)
+    return null;
+  const total = shown + more;
+  return `answered ${shown} of ${total} ${what}: pass --limit ${total} (or --limit 0 for all) for the rest`;
+}
+function limitOf(p) {
+  const v = p.flags.get("--limit");
+  if (v === undefined)
+    return {};
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0)
+    throw new Error(`--limit takes a count (0 for no limit), not "${v}"`);
+  return { limit: n };
+}
 function printStaff(a, say) {
   say(`${a.arm}  ${a.role} "${a.asked}"  in ${a.tag}${a.refused !== undefined ? `  (refused: ${a.refused})` : ""}`);
   for (const p of a.people) {
@@ -661,6 +686,14 @@ function oireachtasFlag(v) {
   };
 }
 var checkDancer = (q) => typeof q.name !== "string" || q.name.trim() === "" ? "a dancer question needs name" : null;
+function staffAsked(q) {
+  if (q.clrg !== undefined && q.clrg !== null) {
+    const n = typeof q.clrg === "string" && q.clrg.trim() !== "" ? Number(q.clrg) : q.clrg;
+    return typeof n === "number" && Number.isInteger(n) && n > 0 ? String(n) : null;
+  }
+  return typeof q.name === "string" && q.name.trim() !== "" ? q.name.trim() : null;
+}
+var checkStaff = (q) => q.clrg !== undefined && q.clrg !== null && staffAsked(q) === null ? "a staff question's clrg is a TD number" : staffAsked(q) === null ? "a staff question needs name or clrg" : null;
 var checkRegistration = (r) => typeof r.name !== "string" || r.name.trim() === "" ? "a registration row needs name" : typeof r.feis !== "string" || r.feis.trim() === "" ? "a registration row needs feis" : !Array.isArray(r.codes) ? "a registration row needs codes[]" : null;
 async function resolveVerb(rel, what, args, p, say, stdin) {
   const year = p.flags.has("--year") ? Number(p.flags.get("--year")) : undefined;
@@ -743,8 +776,21 @@ async function resolveVerb(rel, what, args, p, say, stdin) {
       await each(lines, async () => answers[k++]);
       return errors > 0 ? 1 : 0;
     }
+    case "teacher":
+    case "adjudicator": {
+      const qs = args.length > 0 ? [{ line: 0, value: { name: args.join(" ") } }] : jsonLines(await stdin(), checkStaff);
+      let none = 0;
+      await each(qs, async (q) => {
+        const asked = staffAsked(q);
+        const a = what === "teacher" ? await rel.staff.teacher(asked) : await rel.staff.adjudicator(asked);
+        if (a.arm === "none")
+          none++;
+        return a;
+      });
+      return errors > 0 || args.length > 0 && none === 1 ? 1 : 0;
+    }
     default:
-      throw new Error("resolve comp|dancer|registrations");
+      throw new Error("resolve comp|dancer|registrations|teacher|adjudicator");
   }
 }
 var SCOPES = ["majors", "transcribed", "platform", "all"];
@@ -1130,7 +1176,7 @@ async function main(argv, io = {}) {
           const id = p.flags.get("--id");
           if (id !== undefined) {
             const d = await rel.dancers.get(Number(id));
-            const rows = d === null ? null : await rel.results.query({ dancer_id: d.dancer_id });
+            const rows = d === null ? null : await rel.results.query({ dancer_id: d.dancer_id, limit: 0 });
             out({ dancer: d, results: rows }, () => {
               if (d === null) {
                 say(`no dancer ${id} in ${rel.tag}`);
@@ -1158,7 +1204,7 @@ async function main(argv, io = {}) {
             ...p.flags.has("--as-of") ? { asOf: p.flags.get("--as-of") } : {},
             ...p.flags.has("--population") ? { population: p.flags.get("--population") } : {},
             ...oireachtasFlag(p.flags.get("--oireachtas")),
-            ...p.flags.has("--limit") ? { limit: Number(p.flags.get("--limit")) } : {}
+            ...limitOf(p)
           };
           const surname = p.flags.get("--surname");
           const like = p.flags.get("--like");
@@ -1178,6 +1224,12 @@ async function main(argv, io = {}) {
               printResults(t, say);
             }
           });
+          const cut = cutNotice(a.candidates.length, a.truncated, "candidates");
+          if (cut !== null)
+            log(cut);
+          for (const t of trajectories)
+            if (t.truncated > 0)
+              log(`answered ${t.rows.length} of ${t.rows.length + t.truncated} rows of dancer ${t.asked.dancer_id}: pass --id ${t.asked.dancer_id} for all of them`);
           return a.candidates.length === 0 ? 1 : 0;
         } finally {
           rel.close();
@@ -1192,10 +1244,13 @@ async function main(argv, io = {}) {
             ...p.flags.has("--comp") ? { competition: p.flags.get("--comp") } : {},
             ...p.flags.has("--school") ? { school_id: await schoolIdOf(rel, p.flags.get("--school")) } : {},
             ...p.flags.has("--year") ? { year: Number(p.flags.get("--year")) } : {},
-            ...p.flags.has("--limit") ? { limit: Number(p.flags.get("--limit")) } : {}
+            ...limitOf(p)
           };
           const a = await rel.results.query(q);
           out(a, () => printResults(a, say));
+          const cut = cutNotice(a.rows.length, a.truncated);
+          if (cut !== null)
+            log(cut);
           return a.rows.length === 0 ? 1 : 0;
         } finally {
           rel.close();
@@ -1214,9 +1269,12 @@ async function main(argv, io = {}) {
               ...dancer !== undefined ? { dancer_id: Number(dancer) } : {},
               ...event !== undefined ? { feis: event } : {},
               ...year !== undefined ? { year: Number(year) } : {},
-              ...p.flags.has("--limit") ? { limit: Number(p.flags.get("--limit")) } : {}
+              ...limitOf(p)
             });
             out(a, () => printResults(a, say));
+            const cut = cutNotice(a.rows.length, a.truncated);
+            if (cut !== null)
+              log(cut);
             return a.rows.length === 0 ? 1 : 0;
           }
           if (event !== undefined) {
@@ -1742,6 +1800,7 @@ export {
   USAGE_FOOTER,
   USAGE_HEADER,
   VERBS,
+  cutNotice,
   jsonLines,
   main,
   parseArgs,

package/dist/index.js

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

package/dist/types/cli.d.ts

@@ -12,6 +12,7 @@ export interface Parsed {
     bools: Set<string>;
 }
 export declare function parseArgs(argv: readonly string[]): Parsed;
+export declare function cutNotice(shown: number, more: number, what?: string): string | null;
 type Line<T> = {
     line: number;
     value: T;

package/dist/types/dancers.d.ts

@@ -106,6 +106,7 @@ export interface DancerAnswer {
     asked: DancerQuery;
     arm: "unique" | "ambiguous" | "none";
     candidates: DancerCandidate[];
+    truncated: number;
     excluded: ExcludedCandidate[];
     preferred?: {
         dancer_id: number;
@@ -203,6 +204,7 @@ export interface DancerYear {
     nationals: string | null;
     nationals_source: string | null;
     geohash: string | null;
+    printed_regions?: string[];
 }
 export declare class DancerResolver {
     private readonly rel;

package/package.json

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