@finbheara/domain 0.49.0 → 0.51.0

package/README.md

@@ -49,7 +49,8 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/dance-types` | `danceTypes()`, `DANCE_TYPES`, `rhythmOfTime`, and the shared `DanceMatch`/`DanceRelation`/`SetRhythm`/`TimeSignature` types |
 | `@finbheara/domain/promotion` | `samePromotedRow`, `samePromotedSchool`, `samePromotedHeir`, `samePromotedName`, `questionMarksRead`, `foldCharSynonyms`: is a row the same row after a promotion (below) |
 | `@finbheara/domain/person` | `seatName`, `dancerName`, `teacherName`, `roleName`, `roleSentinelOf`, `rolePrintsNoName`, `dancerPrintsNoName`, the role lists and `SHARED_ROW_SENTINELS`: a person's print read in its role (below) |
-| `@finbheara/domain/title` | `compTitle`, `titleRelation`, `matchTitle`, `ladderOf`, `populationIn`, `populationRelation`, `roundNumbersIn`, `codePopulation`, `secondIn`: a competition title read and matched onto syllabus entries, a code's sex suffix, a second chance (below) |
+| `@finbheara/domain/title` | `compTitle`, `titleRelation`, `matchTitle`, `ladderOf`, `populationIn`, `populationRelation`, `roundNumbersIn`, `roundFold`, `codePopulation`, `secondIn`: a competition title read and matched onto syllabus entries, a code's sex suffix, a second chance (below) |
+| `@finbheara/domain/code` | `createCodeReader`, `compCode`, `DEFAULT_CODE_READER`, the `CompCode` type: a competition code read at the feis it belongs to, from that feis's syllabus or, on a platform you name as standardized, from the code alone (below) |
 | `@finbheara/domain/schedule` | `scheduleAt`, `sameHall`, `readRunningOrder`, the `ScheduleSlot` type: which entries a hall runs (below) |
 
 The library does no I/O and installs nothing process-wide. Every reader has a default and a
@@ -426,6 +427,13 @@ compTitle("Treble Reel Special").invalidReason(); // "no-age"
 A spoken dash is read as a space: `boys u-17`, `Boys U-17` and `boys u- 17` read as `boys u17`,
 `girls o-16` as `girls o16`, and `under-15` as `under 15`.
 
+A count printed before `Rounds` is how many rounds are danced, and the number after it is the
+band: `Ladies Champion 3 Rounds 18 & Over` reads `[18,∞)` and no round, and `2 Rounds 1 & 2`
+lists the two rounds it counts. A number an and-over closes (`18 & Over`, `18&O`, `18+`) is the
+band, so `Round 2 - 18&O` is round 2, and so is the number after an and-over word (`Rounds 1-3
+Over 18` is rounds 1 and 3). An and-over word with no connector pops nothing: `Round 2 Plus` is
+round 2.
+
 A band split into parallel competitions (`Girls Under 13 A`, `Girls Under 13 B`) answers every
 split, unless the title prints the letter. A title naming no band names nothing. Hand in the
 entries of the kind you mean: a solo championship's ages are often a team event's too.
@@ -447,6 +455,50 @@ secondIn("Preliminary Champion, Supplementary Prelim (U15)");   // true
 secondIn("Preliminary Champion, Hard Shoe (U10)");              // false
 ```
 
