@finbheara/domain 0.5.0 → 0.7.0

package/README.md

@@ -39,7 +39,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/tune` | `tune()`, `tuneRelation`, `tempoLegal`, `settingAt`, `TUNE_NODES`: the CLRG set dance list, each tune with its time, speeds and bars |
 | `@finbheara/domain/ceili` | `ceili()`, `ceiliRelation`, `CEILI_NODES`: the céilí handbook dances |
 | `@finbheara/domain/dance` | `dance()`: a print read as a tune and a céilí dance, narrowed by its round |
-| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, `validYOB`, the age constants |
+| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `Age.fromTitle`, `ageTitleToken`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, `validYOB`, the age constants |
 | `@finbheara/domain/noun-index` | `createIndex`, `indexSchema`, `personEncoder`, and the `SqlHandle`/`NounEncoder` types: a database-backed name map (below) |
 | `@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) |
@@ -56,7 +56,7 @@ questions:
 | method | true when |
 |---|---|
 | `isEmpty()` | nothing was printed: an empty or blank cell, no dance named |
-| `isRefused()` | something was printed and the type declines it: a placeholder, a school in a place field, `U2`, a `1900` year of birth |
+| `isRefused()` | something was printed and the type declines it: a placeholder, a school in a place field, a URL or an online event in a place field, `U2`, a `1900` year of birth |
 | `isValid()` | neither: `!isEmpty() && !isRefused()` |
 
 `invalidReason()` is `null` when the value is valid, `"empty"` when it is empty, and the
@@ -71,6 +71,7 @@ Valid does not mean usable. A print the reader does not know but cannot rule out
 place("").invalidReason();                                    // "empty"
 place("n/a").invalidReason();                                 // "placeholder"
 place("Ardmore").isValid();                                   // true: valid, unknown
+place("Video Feis").invalidReason();                          // "online"
 DEFAULT_SCHOOL_NAME_READER.schoolName("N/A").isRefused();     // true
 Age.fromYOB(1900).invalidReason();                            // "year-out-of-range"
 tune("").isEmpty();                                           // true
