@finbheara/archive-client 0.18.0 → 0.20.1

package/README.md

@@ -80,6 +80,7 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | feature | the calls | from cut |
 | --- | --- | --- |
 | `results.level` | `results.query`, `majors.results` | 215 |
+| `results.dancer-level` | `results.dancerLevel` | 270 |
 | `dancers` | `dancers.resolve`, `search`, `get` | 260 |
 | `schools` | `schools.resolve`, a dancer question with a school | 260 |
 | `staff` | `staff.teacher`, `staff.adjudicator` | 260 |
@@ -100,7 +101,10 @@ A spec is `pinned` (the default: the user-local pin, else the latest), `latest`,
 
 EVERY FILE IS CHECKED before it lands: the downloaded bytes against the host's own sha256 digest,
 and the content against the manifest (a database's decompressed bytes against
-`databases.<name>.sha256`, a parquet file against `parquet.files[<name>].sha256`). A mismatch
+`databases.<name>.sha256`, a side file's decompressed bytes against `sideFiles.<name>.sha256`, a
+parquet file against `parquet.files[<name>].sha256`). A side file the manifest names under
+`sideFiles` is published zstd'd (`<name>.zst`, or the `file` it states) and lands plain under its
+own name. A mismatch
 refuses and leaves nothing in place. A file nothing vouches for is kept and its receipt says so
 (`strict: true` refuses it). A database is decompressed in process, streamed, never through a
 `zstd` binary.
@@ -448,6 +452,49 @@ A row carries the prints and the ids that stand for them: the address, the compe
 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.
 
