@finbheara/domain 0.2.0 → 0.3.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 |
 | `@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`, the age constants |
+| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, the `Validated` type, 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 |
 
@@ -180,6 +180,19 @@ Age.fromYOB(1999).fitsIn(Age.from("Over 21", { year: 2026, top: true })); // tru
 canOverlap(u12, Age.from("U14", { year: 2026 }), dancer);                 // true
 ```
 
+A value the reader cannot stand behind is returned, not thrown. Every `Age` answers
+`isValid()` and `invalidReason()`: an age group under `U3` admits nobody old enough to dance,
+and a year of birth outside 1900 to 2099 is not one. An invalid `Age` has no birth years and
+rules nothing out.
+
+```ts
+Age.from("U2", { year: 2026 }).isValid();               // false
+Age.from("U2", { year: 2026 }).invalidReason();         // "below-youngest-band"
+Age.fromYOB(2222).invalidReason();                      // "year-out-of-range"
+Age.from("All", { year: 2026 }).invalidReason();        // "not-a-band"
+Age.from("", { year: 2026 }).isValid();                 // true: empty, not invalid
+```
+
 A team's age is the average of its dancers' ages, rounded to two decimals. `averageAge`
 takes exact ages only and returns an `AverageAge`, a separate type that refuses, by name,
 any use that would treat it as one dancer's age.

package/dist/age.js

@@ -6,6 +6,8 @@ var UNDER_CAP_MAX_TOP = 21;
 var YOUNG_FLOOR = Object.freeze({ hard: 2, soft: 4 });
 var MIN_MAJOR_AGE = 4;
 var MIN_FEIS_AGE = 3;
+var YOUNGEST_BAND_TOP = MAJORS_FLOOR_YEARS;
+var YOB_RANGE = Object.freeze({ first: 1900, last: 2099 });
 var DANCE_UP_YEARS = 1;
 var ageOnJanuary1 = (year, born) => year - born - 1;
 var yearsSinceBirth = (year, born) => year - born;
@@ -116,6 +118,11 @@ function read(token, ladder, top) {
   }
   return { kind: null, interval: null, refusal: "not-a-band", clauses: [], parts: [] };
 }
+function refuseBelowYoungest(r) {
+  if (r.interval === null || r.interval.hi >= YOUNGEST_BAND_TOP)
+    return r;
+  return { ...r, interval: null, refusal: "below-youngest-band", clauses: [] };
+}
 
 class AgeMisuseError extends Error {
   misuse;
@@ -146,7 +153,7 @@ function fromPrint(print, context = {}) {
   const ladder = context.ladder ?? NO_LADDER;
   const year = context.year === undefined ? currentYear() : context.year;
   const ag1 = print.trim().toLowerCase();
-  const reading = ag1 === "" ? { kind: null, interval: null, refusal: null, clauses: [], parts: [] } : read(print.trim(), ladder, context.top === true);
+  const reading = ag1 === "" ? { kind: null, interval: null, refusal: null, clauses: [], parts: [] } : refuseBelowYoungest(read(print.trim(), ladder, context.top === true));
   const iv = reading.interval;
   const arm = ag1 === "" ? "empty" : iv === null ? "open" : "band";
   const ag2 = iv !== null ? display(iv) : ag1 === "" ? "" : `${ag1}?`;
@@ -162,6 +169,8 @@ function fromPrint(print, context = {}) {
     parts: reading.parts,
     length: ag2.length,
     refusal: reading.refusal,
+    isValid: () => reading.refusal === null,
+    invalidReason: () => reading.refusal,
     source,
     clauses: reading.clauses,
     ladder,
@@ -186,7 +195,7 @@ function fromPrint(print, context = {}) {
     floorObserved: () => reading.kind !== "under" || iv === null ? null : reading.clauses.includes("under-floored-on-rung")
   });
 }
-function fromYOB(from, to = from) {
+function fromYOB(from, to = from, context = {}) {
   for (const y of [from, to])
     if (y !== null && !Number.isInteger(y))
       throw new RangeError(`Age.fromYOB(${from}, ${to}): a year of birth is a whole number`);
@@ -194,29 +203,34 @@ function fromYOB(from, to = from) {
     throw new RangeError("Age.fromYOB(null, null): at least one end is a year");
   if (from !== null && to !== null && from > to)
     throw new RangeError(`Age.fromYOB(${from}, ${to}): the earliest year comes first`);
-  const exact = from !== null && from === to;
-  const ag0 = exact ? String(from) : `${from ?? ""}..${to ?? ""}`;
-  const ag2 = `b${ag0}`;
-  const years = Object.freeze({ from, to });
+  const at = context.year ?? null;
+  const valid = [from, to].every((y) => y === null || y >= YOB_RANGE.first && y <= YOB_RANGE.last) && (at === null || to === null || yearsSinceBirth(at, to) >= YOUNG_FLOOR.hard);
+  const refusal = valid ? null : "year-out-of-range";
+  const exact = valid && from !== null && from === to;
+  const ag0 = from !== null && from === to ? String(from) : `${from ?? ""}..${to ?? ""}`;
+  const ag2 = valid ? `b${ag0}` : `b${ag0}?`;
+  const years = Object.freeze(valid ? { from, to } : { from: null, to: null });
   return withRelations({
     [Symbol.toStringTag]: "Age",
     toString: () => ag2,
-    arm: "yob",
+    arm: valid ? "yob" : "open",
     kind: "yob",
     ag0,
     ag1: ag0,
     ag2,
-    parts: exact ? [from] : [from, to].filter((y) => y !== null),
+    parts: from !== null && from === to ? [from] : [from, to].filter((y) => y !== null),
     length: ag2.length,
-    refusal: null,
-    source: "printed-yob",
+    refusal,
+    isValid: () => valid,
+    invalidReason: () => refusal,
+    source: valid ? "printed-yob" : "open",
     clauses: [],
     ladder: NO_LADDER,
     year: null,
     isEmpty: () => false,
-    isAge: () => true,
+    isAge: () => valid,
     isExact: () => exact,
-    isAndOver: () => from === null,
+    isAndOver: () => valid && from === null,
     isAdult: () => false,
     interval: () => null,
     birthYears: () => years,
@@ -250,7 +264,7 @@ function birthYearsOfInterval(iv, year) {
     to: Math.min(year - iv.lo - 1, year - MAJORS_FLOOR_YEARS)
   };
 }
-var inBirthYears = (a) => a.arm === "yob" || a.year !== null;
+var inBirthYears = (a) => a.kind === "yob" || a.year !== null;
 function spanOf(a) {
   if (!a.isAge())
     return null;
@@ -355,6 +369,25 @@ function birthYearsDisjoint(a, b) {
     return true;
   return false;
 }
+function intersectBirthYears(windows) {
+  let from = null;
+  let to = null;
+  let n = 0;
+  for (const w of windows) {
+    if (w.from === null && w.to === null)
+      continue;
+    n++;
+    if (w.from !== null)
+      from = from === null ? w.from : Math.max(from, w.from);
+    if (w.to !== null)
+      to = to === null ? w.to : Math.min(to, w.to);
+  }
+  if (n === 0)
+    return { from: null, to: null, n: 0 };
+  if (from !== null && to !== null && from > to)
+    return null;
+  return { from, to, n };
+}
 function birthYearsMeet(card, other, slack = 0) {
   if (card.from !== null && other.to !== null && card.from > other.to)
     return false;
@@ -378,6 +411,11 @@ function underCappedYears(b, year, n = UNDER_CAP.plain) {
 function underCapRefuses(bandFrom, identityFrom, n) {
   return identityFrom > bandFrom + n;
 }
+function validYOB(y, year) {
+  if (y === null || y === undefined || !Number.isInteger(y))
+    return null;
+  return Age.fromYOB(y, y, { year: year ?? null }).isValid() ? y : null;
+}
 function youngFloor(year, oldest) {
   const s = yearsSinceBirth(year, oldest);
   if (s >= YOUNG_FLOOR.soft)
@@ -399,6 +437,8 @@ export {
   MIN_MAJOR_AGE,
   UNDER_CAP,
   UNDER_CAP_MAX_TOP,
+  YOB_RANGE,
+  YOUNGEST_BAND_TOP,
   YOUNGEST_FLOOR,
   YOUNG_FLOOR,
   ageOnJanuary1,
@@ -408,6 +448,7 @@ export {
   birthYearsMeet,
   birthYearsOfInterval,
   canOverlap,
+  intersectBirthYears,
   isAveraged,
   roundedMeanHundredths,
   tooYoungForFeis,
@@ -415,6 +456,7 @@ export {
   underCapApplies,
   underCapRefuses,
   underCappedYears,
+  validYOB,
   yearsSinceBirth,
   youngFloor
 };

package/dist/ceili.js

@@ -4,8 +4,8 @@ import {
   ceiliById2,
   ceili2,
   ceiliRelation2
-} from "./chunks/place-7gqecaxd.js";
-import"./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-0ehc2q69.js";
+import"./chunks/place-htxgptyv.js";
 export {
   CEILI_NODES2 as CEILI_NODES,
   allCeilis2 as allCeilis,

package/dist/chunks/{place-7gqecaxd.js → place-0ehc2q69.js}

@@ -3,7 +3,7 @@ import {
   matchNodes,
   candidateRelation,
   isDanceTypePrint2
-} from "./place-g6yw4cq6.js";
+} from "./place-htxgptyv.js";
 
 function node(id, name, irish, family, formation, opts = {}) {
   const kind = "round" in formation ? "round" : ("long" in formation) ? "long" : "set";

package/dist/chunks/{place-kr42294h.js → place-2ja9yx08.js}

@@ -5,7 +5,7 @@ import {
   candidateRelation,
   rhythmOfTime2,
   isDanceTypePrint2
-} from "./place-g6yw4cq6.js";
+} from "./place-htxgptyv.js";
 
 var SET_MIN_SPEED2 = Object.freeze({
   jig: 66,

package/dist/chunks/{place-g6yw4cq6.js → place-htxgptyv.js}

@@ -104,6 +104,7 @@ function rhythmOfTime2(time) {
 }
 var TYPE_PRINTS = new Map([
   ["reel", ["reel"]],
+  ["jig", ["light-jig", "single-jig", "treble-jig"]],
   ["light jig", ["light-jig"]],
   ["single jig", ["single-jig"]],
   ["slip jig", ["slip-jig"]],

package/dist/dance-types.js

@@ -4,7 +4,7 @@ import {
   danceTypes2,
   danceTypePrints2,
   isDanceTypePrint2
-} from "./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-htxgptyv.js";
 export {
   DANCE_TYPES2 as DANCE_TYPES,
   danceTypePrints2 as danceTypePrints,

package/dist/dance.js

@@ -1,10 +1,10 @@
-import"./chunks/place-g6yw4cq6.js";
+import"./chunks/place-htxgptyv.js";
 import {
   ceili2
-} from "./chunks/place-7gqecaxd.js";
+} from "./chunks/place-0ehc2q69.js";
 import {
   tune2
-} from "./chunks/place-kr42294h.js";
+} from "./chunks/place-2ja9yx08.js";
 
 function dance(print, round) {
   const setting = round === "traditional-set" ? "traditional" : undefined;

package/dist/tune.js

@@ -8,8 +8,8 @@ import {
   settingAt2,
   tune2,
   tuneRelation2
-} from "./chunks/place-kr42294h.js";
-import"./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-2ja9yx08.js";
+import"./chunks/place-htxgptyv.js";
 export {
   PLAUSIBLE_SET_TEMPO_MAX2 as PLAUSIBLE_SET_TEMPO_MAX,
   SET_MIN_SPEED2 as SET_MIN_SPEED,

package/dist/types/age-types.d.ts

@@ -11,6 +11,9 @@ export interface AgeLadder {
     readonly overs: readonly number[];
     readonly ranges: readonly number[];
 }
+export interface YOBContext {
+    readonly year?: number | null;
+}
 export interface AgeContext {
     readonly ladder?: AgeLadder;
     readonly year?: number | null;
@@ -18,7 +21,7 @@ export interface AgeContext {
 }
 export type AgeArm = "band" | "yob" | "open" | "empty";
 export type AgeKind = "under" | "over" | "range" | "adult" | "senior" | "yob";
-export type AgeRefusal = "not-a-band" | "backwards-range" | "senior-without-ladder";
+export type AgeRefusal = "not-a-band" | "backwards-range" | "senior-without-ladder" | "below-youngest-band" | "year-out-of-range";
 export type AgeSource = "sibling-narrowed" | "printed-band" | "printed-range" | "printed-yob" | "open";
 export type AgeClause = "under-floored-on-rung" | "youngest-absorbs" | "over-ceiling-from-next-over" | "over-ceiling-refused-gap" | "and-over-no-ceiling" | "range-overlapping" | "range-inclusive" | "range-floor-on-rung" | "range-floor-widened" | "range-adult-floor";
 export type AgeRelation = "same" | "contains" | "overlaps" | "disjoint" | "silent";

package/dist/types/age.d.ts

@@ -1,5 +1,6 @@
-import type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YoungFloorVerdict } from "./age-types.ts";
-export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YoungFloorVerdict, };
+import type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YOBContext, YoungFloorVerdict } from "./age-types.ts";
+import type { Validated } from "./validated.ts";
+export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, Validated, YOBContext, YoungFloorVerdict, };
 export declare const YOUNGEST_FLOOR = 0;
 export declare const ADULT_FLOOR = 18;
 export declare const MAJORS_FLOOR_YEARS = 3;
@@ -14,10 +15,15 @@ export declare const YOUNG_FLOOR: Readonly<{
 }>;
 export declare const MIN_MAJOR_AGE = 4;
 export declare const MIN_FEIS_AGE = 3;
+export declare const YOUNGEST_BAND_TOP = 3;
+export declare const YOB_RANGE: Readonly<{
+    readonly first: 1900;
+    readonly last: 2099;
+}>;
 export declare const DANCE_UP_YEARS = 1;
 export declare const ageOnJanuary1: (year: number, born: number) => number;
 export declare const yearsSinceBirth: (year: number, born: number) => number;
-export interface Age {
+export interface Age extends Validated<AgeRefusal> {
     readonly [Symbol.toStringTag]: "Age";
     toString(): string;
     readonly arm: AgeArm;
@@ -48,7 +54,7 @@ export declare class AgeMisuseError extends Error {
     constructor(misuse: AgeMisuse, detail: string);
 }
 declare function fromPrint(print: string, context?: AgeContext): Age;
-declare function fromYOB(from: number | null, to?: number | null): Age;
+declare function fromYOB(from: number | null, to?: number | null, context?: YOBContext): Age;
 export declare const Age: Readonly<{
     from: typeof fromPrint;
     fromYOB: typeof fromYOB;
@@ -75,10 +81,16 @@ export interface AverageAge {
 export declare function isAveraged(a: Age | AverageAge): a is AverageAge;
 export declare function averageAge(ages: readonly Age[]): AverageAge;
 export declare function birthYearsDisjoint(a: BirthYears, b: BirthYears): boolean;
+export declare function intersectBirthYears(windows: readonly BirthYears[]): {
+    from: number | null;
+    to: number | null;
+    n: number;
+} | null;
 export declare function birthYearsMeet(card: BirthYears, other: BirthYears, slack?: number): boolean;
 export declare function underCapApplies(bandFrom: number | null, year: number): boolean;
 export declare function underCappedYears(b: BirthYears, year: number, n?: number): BirthYears;
 export declare function underCapRefuses(bandFrom: number, identityFrom: number, n: number): boolean;
+export declare function validYOB(y: number | null | undefined, year?: number | null): number | null;
 export declare function youngFloor(year: number, oldest: number): YoungFloorVerdict;
 export declare const tooYoungForMajor: (year: number, oldest: number) => boolean;
 export declare const tooYoungForFeis: (year: number, oldest: number) => boolean;

package/dist/types/validated.d.ts

@@ -0,0 +1,4 @@
+export interface Validated<Reason extends string> {
+    isValid(): boolean;
+    invalidReason(): Reason | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Places, CLRG regions, school names, ages and dances as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
@@ -69,6 +69,6 @@
 		"prepublishOnly": "bun scripts/build.ts && bun scripts/guard-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/names": "0.12.0"
+		"@finbheara/names": "0.17.0"
 	}
 }