@finbheara/domain 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finbheara Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+# @finbheara/domain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Places, CLRG regions, school names, ages and dances as they are actually printed: read,
+compared and told apart. A domain model downstream of
+[`@finbheara/names`](https://www.npmjs.com/package/@finbheara/names), which reads the
+person names.
+
+- **Places**: a print in, the set of place-tree nodes it may mean out. A country, a state or
+  province, a county, a city, or a CLRG region, with a relation between any two readings.
+- **CLRG regions**: the CLRG's dance regions and their Oireachtas codes, and the region a
+  location phrase falls in.
+- **School names**: a printed school name in, a `SchoolName` out, with a display form, a
+  filing key and a verdict on whether two prints may be one school.
+- **Ages**: an age group (`U12`, `Over 21`, `13-14`) or a year of birth in, an `Age` out: a
+  closed range of birth years, exact when it is one year, with `fitsIn`, `overlaps` and a
+  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.
+- **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.
+
+It was built on the stage announcements and results sheets of Irish dance competitions,
+where one school arrives as `Ardvarna Academy of Irish Dance (Calgary, AB)` and as
+`ARDVARNA ACADEMY - Calgary, Alberta`.
+
+```sh
+npm install @finbheara/domain
+```
+
+ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any dance commission.
+
+## Entry points
+
+| import | what |
+|---|---|
+| `@finbheara/domain/place` | `place()`, `createPlaceReader`, `placeRelation`, the `Place` types |
+| `@finbheara/domain/clrg-regions` | `REGIONS`, `regionOf`, `resolvePhrase` |
+| `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns` |
+| `@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/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 |
+
+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.
+
+## Read a place
+
+```ts
+import { place, placeRelation } from "@finbheara/domain/place";
+
+const p = place("Pennsylvania, Mid-Atlantic Region");
+p.arm;                       // "resolved"
+p.pl2;                       // "USA-PA"
+p.nodes.map((n) => n.id);    // ["USA", "USA-PA", "IDTANA-MARO"]
+p.country;                   // "USA"
+p.region;                    // "IDTANA-MARO"
+
+place("Calgary, AB").pl2;    // "CAN-AB/calgary"
+place("Co. Cork").region;    // "MUNSTER"
+place("CA").arm;             // "ambiguous": California or Canada
+place("Dublin").arm;         // "ambiguous": Ireland, California or Ohio
+
+placeRelation(place("Calgary, AB"), place("Western Canada"));  // "contains"
+placeRelation(place("Virginia"), place("Ontario"));            // "conflict"
+```
+
+A `Place` is one of four arms: `resolved`, `plural` (a print naming more than one place),
+`ambiguous` (one print, several readings) and `unread`. Only `conflict` between two readings
+says they cannot be one place; `same`, `contains` and `overlaps` do not.
+
+## Find a CLRG region
+
+```ts
+import { REGIONS, regionOf, resolvePhrase } from "@finbheara/domain/clrg-regions";
+
+regionOf("Pennsylvania");                          // "MARO"
+REGIONS.MARO;                                      // "Mid-Atlantic Region USA"
+resolvePhrase("Pennsylvania, Mid-Atlantic Region"); // ["MARO"]
+resolvePhrase("Calgary in Western Canada");         // ["WCRO"]
+resolvePhrase("Derry in Ireland");                  // ["ULSTER"]
+```
+
+`resolvePhrase` answers every region a phrase supports, and `[]` where it supports none. A
+token that names places in two regions resolves only with a co-token that settles it.
+
+## Read a school name
+
+```ts
+import { DEFAULT_SCHOOL_NAME_READER, compareSchoolNames } from "@finbheara/domain/school";
+
+const reader = DEFAULT_SCHOOL_NAME_READER;
+const s = reader.schoolName("Ardvarna Academy of Irish Dance (Calgary, AB)");
+s.sn2;               // "Ardvarna Academy (CAN-AB/calgary)"   display form
+s.sn3;               // "ARDVARNA ACADEMY (CAN-AB/calgary)"   filing key
+s.institution;       // "academy"
+s.location?.pl3;     // "CAN-AB/calgary"
+s.isSchool();        // true
+
+reader.schoolName("Scoil Rince Glenmorvan").sn2;  // "S.R. Glenmorvan"
+reader.schoolName("N/A").refusal?.reason;         // "placeholder"
+
+compareSchoolNames("Ardvarna Academy of Irish Dance (Calgary, AB)",
+                   "ARDVARNA ACADEMY - Calgary, Alberta", reader).verdict;  // "CANDIDATE"
+compareSchoolNames("Ardvarna Academy (Calgary, AB)",
+                   "Ardvarna Academy (Ontario)", reader).verdict;           // "BLOCKED"
+compareSchoolNames("Ardvarna Academy",
+                   "Ardvarna Academy (Ontario)", reader).verdict;           // "AMBIGUOUS"
+compareSchoolNames("Ardvarna Academy", "Glenmorvan Academy", reader).verdict; // "DIFFERENT"
+```
+
+The verdicts: `CANDIDATE` (same name, compatible qualifiers), `BLOCKED` (same name,
+contradicting qualifiers), `AMBIGUOUS` (needs context) and `DIFFERENT`. A verdict is a name
+reading and never an identity: two schools can share a name.
+
+`DEFAULT_SCHOOL_NAME_READER` is the generic reader: no lexicon, the shipped registers, frozen.
+Nothing replaces it, and the package holds no other. `compareSchoolNames` and
+`schoolPrintSplit` take the reader as an argument, always, so a print is never read by a
+reader you did not choose. A reader with a lexicon (for the surnames a school is named after),
+your own exception and refusal registers, or your own garbage is one you build:
+
+```ts
+import { compareSchoolNames, createSchoolNameReader } from "@finbheara/domain/school";
+
+const reader = createSchoolNameReader({ lexicon: (key) => myLexicon.get(key) });
+compareSchoolNames("Ardvarna Academy", "Ardvarna Academy (Ontario)", reader);
+```
+
+### Your own garbage
+
+The shipped refusals are generic: a card number, keyboard filler, a run with no letter in it,
+the shared placeholder list of `@finbheara/names` (`N/A`, `No School`, ...). What YOUR data
+prints in a school field and is not a school, such as an entry system's own "school not
+listed" instruction, a test entry, or a note typed into the wrong field, is yours to declare.
+Pass it as `garbage`, the same idea as `phraseClassifier(lexicon, { garbageVocab })` in
+`@finbheara/names`:
+
+```ts
+import { createSchoolNameReader } from "@finbheara/domain/school";
+
+const reader = createSchoolNameReader({
+	garbage: [
+		{ pattern: "-- my school is not on this list --", kind: "exact", reason: "placeholder" },
+		{ pattern: "demo school ", kind: "prefix", reason: "placeholder" },
+		{ pattern: "^sister of .+$", kind: "regex", reason: "not-a-name" },
+	],
+});
+reader.schoolName("-- My School Is Not On This List --").refusal?.reason;  // "placeholder"
+```
+
+A row's `pattern` is matched against the print with its case lowered, its accents and
+invisible characters dropped and its whitespace collapsed; a `regex` is compiled with the `i`
+flag and anchors itself. Your rows are asked before the shipped ones and the first match
+answers.
+
+## Read an age
+
+Ages are as of 1 January of the competition year. An `Age` is a closed range of birth years,
+whatever it was read from, so a year of birth and a one-year age group are the same thing.
+
+```ts
+import { Age, averageAge, canOverlap } from "@finbheara/domain/age";
+
+const dancer = Age.fromYOB(2014);
+dancer.isExact();                                       // true
+
+const u12 = Age.from("U12", { year: 2026 });
+u12.birthYears();                                       // { from: 2014, to: 2023 }
+dancer.fitsIn(u12);                                     // true
+
+// With the age groups the event offered, U12 is one birth year, so it is exact.
+const ladder = { caps: [11, 12, 13], overs: [], ranges: [] };
+Age.from("U12", { year: 2026, ladder }).isExact();      // true
+
+Age.fromYOB(1999).fitsIn(Age.from("U18", { year: 2025 }));               // false
+Age.fromYOB(1999).fitsIn(Age.from("Over 21", { year: 2026, top: true })); // true
+
+canOverlap(u12, Age.from("U14", { year: 2026 }), dancer);                 // true
+```
+
+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.
+
+```ts
+const team = averageAge([1990, 1985, 1999, 1988].map((y) => Age.fromYOB(y)));
+team.meanAge(2026);                                     // 34.5
+team.fitsIn(Age.from("U40", { year: 2026 }));           // true
+
+averageAge([u12]);                                      // throws AgeMisuseError "not-exact"
+```
+
+## Index names in a database
+
+`createNameMap` (from `@finbheara/names`) and `mapOfSchools` hold their names in memory. An
+index holds them in a SQLite table, as columns: every slot those maps hash a name on, indexed,
+so a lookup at a level is one equality and nothing is loaded. It is a multi-map: a row is one
+name and one value, and a lookup answers every value filed at the name's slot.
+
+The package depends on no SQLite module. Hand it a handle with `prepare(sql)` returning a
+statement with `run(...)` and `all(...)`: `bun:sqlite`'s `Database` and `node:sqlite`'s
+`DatabaseSync` (Node ≥ 22.5) are both one as they are.
+
+```ts
+import { Database } from "bun:sqlite";            // or: import { DatabaseSync } from "node:sqlite"
+import { createNameMap, personName } from "@finbheara/names/normalize";
+import { createIndex, indexSchema, personEncoder } from "@finbheara/domain/noun-index";
+
+const db = new Database(":memory:");
+const people = personEncoder();
+const { table, indexes } = indexSchema(people, { table: "person" });
+db.prepare(table).run();
+for (const s of indexes) db.prepare(s).run();      // after a bulk load, if you have one
+
+const index = createIndex(db, people, { table: "person" });
+index.add(personName("Aoife Ní Mhaolvarna"), 1);
+index.add(personName("Mhaolvarna, Aoife Ni"), 2);
+index.add(personName("Kestrel Evbatyrov"), 3);
+
+index.get(personName("AOIFE NI MHAOLVARNA"), "nn3");  // [1, 2]
+index.get(personName("Aoife Ní Mhaolvarna"), "nn0");  // [1]
+index.find("surname_key", personName("Aoife Ní Mhaolvarna").surnameKey());  // [1, 2]
+index.nouns(2)[0]?.nn2;                                // "NiMhaolvarna<<Aoife": the parse, read back
+```
+
+`map(level)` is the single-valued view, with `createNameMap`'s interface and its answers:
+the first name filed at a slot keeps it, a later `set` replaces the value, and a print that
+names no person is held and never found.
+
+```ts
+const byName = index.map("nn3");
+byName.get(personName("Aoife Ni Mhaolvarna"));        // 1
+byName.size;                                           // 2
+createNameMap<number>("nn3", [...byName]).size;        // 2
+```
+
+The person columns are the print, the reading it was parsed under, and `nameColumns()` from
+`@finbheara/names`; the levels are `nn0`-`nn4`. A school's (`schoolEncoder` from
+`@finbheara/domain/school`) are the print, `sn0`-`sn4`, `realWords` and `matchKey`, and its
+levels are `mapOfSchools`'s. One print may be filed under several schools, and a school under
+many prints:
+
+```ts
+import { DEFAULT_SCHOOL_NAME_READER, schoolEncoder } from "@finbheara/domain/school";
+
+const read = (p: string) => DEFAULT_SCHOOL_NAME_READER.schoolName(p);
+const schools = createIndex(db, schoolEncoder(), { table: "school" });  // after its indexSchema
+schools.add(read("Ardvarna Academy"), 10);
+schools.add(read("Ardvarna Academy"), 11);
+schools.add(read("Ardvarna Academy (Ontario)"), 11);
+schools.add(read("ARDVARNA ACADEMY - Calgary, Alberta"), 10);
+
+schools.get(read("Ardvarna Academy"), "sn0");         // [10, 11]
+schools.nouns(11).map((s) => s.sn0);                   // ["Ardvarna Academy", "Ardvarna Academy (Ontario)"]
+schools.get(read("Ardvarna Academy of Irish Dance (Calgary, AB)"), "sn3");  // [10]
+```
+
+`rows({ column: keys, ... })` answers every row where any column holds one of its keys, and
+`glob(column, pattern)` a SQLite `GLOB` on one column. An encoder is a plain object: add a
+column of your own by spreading one, `{ ...enc, columns: [...enc.columns, "k"], encode: (x) =>
+({ ...enc.encode(x), k: f(x) }) }`. `indexSchema` takes the table, the value column and its
+type (`{ value: "id", valueType: "INTEGER PRIMARY KEY" }` makes the value the row id); on such a table `map(level)` iterates in value order, and a `set` to a value another row
+holds is refused by the key).
+
+## Known gaps
+
+- `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does
+  not split a phrase at `in`. `resolvePhrase` finds their regions.
+
+## Licence
+
+MIT, Copyright (c) 2026 Finbheara Systems.