@@ -102,6 +103,13 @@ A `Place` is one of four arms: `resolved`, `plural` (a print naming more than on
 `ambiguous` (one print, several readings) and `unread`. Only `conflict` between two readings
 says they cannot be one place; `same`, `contains` and `overlaps` do not.
 
+A print that is clearly not a place is refused, with its reason: a placeholder
+(`[address withheld]`, `Other`), a URL anywhere in the print (`web`), an online event in the
+venue field (`online`), a change-of-venue notice (`notice`), or a replacement character where
+the source lost bytes (`damaged`). These are asked only where the store reads nothing, so a
+refusal never takes a reading away. Mojibake that can be decoded back is not refused: repair it
+before reading.
+
 ## Find a CLRG region
 
 ```ts
@@ -234,8 +242,41 @@ Age.fromYOB(1999).fitsIn(Age.from("U18", { year: 2025 }));               // fals
 Age.fromYOB(1999).fitsIn(Age.from("Over 21", { year: 2026, top: true })); // true
 
 canOverlap(u12, Age.from("U14", { year: 2026 }), dancer);                 // true
+
+Age.from("13 & Over", { year: 2026 }).interval();       // { lo: 13, hi: Infinity }, as "Over 13"
+```
+
+A competition title usually carries its age group in its words. `Age.fromTitle` finds the
+phrase, reads it as `Age.from` would, and says where it was. A title that names no age group
+is empty, not refused. Competition numbers are never read as ages.
+
+```ts
+const t = Age.fromTitle("Novice Hornpipe Under 10", { year: 2026 });
+t.token;                                                // "u10"
+t.span;                                                 // { start: 16, end: 24, text: "Under 10" }
+t.age.birthYears();                                     // { from: 2016, to: 2023 }
+
+Age.fromTitle("Open Championship 15-16", { year: 2026 }).token;          // "15-16"
+Age.fromTitle("Competition 719OC - Open Championship (O18)").token;     // "o18", not "o9"
+Age.fromTitle("Treble Reel Special", { year: 2026 }).age.isEmpty();     // true
+Age.fromTitle("Mixed Reel 7 & Under").token;            // "u8": a 7-year-old dances in it
+Age.fromTitle("Girls 8 and under 9 years").token;       // "8-9"
+Age.fromTitle("Junior Boys 12 Years").token;            // "u13"
+Age.fromTitle("10-11 Single Jig").token;                // "10-11", a band, not a number
+Age.fromTitle("Competition 001-013 - Reel").token;      // "", a competition number
+Age.fromTitle("Senior Boys Reel 15&16").token;          // "15-16": a range beats the word
+Age.fromTitle("Beginner Adults Reel U40").token;        // "adult u40": the adult band under 40
+Age.fromTitle("Adult / Child Reel Under 10").token;     // "u10": no adult dances in it
 ```
 
+An adult word beside an `Under N` above 18 reads both: `adult u40` is adult (`isAdult()`), with
+the adult floor of 18 and a ceiling of 40, so `Age.from("adult u40", { year: 2026 })` is born
+1986 to 2007. At `Under 18` the ceiling meets the floor and the word alone is read. Below 18 the
+youth band stands.
+
+An age group is the age on the first of January, so a title that admits the dancer who is
+`N` (`7 & Under`, `7/U`, `7 Years`) is the `Under N+1` group.
+
 A value the reader cannot stand behind is returned, not thrown. An `Age` is `Validated` (above):
 an age group under `U3` admits nobody old enough to dance, and a year of birth outside 1901 to
 2099 is not one, so the placeholders `1000` and `1900` are refused. An invalid `Age` has no

package/dist/age.js

@@ -2,6 +2,112 @@ import {
   validity
 } from "./chunks/place-q9kwsmzd.js";
 
+var LEAD_ID = /^\s*(?:comp(?:etition)?\.?\s*)?\d+[a-z]*(?:[/-]\d*[a-z]*)*\s*[-:.]?\s*/i;
+var PAREN = /\(([^)]*)\)/g;
+var AND_OVER = /(?<![a-z0-9])(\d{1,2})\s*(?:years?\s*)?(?:&|\+|\band\b)\s*(?:over|older|up|o)(?![a-z])/i;
+var OVER_WORD = /(?:\bover\s*|\bos\s+cionn\s*|(?<![a-z0-9])o\.?\s*)(\d{1,2})(?![a-z0-9])/i;
+var OVER_GLUED = /(?<![a-z0-9])(\d{1,2})\s*o(?![a-z'’])/i;
+var OVER_PLUS = /(?<![a-z0-9])(\d{1,2})\s*\+/;
+var UNDER = /(?:\bunder\s*|\bfaoi\s*|(?<![a-z0-9])u\.?\s*)(\d{1,2})(?![a-z0-9])/i;
+var AND_UNDER = /(?<![a-z0-9])(\d{1,2})\s*(?:years?\s*)?(?:&|\/|\band\b)\s*u(?:nder)?(?![a-z])(?!\s*\d)/i;
+var AND_UNDER_RANGE = /(?<![a-z0-9])(\d{1,2})\s*(?:&|\band\b)\s*under\s*(\d{1,2})(?![a-z0-9])/i;
+var AND_RANGE = /(?<![a-z0-9])(?<!\b(?:under|und|over|faoi|cionn|u|o)\.?\s*)(?<!\d\s*,\s*)(?<!\(\s*)(\d{1,2})\s*(?:&|\band\b)\s*(\d{1,2})(?![a-z0-9])(?!\s*-?\s*hand)(?!\s*(?:&|\+|\/|,|\)|\band\b|\bor\b))/i;
+var YEARS = /(?<![a-z0-9])(?<!\d\s*(?:&|\/|\band\b|[-\u0096–—]|\bto\b)\s*)(\d{1,2})\s*(?:years?|yrs?)(?![a-z0-9])(?!\s*(?:&|\+|\/|\band\b|\bor\b|old))/i;
+var RANGE_DASH = String.raw`(?:\u00c2?[-\u0096–—]|\bto\b)`;
+var RANGE = new RegExp(String.raw`(?<![0-9])(?<![0-9][a-z]*)(?<!(?:^|[^a-z0-9])[a-z])(?:u\s*)?(\d{1,2})\s*${RANGE_DASH}\s*(\d{1,2})(?![a-z0-9])`, "i");
+var LEAD_RANGE = new RegExp(String.raw`^\s*([1-9]\d?)\s*${RANGE_DASH}\s*([1-9]\d?)(?![a-z0-9])(?!\s*[/&])`, "i");
+var ADULT_CODE = /^\s*a(?:\d{1,2}(?:u|o|&o))?\s*$/i;
+var ADULT = /(?<!non[\s-])(?<!-)\b(?:adults?|advanced\s+adults?|masters?)\b/i;
+var SENIOR = /(?<!-)\bseniors?\b/i;
+var TITLE_RANGE_MIN = 3;
+var TITLE_RANGE_MAX = 40;
+var NONE = Object.freeze({ token: "", span: null });
+function at(title, offset, start, end, token) {
+  const a = offset + start;
+  const b = offset + end;
+  return { token, span: { start: a, end: b, text: title.slice(a, b) } };
+}
+function inFence(a, b) {
+  const lo = Number(a);
+  const hi = Number(b);
+  return lo >= TITLE_RANGE_MIN && hi <= TITLE_RANGE_MAX && lo < hi;
+}
+function readAnchored(title, s, offset, aside = false) {
+  for (const re of [AND_OVER, OVER_WORD, OVER_GLUED]) {
+    const m = re.exec(s);
+    if (m?.[1] !== undefined)
+      return at(title, offset, m.index, m.index + m[0].length, `o${Number(m[1])}`);
+  }
+  const u = AND_UNDER_RANGE.exec(s);
+  if (u?.[1] !== undefined && u[2] !== undefined && inFence(u[1], u[2]))
+    return at(title, offset, u.index, u.index + u[0].length, `${Number(u[1])}-${Number(u[2])}`);
+  const j = aside ? null : AND_RANGE.exec(s);
+  if (j?.[1] !== undefined && j[2] !== undefined && inFence(j[1], j[2]))
+    return at(title, offset, j.index, j.index + j[0].length, `${Number(j[1])}-${Number(j[2])}`);
+  const l = LEAD_RANGE.exec(s);
+  if (l?.[1] !== undefined && l[2] !== undefined && inFence(l[1], l[2])) {
+    const lead = l[0].length - l[0].trimStart().length;
+    return at(title, offset, lead, l[0].length, `${Number(l[1])}-${Number(l[2])}`);
+  }
+  const stripped = s.replace(LEAD_ID, "");
+  const shift = s.length - stripped.length;
+  const r = RANGE.exec(stripped);
+  if (r?.[1] !== undefined && r[2] !== undefined && inFence(r[1], r[2]))
+    return at(title, offset + shift, r.index, r.index + r[0].length, `${Number(r[1])}-${Number(r[2])}`);
+  const au = AND_UNDER.exec(s);
+  if (au?.[1] !== undefined)
+    return at(title, offset, au.index, au.index + au[0].length, `u${Number(au[1]) + 1}`);
+  const m = UNDER.exec(s);
+  if (m?.[1] !== undefined)
+    return at(title, offset, m.index, m.index + m[0].length, `u${Number(m[1])}`);
+  const y = YEARS.exec(s);
+  if (y?.[1] !== undefined)
+    return at(title, offset, y.index, y.index + y[0].length, `u${Number(y[1]) + 1}`);
+  const p = OVER_PLUS.exec(s);
+  if (p?.[1] !== undefined)
+    return at(title, offset, p.index, p.index + p[0].length, `o${Number(p[1])}`);
+  const a = ADULT.exec(s);
+  if (a !== null)
+    return at(title, offset, a.index, a.index + a[0].length, "adult");
+  const n = SENIOR.exec(s);
+  if (n !== null)
+    return at(title, offset, n.index, n.index + n[0].length, "senior");
+  return NONE;
+}
+function ageTitleToken(title) {
+  const s = title.trim();
+  if (s === "")
+    return NONE;
+  const lead = title.length - title.trimStart().length;
+  PAREN.lastIndex = 0;
+  let adultAside = null;
+  for (const m of s.matchAll(PAREN)) {
+    const inner = m[1] ?? "";
+    const from = lead + (m.index ?? 0) + 1;
+    const i = m.index ?? 0;
+    const tail = i + m[0].length === s.length && !/[a-z0-9]/i.test(s[i - 1] ?? "");
+    if (tail && ADULT_CODE.test(inner)) {
+      const a = inner.length - inner.trimStart().length;
+      adultAside = at(title, from, a, inner.trimEnd().length, "adult");
+      continue;
+    }
+    const t = readAnchored(title, inner, from, true);
+    if (t.token !== "")
+      return adultOverUnder(title, s, lead, t);
+  }
+  const words = readAnchored(title, s, lead);
+  return words.token === "" && adultAside !== null ? adultAside : adultOverUnder(title, s, lead, words);
+}
+var ADULT_UNDER_MIN = 18;
+function adultOverUnder(title, s, lead, t) {
+  const n = /^u(\d+)$/.exec(t.token)?.[1];
+  if (n === undefined || Number(n) < ADULT_UNDER_MIN)
+    return t;
+  const a = ADULT.exec(s);
+  const token = Number(n) > ADULT_UNDER_MIN ? `adult u${n}` : "adult";
+  return a === null ? t : at(title, lead, a.index, a.index + a[0].length, token);
+}
+
 var YOUNGEST_FLOOR = 0;
 var ADULT_FLOOR = 18;
 var MAJORS_FLOOR_YEARS = 3;
@@ -15,10 +121,12 @@ var YOB_RANGE = Object.freeze({ first: 1901, last: 2099 });
 var DANCE_UP_YEARS = 1;
 var ageOnJanuary1 = (year, born) => year - born - 1;
 var yearsSinceBirth = (year, born) => year - born;
-var UNDER = /^(?:u|under\s*)(\d+)$/i;
+var UNDER2 = /^(?:u|under\s*)(\d+)$/i;
 var OVER = /^(?:o|over\s*)(\d+)$/i;
-var RANGE = /^u?(\d+)\s*[-–]\s*(\d+)$/i;
+var AND_OVER2 = /^(\d+)\s*(?:&|and\b)\s*(?:over|o)$/i;
+var RANGE2 = /^u?(\d+)\s*[-–]\s*(\d+)$/i;
 var ADULT_WORD = /^(?:adults?|ad|advanced|masters?)$/i;
+var ADULT_UNDER = /^(?:adults?|ad)[\s-]*(?:u|under\s*)(\d+)$/i;
 var SENIOR_WORD = /^seniors?$/i;
 var NO_LADDER = Object.freeze({ caps: [], overs: [], ranges: [] });
 function maxWhere(xs, pred) {
@@ -44,32 +152,48 @@ function readRange(a, b, ladder) {
       clauses: [],
       parts: [a, b]
     };
-  const overlapping = ladder.ranges.includes(a) || ladder.ranges.includes(b + 1);
-  const bottom = !ladder.caps.some((c) => c <= a);
-  const atAdultFloor = bottom && a >= ADULT_FLOOR;
-  const youngest = bottom && !atAdultFloor;
-  const onRung = ladder.caps.includes(a);
-  const floor = overlapping || atAdultFloor || onRung ? a : Math.max(YOUNGEST_FLOOR, a - 1);
-  const clauses = [overlapping ? "range-overlapping" : "range-inclusive"];
-  if (youngest)
-    clauses.push("youngest-absorbs");
-  else if (atAdultFloor)
-    clauses.push("range-adult-floor");
-  else if (!overlapping)
-    clauses.push(onRung ? "range-floor-on-rung" : "range-floor-widened");
+  if (ladder.ranges.some(([c, d]) => (c !== a || d !== b) && c < b && a < d))
+    return {
+      kind: "range",
+      interval: null,
+      refusal: "overlapping-ranges",
+      clauses: ["range-overlapping"],
+      parts: [a, b]
+    };
+  const below = maxWhere(ladder.caps, (c) => c < b);
+  const adultFloor = below === undefined && ladder.adult === true && b > ADULT_FLOOR;
+  const meetsOver = ladder.overs.includes(b + 1) && !ladder.caps.some((c) => c > b);
+  const clauses = [
+    "range-as-under",
+    below !== undefined ? "under-floored-on-rung" : adultFloor ? "range-adult-floor" : "youngest-absorbs"
+  ];
+  if (meetsOver)
+    clauses.push("range-top-meets-over");
   return {
     kind: "range",
-    interval: { lo: youngest ? YOUNGEST_FLOOR : floor, hi: overlapping ? b : b + 1 },
+    interval: {
+      lo: below ?? (adultFloor ? ADULT_FLOOR : YOUNGEST_FLOOR),
+      hi: meetsOver ? b + 1 : b
+    },
     refusal: null,
     clauses,
     parts: [a, b]
   };
 }
 function read(token, ladder, top) {
-  const r = RANGE.exec(token);
+  const r = RANGE2.exec(token);
   if (r !== null)
     return readRange(Number(r[1]), Number(r[2]), ladder);
-  if (ADULT_WORD.test(token))
+  const au = ADULT_UNDER.exec(token);
+  if (au !== null && Number(au[1]) > ADULT_FLOOR)
+    return {
+      kind: "adult",
+      interval: { lo: ADULT_FLOOR, hi: Number(au[1]) },
+      refusal: null,
+      clauses: ["adult-under-ceiling"],
+      parts: [Number(au[1])]
+    };
+  if (au !== null || ADULT_WORD.test(token))
     return {
       kind: "adult",
       interval: { lo: ADULT_FLOOR, hi: Number.POSITIVE_INFINITY },
@@ -87,7 +211,7 @@ function read(token, ladder, top) {
       parts: []
     };
   }
-  const u = UNDER.exec(token);
+  const u = UNDER2.exec(token);
   if (u !== null) {
     const n = Number(u[1]);
     const below = maxWhere(ladder.caps, (c) => c < n);
@@ -99,7 +223,7 @@ function read(token, ladder, top) {
       parts: [n]
     };
   }
-  const o = OVER.exec(token);
+  const o = OVER.exec(token) ?? AND_OVER2.exec(token);
   if (o !== null) {
     const n = Number(o[1]);
     const above = top ? undefined : minWhere(ladder.overs, (c) => c > n);
@@ -194,7 +318,7 @@ function fromPrint(print, context = {}) {
         throw new Error(`Age.from(${JSON.stringify(print)}): birthYears needs a competition year`);
       return birthYearsOfInterval(iv, at);
     },
-    floorObserved: () => reading.kind !== "under" || iv === null ? null : reading.clauses.includes("under-floored-on-rung")
+    floorObserved: () => reading.kind !== "under" && reading.kind !== "range" || iv === null ? null : reading.clauses.includes("under-floored-on-rung") || reading.clauses.includes("range-adult-floor")
   });
 }
 function fromYOB(from, to = from, context = {}) {
@@ -237,21 +361,24 @@ function fromYOB(from, to = from, context = {}) {
     floorObserved: () => null
   });
 }
