@finbheara/domain 0.30.0 → 0.32.0

package/README.md

@@ -16,6 +16,10 @@ person names.
   team's `averageAge`.
 - **Dances**: a spoken or printed set dance or céilí dance in, the dances it may name out,
   with tempo rules and hand counts.
+- **Competition titles**: a spoken or printed title (`girls 16 to 17`, `U17 BOYS R3`) in, the
+  syllabus entries it names and its round out, read through `Age` on the entries' own ladder.
+- **Schedules**: which entries, and which round, a hall runs at a time, and a printed running
+  order read into that shape.
 - **A database-backed index** of any of these nouns: the slots an in-memory name map hashes
   on, stored as indexed columns of a SQLite table you own.
 
@@ -45,6 +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`: a competition title read and matched onto syllabus entries (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
 factory: build your own with options when the default is not what you want.
@@ -122,13 +128,19 @@ geocode("Brooklyn").isPlace();   // false: a town of six US states and more, so
                                  // `Brooklyn, NY` reads
 place("Drogheda").arm;           // "unread": the store holds no Drogheda
 geocode("Prague", { near: "RCCEA", declared: true }).isPlace();
-                                 // false: the context lies outside the layer's
-                                 // countries, so no namesake town is read
+                                 // false: the town lies outside the context, so
+                                 // no namesake town is read
+geocode("Fife").isPlace();       // false: a town of Washington, and a council area
+                                 // of Scotland
 ```
 
-A context (a `country` or `near`) that reads to a place outside those six countries stops the
-layer for a bare town, so a city elsewhere is never read as its namesake in them. With no
-context `geocode("Prague")` is Prague, Oklahoma, the one Prague the layer holds. A print with a
+The layer reads a bare town by its name alone, so it reads one only where nothing contradicts
+it. A context (a `country` or `near`, read by the store, never as a town of the layer) that
+reads to ONE place which neither holds the town nor shares its country stops the layer: `Prague`
+near `RCCEA` and `Whitecross` under `Ireland` and `Ulster` read nothing. A context the store
+reads nothing for, or reads as several places, stops nothing, so with no context
+`geocode("Prague")` is still Prague, Oklahoma. A town named like a GeoNames admin2 area of those
+six countries that does not hold it (`Fife`) reads only where a context places it. A print with a
 qualifier (`Yonkers, NY`) is never stopped: the context never overrules the print.
 
 A `Place` is one of four arms: `resolved`, `plural` (a print naming more than one place),
@@ -364,6 +376,63 @@ team.fitsIn(Age.from("U40", { year: 2026 }));           // true
 averageAge([u12]);                                      // throws AgeMisuseError "not-exact"
 ```
 
+## Match a competition title
+
+An announcer names a competition by its title more often than by its number, and never quite
+as the syllabus prints it. `matchTitle` reads a title's age band with `Age.fromTitle`, reads every
+entry's band on the same ladder (the rungs the entries of the title's population offer), and
+answers the entries whose band is the same and whose population (girls and ladies one line, boys
+and men another) the title does not contradict. The entries are yours, as you hold them: a
+`title`, an optional `age` where the syllabus prints the band apart, and anything else you keep.
+
+```ts
+import { compTitle, matchTitle } from "@finbheara/domain/title";
+
+const entries = [
+	{ code: "27", title: "Girls 15 - 16", age: "15-16" },
+	{ code: "28", title: "Girls 14 - 15", age: "14-15" },
+	{ code: "29", title: "Girls 13 - 14", age: "13-14" },
+	{ code: "8", title: "Boys 14 - 15", age: "14-15" },
+];
+matchTitle("under 15 girls", entries).entries;   // [{ code: "28", ... }]: a rung at 14
+matchTitle("girls 14 to 15", entries).entries;   // the same entry
+matchTitle("boys 14-15 R2", entries).round;      // 2
+
+const t = compTitle("U17 BOYS R3");
+t.age.ag1;          // "u17"
+t.population;       // "boys"
+t.round;            // 3
+compTitle("Girls Under 13 B").split;             // "b"
+compTitle("Treble Reel Special").invalidReason(); // "no-age"
+```
+
+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.
+
+## Ask a schedule
+
+A split band's competitions share their card numbers, so a card heard on a stage fits each of
+them. Only the schedule says which split runs in which hall. A schedule is slots: an entry, a
+round where one is printed, a hall, a day, and a start and an end in whatever clock you keep.
+
+```ts
+import { readRunningOrder, scheduleAt } from "@finbheara/domain/schedule";
+
+const slots = [
+	{ hall: "Hall A", day: 1, start: 540, end: 660, round: 1, entry: girlsU13A },
+	{ hall: "Hall B", day: 1, start: 540, end: 660, round: 1, entry: girlsU13B },
+];
+scheduleAt(slots, { hall: "HALL B", day: 1, at: 600 });   // the B split
+
+// a running order printed for one hall: titles cut after each round mark and at each comma,
+// an age list sharing the population before it
+readRunningOrder("U17 BOYS R3 U13 GIRLS B R1 & R2", entries, { hall: "Hall B", day: 2 });
+```
+
+A slot with no times is its hall's whole day. `sameHall` reads `Hall A`, `HALL A` and `hall-a` as
+one hall. The module reads no file: a full schedule, with its times, is yours to transcribe.
+
 ## Index names in a database
 
 `createNameMap` (from `@finbheara/names`) and `mapOfSchools` hold their names in memory. An