@finbheara/domain 0.50.0 → 0.51.0

package/README.md

@@ -50,6 +50,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@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`, `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
@@ -454,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/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/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/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.50.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.23.0"
+		"@finbheara/names": "0.25.0"
 	},
 	"devDependencies": {
 		"typescript": "7.0.2"