-var Age = Object.freeze({ from: fromPrint, fromYOB });
+function fromTitle(title, context = {}) {
+  const t = ageTitleToken(title);
+  return Object.freeze({ age: fromPrint(t.token, context), token: t.token, span: t.span });
+}
+var Age = Object.freeze({ from: fromPrint, fromYOB, fromTitle });
 function sourceOf(r) {
   const iv = r.interval;
   if (iv === null)
     return "open";
   switch (r.kind) {
     case "range":
-      return "printed-range";
+    case "under":
+      return iv.lo > YOUNGEST_FLOOR ? "sibling-narrowed" : "printed-band";
     case "over":
       return iv.hi === Number.POSITIVE_INFINITY ? "printed-band" : "sibling-narrowed";
     case "adult":
     case "senior":
       return "printed-band";
-    case "under":
-      return iv.lo > YOUNGEST_FLOOR ? "sibling-narrowed" : "printed-band";
     default:
       return "open";
   }
@@ -435,6 +562,8 @@ export {
   MAJORS_FLOOR_YEARS,
   MIN_FEIS_AGE,
   MIN_MAJOR_AGE,
+  TITLE_RANGE_MAX,
+  TITLE_RANGE_MIN,
   UNDER_CAP,
   UNDER_CAP_MAX_TOP,
   YOB_RANGE,
@@ -443,6 +572,7 @@ export {
   YOUNG_FLOOR,
   ageOnJanuary1,
   ageRelation,
+  ageTitleToken,
   averageAge,
   birthYearsDisjoint,
   birthYearsMeet,