+## Read a competition code
+
+A code is a feis's own number for a competition. Some platforms number every feis by one
+grammar: a level digit (`1` first feis to `7` open championship), two digits for the age column
+(fifty more for a boys' column, `99` for adults) and letters for the dance, so `512SJ` is a
+prizewinner slip jig under 12 wherever it is printed. Most platforms let each feis number as it
+likes, and the same `344` is a novice under 11 at one feis and a beginner reel at the next. Read
+with the grammar, such a code gives an age and a level that look right and are wrong.
+
+So a code is read only at a feis. `read` takes the platform and the feis's address or slug, and
+answers from the feis's syllabus where you hand it in, on any platform. With no syllabus, only a
+platform you name as standardized reads its code alone. Everything else is refused, with its
+reason: `no-feis`, `feis-specific`, `not-in-syllabus`, `two-entries` or `not-a-code`. An empty
+`syllabus: []` is no syllabus, never a syllabus that prints no code. The default
+reader names no platform, so with no configuration a code reads only from a syllabus. A title is
+not a code: `compTitle` still reads it at any feis.
+
+```ts
+import { createCodeReader } from "@finbheara/domain/code";
+
+const codes = createCodeReader({ standardized: ["examplefeis"] });
+
+const c = codes.read("512SJ", { platform: "examplefeis", feis: "ex:1001" });
+c.age.ag1;     // "u12"
+c.level;       // 500
+c.source;      // "code"
+
+codes.read("344", { platform: "other", feis: "x:ABC26" }).invalidReason();  // "feis-specific"
+codes.read("512SJ", { platform: "examplefeis", feis: null }).invalidReason(); // "no-feis"
+
+const syllabus = [{ code: "344", title: "Novice Girls Under 11 Light Jig" }];
+const s = codes.read("344", { platform: "other", feis: "x:ABC26", syllabus });
+s.age.ag1;     // "u11"
+s.entry;       // the entry: read its level yourself
+```
+
+The level comes from the grammar's level digit only. A set, a treble reel, a figure and a future
+champions competition run off the grade ladder and read no level, and a syllabus answer reads none,
+on a standardized platform too (the syllabus wins, and the package reads no level word): the
+matching `entry` comes back for you to read. The oldest
+column a feis offers in one series is its and-over (`719OC` is 18 and over where it is the top
+open column). Hand in every code the feis printed (`codes`) to read the top column and a level
+split by sex. Without them a column reads as its `Under` band and who dances is not said.
+
 ## Ask a schedule
 
 A split band's competitions share their card numbers, so a card heard on a stage fits each of

package/dist/chunks/{place-k0p9af4f.js → place-7jfd4m3j.js}

@@ -48,11 +48,24 @@ var SECOND_WORDS = /\b(?:(?:2nd|second)[\s-]*ch(?:ance|c)?\b|supplementary\b|(?:
 function secondIn2(text) {
   return SECOND_WORDS.test(toAscii(text).toLowerCase());
 }
+var ROUND_LIST = / (?:(\d+) )?(rounds?) ((?:\d+ (?:and )?)+)/g;
 function roundNumbersIn2(folded, printed) {
   const out = new Set;
-  for (const m of folded.matchAll(/ rounds? ((?:\d+ (?:and )?)+)/g))
-    for (const n of m[1].match(/\d+/g) ?? [])
-      out.add(Number(n));
+  for (const m of folded.matchAll(ROUND_LIST)) {
+    const list = m[3];
+    const after = folded.slice((m.index ?? 0) + m[0].length);
+    const ns = (list.match(/\d+/g) ?? []).map(Number);
+    const andOver = list.endsWith(" and ") && /^(?:over|o) /.test(after);
+    if (andOver || after.startsWith("+ "))
+      ns.pop();
+    if (m[1] !== undefined && m[2] === "rounds") {
+      const count = Number(m[1]);
+      if (ns.length < 2 || ns.some((n) => n < 1 || n > count))
+        continue;
+    }
+    for (const n of ns)
+      out.add(n);
+  }
   for (const m of folded.matchAll(/ r([1-9])(?= )/g))
     out.add(Number(m[1]));
   if (printed)
@@ -60,8 +73,8 @@ function roundNumbersIn2(folded, printed) {
       out.add(Number(m[1]));
   return out;
 }
-function roundFold(print) {
-  return ` ${toAscii(print).toLowerCase().replace(/(\d)(\p{L})/gu, "$1 $2").replace(/[-–—,/()&+:;|.']/g, " ").replace(/\s+/g, " ").trim()} `;
+function roundFold2(print) {
+  return ` ${toAscii(print).toLowerCase().replace(/(\d)(\p{L})/gu, "$1 $2").replace(/&/g, " and ").replace(/\+/g, " + ").replace(/[-–—,/():;|.']/g, " ").replace(/\s+/g, " ").trim()} `;
 }
 var SPLIT = / ([a-d]) $|(?:\d|girls?|boys?|lad(?:y|ies)|m[ae]n|mixed) ([a-d])(?= )/;
 var spoken = (print) => print.replace(/\b(under|over|u|o)-(?=[ \t]*\d)/giu, "$1 ");
@@ -76,7 +89,7 @@ function read(print, ctx, agePrint) {
     age = t.age;
     ageSpan = t.span;
   }
-  const folded = roundFold(print);
+  const folded = roundFold2(print);
   const rounds = [...roundNumbersIn2(folded, / rounds? /.test(folded))].sort((a, b) => a - b);
   const split = SPLIT.exec(folded);
   const empty = print.trim() === "" && (agePrint ?? "").trim() === "";
@@ -160,4 +173,4 @@ function matchTitle2(print, entries, ctx = {}) {
   });
 }
 
-export { populationIn2, codePopulation2, secondIn2, roundNumbersIn2, compTitle2, populationRelation2, titleRelation2, ladderOf2, matchTitle2 };
+export { populationIn2, codePopulation2, secondIn2, roundNumbersIn2, roundFold2, compTitle2, populationRelation2, titleRelation2, ladderOf2, matchTitle2 };

package/dist/code.js

@@ -0,0 +1,136 @@
+import {
+  Age2
+} from "./chunks/place-kmh59zkw.js";
+import {
+  populationIn2,
+  compTitle2
+} from "./chunks/place-7jfd4m3j.js";
+import {
+  validity
+} from "./chunks/place-q9kwsmzd.js";
+
+var TRAILING = /(?:-[A-Za-z0-9]+|\[[A-Za-z0-9]+\])$/;
+var GROUP = /^([1-7])(\d{2})([A-Za-z]+?)2?$/;
+var OFF_LADDER = new Set(["TR", "TS", "SD", "FD", "FC"]);
+function group(print) {
+  let s = print.trim();
+  let male = false;
+  let female = false;
+  for (let m = TRAILING.exec(s);m !== null; m = TRAILING.exec(s)) {
+    const t = m[0].toUpperCase();
+    if (t === "-M" || t === "[M]")
+      male = true;
+    if (t === "-F" || t === "[F]")
+      female = true;
+    s = s.slice(0, m.index);
+  }
+  const g = GROUP.exec(s);
+  if (g === null)
+    return null;
+  const mm = Number(g[2]);
+  const plus50 = mm >= 50 && mm <= 89;
+  return {
+    digit: g[1],
+    letters: g[3].toUpperCase(),
+    column: mm === 99 ? null : plus50 ? mm - 50 : mm,
+    boys: plus50 || male,
+    girls: female
+  };
+}
+function groups(print) {
+  const out = [];
+  for (const part of print.split("/")) {
+    const g = group(part);
+    if (g === null)
+      return null;
+    out.push(g);
+  }
+  return out.length === 0 ? null : out;
+}
+function decode(print, year, codes) {
+  const gs = groups(print);
+  if (gs === null)
+    return null;
+  const first = gs[0];
+  if (gs.some((g) => g.digit !== first.digit))
+    return null;
+  const adult = gs.filter((g) => g.column === null).length;
+  if (adult > 0 && adult < gs.length)
+    return null;
+  const level = OFF_LADDER.has(first.letters) ? null : Number(first.digit) * 100;
+  const others = codes === null ? [] : codes.flatMap((c) => groups(c) ?? []);
+  const boys = gs.every((g) => g.boys);
+  const split = others.some((g) => g.digit === first.digit && g.boys);
+  const population = gs.some((g) => g.boys) && !boys ? "mixed" : boys ? "boys" : codes === null ? "" : split || first.girls && others.some((g) => g.boys) ? "girls" : "mixed";
+  if (adult > 0)
+    return { age: Age2.from("Adult", { year }), level, population };
+  const cols = gs.map((g) => g.column);
+  const lo = Math.min(...cols);
+  const hi = Math.max(...cols);
+  const series = others.filter((g) => g.digit === first.digit && g.letters === first.letters && g.boys === boys);
+  const offered = series.map((g) => g.column).filter((c) => c !== null);
+  const top = offered.length > 1 && hi >= Math.max(...offered);
+  const band = top ? `O${lo - 1}` : lo === hi ? `U${hi}` : `U${hi}/${hi - lo + 1}yr`;
+  return { age: Age2.from(band, { year }), level, population };
+}
+var foldCode = (code) => code.trim().toUpperCase();
+var NO_AGE = Age2.from("", { year: null });
+function createCodeReader(options = {}) {
+  const standardized = new Set([...options.standardized ?? []].map((p) => p.trim().toLowerCase()));
+  const scheme = (platform) => standardized.has(platform.trim().toLowerCase()) ? "standardized" : "feis-specific";
+  function read(code, ctx) {
+    const s = scheme(ctx.platform);
+    const feis = (ctx.feis ?? "").trim() === "" ? null : ctx.feis.trim();
+    const year = ctx.year ?? null;
+    const make = (refusal, source, age, level, population, entry) => {
+      const v = validity(code.trim() === "", refusal);
+      return Object.freeze({
+        [Symbol.toStringTag]: "CompCode",
+        ...v,
+        print: code,
+        platform: ctx.platform,
+        feis,
+        scheme: s,
+        source: v.isValid() ? source : null,
+        age: v.isValid() ? age : NO_AGE,
+        level: v.isValid() ? level : null,
+        population: v.isValid() ? population : "",
+        entry: v.isValid() ? entry : null,
+        isComp: () => v.isValid() && age.isAge()
+      });
+    };
+    const refuse = (r) => make(r, null, NO_AGE, null, "", null);
+    if (code.trim() === "")
+      return refuse("not-a-code");
+    if (feis === null)
+      return refuse("no-feis");
+    const codes = ctx.codes === undefined ? null : [...ctx.codes];
+    if (ctx.syllabus !== undefined && ctx.syllabus.length > 0) {
+      const hits = ctx.syllabus.filter((e) => foldCode(e.code) === foldCode(code));
+      if (hits.length === 0)
+        return refuse("not-in-syllabus");
+      if (hits.length > 1)
+        return refuse("two-entries");
+      const e = hits[0];
+      const printed = e.age !== undefined && e.age.trim() !== "" ? Age2.from(e.age, { year }) : null;
+      const age = printed?.isAge() === true ? printed : compTitle2(e.title, { year }).age;
+      return make(null, "syllabus", age, null, populationIn2(e.title), e);
+    }
+    if (s === "feis-specific")
+      return refuse("feis-specific");
+    const decoded = decode(code, year, codes);
+    if (decoded === null || !decoded.age.isAge())
+      return refuse("not-a-code");
+    return make(null, "code", decoded.age, decoded.level, decoded.population, null);
+  }
+  return Object.freeze({ scheme, read });
+}
+var DEFAULT_CODE_READER = createCodeReader();
+function compCode(code, ctx) {
+  return DEFAULT_CODE_READER.read(code, ctx);
+}
+export {
+  DEFAULT_CODE_READER,
+  compCode,
+  createCodeReader
+};

package/dist/schedule.js

@@ -2,7 +2,7 @@ import"./chunks/place-kmh59zkw.js";
 import {
   compTitle2,
   matchTitle2
-} from "./chunks/place-k0p9af4f.js";
+} from "./chunks/place-7jfd4m3j.js";
 
 function hallKey(hall) {
   return hall.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();

package/dist/title.js

@@ -3,12 +3,13 @@ import {
   codePopulation2,
   secondIn2,
   roundNumbersIn2,
+  roundFold2,
   compTitle2,
   populationRelation2,
   titleRelation2,
   ladderOf2,
   matchTitle2
-} from "./chunks/place-k0p9af4f.js";
+} from "./chunks/place-7jfd4m3j.js";
 import"./chunks/place-kmh59zkw.js";
 export {
   codePopulation2 as codePopulation,
@@ -17,6 +18,7 @@ export {
   matchTitle2 as matchTitle,
   populationIn2 as populationIn,
   populationRelation2 as populationRelation,
+  roundFold2 as roundFold,
   roundNumbersIn2 as roundNumbersIn,
   secondIn2 as secondIn,
   titleRelation2 as titleRelation

package/dist/types/code.d.ts

@@ -0,0 +1,41 @@
+import { Age } from "./age.ts";
+import { type Population } from "./title.ts";
+import { type Validated } from "./validated.ts";
+export type { EmptyReason, Validated } from "./validated.ts";
+export type CodeScheme = "standardized" | "feis-specific";
+export type CodeRefusal = "no-feis" | "feis-specific" | "not-in-syllabus" | "two-entries" | "not-a-code";
+export interface CodeEntry {
+    readonly code: string;
+    readonly title: string;
+    readonly age?: string;
+}
+export interface CodeContext<E extends CodeEntry = CodeEntry> {
+    readonly platform: string;
+    readonly feis: string | null | undefined;
+    readonly year?: number | null;
+    readonly syllabus?: readonly E[];
+    readonly codes?: Iterable<string>;
+}
+export interface CompCode<E extends CodeEntry = CodeEntry> extends Validated<CodeRefusal> {
+    readonly [Symbol.toStringTag]: "CompCode";
+    readonly print: string;
+    readonly platform: string;
+    readonly feis: string | null;
+    readonly scheme: CodeScheme;
+    readonly source: "syllabus" | "code" | null;
+    readonly age: Age;
+    readonly level: number | null;
+    readonly population: Population | "";
+    readonly entry: E | null;
+    isComp(): boolean;
+}
+export interface CodeReaderOptions {
+    readonly standardized?: Iterable<string>;
+}
+export interface CodeReader {
+    scheme(platform: string): CodeScheme;
+    read<E extends CodeEntry>(code: string, ctx: CodeContext<E>): CompCode<E>;
+}
+export declare function createCodeReader(options?: CodeReaderOptions): CodeReader;
+export declare const DEFAULT_CODE_READER: CodeReader;
+export declare function compCode<E extends CodeEntry>(code: string, ctx: CodeContext<E>): CompCode<E>;

package/dist/types/title.d.ts

@@ -8,6 +8,7 @@ export declare function populationIn(text: string): Population | "";
 export declare function codePopulation(code: string, codes: Iterable<string>): Population | "";
 export declare function secondIn(text: string): boolean;
 export declare function roundNumbersIn(folded: string, printed: boolean): Set<number>;
+export declare function roundFold(print: string): string;
 export interface TitleContext {
     readonly year?: number | null;
     readonly ladder?: AgeLadder;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.49.0",
-	"description": "Places, CLRG regions, school names, ages, dances, competition titles and schedules, and a person's print in its role, as they are printed: read, compared and told apart",
+	"version": "0.51.0",
+	"description": "Places, CLRG regions, school names, ages, dances, competition titles, codes and schedules, and a person's print in its role, as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
 		"regions",
@@ -73,6 +73,10 @@
 			"types": "./dist/types/schedule.d.ts",
 			"default": "./dist/schedule.js"
 		},
+		"./code": {
+			"types": "./dist/types/code.d.ts",
+			"default": "./dist/code.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],
@@ -89,7 +93,7 @@
 		"prepublishOnly": "bun scripts/build.ts && bun scripts/guard-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/names": "0.22.0"
+		"@finbheara/names": "0.25.0"
 	},
 	"devDependencies": {
 		"typescript": "7.0.2"