+### What level a dancer dances
+
+```ts
+await rel.results.dancerLevel({ dancer_id: 1001, year: 2025 });
+// { level: 200, grades: { advancement_range: { lo: 300, hi: 400 },
+//                         level_range: { lo: 200, hi: 400 }, oireachtas_level: true } }
+await rel.results.dancerLevel({ dancer_id: 1002 });   // its latest year: { level: 600 }
+```
+
+No single number is a grades dancer's level. Grades are won PER DANCE: a dancer can be Novice in
+the reel and Prizewinner in the slip jig at once. Only a championship (600 preliminary, 700 open)
+is a level of the dancer. A competition's `feis_level` is the competition's rung. A set, a set
+dance, a treble reel or a special prints a rung that its entrants need not hold. So the answer
+reads:
+
+- **the year**: the competition's calendar year. When it is omitted, the latest year in which the
+  dancer has a rated feis row.
+- **a rated row**: a feis row (tier `T4`, a platform's) of the dancer, on the floor (no printed
+  absence, no `DNT`), whose competition publishes a `feis_level`.
+- **a championship row**: a rated row at 600 or 700. A 700 whose title or level field also names
+  the preliminary (`PC and OC`, `Prelim and Champ`) joins the two, and it reads 600 here.
+- **a graded row**: a rated row at 100 to 500 whose `dance` is one of the six graded dances (reel,
+  light jig, single jig, slip jig, treble jig, hornpipe) and whose title, level or dance field names
+  no special (`special`, `spcl`, `trophy`). Sets, set dances, treble reels and specials are never
+  read.
+
+| field | meaning |
+| --- | --- |
+| `level` | for a championship dancer (any championship row that year), the LOWEST championship rung danced that year. Otherwise the lowest graded rung danced that year. Null where the year holds neither |
+| `grades` | present only for a grades dancer: no championship row that year, and at least one graded row |
+| `grades.advancement_range` | `{ lo, hi }`, the lowest and highest rung over the reel, slip jig, treble jig and hornpipe, the dances a dancer advances in. Null where none of them was danced |
+| `grades.level_range` | `{ lo, hi }` over all six graded dances |
+| `grades.oireachtas_level` | `true` where the dancer danced a championship solo at a regional Oireachtas that year: a row on the floor at a tier `T3` event, the same calendar year, whose competition's `category` is `Solo`. A grade championship that the release files as `Solo` counts as well (one regional, in one year, prints ten) |
+
+Only feis rows set the level. A dancer with majors rows and no feis row in the year (tier `T4`) gets `level` null, whatever they danced at the majors.
+
+A dance that was not danced that year takes no part: each range covers what was danced. An adult
+grade row is read like any other, since the adult ladder also grades per dance. A release older
+than the published `dance` column is refused by name (`results.dancer-level`).
+
+Each call reads the dancer's rows once. The release does not index the dancer id, so one call
+scans the results table, as `results.query` does (about half a second on a full release).
+
 ## Every row, streamed
 
 ```ts

package/dist/chunks/{index-tr14vc1c.js → index-6028k52f.js}

@@ -27,6 +27,17 @@ function planAsset2(name, manifest) {
       contentSha256: manifest?.databases?.[name]?.sha256 ?? null
     };
   }
+  const side = manifest?.sideFiles?.[name];
+  if (side !== undefined) {
+    const file = side.file ?? `${name}.zst`;
+    return {
+      asked: name,
+      published: file === name ? [name] : [file, name],
+      local: name,
+      decompress: true,
+      contentSha256: side.sha256 ?? null
+    };
+  }
   return {
     asked: name,
     published: [name],
@@ -366,6 +377,69 @@ function notOnTheFloor(placePrinted, atts, withdrawn) {
   return withdrawn !== null && DID_NOT_TABULATE.has(withdrawn);
 }
 
+import { GRADE_DANCES } from "@finbheara/domain/dance-types";
+var ADVANCEMENT_DANCES2 = Object.freeze([
+  "reel",
+  "slip-jig",
+  "treble-jig",
+  "hornpipe"
+]);
+var SPECIAL_WORDS = Object.freeze(["special", "spcl", "trophy"]);
+var JOINED_WORDS = Object.freeze([
+  "prelim",
+  "pc and oc",
+  "pc/oc",
+  "pc & oc",
+  "pc-oc",
+  "pc/c",
+  "pr\xEDomh",
+  "priomh"
+]);
+var MAJORS_SOURCES = new Set(["transcript", "manifested"]);
+var has = (t, words) => words.some((w) => t.includes(w));
+function range(levels) {
+  if (levels.length === 0)
+    return null;
+  return { lo: Math.min(...levels), hi: Math.max(...levels) };
+}
+var isRated = (r) => r.tier === "T4" && !MAJORS_SOURCES.has(r.source) && r.feis_level !== null;
+function dancerLevelOf(db, tag, q) {
+  const all = db.query(`SELECT c.year AS year, c.tier AS tier, c.source AS source, c.feis_level AS feis_level,
+				        c.dance AS dance, c.category AS category,
+				        lower(coalesce(c.title, '') || ' | ' || coalesce(c.level_printed, '') || ' | ' ||
+				              coalesce(c.dance_printed, '')) AS t,
+				        r.place_printed AS place_printed, r.atts AS atts, r.withdrawn AS withdrawn
+				 FROM results r JOIN competitions c ON c.file = r.file AND c.line = r.competition_line
+				 WHERE r.dancer_id = ? AND c.tier IN ('T3', 'T4')`).all(q.dancer_id).filter((r) => !notOnTheFloor(r.place_printed, r.atts, r.withdrawn));
+  let year = q.year ?? null;
+  if (year === null) {
+    for (const r of all)
+      if (isRated(r) && r.year !== null && (year === null || r.year > year))
+        year = r.year;
+  }
+  const answer = { tag, asked: q, dancer_id: q.dancer_id, year, level: null };
+  if (year === null)
+    return answer;
+  const rows = all.filter((r) => r.year === year);
+  const rated = rows.filter(isRated);
+  const champs = rated.filter((r) => r.feis_level >= 600).map((r) => r.feis_level === 700 && has(r.t, JOINED_WORDS) ? 600 : r.feis_level);
+  if (champs.length > 0)
+    return { ...answer, level: Math.min(...champs) };
+  const graded = rated.filter((r) => r.feis_level >= 100 && r.feis_level <= 500 && r.dance !== null && GRADE_DANCES.includes(r.dance) && !has(r.t, SPECIAL_WORDS));
+  const levelRange = range(graded.map((r) => r.feis_level));
+  if (levelRange === null)
+    return answer;
+  return {
+    ...answer,
+    level: levelRange.lo,
+    grades: {
+      advancement_range: range(graded.filter((r) => ADVANCEMENT_DANCES2.includes(r.dance)).map((r) => r.feis_level)),
+      level_range: levelRange,
+      oireachtas_level: rows.some((r) => r.tier === "T3" && r.category === "Solo")
+    }
+  };
+}
+
 var ENTRY_RANK = new Map([
   ["final", 0],
   ["", 1],
@@ -565,6 +639,11 @@ class ResultFinder2 {
     await this.rel.require("results.level");
     return queryResults(this.rel, "results", q);
   }
+  async dancerLevel(q) {
+    await this.rel.fetch("results");
+    await this.rel.require("results.dancer-level");
+    return dancerLevelOf(this.rel.db("results"), this.rel.tag, q);
+  }
   async streamDb(q) {
     const db = scopeDb(q.scope);
     await this.rel.fetch(db);
@@ -3077,6 +3156,21 @@ var FEATURES2 = [
     since: 215,
     calls: "results.query, majors.results"
   },
+  {
+    feature: "results.dancer-level",
+    needs: [
+      "results:competitions.feis_level",
+      "results:competitions.dance",
+      "results:competitions.level_printed",
+      "results:competitions.dance_printed",
+      "results:competitions.category",
+      "results:results.place_printed",
+      "results:results.atts",
+      "results:results.withdrawn"
+    ],
+    since: 270,
+    calls: "results.dancerLevel"
+  },
   {
     feature: "majors.order",
     needs: ["majors:competitions.seq"],
@@ -3746,7 +3840,8 @@ class ReleaseManager2 {
         copyFileSync(src, raw);
       }
       const base = name.replace(/\.sqlite(\.zst)?$/, "");
-      const asked = base !== name && isDatabase(base) ? base : name;
+      const side = Object.entries(manifest.sideFiles ?? {}).find(([k, f]) => (f.file ?? `${k}.zst`) === name)?.[0];
+      const asked = base !== name && isDatabase(base) ? base : side ?? name;
       const plan = planAsset2(asked, manifest);
       const landed = await land(raw, { name, digest: null }, plan, join4(dest, plan.local), this.opts, log);
       receipt.files[plan.local] = landed;
@@ -3842,4 +3937,4 @@ function releases2(opts = {}) {
   return new ReleaseManager2(opts);
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, NO_CALENDAR2, FeisFinder2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };
+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, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, resolveTag2, Release2, openRelease2, openCached2, ReleaseManager2, releases2 };

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   nameOrderOf,
   openRelease2,
   releases2
-} from "./chunks/index-tr14vc1c.js";
+} from "./chunks/index-6028k52f.js";
 import"./chunks/index-hne1wadw.js";
 import"./chunks/index-hghdy980.js";
 

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   nameLevel2,
   NO_CALENDAR2,
   FeisFinder2,
+  ADVANCEMENT_DANCES2,
   entryRank2,
   FEIS_LOCAL_ID_FLOOR2,
   ResultFinder2,
@@ -51,7 +52,7 @@ import {
   openCached2,
   ReleaseManager2,
   releases2
-} from "./chunks/index-tr14vc1c.js";
+} from "./chunks/index-6028k52f.js";
 import {
   cacheRoot2,
   repoOf2
@@ -66,6 +67,7 @@ import {
   pickTag2
 } from "./chunks/index-hghdy980.js";
 export {
+  ADVANCEMENT_DANCES2 as ADVANCEMENT_DANCES,
   ARCHIVE_TAG2 as ARCHIVE_TAG,
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,

package/dist/types/assets.d.ts

@@ -14,6 +14,11 @@ export interface ReleaseManifest {
             table?: string;
         }>;
     };
+    sideFiles?: Record<string, {
+        file?: string;
+        bytes?: number;
+        sha256?: string;
+    }>;
     [k: string]: unknown;
 }
 export declare const DATABASES: readonly ["results", "majors"];

package/dist/types/dancer-level.d.ts

@@ -0,0 +1,24 @@
+import type { Database } from "bun:sqlite";
+export declare const ADVANCEMENT_DANCES: readonly string[];
+export interface DancerLevelQuery {
+    dancer_id: number;
+    year?: number;
+}
+export interface LevelRange {
+    lo: number;
+    hi: number;
+}
+export interface DancerGrades {
+    advancement_range: LevelRange | null;
+    level_range: LevelRange;
+    oireachtas_level: boolean;
+}
+export interface DancerLevelAnswer {
+    tag: string;
+    asked: DancerLevelQuery;
+    dancer_id: number;
+    year: number | null;
+    level: number | null;
+    grades?: DancerGrades;
+}
+export declare function dancerLevelOf(db: Database, tag: string, q: DancerLevelQuery): DancerLevelAnswer;

package/dist/types/index.d.ts

@@ -2,6 +2,7 @@ export { type AssetPlan, DATABASES, type DatabaseName, type LandedFile, type Rec
 export { sha256File, unzstdTo } from "./bytes.js";
 export { type AgeAsked, type AgeEvidence, type DancerAnswer, type DancerBulkRecord, type DancerCandidate, type DancerQuery, type DancerRecord, DancerResolver, type DancerRegion, type DancerSchool, type DancerSearchQuery, type DancerYear, type ExcludedCandidate, FEIS_LOCAL_ID_FLOOR, type InitialsRefuted, type Narrowing, initialsOnly, type OireachtasAsked, type PopulationEvidence, type RegionEvidence, type SchoolEvidence, readPopulation, } from "./dancers.js";
 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";

package/dist/types/results.d.ts

@@ -1,3 +1,4 @@
+import { type DancerLevelAnswer, type DancerLevelQuery } from "./dancer-level.js";
 import type { Release } from "./release.js";
 import { type EntryRow, type StreamQuery, type StreamRow } from "./stream.js";
 export declare const FEIS_LOCAL_ID_FLOOR = 17179869184;
@@ -44,6 +45,7 @@ export declare class ResultFinder {
     private readonly rel;
     constructor(rel: Release);
     query(q: ResultQuery): Promise<ResultAnswer>;
+    dancerLevel(q: DancerLevelQuery): Promise<DancerLevelAnswer>;
     private streamDb;
     stream(q: StreamQuery): AsyncGenerator<StreamRow>;
     entries(q: StreamQuery): AsyncGenerator<EntryRow>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.18.0",
+	"version": "0.20.1",
 	"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,8 +44,8 @@
 		"prepublishOnly": "bun scripts/build.ts && bun ../../tools/checks/archive-client-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/domain": "0.56.0",
-		"@finbheara/names": "0.28.0",
+		"@finbheara/domain": "0.57.1",
+		"@finbheara/names": "0.29.0",
 		"hyparquet": "1.31.2"
 	},
 	"devDependencies": {