@finbheara/domain 0.60.0 → 0.62.0

package/README.md

@@ -39,11 +39,11 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 
 | import | what |
 |---|---|
-| `@finbheara/domain/place` | `place()`, `createPlaceReader`, `placeRelation`, the `Place` types |
+| `@finbheara/domain/place` | `place()`, `createPlaceReader`, `placeRelation`, `placeFromId`, `ownRegionCountries`, the `Place` types |
 | `@finbheara/domain/geocode` | `geocode()`: a location field read by the place store, then by every GeoNames town of AU, CA, GB, IE, NZ and US; `townCell` |
 | `@finbheara/domain/clrg-regions` | `REGIONS`, `regionOf`, `resolvePhrase` |
 | `@finbheara/domain/event` | `EVENT_REGISTER`, `EVENT_REGISTER_BY_CODE`, `EVENT_TIER`, `eventTier`, `isMajorEvent`, `eventCodeOfSlug`, the `EventRegisterRow` type: the CLRG championships of tier 1 to 3 (below) |
-| `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns` |
+| `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns`, the word questions `namesInstitution`, `isSchoolVocabularyWord`, `isFluffOrFragment`, `notASchoolIn`, the `InstitutionType` type |
 | `@finbheara/domain/school-graph` | `schoolGraph`, `FAMILY_EDGES`, `LINK_YEARS`, `ANY_PATH`, `FAMILY_PATH`, and the `SchoolLink`/`LinkPath`/`LinkPolicy` types: how two schools are linked, as candidate paths with flags (below) |
 | `@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 |
@@ -56,6 +56,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@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) |
+| `@finbheara/domain/internals` | NOT A PUBLIC API: the place store and the school reader's building blocks, for a tool that mirrors how this package builds its readings (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.
@@ -117,6 +118,20 @@ A town followed by a county, district or region reads as the town only where tha
 it: `place("Coventry, West Midlands")` is Coventry, and `place("Coventry, Kent")` is two places.
 Which units hold each town is a table read off GeoNames.
 
+A node is read by its id with `placeFromId`, and its fields are on the reading's `nodes`:
+
+```ts
+import { ownRegionCountries, placeFromId } from "@finbheara/domain/place";
+
+placeFromId("NZL").nodes.find((n) => n.id === "NZL")?.iso2;  // "NZ"
+ownRegionCountries().has("NZL");   // true: New Zealand is one CLRG region
+ownRegionCountries().has("USA");   // false
+```
+
+`ownRegionCountries` is every country whose CLRG region covers the whole of it on the map: New
+Zealand, Australia, South Africa and the South American states. A region placed on no map (the
+RCCEA) and a foreign member (Mexico, in the Southern Region) are not in it.
+
 ### Geocoding a location field
 
 `place()` holds the places a print of a school or a person may carry, and it reads no other
@@ -242,6 +257,26 @@ const reader = createSchoolNameReader({ lexicon: (key) => myLexicon.get(key) });
 compareSchoolNames("Ardvarna Academy", "Ardvarna Academy (Ontario)", reader);
 ```
 
+### One word at a time
+
+A caller reading a print word by word, before or beside the reader, asks the vocabularies the
+reader asks:
+
+```ts
+import { isFluffOrFragment, isSchoolVocabularyWord, namesInstitution } from "@finbheara/domain/school";
+
+namesInstitution("Ardvarna Academy (Calgary, AB)");  // true: `Academy`
+namesInstitution("Ardvarna, Calgary");               // false
+isSchoolVocabularyWord("Calgary");                   // true: a place token
+isSchoolVocabularyWord("Ardvarna");                  // false
+isFluffOrFragment("danc");                           // true: a cut of `dance`
+```
+
+`isSchoolVocabularyWord` is a place token, an institution word or a whole fluff word, and knows
+no names: a caller with a lexicon asks it beside this. `isFluffOrFragment` reads a token
+`foldSchoolName` has folded. `notASchoolIn(rows)` is the refusal check a reader builds from its
+registers, for a caller that asks it without parsing: it answers the first row a print matches.
+
 ### Your own garbage
 
 The shipped refusals are generic: a card number, keyboard filler, a run with no letter in it,
@@ -789,6 +824,20 @@ seatName("Aoife Mhaolvarna").nn2;                    // "Mhaolvarna<<Aoife": nam
   `dancerPrintsNoName(print)`) is `roleName(role, print).printsNoName()` without the parse, for
   a walk that parses no name. Names' `isNoNamePrint` alone misses a role's own sentinel.
 
+## Internals
+
+```ts
+/* Use at your own risk: not a public API, may change in any release. File an issue to make it public if you have a real use case. */
+import { PLACE_NODES, schoolTokens } from "@finbheara/domain/internals";
+```
+
+`@finbheara/domain/internals` exports the place store (`PLACE_NODES`, `AMBIGUOUS_PRINTS`) and
+the school reader's building blocks (its token classes, its location zones, its fluff and
+institution scans) for a tool that mirrors how this package builds its readings, such as a table
+generated from the place store. It follows no semver: any release may rename or remove a name in
+it. A question a reading answers belongs on `/place` or `/school` as an accessor, and an issue
+asking for one is the way to get it there.
+
 ## Known gaps
 
 - `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does